feat(admin): close worker admin support access with scoped capabilities

ENVIRONMENT.md

@@ -132,6 +132,11 @@ ordinary local startup does not require this credential.
 - `CLOUD_AGENT_RESOURCE_TOKENS_ENABLED` - Default-off family gate for Cloud Agent Next request control and workflow control tokens; requires the master and exact `true`. [SERVER]
 - `GASTOWN_RESOURCE_TOKENS_ENABLED` - Default-off family gate for Gastown control tokens; requires the master and exact `true`. This is not a safe-activation declaration: known ingest-audience and live-token-transport blockers remain deferred. [SERVER]
 - `WASTELAND_RESOURCE_TOKENS_ENABLED` - Default-off family gate for Wasteland control tokens; requires the master and exact `true`. [SERVER]
+- `WORKER_ADMIN_LEGACY_CLAIM_ISSUANCE` - `on` by default. Controls whether `/api/gastown/token`, `/api/wasteland/token`, Wasteland server resolution, and the admin Gastown REST client still put `isAdmin` on the ordinary Worker identity token. Set to `off` only during the legacy drain; Workers independently cap any legacy `isAdmin` claim at one hour and reject dateless claims. [SERVER]
+- `WORKER_ADMIN_CAPABILITY_ISSUANCE` - Default off; requires exact `on`. Enables minting short-lived ES256 Worker admin capabilities from a browser session endpoint. Must stay off until session-bound MFA step-up (PR2) is live; the interim actor adapter always fails closed. [SERVER]
+- `WORKER_ADMIN_CAPABILITY_PRIVATE_JWK` - `[SECRET]` ES256 private JWK (with `kid`) used to sign Worker admin capabilities. Never commit a private key; rotate by publishing a new `kid` before signing with it. [SECRET]
+- `WORKER_ADMIN_CAPABILITY_PUBLIC_KEYS` - Worker-side JSON JWKS (`{"keys":[...]}`) of public capability keys, including retired keys during rotation. [SERVER]
+- `LEGACY_ADMIN_CLAIM_MODE` - Worker-side `honor` (default), `observe`, or `reject`. `honor` keeps legacy `isAdmin` support access; `observe` grants but emits `observe_would_deny`; `reject` stops granting legacy admin. Applies to both Gastown and Wasteland. [SERVER]
 - `CHAT_RESOURCE_TOKENS_ENABLED` - Default-off family gate for fresh chat resource issuance; requires the master and exact `true`. Validated modern devices retain chat/event-service/notifications issuance after rollback, capped by one hour and parent expiry. [SERVER]
 - `DELEGATED_RESOURCE_TOKENS_ENABLED` - Default-off family gate for explicit API, gateway, and attribution delegation, including the organization user-token resource route; requires the master and exact `true`. Disabled explicit delegation remains unavailable. [SERVER]
 - `WORKFLOW_GATEWAY_RESOURCE_TOKENS_ENABLED` - Default-off family gate for server workflow gateway tokens; requires the master and exact `true`. [SERVER]

apps/web/package.json

@@ -143,6 +143,7 @@
     "form-data": "4.0.6",
     "google-auth-library": "10.6.2",
     "jotai": "2.18.1",
+    "jose": "catalog:",
     "jotai-minidb": "0.0.8",
     "js-yaml": "4.3.2",
     "jsonwebtoken": "catalog:",

apps/web/src/app/api/gastown/token/route.test.ts

@@ -0,0 +1,134 @@
+jest.mock('@kilocode/web-shared/lib/user/server', () => ({
+  getUserFromAuth: jest.fn(),
+}));
+jest.mock('@/lib/gastown/feature-flags', () => ({
+  isGastownEnabled: jest.fn(async () => true),
+}));
+jest.mock('@kilocode/web-shared/lib/organizations/organizations', () => ({
+  getUserOrgMemberships: jest.fn(async () => []),
+}));
+jest.mock('@kilocode/web-shared/lib/tokens', () => ({
+  generateApiToken: jest.fn(() => 'identity-token'),
+}));
+jest.mock('@kilocode/web-shared/lib/admin/admin-access-log', () => ({
+  recordKiloAdminElevationForRequest: jest.fn(async () => undefined),
+  serviceTarget: (id: string) => `service:${id}`,
+}));
+jest.mock('@kilocode/web-shared/lib/config.server', () => ({
+  isWorkerAdminLegacyClaimIssuanceEnabled: jest.fn(() => true),
+  isWorkerAdminCapabilityIssuanceEnabled: jest.fn(() => true),
+  INTERNAL_API_SECRET: 'internal-secret',
+}));
+jest.mock('@/lib/worker-admin/actor-guard', () => ({
+  requireWorkerAdminActor: jest.fn(),
+  WorkerAdminActorError: class WorkerAdminActorError extends Error {
+    constructor(
+      public status: number,
+      public code: string,
+      message: string
+    ) {
+      super(message);
+    }
+  },
+}));
+jest.mock('@/lib/worker-admin/capability-issuer', () => ({
+  AdminCapabilityRequestSchema: jest.requireActual('@/lib/worker-admin/capability-issuer')
+    .AdminCapabilityRequestSchema,
+  WorkerAdminCapabilityIssuanceError: class WorkerAdminCapabilityIssuanceError extends Error {},
+  issueWorkerAdminCapability: jest.fn(),
+}));
+
+import { getUserFromAuth } from '@kilocode/web-shared/lib/user/server';
+import { generateApiToken } from '@kilocode/web-shared/lib/tokens';
+import { isWorkerAdminLegacyClaimIssuanceEnabled } from '@kilocode/web-shared/lib/config.server';
+import { requireWorkerAdminActor, WorkerAdminActorError } from '@/lib/worker-admin/actor-guard';
+import { issueWorkerAdminCapability } from '@/lib/worker-admin/capability-issuer';
+import { POST } from './route';
+
+const user = { id: 'user-1', is_admin: true, api_token_pepper: 'pepper-1' };
+
+function request(body?: unknown): Request {
+  return new Request('https://app.example.test/api/gastown/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: body === undefined ? null : JSON.stringify(body),
+  });
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  jest.mocked(getUserFromAuth).mockResolvedValue({ user, tokenSource: 'session' } as never);
+  jest.mocked(isWorkerAdminLegacyClaimIssuanceEnabled).mockReturnValue(true);
+});
+
+describe('POST /api/gastown/token', () => {
+  it('mints the ordinary identity token with the legacy admin claim by default', async () => {
+    const response = await POST(request());
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ token: 'identity-token' });
+    expect(generateApiToken).toHaveBeenCalledWith(
+      user,
+      expect.objectContaining({ isAdmin: true, gastownAccess: true }),
+      { expiresIn: 3600 }
+    );
+    expect(issueWorkerAdminCapability).not.toHaveBeenCalled();
+  });
+
+  it('stops issuing the legacy admin claim when the flag is off', async () => {
+    jest.mocked(isWorkerAdminLegacyClaimIssuanceEnabled).mockReturnValue(false);
+    await POST(request());
+    expect(generateApiToken).toHaveBeenCalledWith(
+      user,
+      expect.not.objectContaining({ isAdmin: true }),
+      { expiresIn: 3600 }
+    );
+  });
+
+  it('mints a capability only after the interim actor guard passes', async () => {
+    jest
+      .mocked(requireWorkerAdminActor)
+      .mockRejectedValue(
+        new WorkerAdminActorError(403, 'step_up_required', 'Fresh multi-factor step-up is required')
+      );
+    const response = await POST(
+      request({ adminCapability: { target: { kind: 'town', id: 'town-1' } } })
+    );
+    expect(response.status).toBe(403);
+    await expect(response.json()).resolves.toMatchObject({ code: 'step_up_required' });
+    expect(issueWorkerAdminCapability).not.toHaveBeenCalled();
+  });
+
+  it('returns the capability once the guard passes', async () => {
+    jest.mocked(requireWorkerAdminActor).mockResolvedValue({
+      actor: { assurance: { userId: 'user-1' } },
+      sessionBinding: { apiTokenPepper: 'pepper-1', webSessionPepper: null },
+    } as never);
+    jest.mocked(issueWorkerAdminCapability).mockResolvedValue({
+      capability: 'capability-token',
+      capabilityExpiresAt: '2026-01-01T00:05:00.000Z',
+      jti: 'jti-1',
+      actions: ['trpc:gastown.getTown'],
+    });
+    const response = await POST(
+      request({ adminCapability: { target: { kind: 'town', id: 'town-1' } } })
+    );
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({
+      capability: 'capability-token',
+      capabilityExpiresAt: '2026-01-01T00:05:00.000Z',
+    });
+  });
+
+  it('ignores an unrelated JSON body like it did before capabilities', async () => {
+    const response = await POST(request({}));
+    expect(response.status).toBe(200);
+    await expect(response.json()).resolves.toMatchObject({ token: 'identity-token' });
+    expect(requireWorkerAdminActor).not.toHaveBeenCalled();
+  });
+
+  it('rejects a malformed capability request', async () => {
+    const response = await POST(request({ adminCapability: { target: { kind: 'nope' } } }));
+    expect(response.status).toBe(400);
+    expect(requireWorkerAdminActor).not.toHaveBeenCalled();
+  });
+});

apps/web/src/app/api/gastown/token/route.ts

@@ -8,6 +8,17 @@ import {
   recordKiloAdminElevationForRequest,
   serviceTarget,
 } from '@kilocode/web-shared/lib/admin/admin-access-log';
+import {
+  isWorkerAdminCapabilityIssuanceEnabled,
+  isWorkerAdminLegacyClaimIssuanceEnabled,
+} from '@kilocode/web-shared/lib/config.server';
+import { GASTOWN_ADMIN_AUDIENCE } from '@kilocode/worker-utils/worker-admin-capability';
+import {
+  AdminCapabilityRequestSchema,
+  WorkerAdminCapabilityIssuanceError,
+  issueWorkerAdminCapability,
+} from '@/lib/worker-admin/capability-issuer';
+import { requireWorkerAdminActor, WorkerAdminActorError } from '@/lib/worker-admin/actor-guard';
 
 const ONE_HOUR_SECONDS = 60 * 60;
 
@@ -17,30 +28,36 @@ const ONE_HOUR_SECONDS = 60 * 60;
  * Mints a short-lived (1 hour) Kilo JWT that the browser can use to
  * authenticate directly with the Gastown Cloudflare Worker.
  *
- * The browser authenticates to this endpoint via the NextAuth session cookie
- * (same-origin). The returned token is sent as `Authorization: Bearer <token>`
- * to the worker's tRPC endpoint (cross-origin).
- *
- * Access is controlled by the `gastown-access` PostHog feature flag.
- * The JWT includes `gastownAccess`, `isAdmin`, `apiTokenPepper`, and
- * `orgMemberships` so the worker can enforce access and check org
- * membership without DB round-trips.
+ * With no body, this is the ordinary identity token. A body of
+ * `{ adminCapability: { target, actions? } }` additionally mints a scoped,
+ * short-lived ES256 capability for the exact admin actions on that target.
+ * Capability minting requires a browser session, an admin role, fresh step-up,
+ * and the WORKER_ADMIN_CAPABILITY_ISSUANCE flag.
  */
-export async function POST() {
+export async function POST(request: Request) {
   const { user, authFailedResponse, tokenSource } = await getUserFromAuth({ adminOnly: false });
   if (authFailedResponse) return authFailedResponse;
   if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
 
   const hasAccess = await isGastownEnabled(user.id);
-
   if (!hasAccess) {
     return NextResponse.json({ error: 'Gastown access denied' }, { status: 403 });
   }
 
-  if (user.is_admin) {
-    // The minted token carries `isAdmin`, so the elevation is exercised inside
-    // the Gastown worker where this app emits nothing. Correlate on
-    // `kiloUserId` within the token's lifetime below.
+  const rawBody: unknown = await request.json().catch(() => null);
+  const hasCapabilityRequest =
+    typeof rawBody === 'object' && rawBody !== null && 'adminCapability' in rawBody;
+  const capabilityRequest = hasCapabilityRequest
+    ? AdminCapabilityRequestSchema.safeParse(rawBody)
+    : null;
+  if (capabilityRequest !== null && !capabilityRequest.success) {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const orgMemberships = await getUserOrgMemberships(user.id);
+  const legacyIssuance = isWorkerAdminLegacyClaimIssuanceEnabled();
+
+  if (legacyIssuance && user.is_admin && capabilityRequest === null) {
     await recordKiloAdminElevationForRequest({
       user,
       tokenSource,
@@ -49,14 +66,65 @@ export async function POST() {
     });
   }
 
-  const orgMemberships = await getUserOrgMemberships(user.id);
-
   const token = generateApiToken(
     user,
-    { isAdmin: user.is_admin, gastownAccess: true, orgMemberships },
+    {
+      ...(legacyIssuance && user.is_admin ? { isAdmin: true } : {}),
+      gastownAccess: true,
+      orgMemberships,
+    },
     { expiresIn: ONE_HOUR_SECONDS }
   );
   const expiresAt = new Date(Date.now() + 55 * 60 * 1000).toISOString();
 
-  return NextResponse.json({ token, expiresAt });
+  if (capabilityRequest !== null) {
+    const { target, actions } = capabilityRequest.data.adminCapability;
+    try {
+      const actor = await requireWorkerAdminActor(request, request.headers, {
+        actionClass: 'worker_admin',
+        target: { kind: 'service', id: 'gastown' },
+        inventoryId: 'rest.gastownToken',
+      });
+      const issued = await issueWorkerAdminCapability({
+        user: {
+          ...user,
+          id: actor.actor.assurance.userId,
+          api_token_pepper: actor.sessionBinding.apiTokenPepper,
+        },
+        audience: GASTOWN_ADMIN_AUDIENCE,
+        target,
+        actions,
+        headersList: request.headers,
+      });
+      return NextResponse.json({
+        token,
+        expiresAt,
+        admin: user.is_admin === true,
+        capabilityIssuance: true,
+        capability: issued.capability,
+        capabilityExpiresAt: issued.capabilityExpiresAt,
+      });
+    } catch (error) {
+      if (error instanceof WorkerAdminActorError) {
+        return NextResponse.json(
+          { error: error.message, code: error.code },
+          { status: error.status }
+        );
+      }
+      if (error instanceof WorkerAdminCapabilityIssuanceError) {
+        return NextResponse.json(
+          { error: error.message, code: error.code },
+          { status: error.status }
+        );
+      }
+      throw error;
+    }
+  }
+
+  return NextResponse.json({
+    token,
+    expiresAt,
+    admin: user.is_admin === true,
+    capabilityIssuance: isWorkerAdminCapabilityIssuanceEnabled(),
+  });
 }