create-ailk 0.15.0 → 0.17.0

package/templates/apps/api/src/services/__tests__/hub-sign-in.test.ts

@@ -0,0 +1,854 @@
+/**
+ * @file hub-sign-in.test.ts
+ *
+ * The hub signs in its spokes — the service (#7894, spec
+ * docs/specs/7894-the-hub-signs-in-its-spec.md D5; AC-4, AC-5).
+ *
+ * The REAL store and service run against an in-memory stand-in for the Prisma
+ * delegates (`__tests__/support/hub-sign-in-fake-db.ts`), so a code minted by
+ * `createCode` is consumed, exactly once, by `exchange`.
+ *
+ * External dependency boundary mocked:
+ *   - @working-theory/database (via the prisma singleton; __mocks__/prisma.ts)
+ */
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
+jest.mock("../../lib/prisma.js");
+
+import {
+  installHubSignInFakeDb,
+  pkcePair,
+  seedSpoke,
+  seedUser,
+  type FakeHubDb,
+  type SeededSpoke,
+} from "../../__tests__/support/hub-sign-in-fake-db.js";
+import { sha256Hex } from "../../lib/hub-sign-in-store.js";
+import { prisma } from "../../lib/prisma.js";
+import {
+  __resetHubSignInBuckets,
+  CODES_PER_USER,
+  CREDENTIAL_TTL_SECONDS,
+  EXCHANGES_PER_CLIENT,
+  createCode,
+  exchange,
+  readMe,
+  revoke,
+} from "../hub-sign-in.js";
+
+const db = jest.mocked(prisma);
+
+let state: FakeHubDb;
+
+beforeEach(() => {
+  jest.resetAllMocks();
+  state = installHubSignInFakeDb(db);
+  __resetHubSignInBuckets();
+});
+
+/** The codes route's job: mint a code for `userId` against `spoke`. */
+async function mintFor(
+  userId: string,
+  spoke: SeededSpoke,
+  challenge: string,
+  redirectUri = spoke.redirectUri,
+): Promise<string> {
+  const result = await createCode({
+    userId,
+    body: {
+      clientId: spoke.client.clientId,
+      redirectUri,
+      codeChallenge: challenge,
+    },
+  });
+  if (!result.ok) throw new Error(`mint refused: ${result.error.code}`);
+  return result.value.code;
+}
+
+function tokenArgs(
+  spoke: SeededSpoke,
+  body: { code: string; redirectUri?: string; codeVerifier: string },
+  overrides: {
+    authorization?: string | undefined;
+    spokeKey?: string | undefined;
+  } = {},
+) {
+  return {
+    authorization:
+      "authorization" in overrides ? overrides.authorization : spoke.basic,
+    spokeKey: "spokeKey" in overrides ? overrides.spokeKey : spoke.key,
+    body: { redirectUri: spoke.redirectUri, ...body },
+  };
+}
+
+describe("createCode (POST /v1/hub-sign-in/codes)", () => {
+  it("mints a 60 s single-use code bound to the person, client, callback and challenge", async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+    const { challenge } = pkcePair();
+
+    const result = await createCode({
+      userId: user.id,
+      body: {
+        clientId: spoke.client.clientId,
+        redirectUri: spoke.redirectUri,
+        codeChallenge: challenge,
+      },
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.redirectUri).toBe(spoke.redirectUri);
+    expect(result.value.code).toMatch(/^[A-Za-z0-9_-]{43}$/);
+
+    // One Verification row, keyed on the DIGEST of the code, never the code.
+    expect(state.verifications).toHaveLength(1);
+    const row = state.verifications[0];
+    expect(row?.identifier).toBe(
+      `hub-sign-in-code:${sha256Hex(result.value.code)}`,
+    );
+    expect(JSON.stringify(row)).not.toContain(result.value.code);
+    expect(JSON.parse(row?.value ?? "{}")).toEqual({
+      userId: user.id,
+      clientId: spoke.client.clientId,
+      redirectUri: spoke.redirectUri,
+      codeChallenge: challenge,
+    });
+    const ttl = (row?.expiresAt.getTime() ?? 0) - Date.now();
+    expect(ttl).toBeGreaterThan(55_000);
+    expect(ttl).toBeLessThanOrEqual(60_000);
+  });
+
+  it.each([
+    [
+      "an unknown client",
+      (s: SeededSpoke) => ({ clientId: `${s.client.clientId}_x` }),
+    ],
+    ["a client in another shape of id", () => ({ clientId: "" })],
+  ])("refuses %s with 400 and writes no code", async (_name, patch) => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+
+    const result = await createCode({
+      userId: user.id,
+      body: {
+        clientId: spoke.client.clientId,
+        redirectUri: spoke.redirectUri,
+        codeChallenge: pkcePair().challenge,
+        ...patch(spoke),
+      },
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.status).toBe(400);
+    expect(state.verifications).toHaveLength(0);
+  });
+
+  it("refuses a disabled client and a revoked spoke as invalid_client", async () => {
+    const user = seedUser(state);
+    const disabled = seedSpoke(state, "a.example.com");
+    disabled.client.enabled = false;
+    const revoked = seedSpoke(state, "b.example.com");
+    revoked.spoke.revokedAt = new Date();
+
+    for (const spoke of [disabled, revoked]) {
+      const result = await createCode({
+        userId: user.id,
+        body: {
+          clientId: spoke.client.clientId,
+          redirectUri: spoke.redirectUri,
+          codeChallenge: pkcePair().challenge,
+        },
+      });
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_client" },
+      });
+    }
+    expect(state.verifications).toHaveLength(0);
+  });
+
+  it("refuses a redirect URI that is not exactly the registered one — no code is minted", async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+
+    for (const redirectUri of [
+      "https://attacker.example.com/api/hub-session/callback",
+      `${spoke.redirectUri}/`,
+      `${spoke.redirectUri}?x=1`,
+      spoke.redirectUri.replace("https:", "http:"),
+    ]) {
+      const result = await createCode({
+        userId: user.id,
+        body: {
+          clientId: spoke.client.clientId,
+          redirectUri,
+          codeChallenge: pkcePair().challenge,
+        },
+      });
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_redirect_uri" },
+      });
+    }
+    expect(state.verifications).toHaveLength(0);
+  });
+
+  it("refuses a person whose email is not verified (403 email_unverified) and mints nothing", async () => {
+    const user = seedUser(state, { emailVerified: false });
+    const spoke = seedSpoke(state);
+
+    const result = await createCode({
+      userId: user.id,
+      body: {
+        clientId: spoke.client.clientId,
+        redirectUri: spoke.redirectUri,
+        codeChallenge: pkcePair().challenge,
+      },
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { status: 403, code: "email_unverified" },
+    });
+    expect(state.verifications).toHaveLength(0);
+  });
+
+  it("refuses a malformed body (400 invalid_request) — a short challenge, an unknown key", async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+    const base = {
+      clientId: spoke.client.clientId,
+      redirectUri: spoke.redirectUri,
+      codeChallenge: pkcePair().challenge,
+    };
+
+    for (const body of [
+      { ...base, codeChallenge: "short" },
+      { ...base, extra: true },
+      null,
+    ]) {
+      const result = await createCode({ userId: user.id, body });
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_request" },
+      });
+    }
+  });
+
+  it(`answers 429 on the ${CODES_PER_USER + 1}st code in ten minutes for one user`, async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+    const body = {
+      clientId: spoke.client.clientId,
+      redirectUri: spoke.redirectUri,
+      codeChallenge: pkcePair().challenge,
+    };
+
+    for (let i = 0; i < CODES_PER_USER; i += 1) {
+      const result = await createCode({ userId: user.id, body });
+      expect(result.ok).toBe(true);
+    }
+    const over = await createCode({ userId: user.id, body });
+    expect(over).toMatchObject({
+      ok: false,
+      error: { status: 429, code: "rate_limited" },
+    });
+    if (!over.ok) expect(over.error.retryAfter).toBeGreaterThan(0);
+
+    // Another person is not throttled by this one's spend.
+    const other = seedUser(state);
+    expect((await createCode({ userId: other.id, body })).ok).toBe(true);
+  });
+});
+
+describe("exchange (POST /v1/hub-sign-in/token)", () => {
+  it("trades a code + secret + spoke key + verifier for a 24 h credential, stored only as a digest", async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+    const { verifier, challenge } = pkcePair();
+    const code = await mintFor(user.id, spoke, challenge);
+
+    const result = await exchange(
+      tokenArgs(spoke, { code, codeVerifier: verifier }),
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.tokenType).toBe("Bearer");
+    expect(result.value.expiresIn).toBe(CREDENTIAL_TTL_SECONDS);
+    expect(result.value.accessToken).toMatch(/^ailk_hst_[A-Za-z0-9_-]{43}$/);
+    expect(result.value.user).toEqual({
+      id: user.id,
+      name: user.name,
+      email: user.email,
+      emailVerified: true,
+      createdAt: user.createdAt.toISOString(),
+    });
+
+    expect(state.authorizations).toHaveLength(1);
+    const grant = state.authorizations[0];
+    expect(grant?.userId).toBe(user.id);
+    expect(grant?.clientId).toBe(spoke.client.id);
+    expect(grant?.accessToken).toBe(sha256Hex(result.value.accessToken));
+    expect(JSON.stringify(grant)).not.toContain(result.value.accessToken);
+    expect(grant?.revokedAt).toBeNull();
+    // The code is gone, and the route-level contract: no Session row, ever.
+    expect(state.verifications).toHaveLength(0);
+    expect(state.sessionCalls).toEqual([]);
+    expect(db.session.create).not.toHaveBeenCalled();
+  });
+
+  it("AC-4: one person signs in to two spokes — two grants, one userId, different client ids", async () => {
+    const user = seedUser(state);
+    const a = seedSpoke(state, "a.example.com");
+    const b = seedSpoke(state, "b.example.com");
+    const pa = pkcePair();
+    const pb = pkcePair();
+
+    const codeA = await mintFor(user.id, a, pa.challenge);
+    const codeB = await mintFor(user.id, b, pb.challenge);
+    const ra = await exchange(
+      tokenArgs(a, { code: codeA, codeVerifier: pa.verifier }),
+    );
+    const rb = await exchange(
+      tokenArgs(b, { code: codeB, codeVerifier: pb.verifier }),
+    );
+
+    expect(ra.ok && rb.ok).toBe(true);
+    expect(state.authorizations).toHaveLength(2);
+    expect(new Set(state.authorizations.map((g) => g.userId))).toEqual(
+      new Set([user.id]),
+    );
+    expect(new Set(state.authorizations.map((g) => g.clientId)).size).toBe(2);
+  });
+
+  it("a second sign-in of the same person to the same spoke rotates the credential (one grant)", async () => {
+    const user = seedUser(state);
+    const spoke = seedSpoke(state);
+    const first = pkcePair();
+    const second = pkcePair();
+
+    const r1 = await exchange(
+      tokenArgs(spoke, {
+        code: await mintFor(user.id, spoke, first.challenge),
+        codeVerifier: first.verifier,
+      }),
+    );
+    const r2 = await exchange(
+      tokenArgs(spoke, {
+        code: await mintFor(user.id, spoke, second.challenge),
+        codeVerifier: second.verifier,
+      }),
+    );
+
+    expect(r1.ok && r2.ok).toBe(true);
+    if (!r1.ok || !r2.ok) return;
+    expect(r1.value.accessToken).not.toBe(r2.value.accessToken);
+    expect(state.authorizations).toHaveLength(1);
+    expect(state.authorizations[0]?.accessToken).toBe(
+      sha256Hex(r2.value.accessToken),
+    );
+  });
+
+  describe("AC-5: a valid secret and spoke key still sign nobody in without a good grant", () => {
+    async function assertInvalidGrant(
+      spoke: SeededSpoke,
+      body: { code: string; redirectUri?: string; codeVerifier: string },
+    ): Promise<void> {
+      const result = await exchange(tokenArgs(spoke, body));
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_grant" },
+      });
+    }
+
+    it("an unknown code", async () => {
+      const spoke = seedSpoke(state);
+      seedUser(state);
+      await assertInvalidGrant(spoke, {
+        code: "x".repeat(43),
+        codeVerifier: pkcePair().verifier,
+      });
+      expect(state.authorizations).toHaveLength(0);
+    });
+
+    it("a code minted for another client — and the code is consumed", async () => {
+      const user = seedUser(state);
+      const a = seedSpoke(state, "a.example.com");
+      const b = seedSpoke(state, "b.example.com");
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, a, challenge);
+
+      await assertInvalidGrant(b, { code, codeVerifier: verifier });
+      expect(state.authorizations).toHaveLength(0);
+      // Burned by the failed attempt: its rightful client cannot use it either.
+      await assertInvalidGrant(a, { code, codeVerifier: verifier });
+    });
+
+    it("an expired code", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+      const row = state.verifications[0];
+      if (row) row.expiresAt = new Date(Date.now() - 1_000);
+
+      await assertInvalidGrant(spoke, { code, codeVerifier: verifier });
+      expect(state.authorizations).toHaveLength(0);
+    });
+
+    it("a correct code with a wrong verifier — and the code is consumed", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+
+      await assertInvalidGrant(spoke, {
+        code,
+        codeVerifier: pkcePair().verifier,
+      });
+      expect(state.authorizations).toHaveLength(0);
+      await assertInvalidGrant(spoke, { code, codeVerifier: verifier });
+    });
+
+    it("a correct code with another redirectUri", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+
+      await assertInvalidGrant(spoke, {
+        code,
+        codeVerifier: verifier,
+        redirectUri: "https://attacker.example.com/api/hub-session/callback",
+      });
+      expect(state.authorizations).toHaveLength(0);
+    });
+
+    it("the same correct code a second time after one successful exchange", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+
+      expect(
+        (await exchange(tokenArgs(spoke, { code, codeVerifier: verifier }))).ok,
+      ).toBe(true);
+      expect(state.authorizations).toHaveLength(1);
+      const before = state.authorizations[0]?.accessToken;
+
+      await assertInvalidGrant(spoke, { code, codeVerifier: verifier });
+      expect(state.authorizations).toHaveLength(1);
+      expect(state.authorizations[0]?.accessToken).toBe(before);
+    });
+
+    it("a person whose email stopped being verified between mint and exchange", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+      user.emailVerified = false;
+
+      await assertInvalidGrant(spoke, { code, codeVerifier: verifier });
+      expect(state.authorizations).toHaveLength(0);
+    });
+
+    it("a malformed body is 400 invalid_request and does not consume a code", async () => {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state);
+      const { challenge } = pkcePair();
+      await mintFor(user.id, spoke, challenge);
+
+      const result = await exchange({
+        authorization: spoke.basic,
+        spokeKey: spoke.key,
+        body: {
+          code: "short",
+          redirectUri: spoke.redirectUri,
+          codeVerifier: "v",
+        },
+      });
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_request" },
+      });
+      expect(state.verifications).toHaveLength(1);
+    });
+  });
+
+  describe("client authentication — the secret alone is not enough", () => {
+    async function ready(): Promise<{
+      spoke: SeededSpoke;
+      other: SeededSpoke;
+      code: string;
+      verifier: string;
+    }> {
+      const user = seedUser(state);
+      const spoke = seedSpoke(state, "a.example.com");
+      const other = seedSpoke(state, "b.example.com");
+      const { verifier, challenge } = pkcePair();
+      const code = await mintFor(user.id, spoke, challenge);
+      return { spoke, other, code, verifier };
+    }
+
+    function expectInvalidClient(
+      result: Awaited<ReturnType<typeof exchange>>,
+    ): void {
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 401, code: "invalid_client" },
+      });
+    }
+
+    it("a valid secret WITHOUT the spoke key is 401 invalid_client — and the code survives", async () => {
+      const { spoke, code, verifier } = await ready();
+      expectInvalidClient(
+        await exchange(
+          tokenArgs(
+            spoke,
+            { code, codeVerifier: verifier },
+            { spokeKey: undefined },
+          ),
+        ),
+      );
+      expect(state.authorizations).toHaveLength(0);
+      expect(state.verifications).toHaveLength(1);
+    });
+
+    it("a valid secret with ANOTHER spoke's key is 401 invalid_client", async () => {
+      const { spoke, other, code, verifier } = await ready();
+      expectInvalidClient(
+        await exchange(
+          tokenArgs(
+            spoke,
+            { code, codeVerifier: verifier },
+            { spokeKey: other.key },
+          ),
+        ),
+      );
+      expect(state.authorizations).toHaveLength(0);
+    });
+
+    it("a wrong secret is 401 invalid_client", async () => {
+      const { spoke, code, verifier } = await ready();
+      const wrong = `Basic ${Buffer.from(`${spoke.spoke.id}:ailk_hcs_wrong`).toString("base64")}`;
+      expectInvalidClient(
+        await exchange(
+          tokenArgs(
+            spoke,
+            { code, codeVerifier: verifier },
+            { authorization: wrong },
+          ),
+        ),
+      );
+    });
+
+    it.each([
+      ["no Authorization header", undefined],
+      ["a Bearer header", "Bearer abc"],
+      [
+        "a Basic header with no colon",
+        `Basic ${Buffer.from("nocolon").toString("base64")}`,
+      ],
+      [
+        "an unknown client id",
+        `Basic ${Buffer.from("spoke_nope:secret").toString("base64")}`,
+      ],
+    ])("%s is 401 invalid_client", async (_name, authorization) => {
+      const { spoke, code, verifier } = await ready();
+      expectInvalidClient(
+        await exchange(
+          tokenArgs(spoke, { code, codeVerifier: verifier }, { authorization }),
+        ),
+      );
+    });
+
+    it("a revoked spoke and a disabled client are 401 invalid_client", async () => {
+      const { spoke, code, verifier } = await ready();
+      spoke.spoke.revokedAt = new Date();
+      expectInvalidClient(
+        await exchange(tokenArgs(spoke, { code, codeVerifier: verifier })),
+      );
+      spoke.spoke.revokedAt = null;
+      spoke.client.enabled = false;
+      expectInvalidClient(
+        await exchange(tokenArgs(spoke, { code, codeVerifier: verifier })),
+      );
+    });
+  });
+
+  it(`answers 429 on the ${EXCHANGES_PER_CLIENT + 1}st exchange in a minute for one client`, async () => {
+    const spoke = seedSpoke(state, "a.example.com");
+    const other = seedSpoke(state, "b.example.com");
+    const body = { code: "x".repeat(43), codeVerifier: pkcePair().verifier };
+
+    for (let i = 0; i < EXCHANGES_PER_CLIENT; i += 1) {
+      const result = await exchange(tokenArgs(spoke, body));
+      expect(result).toMatchObject({
+        ok: false,
+        error: { code: "invalid_grant" },
+      });
+    }
+    const over = await exchange(tokenArgs(spoke, body));
+    expect(over).toMatchObject({
+      ok: false,
+      error: { status: 429, code: "rate_limited" },
+    });
+
+    // The bucket is the VERIFIED client's: another spoke is untouched, and an
+    // unauthenticated flood never reaches (or fills) a bucket.
+    const next = await exchange(tokenArgs(other, body));
+    expect(next).toMatchObject({ ok: false, error: { code: "invalid_grant" } });
+  });
+});
+
+describe("revoke (POST /v1/hub-sign-in/revoke)", () => {
+  async function signedIn(spoke: SeededSpoke, userId: string) {
+    const { verifier, challenge } = pkcePair();
+    const code = await mintFor(userId, spoke, challenge);
+    const result = await exchange(
+      tokenArgs(spoke, { code, codeVerifier: verifier }),
+    );
+    if (!result.ok) throw new Error("exchange failed");
+    return result.value.accessToken;
+  }
+
+  it("revokes a credential of THIS client only", async () => {
+    const user = seedUser(state);
+    const a = seedSpoke(state, "a.example.com");
+    const b = seedSpoke(state, "b.example.com");
+    const tokenA = await signedIn(a, user.id);
+    const tokenB = await signedIn(b, user.id);
+
+    // Spoke B tries to end spoke A's credential: nothing matches.
+    const cross = await revoke({
+      authorization: b.basic,
+      spokeKey: b.key,
+      body: { accessToken: tokenA },
+    });
+    expect(cross).toEqual({ ok: true, value: { revoked: false } });
+    expect(state.authorizations.every((g) => g.revokedAt === null)).toBe(true);
+
+    const own = await revoke({
+      authorization: a.basic,
+      spokeKey: a.key,
+      body: { accessToken: tokenA },
+    });
+    expect(own).toEqual({ ok: true, value: { revoked: true } });
+    const grants = new Map(state.authorizations.map((g) => [g.accessToken, g]));
+    expect(grants.get(sha256Hex(tokenA))?.revokedAt).toBeInstanceOf(Date);
+    expect(grants.get(sha256Hex(tokenB))?.revokedAt).toBeNull();
+  });
+
+  it("burns this client's unexpired code (the callback's cleanup, SEC-7894-4), and only that", async () => {
+    const user = seedUser(state);
+    const a = seedSpoke(state, "a.example.com");
+    const b = seedSpoke(state, "b.example.com");
+    const { verifier, challenge } = pkcePair();
+    const code = await mintFor(user.id, a, challenge);
+
+    const cross = await revoke({
+      authorization: b.basic,
+      spokeKey: b.key,
+      body: { code },
+    });
+    expect(cross).toEqual({ ok: true, value: { revoked: false } });
+    expect(state.verifications).toHaveLength(1);
+
+    const own = await revoke({
+      authorization: a.basic,
+      spokeKey: a.key,
+      body: { code },
+    });
+    expect(own).toEqual({ ok: true, value: { revoked: true } });
+    expect(state.verifications).toHaveLength(0);
+
+    // A burned code is `invalid_grant` at the token route.
+    const result = await exchange(
+      tokenArgs(a, { code, codeVerifier: verifier }),
+    );
+    expect(result).toMatchObject({
+      ok: false,
+      error: { status: 400, code: "invalid_grant" },
+    });
+  });
+
+  it("answers revoked:false — never an error — for an unknown credential or code", async () => {
+    const a = seedSpoke(state);
+    for (const body of [
+      { accessToken: `ailk_hst_${"z".repeat(43)}` },
+      { code: "z".repeat(43) },
+    ]) {
+      const result = await revoke({
+        authorization: a.basic,
+        spokeKey: a.key,
+        body,
+      });
+      expect(result).toEqual({ ok: true, value: { revoked: false } });
+    }
+  });
+
+  it("needs the same client authentication as the token route", async () => {
+    const a = seedSpoke(state);
+    const result = await revoke({
+      authorization: a.basic,
+      spokeKey: undefined,
+      body: { code: "z".repeat(43) },
+    });
+    expect(result).toMatchObject({
+      ok: false,
+      error: { status: 401, code: "invalid_client" },
+    });
+  });
+
+  it("refuses a body naming both, or neither (400 invalid_request)", async () => {
+    const a = seedSpoke(state);
+    for (const body of [
+      { accessToken: `ailk_hst_${"z".repeat(43)}`, code: "z".repeat(43) },
+      {},
+    ]) {
+      const result = await revoke({
+        authorization: a.basic,
+        spokeKey: a.key,
+        body,
+      });
+      expect(result).toMatchObject({
+        ok: false,
+        error: { status: 400, code: "invalid_request" },
+      });
+    }
+  });
+});
+
+describe("readMe (GET /v1/hub-sign-in/me)", () => {
+  const WS = "wksp_00000000-0000-7000-8000-0000000079a1";
+  const OTHER_WS = "wksp_00000000-0000-7000-8000-0000000079a2";
+
+  type PersonRow = {
+    id: string;
+    workspaceId: string;
+    email: string;
+    userId: string | null;
+    billingCustomerId: string | null;
+  };
+  let people: PersonRow[];
+
+  /** The Person delegate `services/person.ts` reads through, over `people`. */
+  function installPeople(): void {
+    people = [];
+    const matches = (row: PersonRow, where: Record<string, unknown>) =>
+      Object.entries(where).every(
+        ([key, value]) => row[key as keyof PersonRow] === value,
+      );
+    db.person.findFirst.mockImplementation(
+      (async ({ where }: { where: Record<string, unknown> }) =>
+        people.find((row) => matches(row, where)) ?? null) as never,
+    );
+    db.person.updateMany.mockImplementation((async ({
+      where,
+      data,
+    }: {
+      where: Record<string, unknown>;
+      data: Partial<PersonRow>;
+    }) => {
+      const hit = people.filter((row) => matches(row, where));
+      for (const row of hit) Object.assign(row, data);
+      return { count: hit.length };
+    }) as never);
+  }
+
+  function seedPerson(row: Partial<PersonRow> & { email: string }): PersonRow {
+    const full: PersonRow = {
+      id: `person_00000000-0000-7000-8000-${String(people.length + 1).padStart(12, "0")}`,
+      workspaceId: WS,
+      userId: null,
+      billingCustomerId: null,
+      ...row,
+    };
+    people.push(full);
+    return full;
+  }
+
+  beforeEach(installPeople);
+
+  it("reads the person live; with no Person in the spoke's workspace it vouches for no customer id", async () => {
+    const user = seedUser(state);
+    expect(await readMe(user.id, WS)).toEqual({
+      ok: true,
+      value: {
+        user: {
+          id: user.id,
+          name: user.name,
+          email: user.email,
+          emailVerified: true,
+          createdAt: user.createdAt.toISOString(),
+        },
+        billingCustomerId: null,
+      },
+    });
+    user.name = "Renamed";
+    const again = await readMe(user.id, WS);
+    expect(again.ok && again.value.user.name).toBe("Renamed");
+  });
+
+  it("answers the billingCustomerId of the spoke workspace's Person whose userId is the caller (AC-8)", async () => {
+    const user = seedUser(state);
+    seedPerson({
+      email: user.email,
+      userId: user.id,
+      billingCustomerId: "cus_known",
+    });
+    const result = await readMe(user.id, WS);
+    expect(result.ok && result.value.billingCustomerId).toBe("cus_known");
+  });
+
+  it("links the Person whose email is the caller's verified email, then answers its id", async () => {
+    const user = seedUser(state);
+    const person = seedPerson({
+      email: user.email,
+      billingCustomerId: "cus_known",
+    });
+    const result = await readMe(user.id, WS);
+    expect(result.ok && result.value.billingCustomerId).toBe("cus_known");
+    expect(person.userId).toBe(user.id);
+  });
+
+  it("never answers a Person matched by email alone: one linked to another user is null", async () => {
+    const user = seedUser(state);
+    seedPerson({
+      email: user.email,
+      userId: "user_someone-else",
+      billingCustomerId: "cus_theirs",
+    });
+    const result = await readMe(user.id, WS);
+    expect(result.ok && result.value.billingCustomerId).toBeNull();
+  });
+
+  it("reads only the spoke's own workspace: the caller's Person elsewhere is null", async () => {
+    const user = seedUser(state);
+    seedPerson({
+      workspaceId: OTHER_WS,
+      email: user.email,
+      userId: user.id,
+      billingCustomerId: "cus_elsewhere",
+    });
+    const result = await readMe(user.id, WS);
+    expect(result.ok && result.value.billingCustomerId).toBeNull();
+  });
+
+  it("a Person read that fails answers null, never an error", async () => {
+    const user = seedUser(state);
+    db.person.findFirst.mockRejectedValue(new Error("down"));
+    const result = await readMe(user.id, WS);
+    expect(result.ok && result.value.billingCustomerId).toBeNull();
+  });
+
+  it("is 404 for a person who no longer exists", async () => {
+    expect(await readMe("user_gone", WS)).toMatchObject({
+      ok: false,
+      error: { status: 404, code: "not_found" },
+    });
+  });
+});