migration(rs256): phase 119 — Implement /v1/api-keys + x-api-key middleware (#20)

* migration(rs256): phase 119 — Implement /v1/api-keys + x-api-key middleware

Generated by workflows/119-*.ts via scripts/run-rs256-migration.sh.
Spec: specs/api-keys-and-rs256-migration.md (phase 119).

Co-Authored-By: agent-relay <agent@agent-relay.com>

* phase 119: fix P0 x-api-key middleware coverage + scope escalation

- Mount apiKeyAuth() on /v1/identities/* (wildcard) and /v1/tokens/*
  so PATCH/DELETE/suspend/retire/reactivate accept x-api-key.
- Global auth gate admits x-api-key as an alternate credential when
  the middleware has authenticated the request.
- Enforce scopes ⊆ caller.scopes on POST /v1/api-keys to prevent
  privilege escalation via caller-supplied scope arrays.
- Regression tests for every identity sub-path via x-api-key, plus
  scope-subset enforcement and legitimate-subset cases.

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

* phase 119: tighten global gate — remove raw x-api-key admission

The previous gate admitted any request carrying a non-empty x-api-key
header, relying on per-route handlers to validate. That's a footgun:
a future route added without mounting apiKeyAuth() would silently
accept unvalidated keys.

apiKeyAuth() already rewrites Authorization into a synthesized Bearer
on valid-key success, so every path that accepts x-api-key already
reaches the gate with Authorization set. The gate now only checks for
Authorization — no raw-x-api-key escape hatch.

Regression test: request with only x-api-key to a path that doesn't
mount apiKeyAuth() must return 401 missing_authorization.

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

---------

Co-authored-by: kjgbot <kjgbot@agentrelay.dev>
Co-authored-by: agent-relay <agent@agent-relay.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: 4 people

.rs256-migration-state.json

@@ -2,5 +2,9 @@
   "118": {
     "status": "passed",
     "ts": "2026-04-22T19:10:56Z"
+  },
+  "119": {
+    "status": "passed",
+    "ts": "2026-04-22T19:34:50Z"
   }
 }

.trajectories/completed/2026-04/traj_dmmcvsc1kghh.json

@@ -0,0 +1,64 @@
+# Trajectory: 119-api-keys-phase1-workflow
+
+> **Status:** ✅ Completed
+> **Task:** abcd27407ffe3de58d0b1498
+> **Confidence:** 87%
+> **Started:** April 22, 2026 at 09:11 PM
+> **Completed:** April 22, 2026 at 09:33 PM
+
+---
+
+## Summary
+
+Self-reviewed the API-key auth changes, fixed cross-org API key minting in POST /v1/api-keys, and verified the focused API-key/identity auth tests pass.
+
+**Approach:** Standard approach
+
+---
+
+## Key Decisions
+
+### Treat caller-supplied cross-org API key creation as a P0 and lock key creation to the caller's org
+- **Chose:** Treat caller-supplied cross-org API key creation as a P0 and lock key creation to the caller's org
+- **Reasoning:** An org-scoped bearer token can currently mint an API key for a different org, which creates cross-tenant impersonation via synthesized API-key claims.
+
+---
+
+## Chapters
+
+### 1. Planning
+*Agent: orchestrator*
+
+### 2. Execution: read-migration-spec, read-openapi, read-contract-test, read-storage-interfaces, read-existing-auth-lib, read-cloud-storage, read-cloud-migrations
+*Agent: orchestrator*
+
+### 3. Convergence: read-migration-spec + read-openapi + read-contract-test + read-storage-interfaces + read-existing-auth-lib + read-cloud-storage + read-cloud-migrations
+*Agent: orchestrator*
+
+- read-migration-spec + read-openapi + read-contract-test + read-storage-interfaces + read-existing-auth-lib + read-cloud-storage + read-cloud-migrations resolved. 7/7 steps completed. All steps completed on first attempt. Unblocking: write-relayauth-tests, implement-cloud-adapter.
+
+### 4. Execution: write-relayauth-tests
+*Agent: relayauth-impl*
+
+### 5. Execution: implement-relayauth, implement-cloud-adapter
+*Agent: orchestrator*
+
+### 6. Execution: implement-relayauth
+*Agent: relayauth-impl*
+
+### 7. Execution: implement-cloud-adapter
+*Agent: cloud-impl*
+
+### 8. Convergence: implement-relayauth + implement-cloud-adapter
+*Agent: orchestrator*
+
+- implement-relayauth + implement-cloud-adapter resolved. 2/2 steps completed. All steps completed on first attempt. Unblocking: verify-impl-files.
+
+### 9. Execution: wire-bearer-or-apikey
+*Agent: relayauth-impl*
+
+### 10. Execution: self-review
+*Agent: relayauth-impl*
+
+- Treat caller-supplied cross-org API key creation as a P0 and lock key creation to the caller's org: Treat caller-supplied cross-org API key creation as a P0 and lock key creation to the caller's org
+- Completed self-review pass on the API-key path, fixed the cross-org key minting blocker, and am validating the remaining invariants against tests and schema.

.trajectories/completed/2026-04/traj_dmmcvsc1kghh.md

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "lastUpdated": "2026-04-22T19:10:55.642Z",
+  "lastUpdated": "2026-04-22T19:34:48.598Z",
   "trajectories": {
     "traj_a11zh8l3gbp5": {
       "title": "Work on the relay: combine relayauth + relayfile for agent sandboxing",
@@ -917,6 +917,12 @@
       "status": "active",
       "startedAt": "2026-04-22T18:51:39.263Z",
       "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayauth/.trajectories/active/traj_x2ejukwirx73.json"
+    },
+    "traj_dmmcvsc1kghh": {
+      "title": "119-api-keys-phase1-workflow",
+      "status": "active",
+      "startedAt": "2026-04-22T19:11:05.487Z",
+      "path": "/Users/khaliqgant/Projects/AgentWorkforce/relayauth/.trajectories/active/traj_dmmcvsc1kghh.json"
     }
   }
 }

.trajectories/index.json

@@ -0,0 +1,276 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { AgentIdentity } from "@relayauth/types";
+import {
+  assertJsonResponse,
+  createTestApp,
+  createTestRequest,
+  generateTestToken,
+} from "./test-helpers.js";
+
+type ApiKeyRecord = {
+  id: string;
+  orgId?: string;
+  prefix: string;
+  name: string;
+  scopes: string[];
+  createdAt?: string;
+  revoked?: boolean;
+  revokedAt?: string;
+};
+
+type ApiKeyCreateResponse = {
+  apiKey: ApiKeyRecord;
+  key: string;
+};
+
+type PaginatedApiKeyResponse = {
+  data: ApiKeyRecord[];
+  pagination?: {
+    cursor?: string | null;
+    hasMore: boolean;
+    limit?: number;
+  };
+};
+
+function createAdminAuthorizationHeader(): HeadersInit {
+  return {
+    Authorization: `Bearer ${generateTestToken({
+      sub: "agent_admin_api_keys",
+      org: "org_test",
+      wks: "ws_admin",
+      sponsorId: "user_admin_api_keys",
+      sponsorChain: ["user_admin_api_keys", "agent_admin_api_keys"],
+      scopes: ["*"],
+    })}`,
+  };
+}
+
+async function createApiKey(
+  app: ReturnType<typeof createTestApp>,
+  body: {
+    name: string;
+    scopes: string[];
+    orgId?: string;
+  },
+): Promise<ApiKeyCreateResponse> {
+  const response = await app.request(
+    createTestRequest("POST", "/v1/api-keys", body, createAdminAuthorizationHeader()),
+    undefined,
+    app.bindings,
+  );
+
+  assert.equal(response.status, 201, "POST /v1/api-keys should create an API key");
+  return assertJsonResponse<ApiKeyCreateResponse>(response, 201);
+}
+
+async function createIdentityWithApiKey(
+  app: ReturnType<typeof createTestApp>,
+  apiKey: string,
+  body: Record<string, unknown>,
+): Promise<Response> {
+  return app.request(
+    createTestRequest("POST", "/v1/identities", body, {
+      "x-api-key": apiKey,
+    }),
+    undefined,
+    app.bindings,
+  );
+}
+
+test("POST /v1/api-keys returns 201 with { apiKey, key } and a rak_ plaintext key", async () => {
+  const app = createTestApp();
+
+  const body = await createApiKey(app, {
+    name: "sage-specialist-caller",
+    scopes: ["relayauth:identity:manage:*", "relayauth:token:create:*"],
+  });
+
+  assert.equal(body.apiKey.name, "sage-specialist-caller");
+  assert.deepEqual(body.apiKey.scopes, ["relayauth:identity:manage:*", "relayauth:token:create:*"]);
+  assert.match(body.apiKey.id, /^ak_[A-Za-z0-9_-]+$/);
+  assert.match(body.apiKey.prefix, /^rak_[A-Za-z0-9_-]{4,}/);
+  assert.match(body.key, /^rak_[A-Za-z0-9_-]+$/);
+  assert.ok(body.key.startsWith(body.apiKey.prefix), "returned plaintext should share the stored prefix");
+});
+
+test("POST /v1/api-keys rejects cross-org creation requests", async () => {
+  const app = createTestApp();
+
+  const response = await app.request(
+    createTestRequest(
+      "POST",
+      "/v1/api-keys",
+      {
+        name: "cross-org-should-fail",
+        orgId: "org_other",
+        scopes: ["relayauth:identity:manage:*"],
+      },
+      createAdminAuthorizationHeader(),
+    ),
+    undefined,
+    app.bindings,
+  );
+
+  const body = await assertJsonResponse<{ error: string; code?: string }>(response, 403);
+  assert.equal(body.error, "org_mismatch");
+  assert.equal(body.code, "org_mismatch");
+});
+
+test("an API key returned from POST /v1/api-keys authenticates POST /v1/identities via x-api-key", async () => {
+  const app = createTestApp();
+  const created = await createApiKey(app, {
+    name: "identity-bootstrap",
+    scopes: ["relayauth:identity:manage:*"],
+  });
+
+  const response = await createIdentityWithApiKey(app, created.key, {
+    name: "service-created-via-api-key",
+    sponsorId: "svc_sponsor_1",
+    type: "service",
+    metadata: {
+      provisioner: "api-key-test",
+    },
+  });
+
+  const body = await assertJsonResponse<AgentIdentity>(response, 201);
+
+  assert.equal(body.name, "service-created-via-api-key");
+  assert.equal(body.type, "service");
+  assert.equal(body.orgId, "org_test");
+});
+
+test("a revoked API key returns 401 on subsequent POST /v1/identities requests", async () => {
+  const app = createTestApp();
+  const created = await createApiKey(app, {
+    name: "revoked-key",
+    scopes: ["relayauth:identity:manage:*"],
+  });
+
+  const revokeResponse = await app.request(
+    createTestRequest(
+      "POST",
+      `/v1/api-keys/${created.apiKey.id}/revoke`,
+      {},
+      createAdminAuthorizationHeader(),
+    ),
+    undefined,
+    app.bindings,
+  );
+  const revoked = await assertJsonResponse<ApiKeyRecord>(revokeResponse, 200);
+  assert.equal(revoked.id, created.apiKey.id);
+
+  const response = await createIdentityWithApiKey(app, created.key, {
+    name: "should-not-create-after-revoke",
+    sponsorId: "svc_sponsor_revoked",
+  });
+
+  const body = await assertJsonResponse<{ error: string; code?: string }>(response, 401);
+  assert.match(body.error, /api key|revoked|invalid/i);
+  assert.notEqual(body.code, "missing_authorization");
+});
+
+function createNarrowCallerAuthHeader(scopes: string[]): HeadersInit {
+  return {
+    Authorization: `Bearer ${generateTestToken({
+      sub: "agent_narrow_caller",
+      org: "org_test",
+      wks: "ws_narrow",
+      sponsorId: "user_narrow_caller",
+      sponsorChain: ["user_narrow_caller", "agent_narrow_caller"],
+      scopes,
+    })}`,
+  };
+}
+
+test("POST /v1/api-keys rejects scope escalation: manage-only caller cannot mint scopes=['*']", async () => {
+  const app = createTestApp();
+
+  const response = await app.request(
+    createTestRequest(
+      "POST",
+      "/v1/api-keys",
+      {
+        name: "escalation-attempt-star",
+        scopes: ["*"],
+      },
+      createNarrowCallerAuthHeader(["relayauth:api-key:manage:*"]),
+    ),
+    undefined,
+    app.bindings,
+  );
+
+  const body = await assertJsonResponse<{ error: string; code?: string }>(response, 403);
+  assert.equal(body.code, "scope_escalation");
+});
+
+test("POST /v1/api-keys rejects partial scope escalation: narrow caller cannot widen via wildcard", async () => {
+  const app = createTestApp();
+
+  // Caller has read access to a SPECIFIC identity path — cannot mint a wildcard read.
+  const response = await app.request(
+    createTestRequest(
+      "POST",
+      "/v1/api-keys",
+      {
+        name: "escalation-attempt-partial",
+        scopes: ["relayauth:identity:read:*"],
+      },
+      createNarrowCallerAuthHeader([
+        "relayauth:api-key:manage:*",
+        "relayauth:identity:read:specific-id",
+      ]),
+    ),
+    undefined,
+    app.bindings,
+  );
+
+  const body = await assertJsonResponse<{ error: string; code?: string }>(response, 403);
+  assert.equal(body.code, "scope_escalation");
+});
+
+test("POST /v1/api-keys allows legitimate subset: wildcard-grant caller CAN mint a narrower scope", async () => {
+  const app = createTestApp();
+
+  const response = await app.request(
+    createTestRequest(
+      "POST",
+      "/v1/api-keys",
+      {
+        name: "legit-subset",
+        scopes: ["relayauth:identity:read:specific-id"],
+      },
+      createNarrowCallerAuthHeader([
+        "relayauth:api-key:manage:*",
+        "relayauth:identity:read:*",
+      ]),
+    ),
+    undefined,
+    app.bindings,
+  );
+
+  const body = await assertJsonResponse<ApiKeyCreateResponse>(response, 201);
+  assert.deepEqual(body.apiKey.scopes, ["relayauth:identity:read:specific-id"]);
+});
+
+test("GET /v1/api-keys never returns the plaintext key and only exposes the prefix", async () => {
+  const app = createTestApp();
+  const created = await createApiKey(app, {
+    name: "list-visible-prefix-only",
+    scopes: ["relayauth:identity:manage:*"],
+  });
+
+  const response = await app.request(
+    createTestRequest("GET", "/v1/api-keys", undefined, createAdminAuthorizationHeader()),
+    undefined,
+    app.bindings,
+  );
+  const body = await assertJsonResponse<PaginatedApiKeyResponse>(response, 200);
+
+  assert.ok(Array.isArray(body.data));
+  const listed = body.data.find((apiKey) => apiKey.id === created.apiKey.id);
+  assert.ok(listed, "expected created API key to appear in the list response");
+  assert.equal(listed?.prefix, created.apiKey.prefix);
+  assert.equal("key" in (listed ?? {}), false, "list response must not expose plaintext keys");
+  assert.doesNotMatch(JSON.stringify(body), new RegExp(created.key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+});