@openparachute/hub 0.5.2 → 0.5.9-rc.6

package/src/__tests__/oauth-handlers.test.ts

@@ -3,13 +3,14 @@ import { createHash, randomBytes } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { registerClient } from "../clients.ts";
+import { getClient, registerClient } from "../clients.ts";
 import { CSRF_COOKIE_NAME } from "../csrf.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
-import { validateAccessToken } from "../jwt-sign.ts";
+import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
 import {
   authorizationServerMetadata,
   buildServicesCatalog,
+  handleApproveClientPost,
   handleAuthorizeGet,
   handleAuthorizePost,
   handleRegister,
@@ -1033,10 +1034,37 @@ describe("handleToken — full OAuth dance", () => {
 
       // closes #81 — services catalog tells the client where vault lives so
       // notes doesn't have to re-probe /.well-known/parachute.json. A
-      // vault:read token only sees the vault entry.
+      // `vault:default:read` token sees both the collapsed `vault` key
+      // (backwards compat) AND the per-vault `vault:default` key (closes
+      // #247 — pre-#247 only the collapsed key was emitted; consumers on
+      // multi-vault hubs were forced to assume `/vault/default` and
+      // collided).
       expect(tokenBody.services).toEqual({
         vault: { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.3.0" },
       });
+
+      // closes #215 reviewer F2 — Phase 1 code-grant access-token registry
+      // exemption pinning. The access token and refresh token share `jti`
+      // by design (signRefreshToken({ jti: access.jti, ... }) at the mint
+      // site), so the `tokens` row keyed by the access-token jti IS the
+      // shared row — refresh_token_hash is non-null, created_via is
+      // 'oauth_refresh'. We deliberately don't write a separate per-jti
+      // access-token row; revocation acts on the shared jti / family,
+      // bounded by the 15-min access TTL.
+      expect(payload.jti).toBeTruthy();
+      const row = findTokenRowByJti(db, payload.jti as string);
+      expect(row).not.toBeNull();
+      expect(row?.createdVia).toBe("oauth_refresh");
+      expect(row?.familyId).toBeTruthy();
+      // Verify the registry has exactly one row for this code-grant
+      // (not two — no separate access-token row).
+      const rowCount = (
+        db
+          .query<{ n: number }, [string]>("SELECT COUNT(*) as n FROM tokens WHERE jti = ?")
+          .get(payload.jti as string) ?? { n: 0 }
+      ).n;
+      expect(rowCount).toBe(1);
     } finally {
       cleanup();
     }
@@ -1522,6 +1550,156 @@ describe("handleToken — full OAuth dance", () => {
       vault: { url: `${ISSUER}/vault/work`, version: "0.3.0" },
     });
   });
+
+  // closes #247 — multi-vault correctness. Pre-#247 every vault collapsed
+  // under the single `vault` key, so Notes' OAuthCallback always wrote
+  // VaultRecord URL = paths[0] of the first vault row regardless of which
+  // vault the token actually granted. Per-vault `vault:<name>` keys let
+  // consumers route each grant to the correct vault URL.
+  describe("services catalog — multi-vault per-vault keys (#247)", () => {
+    // Real shape from a multi-vault hub: one `parachute-vault` row with N
+    // paths, each path naming an instance. Aaron's setup verbatim (4
+    // vaults: default, boulder, gitcoin, techne).
+    const multiVaultManifest: ServicesManifest = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default", "/vault/boulder", "/vault/gitcoin", "/vault/techne"],
+          health: "/health",
+          version: "0.4.4",
+        },
+      ],
+    };
+
+    test("single-vault hub with broad scope: only collapsed `vault` key (unchanged)", () => {
+      // Per-vault keys are noise on single-vault hubs — no disambiguation
+      // is needed. Backwards compat for pre-popover clients matters here.
+      expect(buildServicesCatalog(FIXTURE_MANIFEST, ISSUER, ["vault:read"])).toEqual({
+        vault: { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+      });
+    });
+
+    test("single-vault hub with per-vault-narrowed scope: emits per-vault key too", () => {
+      // A `vault:default:read` token is an explicit consumer signal that
+      // the per-vault key matters — emit it even on a single-vault hub so
+      // the consumer's `services["vault:default"]` lookup works uniformly
+      // regardless of how many vaults the hub has.
+      expect(buildServicesCatalog(FIXTURE_MANIFEST, ISSUER, ["vault:default:read"])).toEqual({
+        vault: { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+      });
+    });
+
+    test("multi-vault hub with broad scope: emits every per-vault key + collapsed `vault`", () => {
+      // Broad `vault:read` admits every vault on the hub. Per-#247
+      // guidance: emit per-vault keys for all admitted vaults so the
+      // consumer (Notes popover) can pick its target by name without
+      // re-probing /.well-known/parachute.json.
+      expect(buildServicesCatalog(multiVaultManifest, ISSUER, ["vault:read"])).toEqual({
+        // Collapsed key still emitted (first admitted path); backwards compat.
+        vault: { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:boulder": { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+        "vault:gitcoin": { url: `${ISSUER}/vault/gitcoin`, version: "0.4.4" },
+        "vault:techne": { url: `${ISSUER}/vault/techne`, version: "0.4.4" },
+      });
+    });
+
+    test("multi-vault hub with per-vault scope: only that vault's per-vault key", () => {
+      // Aaron's "Connect boulder" flow: token has `vault:boulder:write`,
+      // scope admits only boulder. Pre-#247 the catalog said `vault.url =
+      // /vault/default` (WRONG), so Notes stored a /vault/default record
+      // with scope `vault:boulder:write` — collision city as more vaults
+      // got connected. Post-#247 the consumer reads
+      // `services["vault:boulder"].url` which correctly says /vault/boulder.
+      expect(buildServicesCatalog(multiVaultManifest, ISSUER, ["vault:boulder:write"])).toEqual({
+        // Collapsed `vault` points at boulder too — the only admitted
+        // vault — so legacy consumers happen to land on the right URL even
+        // though they have no per-vault awareness.
+        vault: { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+        "vault:boulder": { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+      });
+    });
+
+    test("multi-vault hub with mixed scopes: per-vault keys for each narrowed vault", () => {
+      // A token granting both `vault:boulder:read` and `vault:gitcoin:write`
+      // admits exactly those two vaults; default and techne aren't reachable.
+      expect(
+        buildServicesCatalog(multiVaultManifest, ISSUER, [
+          "vault:boulder:read",
+          "vault:gitcoin:write",
+        ]),
+      ).toEqual({
+        vault: { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+        "vault:boulder": { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+        "vault:gitcoin": { url: `${ISSUER}/vault/gitcoin`, version: "0.4.4" },
+      });
+    });
+
+    test("multi-vault hub: broad + per-vault scopes coexist; broad opens all vaults", () => {
+      // A token that carries BOTH `vault:read` (broad) AND
+      // `vault:boulder:write` (narrow) should land in the broad bucket
+      // because the broad scope is more permissive — narrowing one verb
+      // can't take away access the unnamed scope already granted.
+      expect(
+        buildServicesCatalog(multiVaultManifest, ISSUER, ["vault:read", "vault:boulder:write"]),
+      ).toEqual({
+        vault: { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:boulder": { url: `${ISSUER}/vault/boulder`, version: "0.4.4" },
+        "vault:gitcoin": { url: `${ISSUER}/vault/gitcoin`, version: "0.4.4" },
+        "vault:techne": { url: `${ISSUER}/vault/techne`, version: "0.4.4" },
+      });
+    });
+
+    test("legacy per-vault rows (parachute-vault-<name>) also produce per-vault keys", () => {
+      // Older multi-vault layout — one row per vault — should produce the
+      // same catalog shape as the single-row-multi-path layout. The
+      // `vaultInstanceNameFor` helper handles both via its
+      // manifest-suffix fallback.
+      const legacyManifest: ServicesManifest = {
+        services: [
+          {
+            name: "parachute-vault",
+            port: 1940,
+            paths: ["/vault/default"],
+            health: "/health",
+            version: "0.4.4",
+          },
+          {
+            name: "parachute-vault-work",
+            port: 1941,
+            paths: ["/vault/work"],
+            health: "/health",
+            version: "0.4.4",
+          },
+        ],
+      };
+      expect(buildServicesCatalog(legacyManifest, ISSUER, ["vault:read"])).toEqual({
+        vault: { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.4.4" },
+        "vault:work": { url: `${ISSUER}/vault/work`, version: "0.4.4" },
+      });
+    });
+
+    test("non-vault services unaffected — only one key per service, no per-instance variant", () => {
+      // The per-vault-key expansion is vault-specific. scribe / notes /
+      // third-party rows still emit one key per service.
+      expect(
+        buildServicesCatalog(FIXTURE_MANIFEST, ISSUER, [
+          "vault:default:read",
+          "scribe:transcribe",
+          "notes:read",
+        ]),
+      ).toEqual({
+        vault: { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+        "vault:default": { url: `${ISSUER}/vault/default`, version: "0.3.0" },
+        scribe: { url: `${ISSUER}/scribe`, version: "0.3.0-rc.1" },
+        notes: { url: `${ISSUER}/notes`, version: "0.3.0" },
+      });
+    });
+  });
 });
 
 // closes #72 — RFC 6749 §3.2.1 + §2.3.1: confidential clients must
@@ -2053,6 +2231,76 @@ describe("DCR approval gate (#74)", () => {
       const html = await res.text();
       expect(html).toContain("App not yet approved");
       expect(html).toContain("approve-client");
+      // No vault hint → no vault row in approve-meta. Single-vault hubs +
+      // pre-vault-popover clients leave the section omitted (#244).
+      expect(html).not.toContain('approve-meta-label">vault');
+    } finally {
+      cleanup();
+    }
+  });
+
+  // closes #244 — vault hint surfaced in approve-pending UI. Notes#115
+  // passes `vault=<name>` on `/oauth/authorize` for per-vault grants; hub's
+  // approve page now displays it alongside the other client metadata so a
+  // multi-vault operator can tell which vault they're approving for.
+  test("authorize: pending client with vault hint → approve UI renders 'vault: <name>'", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+          vault: "boulder",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).toContain("App not yet approved");
+      // The vault hint surfaces as a labeled row in the approve-meta block.
+      expect(html).toContain('approve-meta-label">vault');
+      expect(html).toContain("boulder");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("authorize: pending client with empty vault param → no vault row", async () => {
+    // Defensive: `vault=` with empty value normalizes to undefined so the
+    // UI doesn't render a blank vault label. Easy to hit if a client builds
+    // the URL via URLSearchParams.set("vault", someMaybeEmptyVar).
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: reg.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:read",
+          vault: "",
+        }),
+      );
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).toContain("App not yet approved");
+      expect(html).not.toContain('approve-meta-label">vault');
     } finally {
       cleanup();
     }
@@ -2102,6 +2350,13 @@ describe("DCR approval gate (#74)", () => {
       const body = (await res.json()) as Record<string, unknown>;
       expect(body.error).toBe("invalid_client");
       expect(body.error_description).toContain("not been approved");
+      // Surface the inline-approval affordances so consumers (Notes, future
+      // cross-origin SPAs) can deep-link the operator to a browser-based
+      // approve flow without dropping to a terminal.
+      expect(body.approve_url).toBe(
+        `${ISSUER}/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
+      );
+      expect(body.cli_alternative).toBe(`parachute auth approve-client ${reg.client.clientId}`);
     } finally {
       cleanup();
     }
@@ -2131,6 +2386,13 @@ describe("DCR approval gate (#74)", () => {
       expect(res.status).toBe(401);
       const body = (await res.json()) as Record<string, unknown>;
       expect(body.error).toBe("invalid_client");
+      // Same pending-affordance shape on the refresh path: a long-lived
+      // OAuth client whose row was unapproved between issuance and refresh
+      // hits this branch and surfaces the same approve_url + cli_alternative.
+      expect(body.approve_url).toBe(
+        `${ISSUER}/admin/approve-client/${encodeURIComponent(reg.client.clientId)}`,
+      );
+      expect(body.cli_alternative).toBe(`parachute auth approve-client ${reg.client.clientId}`);
     } finally {
       cleanup();
     }
@@ -2244,6 +2506,226 @@ describe("DCR approval gate (#74)", () => {
   });
 });
 
+// closes #199 — DCR auto-approve for the operator's own browser. A valid
+// `parachute_hub_session` cookie indicates the operator is authenticated as
+// themselves; combined with a same-origin Origin/Referer (the CSRF gate)
+// that's enough to skip the manual `parachute auth approve-client` step.
+describe("DCR auto-approve via session cookie (#199)", () => {
+  const SESSION_COOKIE_TTL_S = Math.floor(SESSION_TTL_MS / 1000);
+
+  function registerRequest(
+    headers: Record<string, string>,
+    bodyExtra: Record<string, unknown> = {},
+  ): Request {
+    return new Request(`${ISSUER}/oauth/register`, {
+      method: "POST",
+      body: JSON.stringify({
+        redirect_uris: ["https://app.example/cb"],
+        ...bodyExtra,
+      }),
+      headers: { "content-type": "application/json", ...headers },
+    });
+  }
+
+  test("valid session cookie + matching Origin → status approved (response + DB)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: ISSUER,
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+      // Persisted, not just response-shaped.
+      const row = getClient(db, body.client_id as string);
+      expect(row?.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid session cookie + cross-origin Origin → status pending (CSRF defense)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: "https://attacker.example",
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid session cookie + Origin: 'null' (opaque/sandbox iframe) → pending", async () => {
+    // Sandbox iframes (`<iframe sandbox>` without `allow-same-origin`),
+    // `data:`/`file:` documents, and some privacy contexts send the literal
+    // string `Origin: null` rather than omitting the header. `new URL("null")`
+    // throws → isSameOriginRequest's try/catch returns false → DCR stays
+    // pending. This test pins that invariant: an opaque-origin caller does
+    // NOT ride the cookie path even with a valid session, because we can't
+    // prove the request came from the issuer's own origin.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: "null",
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+      // Persisted, not just response-shaped.
+      const row = getClient(db, body.client_id as string);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid session cookie + Origin matching exact origin (port included) → approved", async () => {
+    // URL.origin includes scheme + host + port, so a port-mismatched Origin
+    // must NOT match. https://hub.example:8443 ≠ https://hub.example.
+    const { db, cleanup } = await makeDb();
+    try {
+      const issuer = "https://hub.example:8443";
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+
+      // Exact match (scheme + host + port) → approved.
+      const okReq = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: "https://hub.example:8443",
+      });
+      const okRes = await handleRegister(db, okReq, { issuer });
+      expect(((await okRes.json()) as Record<string, unknown>).status).toBe("approved");
+
+      // Port-mismatched Origin (default 443 vs 8443) → pending.
+      const badReq = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: "https://hub.example",
+      });
+      const badRes = await handleRegister(db, badReq, { issuer });
+      expect(((await badRes.json()) as Record<string, unknown>).status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid session cookie + matching Referer (no Origin) → approved (Referer fallback)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        referer: `${ISSUER}/notes/`,
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("valid session cookie + no Origin AND no Referer → pending (deny without proof of origin)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("expired session cookie + matching Origin → pending (expiry check)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      // Session created in the "now()" frame, but handleRegister sees a much
+      // later clock — findSession (via findActiveSession) treats it as expired.
+      const session = createSession(db, { userId: user.id });
+      const future = new Date(Date.now() + SESSION_TTL_MS + 60_000);
+      const req = registerRequest({
+        cookie: buildSessionCookie(session.id, SESSION_COOKIE_TTL_S),
+        origin: ISSUER,
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER, now: () => future });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("invalid session cookie (id not in DB) + matching Origin → pending", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const req = registerRequest({
+        cookie: buildSessionCookie("not-a-real-session-id", SESSION_COOKIE_TTL_S),
+        origin: ISSUER,
+      });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no cookie at all → pending (current public-DCR behavior)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const req = registerRequest({ origin: ISSUER });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("operator-bearer header (existing path) still → approved (regression)", async () => {
+    // The new cookie-based path must not regress the bearer-based path that
+    // first-party install (#74) depends on. Same setup as the #74 test, no
+    // cookie supplied — bearer alone must continue to land approved.
+    const { db, cleanup } = await makeDb();
+    try {
+      const { rotateSigningKey } = await import("../signing-keys.ts");
+      const { mintOperatorToken } = await import("../operator-token.ts");
+      rotateSigningKey(db);
+      const user = await createUser(db, "owner", "pw");
+      const operator = await mintOperatorToken(db, user.id, { issuer: ISSUER });
+
+      const req = registerRequest({ authorization: `Bearer ${operator.token}` });
+      const res = await handleRegister(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(201);
+      const body = (await res.json()) as Record<string, unknown>;
+      expect(body.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 // closes #73 — RFC 6749 §6 refresh-token rotation, RFC 6819 §5.2.2.3 replay
 // detection (family-wide revocation), RFC 7009 token revocation.
 describe("refresh-token rotation + /oauth/revoke (#73)", () => {
@@ -3110,3 +3592,518 @@ describe("handleAuthorizeGet — skip consent when scope already granted (#75)",
     }
   });
 });
+
+// closes #208 — inline "Approve this app" form on the pending-client page
+// (cross-origin SPA recovery). Same security model as #199/#200 DCR
+// auto-approve: valid session + matching Origin = trusted operator. The
+// CSRF token is the third belt — a cross-origin POST with a leaked session
+// cookie still fails because the rendered token won't match.
+describe("inline approve button on pending /oauth/authorize (#208)", () => {
+  const SESSION_COOKIE_TTL_S = Math.floor(SESSION_TTL_MS / 1000);
+
+  function pendingAuthorizeUrl(clientId: string): string {
+    const { challenge } = makePkce();
+    return authorizeUrl({
+      client_id: clientId,
+      redirect_uri: "https://app.example/cb",
+      response_type: "code",
+      code_challenge: challenge,
+      code_challenge_method: "S256",
+      scope: "vault:read",
+      state: "rt-208",
+    });
+  }
+
+  test("session absent → page renders WITHOUT approve form (CLI-only fallback)", async () => {
+    // Regression: pre-#208 behavior preserved when no session cookie is
+    // present. The CLI-fallback message must still be visible so an operator
+    // who arrived from a fresh browser knows what to do.
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+        status: "pending",
+      });
+      const req = new Request(pendingAuthorizeUrl(reg.client.clientId));
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).toContain("App not yet approved");
+      // CLI-fallback message present — the only way to recover without a session.
+      expect(html).toContain("approve-client");
+      // No form element pointing at the approve endpoint.
+      expect(html).not.toContain('action="/oauth/authorize/approve"');
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("session valid + matching Origin → page renders WITH approve form + CSRF token", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "MyApp",
+        status: "pending",
+      });
+      const req = new Request(pendingAuthorizeUrl(reg.client.clientId), {
+        headers: {
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = handleAuthorizeGet(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      const html = await res.text();
+      expect(html).toContain("App not yet approved");
+      // The form posts to the approve endpoint
+      expect(html).toContain('action="/oauth/authorize/approve"');
+      expect(html).toContain('name="client_id"');
+      expect(html).toContain(`value="${reg.client.clientId}"`);
+      // CSRF token present in the form
+      expect(html).toContain(`value="${TEST_CSRF}"`);
+      // return_to carries the original authorize URL so the post-approve
+      // redirect lands the operator back on the same flow.
+      expect(html).toContain('name="return_to"');
+      expect(html).toContain("/oauth/authorize?");
+      expect(html).toContain("rt-208"); // state echoed via return_to URL
+      // Display fields present so operator can verify what they're approving.
+      expect(html).toContain("MyApp");
+      expect(html).toContain(reg.client.clientId);
+      expect(html).toContain("https://app.example/cb");
+      // CLI fallback still visible.
+      expect(html).toContain("approve-client");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST happy path: CSRF + session + matching Origin → DB flips approved + 302 to authorize URL", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const returnTo = `/oauth/authorize?client_id=${reg.client.clientId}&state=rt-208`;
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: returnTo,
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(302);
+      expect(res.headers.get("location")).toBe(returnTo);
+      // DB row flipped, not just response-shaped.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: invalid CSRF → 403", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: "wrong-token",
+        client_id: reg.client.clientId,
+        return_to: `/oauth/authorize?client_id=${reg.client.clientId}`,
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      // Row stays pending.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: no session cookie → 401", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: `/oauth/authorize?client_id=${reg.client.clientId}`,
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: CSRF_COOKIE,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(401);
+      // Row stays pending.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: cross-origin Origin → 403 (CSRF defense)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: `/oauth/authorize?client_id=${reg.client.clientId}`,
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: "https://attacker.example",
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      // Row stays pending.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: Origin: 'null' (sandbox iframe / opaque origin) → 403", async () => {
+    // Opaque-origin contexts (sandboxed iframes, some `data:` and `file:`
+    // pages) send the literal string "null" as the Origin header. The DCR
+    // /register path covers this; the inline-approve endpoint must reject it
+    // too. isSameOriginRequest() handles this correctly because new URL("null")
+    // throws → returns false; this test pins that contract.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: `/oauth/authorize?client_id=${reg.client.clientId}`,
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: "null",
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(403);
+      // Row stays pending.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: idempotent on already-approved client (double-click / refresh)", async () => {
+    // approveClient() short-circuits if the row is already approved
+    // (clients.ts:153). A double-click or page refresh should not error —
+    // the second POST also succeeds with a 302 to return_to and the row
+    // stays approved. This pins idempotency end-to-end.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const returnTo = `/oauth/authorize?client_id=${reg.client.clientId}&state=rt-208`;
+      const buildReq = () => {
+        const form = new URLSearchParams({
+          __csrf: TEST_CSRF,
+          client_id: reg.client.clientId,
+          return_to: returnTo,
+        });
+        return new Request(`${ISSUER}/oauth/authorize/approve`, {
+          method: "POST",
+          body: form,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+            origin: ISSUER,
+          },
+        });
+      };
+
+      // First POST: pending → approved.
+      const first = await handleApproveClientPost(db, buildReq(), { issuer: ISSUER });
+      expect(first.status).toBe(302);
+      expect(first.headers.get("location")).toBe(returnTo);
+      expect(getClient(db, reg.client.clientId)?.status).toBe("approved");
+
+      // Second POST (same client_id, same form): also succeeds, no error.
+      const second = await handleApproveClientPost(db, buildReq(), { issuer: ISSUER });
+      expect(second.status).toBe(302);
+      expect(second.headers.get("location")).toBe(returnTo);
+      expect(getClient(db, reg.client.clientId)?.status).toBe("approved");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: unknown client_id → 404", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: "no-such-client-id",
+        return_to: "/oauth/authorize?client_id=no-such-client-id",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(404);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: malicious return_to (absolute URL) → 400 (open-redirect defense)", async () => {
+    // The form must always supply a hub-relative /oauth/authorize?... URL.
+    // Anything else is either an open-redirect attempt or a misuse — refuse
+    // to follow it. return_to is validated BEFORE the DB mutation, so a bad
+    // value also leaves the client row at status=pending.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: "https://evil.example/steal",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      // No redirect to evil.example.
+      expect(res.headers.get("location")).toBeNull();
+      // DB row remains pending — validate-before-mutate ordering.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: scheme-relative return_to (//evil.example) → 400", async () => {
+    // `//evil.example/foo` is a scheme-relative URL — browsers resolve it
+    // against the current scheme to land at https://evil.example/foo.
+    // Reject anything that doesn't start with a single `/`.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: "//evil.example/foo",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      // DB row remains pending — validate-before-mutate ordering.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("approve POST: return_to off /oauth/authorize path (e.g. /admin/config) → 400", async () => {
+    // Even hub-relative paths must target the authorize endpoint. A
+    // hand-crafted form trying to redirect to /admin/config or any other
+    // hub surface is misuse — this endpoint exists to re-enter the OAuth
+    // flow, nothing else.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const form = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: "/admin/config",
+      });
+      const req = new Request(`${ISSUER}/oauth/authorize/approve`, {
+        method: "POST",
+        body: form,
+        headers: {
+          "content-type": "application/x-www-form-urlencoded",
+          cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`,
+          origin: ISSUER,
+        },
+      });
+      const res = await handleApproveClientPost(db, req, { issuer: ISSUER });
+      expect(res.status).toBe(400);
+      // DB row remains pending — validate-before-mutate ordering.
+      const row = getClient(db, reg.client.clientId);
+      expect(row?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("end-to-end: GET (pending) → POST approve → GET (now approved) renders consent", async () => {
+    // The full redirect chain. Sessions and CSRF carry across all three
+    // requests in the same cookie. The final GET sees status=approved and
+    // renders the consent screen.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const reg = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "RoundTrip",
+        status: "pending",
+      });
+      const cookie = `${CSRF_COOKIE}; ${buildSessionCookie(session.id, SESSION_COOKIE_TTL_S)}`;
+      const authorizeHref = pendingAuthorizeUrl(reg.client.clientId);
+
+      // Step 1: GET /oauth/authorize on a pending client renders the approve form.
+      const getRes = handleAuthorizeGet(
+        db,
+        new Request(authorizeHref, { headers: { cookie, origin: ISSUER } }),
+        { issuer: ISSUER },
+      );
+      expect(getRes.status).toBe(403);
+      const getHtml = await getRes.text();
+      expect(getHtml).toContain('action="/oauth/authorize/approve"');
+
+      // Pull the return_to value the form would submit. It's the path+search
+      // of the authorize URL.
+      const authorizeUrlParsed = new URL(authorizeHref);
+      const returnTo = `${authorizeUrlParsed.pathname}${authorizeUrlParsed.search}`;
+
+      // Step 2: POST the approve form.
+      const postForm = new URLSearchParams({
+        __csrf: TEST_CSRF,
+        client_id: reg.client.clientId,
+        return_to: returnTo,
+      });
+      const postRes = await handleApproveClientPost(
+        db,
+        new Request(`${ISSUER}/oauth/authorize/approve`, {
+          method: "POST",
+          body: postForm,
+          headers: {
+            "content-type": "application/x-www-form-urlencoded",
+            cookie,
+            origin: ISSUER,
+          },
+        }),
+        { issuer: ISSUER },
+      );
+      expect(postRes.status).toBe(302);
+      expect(postRes.headers.get("location")).toBe(returnTo);
+
+      // Step 3: GET /oauth/authorize again — now the client is approved, so
+      // the operator lands on the consent screen.
+      const reentryRes = handleAuthorizeGet(
+        db,
+        new Request(authorizeHref, { headers: { cookie, origin: ISSUER } }),
+        { issuer: ISSUER, loadServicesManifest: fixtureLoadServicesManifest },
+      );
+      expect(reentryRes.status).toBe(200);
+      const consentHtml = await reentryRes.text();
+      // Consent screen markers (renderConsent uses these).
+      expect(consentHtml).toContain('name="__action" value="consent"');
+      expect(consentHtml).toContain("Authorize");
+      expect(consentHtml).toContain("RoundTrip");
+    } finally {
+      cleanup();
+    }
+  });
+});