create-ailk 0.14.0 → 0.16.0

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

@@ -0,0 +1,471 @@
+/**
+ * The hub signs in its spokes — the service behind `routes/auth/hub-sign-in.ts`
+ * (#7894, spec docs/specs/7894-the-hub-signs-in-its-spec.md D2, D5).
+ *
+ * An authorization code with PKCE between a confidential client (a spoke) and
+ * its hub. Four operations:
+ *
+ *   - `createCode`  — a signed-in, email-verified person, a registered client
+ *                     and a registered callback mint a single-use 60 s code;
+ *   - `exchange`    — the client trades that code (plus its secret, its spoke
+ *                     key and the PKCE verifier) for a 24 h credential;
+ *   - `revoke`      — the client ends a credential, or burns a code it cannot
+ *                     complete;
+ *   - `readMe`      — the live read behind `GET /v1/hub-sign-in/me` (it may
+ *                     link the caller's Person, by the verified-email rule).
+ *
+ * Every refusal is a typed result, never a throw. The routes map a result to
+ * a status and an envelope; nothing here touches a request or a reply. No log
+ * line carries a code, a verifier, a secret, a credential or an email.
+ *
+ * WHAT STOPS A LEAKED CLIENT SECRET SIGNING SOMEBODY IN. The token route
+ * needs a code, and a code is minted only for a person who is signed in on the
+ * hub in a browser; the exchange then needs the PKCE verifier the spoke
+ * generated for that one flow, the client secret AND the spoke's own key. A
+ * secret alone mints nothing, a code alone mints nothing, and a credential is
+ * refused (at the preHandler) with any other spoke's key.
+ */
+import { timingSafeEqual } from "node:crypto";
+
+import { getClock } from "@working-theory/common";
+import {
+  hubSignInCodeBodySchema,
+  hubSignInRevokeBodySchema,
+  hubSignInTokenBodySchema,
+  type HubSignInMeResponse,
+  type HubSignInRevokeResponse,
+  type HubSignInTokenResponse,
+  type HubSignInUser,
+} from "@working-theory/validation";
+
+import {
+  burnCode,
+  consumeCode,
+  deleteExpiredCodes,
+  findClientByClientId,
+  findSignInUser,
+  mintCode,
+  mintCredential,
+  revokeAuthorization,
+  sha256Hex,
+  upsertAuthorization,
+  writeCode,
+  type SignInClientRow,
+  type SignInUserRow,
+} from "../lib/hub-sign-in-store.js";
+import {
+  findSpokeById,
+  findSpokeByKeyHash,
+  hashSpokeKey,
+} from "../lib/spoke-store.js";
+
+import { resolveCallerBillingCustomerId } from "./person.js";
+
+/** How long a code is valid: the browser redirect and the server exchange. */
+export const CODE_TTL_MS = 60_000;
+
+/** How long a credential is valid: 24 hours. */
+export const CREDENTIAL_TTL_SECONDS = 86_400;
+
+/** The per-user code budget (D5): 30 codes per 10 minutes. */
+export const CODES_PER_USER = 30;
+export const CODES_WINDOW_MS = 600_000;
+
+/** The per-client exchange budget (D5): 120 exchanges per minute. */
+export const EXCHANGES_PER_CLIENT = 120;
+export const EXCHANGES_WINDOW_MS = 60_000;
+
+/** Cap on distinct buckets per limiter — the oldest is evicted at capacity. */
+const MAX_BUCKETS = 5_000;
+
+export type ServiceStatus = 400 | 401 | 403 | 404 | 429;
+
+export interface ServiceError {
+  status: ServiceStatus;
+  code: string;
+  message: string;
+  /** Seconds, on a 429. */
+  retryAfter?: number;
+}
+
+export type Result<T> =
+  { ok: true; value: T } | { ok: false; error: ServiceError };
+
+function refuse<T = never>(
+  status: ServiceStatus,
+  code: string,
+  message: string,
+  retryAfter?: number,
+): Result<T> {
+  return {
+    ok: false,
+    error: {
+      status,
+      code,
+      message,
+      ...(retryAfter !== undefined ? { retryAfter } : {}),
+    },
+  };
+}
+
+// ── In-process fixed-window limiter, keyed on a VERIFIED identity ────────────
+//
+// In the service and not in an `onRequest` hook: a bucket must only ever be
+// keyed on an identity the request has already proved (the user the cookie
+// session resolved to; the client that passed secret AND spoke key), so an
+// invented key never gets one (SEC-7894-8). The shape of `middleware/auth.ts`'s
+// per-agent limiter. SINGLE-REPLICA, like every limiter in this app.
+
+interface Bucket {
+  windowStartMs: number;
+  count: number;
+}
+
+interface WindowLimiter {
+  /** `undefined` when admitted; the seconds to wait when over budget. */
+  charge(key: string, now: number): number | undefined;
+  clear(): void;
+}
+
+function createWindowLimiter(limit: number, windowMs: number): WindowLimiter {
+  const buckets = new Map<string, Bucket>();
+
+  return {
+    charge(key, now) {
+      let bucket = buckets.get(key);
+      if (!bucket || now - bucket.windowStartMs >= windowMs) {
+        if (!buckets.has(key) && buckets.size >= MAX_BUCKETS) {
+          for (const [id, b] of buckets) {
+            if (now - b.windowStartMs >= windowMs) buckets.delete(id);
+          }
+          if (buckets.size >= MAX_BUCKETS) {
+            const oldest = buckets.keys().next().value;
+            if (oldest !== undefined) buckets.delete(oldest);
+          }
+        }
+        // Re-insert, so Map order stays oldest-window-first for the eviction.
+        buckets.delete(key);
+        bucket = { windowStartMs: now, count: 0 };
+        buckets.set(key, bucket);
+      }
+      bucket.count += 1;
+      if (bucket.count > limit) {
+        return Math.max(
+          1,
+          Math.ceil((bucket.windowStartMs + windowMs - now) / 1_000),
+        );
+      }
+      return undefined;
+    },
+    clear() {
+      buckets.clear();
+    },
+  };
+}
+
+const codeLimiter = createWindowLimiter(CODES_PER_USER, CODES_WINDOW_MS);
+const exchangeLimiter = createWindowLimiter(
+  EXCHANGES_PER_CLIENT,
+  EXCHANGES_WINDOW_MS,
+);
+
+/** Test-only reset. Not intended for production use. */
+export function __resetHubSignInBuckets(): void {
+  codeLimiter.clear();
+  exchangeLimiter.clear();
+}
+
+// ── Shapes ───────────────────────────────────────────────────────────────────
+
+function toWireUser(user: SignInUserRow): HubSignInUser {
+  return {
+    id: user.id,
+    name: user.name,
+    email: user.email,
+    emailVerified: user.emailVerified,
+    createdAt: user.createdAt.toISOString(),
+  };
+}
+
+// ── POST /v1/hub-sign-in/codes ───────────────────────────────────────────────
+
+/**
+ * Mint a single-use code for a person the cookie session resolved. The caller
+ * (the route) has already refused every bearer; this is the cookie path only.
+ */
+export async function createCode(params: {
+  userId: string;
+  body: unknown;
+}): Promise<Result<{ code: string; redirectUri: string }>> {
+  const now = getClock().now();
+
+  const retryAfter = codeLimiter.charge(params.userId, now);
+  if (retryAfter !== undefined) {
+    return refuse(429, "rate_limited", "Too many requests", retryAfter);
+  }
+
+  const parsed = hubSignInCodeBodySchema.safeParse(params.body);
+  if (!parsed.success) {
+    return refuse(400, "invalid_request", "Invalid request");
+  }
+  const { clientId, redirectUri, codeChallenge } = parsed.data;
+
+  const client = await findClientByClientId(clientId);
+  if (!client || !client.enabled) {
+    return refuse(400, "invalid_client", "Unknown client");
+  }
+  // A client is a spoke's: a revoked spoke signs nobody in.
+  const spoke = await findSpokeById(client.clientId);
+  if (!spoke || spoke.revokedAt) {
+    return refuse(400, "invalid_client", "Unknown client");
+  }
+  // Exact match only — a callback not registered for this client is refused
+  // before anything is minted, and never redirected to.
+  if (!client.redirectUris.includes(redirectUri)) {
+    return refuse(400, "invalid_redirect_uri", "Redirect URI not registered");
+  }
+
+  const user = await findSignInUser(params.userId);
+  if (!user) return refuse(401, "unauthorized", "Authentication required");
+  if (user.emailVerified !== true) {
+    return refuse(403, "email_unverified", "Email address not verified");
+  }
+
+  const code = mintCode();
+  await writeCode({
+    code,
+    payload: {
+      userId: user.id,
+      clientId: client.clientId,
+      redirectUri,
+      codeChallenge,
+    },
+    expiresAt: new Date(now + CODE_TTL_MS),
+  });
+  return { ok: true, value: { code, redirectUri } };
+}
+
+// ── Client authentication (token and revoke) ─────────────────────────────────
+
+const BASIC = /^Basic\s+([A-Za-z0-9+/]+={0,2})$/;
+
+/** The stand-in compared against when the client is unknown, so timing is flat. */
+const DUMMY_DIGEST = Buffer.alloc(32);
+
+function parseBasic(
+  header: string | undefined,
+): { clientId: string; secret: string } | null {
+  if (!header) return null;
+  const match = BASIC.exec(header);
+  if (!match?.[1]) return null;
+  const decoded = Buffer.from(match[1], "base64").toString("utf8");
+  const colon = decoded.indexOf(":");
+  if (colon <= 0) return null;
+  const clientId = decoded.slice(0, colon);
+  const secret = decoded.slice(colon + 1);
+  if (!clientId || !secret) return null;
+  return { clientId, secret };
+}
+
+/**
+ * Authenticate a spoke as a sign-in client: the secret (compared as digests,
+ * constant time) AND its spoke key, which must resolve to an unrevoked spoke
+ * whose id is this client. Any failure is the one `401 invalid_client`.
+ */
+async function authenticateClient(params: {
+  authorization: string | undefined;
+  spokeKey: string | undefined;
+}): Promise<Result<SignInClientRow>> {
+  const failure = refuse<SignInClientRow>(
+    401,
+    "invalid_client",
+    "Client authentication failed",
+  );
+
+  const basic = parseBasic(params.authorization);
+  if (!basic) return failure;
+
+  const client = await findClientByClientId(basic.clientId);
+
+  const provided = Buffer.from(sha256Hex(basic.secret), "hex");
+  const stored = client
+    ? Buffer.from(client.clientSecret, "hex")
+    : DUMMY_DIGEST;
+  const secretMatches =
+    stored.length === provided.length && timingSafeEqual(provided, stored);
+
+  const spokeKey = params.spokeKey?.trim();
+  const spoke = spokeKey
+    ? await findSpokeByKeyHash(hashSpokeKey(spokeKey)).catch(() => null)
+    : null;
+
+  if (
+    !client ||
+    !secretMatches ||
+    !client.enabled ||
+    !spoke ||
+    spoke.revokedAt ||
+    spoke.id !== client.clientId
+  ) {
+    return failure;
+  }
+  return { ok: true, value: client };
+}
+
+// ── POST /v1/hub-sign-in/token ───────────────────────────────────────────────
+
+function base64urlSha256(value: string): string {
+  return Buffer.from(sha256Hex(value), "hex").toString("base64url");
+}
+
+/** True when two short strings are equal, in constant time. */
+function safeEqual(a: string, b: string): boolean {
+  const left = Buffer.from(a);
+  const right = Buffer.from(b);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/**
+ * Trade a single-use code for a 24 h credential (the token route). The order
+ * is the security argument:
+ *
+ *   1. authenticate the CLIENT — secret AND spoke key, or the one 401;
+ *   2. charge the per-client bucket (a verified identity only);
+ *   3. parse the body;
+ *   4. CONSUME the code — exactly once, before any check on it — so a failed
+ *      verifier or a wrong callback also burns it;
+ *   5. only then check client, callback and PKCE, and the person's email;
+ *   6. mint the credential, stored only as a digest (one grant per person and
+ *      spoke, so a new sign-in rotates the previous credential).
+ *
+ * Every failure after step 3 is the one `400 invalid_grant`.
+ */
+export async function exchange(params: {
+  authorization: string | undefined;
+  spokeKey: string | undefined;
+  body: unknown;
+}): Promise<Result<HubSignInTokenResponse>> {
+  const auth = await authenticateClient(params);
+  if (!auth.ok) return auth;
+  const client = auth.value;
+
+  const now = getClock().now();
+  const retryAfter = exchangeLimiter.charge(client.clientId, now);
+  if (retryAfter !== undefined) {
+    return refuse(429, "rate_limited", "Too many requests", retryAfter);
+  }
+
+  const parsed = hubSignInTokenBodySchema.safeParse(params.body);
+  if (!parsed.success) {
+    return refuse(400, "invalid_request", "Invalid request");
+  }
+  const { code, redirectUri, codeVerifier } = parsed.data;
+
+  const invalidGrant = () =>
+    refuse<HubSignInTokenResponse>(400, "invalid_grant", "Invalid grant");
+
+  // The code is consumed FIRST and exactly once — before any check — so a
+  // failed verifier or a wrong callback also burns it.
+  const row = await consumeCode(code);
+  if (!row || row.payload === null) return invalidGrant();
+  if (row.expiresAt.getTime() <= now) return invalidGrant();
+  const { payload } = row;
+  if (payload.clientId !== client.clientId) return invalidGrant();
+  if (payload.redirectUri !== redirectUri) return invalidGrant();
+  if (!safeEqual(base64urlSha256(codeVerifier), payload.codeChallenge)) {
+    return invalidGrant();
+  }
+
+  const user = await findSignInUser(payload.userId);
+  if (!user || user.emailVerified !== true) return invalidGrant();
+
+  const credential = mintCredential();
+  await upsertAuthorization({
+    userId: user.id,
+    clientRowId: client.id,
+    accessTokenHash: sha256Hex(credential),
+    expiresAt: new Date(now + CREDENTIAL_TTL_SECONDS * 1_000),
+  });
+  // Housekeeping: a failed sweep never fails a completed exchange.
+  await deleteExpiredCodes(new Date(now)).catch(() => undefined);
+
+  return {
+    ok: true,
+    value: {
+      accessToken: credential,
+      tokenType: "Bearer",
+      expiresIn: CREDENTIAL_TTL_SECONDS,
+      user: toWireUser(user),
+    },
+  };
+}
+
+// ── POST /v1/hub-sign-in/revoke ──────────────────────────────────────────────
+
+/**
+ * End one of THIS client's credentials, or burn one of its unexpired codes
+ * (the spoke's callback burns every code it cannot complete, SEC-7894-4).
+ * Another client's credential or code is never touched. `{ revoked: false }`
+ * for a miss — never an error, so it is no oracle for what exists.
+ */
+export async function revoke(params: {
+  authorization: string | undefined;
+  spokeKey: string | undefined;
+  body: unknown;
+}): Promise<Result<HubSignInRevokeResponse>> {
+  const auth = await authenticateClient(params);
+  if (!auth.ok) return auth;
+  const client = auth.value;
+
+  const parsed = hubSignInRevokeBodySchema.safeParse(params.body);
+  if (!parsed.success) {
+    return refuse(400, "invalid_request", "Invalid request");
+  }
+
+  const now = new Date(getClock().now());
+  const revoked =
+    "accessToken" in parsed.data
+      ? await revokeAuthorization({
+          clientRowId: client.id,
+          accessTokenHash: sha256Hex(parsed.data.accessToken),
+          now,
+        })
+      : await burnCode({
+          code: parsed.data.code,
+          clientId: client.clientId,
+          now,
+        });
+  return { ok: true, value: { revoked } };
+}
+
+// ── GET /v1/hub-sign-in/me ───────────────────────────────────────────────────
+
+/**
+ * The person a credential speaks for, read live, and the customer id the hub
+ * vouches for (D13): the `billingCustomerId` of the Person #852's service
+ * answers for the credential's spoke's workspace, only while that Person's
+ * `userId` is the caller, else `null`. It is read through `services/person.ts`
+ * and nowhere else (SEC-7894-6, -7). That service's one write applies here
+ * too: an unlinked Person whose email is the caller's verified email is linked
+ * to the caller on this read (`stampPersonUser`'s rule, as a member read does),
+ * and a refused link is logged under the member area's `member-person-stamp`
+ * event. The preHandler admitted the credential only for a verified email, so
+ * `user.email` is the verified address.
+ */
+export async function readMe(
+  userId: string,
+  workspaceId: string,
+  log?: { warn: (obj: object, msg: string) => void },
+): Promise<Result<HubSignInMeResponse>> {
+  const user = await findSignInUser(userId);
+  if (!user) return refuse(404, "not_found", "Not found");
+  const billingCustomerId = user.emailVerified
+    ? await resolveCallerBillingCustomerId(
+        workspaceId,
+        user.id,
+        user.email,
+        log,
+      )
+    : null;
+  return { ok: true, value: { user: toWireUser(user), billingCustomerId } };
+}