create-ailk 0.23.0 → 0.25.1

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

@@ -1,472 +0,0 @@
-/**
- * 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 the in-process limiters in this
-// app (the per-IP middleware shares a database store, #5040).
-
-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 } };
-}

package/templates/apps/api/src/services/lead-accept-user.ts

@@ -1,126 +0,0 @@
-// oss: false
-/**
- * @file lead-accept-user.ts
- * @description The `auth.User` behind an accepted inbox message (#7418) —
- * find the user whose email matches the lead's, or create one, so the person
- * who wrote in can later sign in with that same address.
- *
- * ## What a created user is (D1, D7a)
- *
- * `emailVerified: true`, `role: "user"`, the lowercased address, no `name` —
- * and NOTHING else: no `Account` (so no password and no linked provider), no
- * `Session`, no `Membership`. Verified is the operator's ruling (2026-10-01),
- * and it is safe only because the row holds no credential: reaching a session
- * still needs the address owner to prove control of it (Google, which
- * reports a verified email, or the password-reset mail). It is also what
- * Better Auth needs to link that Google login at all — it refuses to link an
- * OAuth account to an existing local user whose `emailVerified` is false.
- * No name is copied: the lead payload is anonymous, unbounded text, and
- * `User.name` is rendered elsewhere.
- *
- * ## What an existing user gets (D2)
- *
- * Nothing. It is linked by id and never written — no `emailVerified`, `role`
- * or `name` change. An operator's click is not proof of address control for
- * an account someone already holds.
- *
- * ## Email normalization (D7, D8)
- *
- * The lead's email is trimmed and must still be an address (else
- * `invalid_email`, before any read). The lookup is case-insensitive and links
- * the OLDEST match: case-variant rows are one mailbox, and a distinct error
- * for them would reveal global account state. A create uses the lowercased
- * form; one that loses a race to the same address (Prisma `P2002`) re-reads
- * and links the winner.
- *
- * ## Why its own file (D3)
- *
- * `inbox-messages.ts` is co-owned by the `workspace` and `multi-tenant`
- * slices and must build in either bundle alone, while `lead-promotion.ts`
- * sits inside a paid-module import closure. This file imports only
- * `lib/prisma.js` and `zod`, so it keeps both bundles buildable.
- *
- * It never returns, logs or rethrows a Prisma error message — a failure is
- * the bare `internal_error` kind (SEC-006).
- */
-
-import { z } from "zod";
-
-import { prisma } from "../lib/prisma.js";
-
-export type FindOrCreateUserResult =
-  | { ok: true; value: { userId: string; created: boolean } }
-  | { ok: false; error: { kind: "invalid_email" | "internal_error" } };
-
-const EMAIL_SHAPE = z.string().email();
-
-/**
- * Prisma's unique-constraint violation, matched by code alone. A local copy
- * of `default-tenant.ts`'s helper, deliberately: importing it would break
- * this file's `lib/prisma.js` + `zod`-only import rule (D3).
- */
-function isUniqueViolation(err: unknown): boolean {
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    (err as { code?: unknown }).code === "P2002"
-  );
-}
-
-/**
- * The oldest user whose email equals `email`, ignoring case. `emailVerified`
- * is selected though no decision here reads it: `tools/lint-email-authz.ts`
- * requires it on every `User` read keyed by email, and this read only links
- * an id — it never gates data on the address.
- */
-function findUserByEmail(email: string) {
-  return prisma.user.findFirst({
-    where: { email: { equals: email, mode: "insensitive" } },
-    orderBy: { createdAt: "asc" },
-    select: { id: true, emailVerified: true },
-  });
-}
-
-/**
- * Resolve the lead's email to one `auth.User` id — linked when one exists,
- * created verified when none does.
- *
- * @param input.email the lead's stored email, untrimmed.
- * @returns the user id and whether this call created it (`created` is for
- *   the caller's audit line only — never for the wire, SEC-002).
- */
-export async function findOrCreateUserForLeadEmail(input: {
-  email: string;
-}): Promise<FindOrCreateUserResult> {
-  const email = typeof input.email === "string" ? input.email.trim() : "";
-  if (!EMAIL_SHAPE.safeParse(email).success) {
-    return { ok: false, error: { kind: "invalid_email" } };
-  }
-
-  try {
-    const existing = await findUserByEmail(email);
-    if (existing) {
-      return { ok: true, value: { userId: existing.id, created: false } };
-    }
-
-    try {
-      const created = await prisma.user.create({
-        data: {
-          email: email.toLowerCase(),
-          emailVerified: true,
-          role: "user",
-        },
-        select: { id: true },
-      });
-      return { ok: true, value: { userId: created.id, created: true } };
-    } catch (err) {
-      if (!isUniqueViolation(err)) throw err;
-      // D8 — a concurrent accept created the same address first.
-      const winner = await findUserByEmail(email);
-      if (!winner) return { ok: false, error: { kind: "internal_error" } };
-      return { ok: true, value: { userId: winner.id, created: false } };
-    }
-  } catch {
-    return { ok: false, error: { kind: "internal_error" } };
-  }
-}