Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

feat(control-api): add host:session:write RPC scope (spec 15 Phase B)

Diego Zacariasdcbdb8f1e874
diff --git a/control-api/package-lock.json b/control-api/package-lock.json
index 4d517e657..a223c56f9 100644
--- a/control-api/package-lock.json
+++ b/control-api/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-api",
- "version": "0.1.549",
+ "version": "0.1.550",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-api",
- "version": "0.1.549",
+ "version": "0.1.550",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/image-policy": "file:../packages/image-policy",
diff --git a/control-api/package.json b/control-api/package.json
index 76164cfd8..05ea1f10b 100644
--- a/control-api/package.json
+++ b/control-api/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-api",
- "version": "0.1.549",
+ "version": "0.1.550",
"description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets",
"main": "dist/main.js",
"engines": {
diff --git a/control-api/src/profileTypes.ts b/control-api/src/profileTypes.ts
index acc295940..ee30f86f8 100644
--- a/control-api/src/profileTypes.ts
+++ b/control-api/src/profileTypes.ts
@@ -13,6 +13,7 @@ export type RpcScope =
| 'host:task:read'
| 'host:approval:write'
| 'host:session:read'
+ | 'host:session:write'
| 'host:model:write'
| 'host:cron:read'
| 'host:cron:ack'
@@ -30,6 +31,7 @@ export const RPC_SCOPES: RpcScope[] = [
'host:task:read',
'host:approval:write',
'host:session:read',
+ 'host:session:write',
'host:model:write',
'host:cron:read',
'host:cron:ack',
diff --git a/control-api/src/routes/rpc-access/users.ts b/control-api/src/routes/rpc-access/users.ts
index 234b1297c..c6d5ea236 100644
--- a/control-api/src/routes/rpc-access/users.ts
+++ b/control-api/src/routes/rpc-access/users.ts
@@ -42,6 +42,7 @@ const HOST_ACCESS_SCOPES = [
'host:model:write',
'host:task:read',
'host:session:read',
+ 'host:session:write',
'desktop:view',
] as const
diff --git a/control-api/src/utils/auth/rpcAuthToken.ts b/control-api/src/utils/auth/rpcAuthToken.ts
index 319f86166..f7a68ce0a 100644
--- a/control-api/src/utils/auth/rpcAuthToken.ts
+++ b/control-api/src/utils/auth/rpcAuthToken.ts
@@ -36,6 +36,11 @@ function defaultScopesForRole(role: TeamRole): RpcScope[] {
'host:task:read',
'host:approval:write',
'host:session:read',
+ // Per-session write (rename). Granted to every role: the blast radius is
+ // the caller's own chat session. A dedicated write scope is required
+ // because host:session:read is minted on every session listing, so
+ // reusing it would hand write to every navigation token.
+ 'host:session:write',
// Per-session model selection (spec §8.2): granted to every role. The
// blast radius of a swap is the caller's own chat session; the operator's
// cost control is the model allowlist, not this scope.
diff --git a/control-api/test/routes.profile.test.ts b/control-api/test/routes.profile.test.ts
index 8cb19e324..042ea4596 100644
--- a/control-api/test/routes.profile.test.ts
+++ b/control-api/test/routes.profile.test.ts
@@ -284,6 +284,42 @@ describe('routes/profile', () => {
})
})
+ it('accepts a host:session:write-only token on the mcp-hosts access endpoint (session rename)', async () => {
+ // The desktop mints an rpc token scoped to ONLY `host:session:write` for the
+ // session-rename flow (rpc-proxy PATCH /rpc/hosts/:hostRef/sessions/.../name
+ // resolves host access via THIS endpoint). If the scope were missing from the
+ // requireValidRpcAccessTokenAny allow-list, control-api would return 403 and
+ // the rename would be silently dropped. Uses the REAL middleware + a REAL
+ // signed token so the scope gate is genuinely exercised (not mocked).
+ const sessionWriteToken = signRpcAccessToken({
+ sub: 'u1',
+ typ: 'user',
+ teamId: 't1',
+ role: 'member',
+ scopes: ['host:session:write'],
+ hostRefs: ['agent-a'],
+ jti: 'rpc-jti-session-write',
+ })
+
+ svc.getUserAgents.mockResolvedValue({ userId: 'u1', agentNames: ['agent-a'] })
+
+ const app = express()
+ app.use(express.json())
+ mountInternalRoutes(app, accessCatalogGateway())
+
+ await withInternalServiceAuth(
+ request(app)
+ .get('/rpc/access/users/u1/mcp-hosts/agent-a')
+ .set('x-rpc-access-token', sessionWriteToken)
+ )
+ .expect(200)
+ .expect({
+ userId: 'u1',
+ hostRef: 'agent-a',
+ url: 'http://agent-a.mcp-host.svc.cluster.local:8080',
+ })
+ })
+
it('rejects a token whose scopes are all outside the mcp-hosts allow-list (gate still closed)', async () => {
// Negative half of the allow-list contract: `mcp:servers:list` is NOT an
// accepted scope for the host-access endpoint, so a token carrying only it
diff --git a/control-api/test/rpcAuthToken.userScope.test.ts b/control-api/test/rpcAuthToken.userScope.test.ts
index 64865865e..661fb8bec 100644
--- a/control-api/test/rpcAuthToken.userScope.test.ts
+++ b/control-api/test/rpcAuthToken.userScope.test.ts
@@ -157,6 +157,35 @@ describe('host:model:write default grant (spec §8.2)', () => {
})
})
+describe('host:session:write default grant (session rename)', () => {
+ // Per-session write (rename) is granted to every role: the blast radius is the
+ // caller's own session. It is a dedicated scope rather than a reuse of
+ // host:session:read, which is minted on every listing.
+ it.each(['admin', 'inviter', 'member'] as const)(
+ 'includes host:session:write in the default scopes for %s',
+ role => {
+ const issued = issueRpcAccessToken(
+ { userId: 'user-1', teamId: 'team-1', role },
+ [],
+ ['pro-agent']
+ )
+ expect(issued?.scopes).toContain('host:session:write')
+ }
+ )
+
+ it('grants host:session:write when explicitly requested by a member', () => {
+ // Exercises normalizeRequestedScopes: an unknown scope is dropped silently,
+ // so a write-only token surviving issuance proves the normalizer recognizes
+ // host:session:write.
+ const issued = issueRpcAccessToken(
+ { userId: 'user-1', teamId: 'team-1', role: 'member' },
+ ['host:session:write'],
+ ['pro-agent']
+ )
+ expect(issued?.scopes).toEqual(['host:session:write'])
+ })
+})
+
describe('classifyRpcTokenDenial', () => {
it('reports desktop_requires_team when a teamless caller is denied only team-only scopes', () => {
// desktop:view is permitted by the member role but team-only, so a teamless