create-ailk 0.24.0 → 0.26.0

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

@@ -1,455 +0,0 @@
-/**
- * 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,
-  });
-}
-
-/** What the hub's sign-in page may show about a spoke (#8790 D2). */
-export interface SignInClientInfo {
-  clientId: string;
-  /** The spoke's display name from the registry. */
-  name: string;
-  /** The origin of the client's first registered redirect URI. */
-  origin: string;
-}
-
-/**
- * The public shape of one spoke's sign-in client, or `null` when the client
- * is missing, disabled, or its spoke is revoked (#8790 D2). Only the
- * registry decides what a sign-in page may name — never a query parameter.
- */
-export async function findSignInClientInfo(
-  clientId: string,
-): Promise<SignInClientInfo | null> {
-  const client = await findClientByClientId(clientId);
-  if (client === null || !client.enabled) return null;
-  const spoke = await findSpokeById(clientId);
-  if (spoke === null || spoke.revokedAt !== null) return null;
-  const first = client.redirectUris[0];
-  if (first === undefined) return null;
-  let origin: string;
-  try {
-    origin = new URL(first).origin;
-  } catch {
-    return null;
-  }
-  return { clientId, name: spoke.name, origin };
-}
-
-/**
- * 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/lead-capture-store.ts

@@ -1,122 +0,0 @@
-/**
- * Lead capture store — always-on JSONL writer (Issue #27 Unit 1).
- *
- * Appends one JSON line per successful lead submission to apps/api/leads.jsonl
- * (or LEAD_CAPTURE_FILE if set). Uses fs.appendFile with flag:'a' which maps to
- * POSIX O_APPEND — the kernel guarantees atomicity for writes ≤ PIPE_BUF on
- * local filesystems, making this safe for concurrent processes/requests.
- *
- * Semantic difference from B6 file-fallback:
- *   B6 file-fallback (.ailk/inbox/) — engaged only when the DB throws (salvage path)
- *   This module — always-on canonical AX surface; disabled explicitly via env, not by DB presence
- *
- * Env vars (all read inside function bodies — module is import-side-effect-free):
- *   LEAD_CAPTURE_FILE            — output path (default: apps/api/leads.jsonl relative to cwd)
- *
- * The default path is LOCAL-ONLY (#6730 D3). In production
- * (`NODE_ENV=production`) with `LEAD_CAPTURE_FILE` unset, the write is skipped:
- * on serverless hosting a file under the process cwd does not outlive the
- * instance, so it is not a record of anything. An operator with a durable
- * volume can keep a side copy by setting `LEAD_CAPTURE_FILE` explicitly —
- * a copy only: in production it never makes a lead count as delivered
- * (`lib/lead-delivery.ts` needs a database or the email vars).
- *
- *   LEAD_CAPTURE_FILE_DISABLED   — set to "true" to skip writes (opt-out)
- *   LEAD_CAPTURE_INCLUDE_IP      — set to "true" to include metadata.ip in the record
- *
- * PII discipline:
- *   IP is excluded from the written record by default.
- *   No other PII is filtered — `data` carries whatever the route gave us.
- *   Callers are responsible for what they put in `data`.
- */
-
-import * as fs from "fs/promises";
-import * as path from "path";
-
-import type { LeadCaptureRecord } from "@working-theory/validation";
-
-// Re-export so consumers can import from one place.
-export type { LeadCaptureRecord };
-
-export type AppendResult =
-  | { ok: true; skipped?: true }
-  | { ok: false; error: string };
-
-/**
- * Append one lead record as a JSONL line.
- *
- * Always resolves — never throws. Returns ok:false on fs errors so the caller
- * can log and continue without crashing the request.
- */
-export async function appendLeadRecord(
-  record: LeadCaptureRecord,
-): Promise<AppendResult> {
-  // Read env inside the function — no module-level side effects.
-  const disabled = process.env.LEAD_CAPTURE_FILE_DISABLED === "true";
-  if (disabled) {
-    return { ok: true, skipped: true };
-  }
-  if (process.env.NODE_ENV === "production" && !process.env.LEAD_CAPTURE_FILE) {
-    return { ok: true, skipped: true };
-  }
-
-  const includeIp = process.env.LEAD_CAPTURE_INCLUDE_IP === "true";
-  const outputPath = resolveOutputPath();
-
-  // Strip IP from metadata unless explicitly opted in.
-  const cleanMeta = includeIp
-    ? record.metadata
-    : Object.fromEntries(
-        Object.entries(record.metadata).filter(([k]) => k !== "ip"),
-      );
-
-  const line = JSON.stringify({ ...record, metadata: cleanMeta }) + "\n";
-
-  try {
-    await fs.appendFile(outputPath, line, { flag: "a", encoding: "utf8" });
-    return { ok: true };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return { ok: false, error: message };
-  }
-}
-
-/**
- * Startup-time validation: if LEAD_CAPTURE_FILE points at a path whose parent
- * directory does not exist, throw immediately so the server fails fast rather
- * than erroring on first write.
- *
- * Call from server.ts build() before registering routes.
- * No-op when LEAD_CAPTURE_FILE is unset or LEAD_CAPTURE_FILE_DISABLED=true.
- */
-export async function validateLeadCaptureDir(): Promise<void> {
-  const disabled = process.env.LEAD_CAPTURE_FILE_DISABLED === "true";
-  const filePath = process.env.LEAD_CAPTURE_FILE;
-
-  if (!filePath || disabled) {
-    return;
-  }
-
-  const dir = path.dirname(path.resolve(filePath));
-
-  try {
-    await fs.access(dir);
-  } catch {
-    throw new Error(
-      `LEAD_CAPTURE_FILE directory does not exist: "${dir}". ` +
-        `Create the directory or unset LEAD_CAPTURE_FILE.`,
-    );
-  }
-}
-
-// ─── Internal ─────────────────────────────────────────────────────────────────
-
-function resolveOutputPath(): string {
-  const envPath = process.env.LEAD_CAPTURE_FILE;
-  if (envPath) {
-    return path.resolve(envPath);
-  }
-  // Default: apps/api/leads.jsonl relative to the process cwd.
-  // In production (Vercel function or Node standalone), cwd is the project root.
-  return path.resolve(process.cwd(), "apps/api/leads.jsonl");
-}

package/templates/apps/api/src/lib/lead-delivery.ts

@@ -1,52 +0,0 @@
-/**
- * @file lead-delivery.ts
- * @description Where a captured lead goes, resolved from the environment (#6730 D1).
- *
- *   inbox — `DATABASE_URL` is set: the database is the destination (the lead
- *           inbox at `/leads`); the owner email is still sent best-effort.
- *   email — no database, but `RESEND_API_KEY` plus both notification
- *           addresses are set: the owner email IS the delivery.
- *   local — neither, outside production (`pnpm dev`, tests): the local file
- *           fallback + `leads.jsonl`, so local work needs nothing configured.
- *   none  — neither, in production: nothing is accepted, so no visitor is
- *           ever told a message was sent when it reached nobody.
- *
- * A key alone delivers nothing (`sendEmail()` also needs both addresses), so
- * it is not counted as configured. `LEAD_CAPTURE_FILE_DISABLED=true` removes
- * the local file path, so outside production it resolves to `none` too.
- *
- * Import-side-effect-free; the environment is read at call time.
- */
-
-export type LeadDelivery = "inbox" | "email" | "local" | "none";
-
-export type LeadDeliveryKind = "submit" | "subscribe" | "callback";
-
-export function resolveLeadDelivery(
-  env: NodeJS.ProcessEnv = process.env,
-): LeadDelivery {
-  if (env.DATABASE_URL) return "inbox";
-  if (
-    env.RESEND_API_KEY &&
-    env.AILK_LEAD_NOTIFICATION_TO &&
-    env.AILK_LEAD_NOTIFICATION_FROM
-  ) {
-    return "email";
-  }
-  if (env.NODE_ENV !== "production" && env.LEAD_CAPTURE_FILE_DISABLED !== "true") {
-    return "local";
-  }
-  return "none";
-}
-
-/**
- * Whether a delivery mode accepts a lead of this kind. A newsletter
- * subscription is a list entry, not a message — emailing the owner one
- * address per signup is not a list — so `subscribe` needs somewhere to keep
- * it (the database, or the local file in development).
- */
-export function acceptsKind(d: LeadDelivery, kind: LeadDeliveryKind): boolean {
-  if (d === "none") return false;
-  if (kind === "subscribe") return d === "inbox" || d === "local";
-  return true;
-}

package/templates/apps/api/src/lib/license-key-store.ts

@@ -1,45 +0,0 @@
-/**
- * Registers the durable home of a renewed licence key (#6677 DD-6).
- *
- * `@working-theory/license` renews the deployment's key before it lapses and
- * keeps the renewed key in a `LicenseKeyStore`. Its default store is a file,
- * which a Vercel redeploy wipes — so a redeployed site would fall back to the
- * older `AILK_LICENSE_KEY` and, past the renewal grace, to free. With a
- * database configured, this registers the store backed by ONE deployment-wide
- * `SiteSetting` row, `(DEFAULT_WORKSPACE_ID, "license.renewed_key")`, shared
- * by this app, apps/mcp and apps/web.
- *
- * The row is deployment-wide, not tenant data: the licence is the
- * deployment's, so it sits under the seeded default workspace in single- and
- * multi-tenant builds alike (the named tenant-scope exclusion in
- * architecture.yaml). A DB-less scaffold keeps the file store.
- */
-
-import { DEFAULT_WORKSPACE_ID } from "@working-theory/database/tenancy";
-import {
-  createSiteSettingLicenseKeyStore,
-  setLicenseKeyStore,
-} from "@working-theory/license";
-import { logger } from "@working-theory/observability";
-
-import { prisma } from "./prisma.js";
-
-/**
- * Register the SiteSetting-backed store when `DATABASE_URL` is set. An
- * explicitly set `AILK_LICENSE_STORAGE_PATH` is the operator choosing the
- * file store, and is honoured. Never throws: a failure logs and leaves the
- * file store in place.
- */
-export async function registerLicenseKeyStore(): Promise<void> {
-  if (!process.env.DATABASE_URL || process.env.AILK_LICENSE_STORAGE_PATH) return;
-  try {
-    setLicenseKeyStore(
-      createSiteSettingLicenseKeyStore(prisma.siteSetting, DEFAULT_WORKSPACE_ID),
-    );
-  } catch (err) {
-    logger.warn(
-      { errName: err instanceof Error ? err.name : "UnknownError" },
-      "[license] could not register the SiteSetting licence-key store — the file store stays in place",
-    );
-  }
-}