feat: edit permission entries (v1.35.0)

The Permissions page only offered Delete, so changing a role or scope
meant removing the grant and re-adding it from memory.

A permission's id is derived from (subjectType, subject, scope, domain),
so changing any of those is a different record rather than an update. The
new PUT creates the new grant and removes the superseded one in that
order, so an edit can never leave the old grant behind still conferring
access.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -1,3 +1,13 @@
+## v1.35.0
+- feat: **permission entries can be edited.** The Permissions page only offered Delete, so changing a role or scope meant removing the grant and re-adding it from memory. New `PUT /api/permission/:id` plus an Edit modal pre-filled from the record.
+- fix: a permission's id is derived from (subjectType, subject, scope, domain), so changing any of those is a *different* record, not an update. The endpoint creates the new grant and removes the superseded one in that order, so an edit can never leave the old grant behind still conferring access.
+
+## v1.34.0
+- feat: the per-host SSO **Allowed groups** field now autocompletes from the SSO directory's groups. Suggestions previously came only from local groups, permission subjects and `conf.auth` maps — none of which can match an SSO-gated host, because its allow-list is checked against the `groups` claim the SSO issues. New `conf.sso` block (`url` + read-only `apiToken`, minted by theta-suite's bootstrap); results are cached for 5 minutes and the endpoint degrades silently to the old local-only list when unset.
+- fix: the SSO group lookup authenticates with `Authorization: Bearer <token>`, not the `auth-token` header — the latter is for browser session UUIDs and would be rejected for a minted API token.
+- docs: `docs/concepts-hosts.md` gains a "Putting a host behind single sign-on" section covering the per-host `/__proxy_auth` flow, the wildcard redirect URI the IdP must allow, and where group suggestions come from.
+- docs: `secrets.js.example` documents the new `sso` block.
+
 ## v1.33.0
 - feat: Add SSO-style error page (404/500) for browser navigation instead of a bare JSON/text response
 - feat: DNS page is now admin-only (hidden from non-admins; API already admin-gated)

docs/concepts-hosts.md

@@ -68,6 +68,38 @@ host form whenever the name you're entering already has a matching
 wildcard available to reuse — including the wildcard's own bare base
 domain (e.g. `example.com` itself, not just `something.example.com`).
 
+## Putting a host behind single sign-on
+
+Each host can be gated on its own, independently of the proxy's management UI.
+On the host's **Auth** tab pick **Single sign-on (SSO)** and, optionally, fill in
+the **Allowed users** / **Allowed groups** lists. Empty lists mean any
+authenticated user is allowed; otherwise the identity must match one of them.
+
+The proxy runs the OIDC flow itself at `/__proxy_auth` on the protected host and
+keeps a Redis-backed session in a `__proxy_sso` cookie, so the app behind it
+needs no changes.
+
+**The IdP must allow the per-host callback.** Each protected host calls back to
+`https://<that-host>/__proxy_auth/callback`, which is a different URL for every
+host, all against the proxy's one OAuth client. Register a wildcard redirect URI
+on that client — the SSO Manager supports `*` (one label) and `**` (any number):
+
+```
+https://**.example.com/__proxy_auth/callback
+https://example.com/__proxy_auth/callback
+```
+
+theta-suite's bootstrap registers both automatically, and backfills them onto an
+existing client. Without them, switching a host to SSO fails at the IdP with
+`400 redirect_uri is not registered for this client`.
+
+**Group suggestions come from the SSO.** The Allowed groups field autocompletes
+from the SSO directory's groups when `sso.url` and `sso.apiToken` are set in the
+proxy's config (theta-suite's bootstrap mints that read-only token). Without it
+the field can only suggest the proxy's local groups, which for an SSO-gated host
+are rarely the ones you want — the allow-list is matched against the `groups`
+claim in the SSO's token, so only SSO groups can ever match.
+
 ## Load Balancing
 
 If you have multiple servers running the same application, you can load balance traffic across them. When editing a host, you can specify **Additional Targets** (one `IP:port` per line). The proxy will automatically distribute incoming requests across your primary target and all additional targets using a round-robin strategy, providing simple high availability and load distribution without extra configuration.

nodejs/conf/base.js

@@ -45,6 +45,18 @@ module.exports = {
 		usernameClaim: 'preferred_username',
 	},
 
+	// Read-only SSO management API access, used to populate the per-host SSO
+	// allow-list autocomplete with the groups that actually exist in the
+	// directory. Without it the "Allowed groups" field can only suggest groups
+	// the proxy already knows locally, which for an SSO-gated host is usually
+	// none of the ones the operator wants. `apiToken` is a machine token minted
+	// by the theta-suite bootstrap and lives in secrets.js; leaving it unset
+	// simply falls back to the local-only suggestions.
+	sso: {
+		url: '',        // e.g. https://sso.example.com
+		apiToken: '',
+	},
+
 	// Authorization: how groups map to roles, and which groups are global admin.
 	// Per-user overrides are Grant records managed in the app.
 	auth: {

nodejs/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "proxy-api",
-  "version": "1.32.0",
+  "version": "1.35.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "proxy-api",
-      "version": "1.32.0",
+      "version": "1.35.0",
       "license": "MIT",
       "dependencies": {
         "@fortawesome/fontawesome-free": "^7.3.0",

nodejs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "proxy-api",
-  "version": "1.32.0",
+  "version": "1.35.0",
   "author": [
     {
       "name": "William Mantly",

nodejs/public/lib/js/app-base.js

@@ -466,13 +466,19 @@ app.permission = (function(app){
 		});
 	}
 
+	function update(id, args, callback){
+		app.api.put('permission/' + encodeURIComponent(id), args, function(error, data){
+			callback(error, data);
+		});
+	}
+
 	function remove(id, callback){
 		app.api.delete('permission/' + encodeURIComponent(id), function(error, data){
 			callback(error, data);
 		});
 	}
 
-	return {list, subjects, add, remove};
+	return {list, subjects, add, update, remove};
 
 })(app);
 

nodejs/routes/host.js

@@ -58,16 +58,55 @@ function hashHostSecrets(body){
 	}
 }
 
+// The SSO's directory groups, for the per-host SSO allow-list autocomplete.
+// The host's allow-list is checked against the `groups` claim the SSO puts in
+// the token (see utils/host_sso.js), so the only suggestions that can ever
+// match are the SSO's own groups -- the local groups below are a fallback, not
+// the real answer. Requires conf.sso.apiToken; degrades to [] without it, and
+// never fails the request (the form still works, just without suggestions).
+//
+// Cached for a few minutes: this is typeahead fodder, and every host editor
+// opening the form would otherwise hit the SSO.
+let ssoGroupCache = {at: 0, groups: []};
+const SSO_GROUP_TTL = 5 * 60 * 1000;
+
+async function ssoGroups(){
+	let sso = conf.sso || {};
+	if(!sso.url || !sso.apiToken) return [];
+	if(Date.now() - ssoGroupCache.at < SSO_GROUP_TTL) return ssoGroupCache.groups;
+	try{
+		let res = await fetch(`${sso.url.replace(/\/$/, '')}/api/group`, {
+			// A minted API token (`sso_<id>_<secret>`) authenticates as a bearer
+			// token; the SSO's `auth-token` header is for browser session UUIDs
+			// only and would be rejected here.
+			headers: {Authorization: `Bearer ${sso.apiToken}`, Accept: 'application/json'},
+			signal: AbortSignal.timeout(5000),
+		});
+		if(!res.ok) throw new Error(`SSO group list failed (${res.status})`);
+		let body = await res.json();
+		// The SSO returns { results: [...] } -- either CN strings or objects.
+		let groups = (body && body.results || []).map(g => (typeof g === 'string' ? g : g && g.name)).filter(Boolean);
+		ssoGroupCache = {at: Date.now(), groups};
+		return groups;
+	}catch(error){
+		console.error(`[auth-suggestions] could not list SSO groups: ${error.message}`);
+		// Cache the failure briefly so a down SSO doesn't stall every form open.
+		ssoGroupCache = {at: Date.now(), groups: ssoGroupCache.groups};
+		return ssoGroupCache.groups;
+	}
+}
+
 // Autocomplete source for the per-host auth allow-lists (SSO users/groups).
 // Available to any authenticated host editor (not just global admins). Groups
-// are derived from local groups, existing permission group-subjects, and the
-// conf.auth admin/role-map groups.
+// are the SSO directory's groups plus local groups, existing permission
+// group-subjects, and the conf.auth admin/role-map groups.
 router.get('/auth-suggestions', async function(req, res, next){
 	try{
 		let users = [];
 		try{ users = (await User.list()) || []; }catch(error){ /* none */ }
 
 		let groups = new Set();
+		for(let g of await ssoGroups()) groups.add(g);
 		try{ for(let g of await LocalGroup.list()) groups.add(g); }catch(error){ /* none */ }
 		try{
 			for(let p of await Permission.listDetail()){

nodejs/routes/permission.js

@@ -57,6 +57,47 @@ router.post('/', async function(req, res, next){
 	}
 });
 
+// Edit an existing grant.
+//
+// The record id is derived from (subjectType, subject, scope, domain)
+// -- Permission.mkId -- so changing any of those is a DIFFERENT record, not an
+// in-place update. Changing only the role is a true update. Handle both here so
+// the UI can offer a single "edit" instead of making the operator delete and
+// re-add, and so a subject/scope change can never leave the old grant behind
+// still conferring access.
+router.put('/:id', async function(req, res, next){
+	try{
+		let existing = await Permission.get(req.params.id);
+		if(!existing) return res.status(404).json({message: `Permission ${req.params.id} not found.`});
+
+		let next_ = {
+			subjectType: req.body.subjectType !== undefined ? req.body.subjectType : existing.subjectType,
+			subject:     req.body.subject     !== undefined ? req.body.subject     : existing.subject,
+			scope:       req.body.scope       !== undefined ? req.body.scope       : existing.scope,
+			domain:      req.body.domain      !== undefined ? req.body.domain      : existing.domain,
+			role:        req.body.role        !== undefined ? req.body.role        : existing.role,
+			created_by:  reqUsername(req),
+		};
+		if(next_.scope === 'global') next_.domain = '*';
+
+		// create() upserts on the new id, so this is safe in either direction;
+		// remove the old record afterwards only when the identity actually moved.
+		let permission = await Permission.create(next_);
+		let newId = Permission.mkId(next_);
+		if(newId !== req.params.id){
+			try{ await existing.remove(); }catch(error){ /* already replaced */ }
+		}
+
+		return res.json({
+			message: `Updated ${next_.subjectType} "${next_.subject}" to ${next_.role}` +
+				(next_.scope === 'global' ? ' globally.' : ` on ${next_.domain}.`),
+			...permission,
+		});
+	}catch(error){
+		next(error);
+	}
+});
+
 router.delete('/:id', async function(req, res, next){
 	try{
 		let permission = await Permission.get(req.params.id);

nodejs/views/permissions.ejs

@@ -6,11 +6,20 @@
 
 <script type="text/javascript">
 
+	// Kept alongside the rendered scope so the Edit modal can pre-fill from the
+	// record without a second round-trip ($.scope exposes push/empty/remove,
+	// not a lookup by key).
+	var permissionsById = {};
+
 	function loadPermissions() {
 		app.permission.list(function(error, data){
 			if(error) return app.messages.action(error, $('#permissions-list'), 'danger');
+			permissionsById = {};
 			$.scope.Permission.empty();
-			for(let p of (data.results || [])) $.scope.Permission.push(p);
+			for(let p of (data.results || [])){
+				permissionsById[p.id] = p;
+				$.scope.Permission.push(p);
+			}
 		});
 	}
 
@@ -82,6 +91,76 @@
 		});
 	}
 
+	// Edit an existing grant. A permission's id is derived from
+	// (subjectType, subject, scope, domain), so changing any of those replaces
+	// the record rather than updating it -- the API handles that and removes the
+	// superseded grant, which is why this is a single Edit rather than making
+	// the operator delete and re-add (and risk leaving the old grant in place).
+	function permissionEditOpen(id){
+		var p = permissionsById[id] || {};
+		function sel(v, want){ return v === want ? ' selected' : ''; }
+		app.modal.open({title: 'Edit Permission', bodyHtml:
+			'<div class="mb-3">'
+			+   '<label class="form-label fw-bold">Subject type</label>'
+			+   '<select class="form-select" id="perm-edit-subjectType">'
+			+     '<option value="user"' + sel(p.subjectType, 'user') + '>User</option>'
+			+     '<option value="group"' + sel(p.subjectType, 'group') + '>Group</option>'
+			+   '</select>'
+			+ '</div>'
+			+ '<div class="mb-3">'
+			+   '<label class="form-label fw-bold">Subject (username or group)</label>'
+			+   '<input type="text" class="form-control" id="perm-edit-subject" list="subjectUsers" autocomplete="off" value="' + app.util.escapeHtml(p.subject || '') + '" />'
+			+ '</div>'
+			+ '<div class="mb-3">'
+			+   '<label class="form-label fw-bold">Scope</label>'
+			+   '<select class="form-select" id="perm-edit-scope">'
+			+     '<option value="domain"' + sel(p.scope, 'domain') + '>Domain</option>'
+			+     '<option value="global"' + sel(p.scope, 'global') + '>Global</option>'
+			+   '</select>'
+			+ '</div>'
+			+ '<div class="mb-3">'
+			+   '<label class="form-label fw-bold">Domain (for domain scope)</label>'
+			+   '<input type="text" class="form-control" id="perm-edit-domain" autocomplete="off" value="' + app.util.escapeHtml(p.domain || '') + '" />'
+			+   '<div class="form-text text-muted">'
+			+     'Wildcards: <code>*.example.com</code> matches one label, '
+			+     '<code>**.example.com</code> matches any depth (incl. the apex), '
+			+     '<code>**</code> matches every domain.'
+			+   '</div>'
+			+ '</div>'
+			+ '<div class="mb-3">'
+			+   '<label class="form-label fw-bold">Role</label>'
+			+   '<select class="form-select" id="perm-edit-role">'
+			+     '<option value="viewer"' + sel(p.role, 'viewer') + '>Viewer (read)</option>'
+			+     '<option value="manager"' + sel(p.role, 'manager') + '>Manager (full over domain)</option>'
+			+     '<option value="admin"' + sel(p.role, 'admin') + '>Admin (global only)</option>'
+			+   '</select>'
+			+ '</div>'
+			+ '<hr />'
+			+ '<div class="d-flex justify-content-end gap-2">'
+			+   '<button type="button" class="btn btn-secondary" onclick="app.modal.close()">Cancel</button>'
+			+   '<button type="button" class="btn btn-primary" onclick="permissionEditSave(\'' + id + '\')">Save changes</button>'
+			+ '</div>',
+		});
+	}
+
+	function permissionEditSave(id){
+		var payload = {
+			subjectType: $('#perm-edit-subjectType').val(),
+			subject: ($('#perm-edit-subject').val() || '').trim(),
+			scope: $('#perm-edit-scope').val(),
+			domain: ($('#perm-edit-domain').val() || '').trim(),
+			role: $('#perm-edit-role').val(),
+		};
+		if(!payload.subject){
+			return app.messages.toast('Subject is required', 'warning');
+		}
+		app.permission.update(id, payload, function(error, data){
+			if(error) return app.messages.action((data && data.message) || error, $('#permissions-list'), 'danger');
+			app.modal.close();
+			loadPermissions();
+		});
+	}
+
 	function removePermission(id){
 		app.permission.remove(id, function(error, data){
 			if(error) return app.messages.action(error, $('#permissions-list'), 'danger');
@@ -148,7 +227,10 @@
 								</div>
 							</div>
 						</div>
-						<div>
+						<div class="d-flex gap-2">
+							<button type="button" class="btn btn-sm btn-outline-secondary" onclick="permissionEditOpen('{{id}}')">
+								<i class="fa-solid fa-pen me-1"></i> Edit
+							</button>
 							<button type="button" class="btn btn-sm btn-outline-danger" onclick="removePermission('{{id}}')">
 								<i class="fa-solid fa-trash me-1"></i> Delete
 							</button>

secrets.js.example

@@ -42,6 +42,18 @@ module.exports = {
         usernameClaim: 'preferred_username',
     },
 
+    // Read-only access to the SSO's management API, used to populate the
+    // per-host SSO allow-list autocomplete with the directory's actual groups.
+    // A host gated on SSO matches its allow-list against the `groups` claim the
+    // SSO issues, so only SSO groups can ever match -- without this the field
+    // can only suggest the proxy's own local groups. `apiToken` is a machine
+    // token minted by theta-suite's bootstrap; leaving it blank simply falls
+    // back to local-only suggestions.
+    sso: {
+        url: 'http://sso-manager:3001',
+        apiToken: '',
+    },
+
     // Direct LDAP user lookups. ldaps:// + rejectUnauthorized:false for a
     // self-signed cert (the SSO's default), or set tlsOptions.ca to a CA path
     // for strict verification. bindPassword MUST match the