create-ailk 0.14.0 → 0.16.0

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

@@ -0,0 +1,419 @@
+/**
+ * The hub's sign-in-client store — the ONE data-access boundary for a spoke's
+ * sign-in (#7894, spec docs/specs/7894-the-hub-signs-in-its-spec.md D3, D5, D6).
+ *
+ * A spoke signs its visitors in through this hub: the hub is the OAuth-style
+ * provider and each spoke a confidential client. This file is the only one in
+ * `apps/api` that names `prisma.oAuthClient` and `prisma.oAuthAuthorization`
+ * (the web app's `onPasswordReset` is the one other writer, through the Better
+ * Auth Prisma client it already holds). It also owns the short-lived
+ * authorization-code rows, which live in `Verification` — the table Better
+ * Auth already keeps short-lived, single-use secrets in.
+ *
+ * A SPOKE'S CLIENT IS ITS `Spoke` ROW'S ID. `OAuthClient.clientId` equals the
+ * `Spoke.id` it serves, so the binding is by value and no column is added.
+ * `OAuthAuthorization.clientId` is the FK to the client row's own `id`
+ * (`oauthc_…`), not to the public `clientId`.
+ *
+ * NOTHING SECRET IS STORED IN CLEAR. The client secret, every code and every
+ * credential are kept as lowercase hex SHA-256 digests: each carries 256 bits
+ * of entropy, so a fast digest of a lookup key leaks nothing usable.
+ *
+ * Three kinds of caller, kept apart:
+ *   - the service (`services/hub-sign-in.ts`) calls the client reads, the code
+ *     functions and the authorization writes;
+ *   - the preHandler branch (`middleware/auth.ts`) calls
+ *     `findAuthorizationByCredentialHash` only;
+ *   - the operator CLI (`bin/spokes.ts`) calls `upsertSignInClient` and
+ *     `disableSignInClient` only. No route imports those two.
+ *
+ * Nothing here caches a row: a revocation takes effect on the next request.
+ */
+import { createHash, randomBytes } from "node:crypto";
+
+import { prisma } from "./prisma.js";
+import { findSpokeById } from "./spoke-store.js";
+
+/** Every hub-issued credential starts with this, so a leaked one is recognisable. */
+export const HUB_SESSION_PREFIX = "ailk_hst_";
+
+/** Every sign-in client secret starts with this. */
+export const HUB_CLIENT_SECRET_PREFIX = "ailk_hcs_";
+
+/** The scope a spoke credential carries: the signed-in person's account area. */
+export const HUB_SIGN_IN_SCOPE = "account";
+
+/** The `Verification.identifier` prefix of an authorization-code row. */
+const CODE_IDENTIFIER_PREFIX = "hub-sign-in-code:";
+
+/** Lowercase hex SHA-256 — the stored form of every secret here. */
+export function sha256Hex(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/** 32 random bytes in base64url (43 characters). */
+function randomToken(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+/** A new authorization code. */
+export function mintCode(): string {
+  return randomToken();
+}
+
+/** A new credential: `ailk_hst_` + 32 random bytes in base64url. */
+export function mintCredential(): string {
+  return `${HUB_SESSION_PREFIX}${randomToken()}`;
+}
+
+/** A new client secret: `ailk_hcs_` + 32 random bytes in base64url. */
+export function mintClientSecret(): string {
+  return `${HUB_CLIENT_SECRET_PREFIX}${randomToken()}`;
+}
+
+// ── The client ───────────────────────────────────────────────────────────────
+
+export interface SignInClientRow {
+  /** The row's own id (`oauthc_…`) — what an authorization's FK points at. */
+  id: string;
+  /** The public identifier: the `Spoke.id` this client serves. */
+  clientId: string;
+  /** SHA-256 hex of the client secret. */
+  clientSecret: string;
+  redirectUris: string[];
+  enabled: boolean;
+}
+
+const CLIENT_SELECT = {
+  id: true,
+  clientId: true,
+  clientSecret: true,
+  redirectUris: true,
+  enabled: true,
+} as const;
+
+/** The client for one spoke, or `null`. */
+export async function findClientByClientId(
+  clientId: string,
+): Promise<SignInClientRow | null> {
+  return prisma.oAuthClient.findUnique({
+    where: { clientId },
+    select: CLIENT_SELECT,
+  });
+}
+
+/**
+ * Create or update a spoke's sign-in client (the operator CLI). Re-running
+ * rotates the secret: `clientSecret` is replaced by the new digest, so the
+ * previous secret stops working at once. Returns nothing secret — the CALLER
+ * minted `secret` and prints it once.
+ */
+export async function upsertSignInClient(params: {
+  spokeId: string;
+  name: string;
+  redirectUri: string;
+  secret: string;
+}): Promise<void> {
+  const data = {
+    name: params.name,
+    clientSecret: sha256Hex(params.secret),
+    redirectUris: [params.redirectUri],
+    scopes: [HUB_SIGN_IN_SCOPE],
+    trusted: true,
+    enabled: true,
+  };
+  await prisma.oAuthClient.upsert({
+    where: { clientId: params.spokeId },
+    create: { clientId: params.spokeId, ...data },
+    update: data,
+  });
+}
+
+/** The one path a spoke's sign-in callback lives at (spec 7894 D3, D7). */
+export const HUB_CALLBACK_PATH = "/api/hub-session/callback";
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1"]);
+
+/**
+ * Validate a callback URL an operator registers for a spoke (D3): `https:`
+ * (or `http:` on a loopback host), the path EXACTLY `/api/hub-session/callback`,
+ * and no query, fragment or userinfo. Returns the canonical origin + path the
+ * spoke will send back, or `null`.
+ */
+export function canonicalRedirectUri(raw: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  const secure =
+    url.protocol === "https:" ||
+    (url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname));
+  if (!secure) return null;
+  if (url.pathname !== HUB_CALLBACK_PATH) return null;
+  if (url.search !== "" || url.hash !== "") return null;
+  // `URL` drops an empty `?` / `#`, so the raw text is checked too.
+  if (raw.includes("?") || raw.includes("#")) return null;
+  if (url.username !== "" || url.password !== "") return null;
+  return `${url.origin}${HUB_CALLBACK_PATH}`;
+}
+
+export type RegisterSignInClientResult =
+  | { ok: true; spokeId: string; secret: string }
+  | { ok: false; reason: "invalid-redirect-uri" | "spoke-not-found" | "spoke-revoked" };
+
+/**
+ * The operator CLI's `sign-in-client` (D3): refuse an invalid callback, an
+ * unknown spoke or a revoked one; otherwise upsert the client and return the
+ * freshly minted secret, which the caller prints ONCE. Re-running rotates it.
+ */
+export async function registerSignInClient(params: {
+  spokeId: string;
+  redirectUri: string;
+}): Promise<RegisterSignInClientResult> {
+  const redirectUri = canonicalRedirectUri(params.redirectUri);
+  if (redirectUri === null) return { ok: false, reason: "invalid-redirect-uri" };
+
+  const spoke = await findSpokeById(params.spokeId);
+  if (!spoke) return { ok: false, reason: "spoke-not-found" };
+  if (spoke.revokedAt) return { ok: false, reason: "spoke-revoked" };
+
+  const secret = mintClientSecret();
+  await upsertSignInClient({
+    spokeId: spoke.id,
+    name: spoke.name,
+    redirectUri,
+    secret,
+  });
+  return { ok: true, spokeId: spoke.id, secret };
+}
+
+/** Switch a spoke's client off. `false` when it has none. */
+export async function disableSignInClient(spokeId: string): Promise<boolean> {
+  const { count } = await prisma.oAuthClient.updateMany({
+    where: { clientId: spokeId },
+    data: { enabled: false },
+  });
+  return count === 1;
+}
+
+// ── The person ───────────────────────────────────────────────────────────────
+
+export interface SignInUserRow {
+  id: string;
+  name: string | null;
+  email: string;
+  emailVerified: boolean;
+  createdAt: Date;
+}
+
+const USER_SELECT = {
+  id: true,
+  name: true,
+  email: true,
+  emailVerified: true,
+  createdAt: true,
+} as const;
+
+/** The five fields a credential speaks for, read live. */
+export async function findSignInUser(
+  userId: string,
+): Promise<SignInUserRow | null> {
+  return prisma.user.findUnique({
+    where: { id: userId },
+    select: USER_SELECT,
+  });
+}
+
+// ── Authorization codes (`Verification` rows) ────────────────────────────────
+
+export interface CodePayload {
+  userId: string;
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+}
+
+export interface CodeRow {
+  id: string;
+  expiresAt: Date;
+  payload: CodePayload | null;
+}
+
+function codeIdentifier(code: string): string {
+  return `${CODE_IDENTIFIER_PREFIX}${sha256Hex(code)}`;
+}
+
+/** Store one single-use code, valid until `expiresAt`. */
+export async function writeCode(params: {
+  code: string;
+  payload: CodePayload;
+  expiresAt: Date;
+}): Promise<void> {
+  await prisma.verification.create({
+    data: {
+      identifier: codeIdentifier(params.code),
+      value: JSON.stringify(params.payload),
+      expiresAt: params.expiresAt,
+    },
+  });
+}
+
+function parsePayload(value: string): CodePayload | null {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const { userId, clientId, redirectUri, codeChallenge } = parsed as Record<
+      string,
+      unknown
+    >;
+    if (
+      typeof userId === "string" &&
+      typeof clientId === "string" &&
+      typeof redirectUri === "string" &&
+      typeof codeChallenge === "string"
+    ) {
+      return { userId, clientId, redirectUri, codeChallenge };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function findCodeRow(code: string): Promise<CodeRow | null> {
+  const row = await prisma.verification.findFirst({
+    where: { identifier: codeIdentifier(code) },
+    select: { id: true, value: true, expiresAt: true },
+  });
+  if (!row) return null;
+  return {
+    id: row.id,
+    expiresAt: row.expiresAt,
+    payload: parsePayload(row.value),
+  };
+}
+
+/**
+ * Consume a code exactly once: read its row, then delete it by id and require
+ * a count of 1. Two concurrent exchanges of one code both read it, but only
+ * the one whose `deleteMany` removes the row gets it. `null` for an unknown
+ * code or a lost race — the code is gone either way.
+ */
+export async function consumeCode(code: string): Promise<CodeRow | null> {
+  const row = await findCodeRow(code);
+  if (!row) return null;
+  const { count } = await prisma.verification.deleteMany({
+    where: { id: row.id },
+  });
+  return count === 1 ? row : null;
+}
+
+/**
+ * Delete one client's unexpired code without exchanging it (the spoke's
+ * callback burns every code it cannot complete, SEC-7894-4). A code minted for
+ * another client is left alone. `true` when a row was deleted.
+ */
+export async function burnCode(params: {
+  code: string;
+  clientId: string;
+  now: Date;
+}): Promise<boolean> {
+  const row = await findCodeRow(params.code);
+  if (!row || row.payload === null) return false;
+  if (row.payload.clientId !== params.clientId) return false;
+  if (row.expiresAt.getTime() <= params.now.getTime()) return false;
+  const { count } = await prisma.verification.deleteMany({
+    where: { id: row.id },
+  });
+  return count === 1;
+}
+
+/** Sweep expired code rows. Best-effort housekeeping on every exchange. */
+export async function deleteExpiredCodes(now: Date): Promise<void> {
+  await prisma.verification.deleteMany({
+    where: {
+      identifier: { startsWith: CODE_IDENTIFIER_PREFIX },
+      expiresAt: { lte: now },
+    },
+  });
+}
+
+// ── The grant (`OAuthAuthorization`) ─────────────────────────────────────────
+
+/**
+ * Issue the credential for (person, client): one row per pair, so a new
+ * sign-in rotates the previous credential (spec 7894 Clarifications). The
+ * digest replaces the old one and the row is un-revoked.
+ */
+export async function upsertAuthorization(params: {
+  userId: string;
+  clientRowId: string;
+  accessTokenHash: string;
+  expiresAt: Date;
+}): Promise<void> {
+  await prisma.oAuthAuthorization.upsert({
+    where: {
+      userId_clientId: { userId: params.userId, clientId: params.clientRowId },
+    },
+    create: {
+      userId: params.userId,
+      clientId: params.clientRowId,
+      scopes: [HUB_SIGN_IN_SCOPE],
+      accessToken: params.accessTokenHash,
+      expiresAt: params.expiresAt,
+    },
+    update: {
+      scopes: [HUB_SIGN_IN_SCOPE],
+      accessToken: params.accessTokenHash,
+      expiresAt: params.expiresAt,
+      revokedAt: null,
+    },
+  });
+}
+
+/** Revoke one client's credential by digest. `true` when a live row matched. */
+export async function revokeAuthorization(params: {
+  clientRowId: string;
+  accessTokenHash: string;
+  now: Date;
+}): Promise<boolean> {
+  const { count } = await prisma.oAuthAuthorization.updateMany({
+    where: {
+      clientId: params.clientRowId,
+      accessToken: params.accessTokenHash,
+      revokedAt: null,
+    },
+    data: { revokedAt: params.now },
+  });
+  return count === 1;
+}
+
+export interface AuthorizationLookupRow {
+  userId: string;
+  expiresAt: Date;
+  revokedAt: Date | null;
+  client: { clientId: string; enabled: boolean };
+  user: { emailVerified: boolean };
+}
+
+/**
+ * The preHandler's one read: a credential's digest to its grant, with the
+ * client's public id and enabled flag and the person's verified flag in the
+ * same query.
+ */
+export async function findAuthorizationByCredentialHash(
+  accessTokenHash: string,
+): Promise<AuthorizationLookupRow | null> {
+  return prisma.oAuthAuthorization.findUnique({
+    where: { accessToken: accessTokenHash },
+    select: {
+      userId: true,
+      expiresAt: true,
+      revokedAt: true,
+      client: { select: { clientId: true, enabled: true } },
+      user: { select: { emailVerified: true } },
+    },
+  });
+}

package/templates/apps/api/src/lib/site.ts

@@ -20,6 +20,14 @@
  * `currentSiteId()` async would edit every one of its dozen non-test call
  * sites across routes/services/bins, including the two route files NFR1
  * requires to stay byte-unchanged.
+ *
+ * The Checkout site stamp (#7868, spec D1/D2): `SITE_STAMP_KEY`,
+ * `siteStamp()` and `isForeignSiteStamp()` are the one definition of the
+ * `metadata.site` key every hub-created Checkout session carries and the
+ * Stripe webhook reads. The stamp is `currentSiteId()`, so writer and reader
+ * cannot disagree inside one deployment. A session is foreign only when its
+ * stamp is a non-empty string other than `currentSiteId()`; an unstamped
+ * session is the hub's own (roadmap D4).
  */
 import { resolvedAdapterKind } from "@working-theory/content-adapters";
 import {
@@ -35,6 +43,35 @@ export function currentSiteId(): string {
   return process.env.AILK_SITE_ID ?? "default";
 }
 
+/** The Checkout session metadata key naming the site a session belongs to (#7868 D1). */
+export const SITE_STAMP_KEY = "site";
+
+/**
+ * The metadata a hub-created Checkout session carries (#7868 D1/D2):
+ * `{ [SITE_STAMP_KEY]: currentSiteId() }`, read per call. Empty when the alias
+ * is `""` (an `AILK_SITE_ID` set to the empty string), so Stripe is never sent
+ * an empty value (SEC-7868-5) — and the webhook treats that deployment's
+ * sessions as unstamped, exactly as today.
+ */
+export function siteStamp(): Record<string, string> {
+  const site = currentSiteId();
+  return site === "" ? {} : { [SITE_STAMP_KEY]: site };
+}
+
+/**
+ * True only when `metadata[SITE_STAMP_KEY]` is a non-empty string that is not
+ * `currentSiteId()` — a session another site on the shared Stripe account
+ * opened (#7868 D2). An absent, empty or non-string stamp is the hub's own
+ * (roadmap D4: Payment Links, invoices, the portal and pre-stamp sessions
+ * carry none). Exact, case-sensitive comparison, as the spokes' own check.
+ */
+export function isForeignSiteStamp(
+  metadata: Record<string, string> | null | undefined,
+): boolean {
+  const stamp: unknown = metadata?.[SITE_STAMP_KEY];
+  return typeof stamp === "string" && stamp !== "" && stamp !== currentSiteId();
+}
+
 /**
  * The resolved workspace id, memoized after the first SUCCESSFUL resolution
  * ("resolves the alias once at startup", ownership brief § Layer 2 / #6155

package/templates/apps/api/src/lib/spoke-store.ts

@@ -16,13 +16,23 @@
  * anonymous visitor of that site, and every agent using its `apps/mcp`, acts
  * through it. It grants what the site's anonymous visitors can already do on
  * the hub — read that workspace's enabled meeting types and public content,
- * and write leads and bookings into it.
+ * and write leads and bookings into it. One opt-in addition (#7876 D3): while
+ * the hub's operator sets `AILK_SPOKE_FLOW_SEED`, a key may also write its
+ * own workspace's flow definitions (`PUT /v1/flows/:slug/definition`),
+ * limited to the blocks the site's own flow pages render — never emails,
+ * deliverables, pricing, registers or listings.
  *
- * Two kinds of caller, kept apart:
+ * Three kinds of caller, kept apart:
  *   - the public resolver (`services/public-site-resolver.ts`) calls
  *     `hashSpokeKey`, `findSpokeByKeyHash` and `hasRegisteredSpoke` only;
  *   - the operator CLI (`bin/spokes.ts`) calls `registerSpoke`, `revokeSpoke`
- *     and `listSpokes`. No route imports them.
+ *     and `listSpokes` (and, through `lib/hub-sign-in-store.ts`'s
+ *     `registerSignInClient`, `findSpokeById`). No route imports them;
+ *   - the operator flow-copy service (`services/flow-copy.ts`, run only by
+ *     `bin/flows-copy.ts`) calls `hasLiveSpokeForWorkspace` only (#7844 D7);
+ *   - the hub sign-in service (`services/hub-sign-in.ts`) and the auth
+ *     preHandler's hub-credential branch call `hashSpokeKey`,
+ *     `findSpokeByKeyHash` and `findSpokeById` (#7894 D5, D6).
  *
  * Nothing here caches a row: a revocation takes effect on the next request
  * (NFR4). The resolver holds `hasRegisteredSpoke`'s answer itself (#7633 D3).
@@ -63,6 +73,20 @@ export async function findSpokeByKeyHash(
   });
 }
 
+/**
+ * The sign-in client's read of its own spoke (#7894 D3, D5): a spoke is
+ * `Spoke.id`-bound to its `OAuthClient`, and the codes route — which has a
+ * cookie session and no spoke key — checks the spoke is still unrevoked by id.
+ */
+export async function findSpokeById(
+  id: string,
+): Promise<(SpokeLookupRow & { name: string }) | null> {
+  return prisma.spoke.findUnique({
+    where: { id },
+    select: { id: true, workspaceId: true, revokedAt: true, name: true },
+  });
+}
+
 /**
  * Whether this deployment is a hub: its registry holds at least one spoke,
  * revoked or not (#7633 D1). Reads every time; the resolver holds the
@@ -73,6 +97,20 @@ export async function hasRegisteredSpoke(): Promise<boolean> {
   return Boolean(row);
 }
 
+/**
+ * Whether at least one unrevoked spoke is bound to this workspace (#7844 D7):
+ * the flow-copy tool's target check. Selects `id` only.
+ */
+export async function hasLiveSpokeForWorkspace(
+  workspaceId: string,
+): Promise<boolean> {
+  const row = await prisma.spoke.findFirst({
+    where: { workspaceId, revokedAt: null },
+    select: { id: true },
+  });
+  return Boolean(row);
+}
+
 // ── Operator functions — `bin/spokes.ts` only ────────────────────────────────
 
 export interface SpokeListRow {

package/templates/apps/api/src/middleware/__tests__/auth.bearer-path.test.ts

@@ -194,6 +194,8 @@ const WS_A1 = "wksp_00000000-0000-7000-8000-0000000000a1";
 
 type AgentFixture = {
   id: string;
+  /** Absent → the row carries none (the double omits the column). */
+  grants?: string[];
   enabled?: boolean;
   keyIssuedToMembershipId?: string | null;
   lastActiveAt?: Date | null;
@@ -215,6 +217,7 @@ function installAgents(agents: Array<AgentFixture & { key: string }>): void {
               workspaceId: WS_A1,
               organizationId: ORG_A,
               permissionLevel: "member",
+              ...(a.grants === undefined ? {} : { grants: a.grants }),
               enabled: a.enabled ?? true,
               keyIssuedToMembershipId:
                 a.keyIssuedToMembershipId === undefined ? ADMIN_MEMBERSHIP : a.keyIssuedToMembershipId,
@@ -298,6 +301,7 @@ describe("auth preHandler — agent branch (#3591)", () => {
         organizationId: ORG_A,
         responsibleMembershipId: PERSON_MEMBERSHIP,
         permissionLevel: "member",
+        grants: [],
       },
       actor: { type: "agent", agentId: AGENT_A, onBehalfOfUserId: PERSON },
       sessionTenant: null,