create-ailk 0.23.0 → 0.25.1

package/templates/apps/api/src/services/public-site-resolver.ts

@@ -1,396 +0,0 @@
-/**
- * Public-read site resolution — which workspace an UNAUTHENTICATED public
- * request serves (#5852, roadmap D4 read half; spokes #7532).
- *
- * THE GUARD MODEL IS FAIL-CLOSED. Two branches yield a workspace, and no
- * other:
- *
- *   1. A REGISTERED SPOKE (#7532, `resolveCallerSite` below). A spoke is a
- *      separately deployed site calling this hub server-to-server with its
- *      hub-minted key in ONE header, `x-ailk-spoke-key`. The key is looked up
- *      by its SHA-256 digest in the hub's registry (`lib/spoke-store.ts`);
- *      the matching unrevoked row's workspace is the answer. A key that is
- *      malformed, unknown or revoked resolves to NOTHING — never to the
- *      alias, never to the default workspace. So does a keyless call on a
- *      hub (#7633).
- *   2. An unambiguously one-workspace deployment, answered by the same
- *      predicate the authenticated path uses
- *      (`services/default-tenant.ts#resolveDefaultWorkspaceId`) — one
- *      predicate, reached two ways, never two predicates. Zero workspaces,
- *      two or more, or a sole workspace that is not the seeded default all
- *      resolve to `unresolved`, and the caller answers 404 before any content
- *      query runs. A header-less request takes this branch exactly as it did
- *      before spokes existed — but only on a deployment that is not a hub.
- *      A hub is a deployment whose spoke registry holds a row, revoked or
- *      not (#7633 D1); there a header-less request is refused exactly as an
- *      unknown key is, with no switch set. `AILK_HUB_REQUIRE_SPOKE_KEY`
- *      `true` refuses it even with an empty registry; `false` is an
- *      emergency opt-out that keeps the keyless answer (#7633 D2).
- *
- * IT READS NO HOST. `request.hostname` resolves from `X-Forwarded-Host` under
- * this server's `trustProxy: true` (`server.ts`), which is caller-suppliable
- * and therefore not a tenancy input; `Origin` is client-supplied outside a
- * browser. The one header read here is the spoke key, and a key selects
- * nothing by itself: only the server-side registry row it digests to does.
- *
- * THE CLIENT NEVER SUPPLIES A WORKSPACE. No path parameter, query string,
- * header or body field naming a workspace is read here, on any request. That
- * is roadmap D4's own STOP boundary, not a default.
- *
- * A HEADER-LESS REQUEST LOADS AT MOST ONE READ. With no `DATABASE_URL`, or
- * the flag `false`, the keyless branch reads nothing and imports nothing
- * (#7532 NFR1, #7633 NFR1); off the database adapter the function then
- * returns `not-required` having issued no query and loaded no database
- * module — which is what keeps the no-`DATABASE_URL` scaffold starting.
- * Otherwise it reads the registry ("is this a hub") until it sees a row,
- * holding a "no" for 30 seconds (requests that miss together may each read
- * once) and a "yes" for the life of the process (#7633 D3). The registry
- * module is imported on first use.
- *
- * A FAILED READ (#7633, conductor amendment to NFR3 on the operator's rule
- * that lead capture is never lost). A process that has seen a hub never reads
- * again, so it keeps refusing keyless calls through an outage. Otherwise:
- * with a previous successful "not a hub" the process reuses it, on every
- * route; with none (a cold start during an outage) only the three lead
- * writes, which pass `keylessOnRegistryFailure: "anonymous"`, proceed as on a
- * non-hub, so `routeLead`'s own outage fallback captures the lead. Every
- * other keyless call rejects. Each such failure is logged at error, without
- * the error's message.
- *
- * NO SECRET IS LOGGED. A refusal reaches `request.log.warn` as `{ reason }`
- * (plus `spokeId` for a matched row) — never the key, its digest or its
- * prefix — and never reaches the wire.
- *
- * THE FLOWS ROUTES' WORKSPACE (#7844 D1). `resolveCallerWorkspace` below is
- * the one function the five `/v1/flows` routes (and the open deliverable)
- * resolve their workspace with: a spoke resolves to its own workspace
- * (`viaSpoke: true`), a keyless call through branch 2's one-workspace
- * predicate (#9145 — never the `AILK_SITE_ID` alias, so every anonymous
- * route answers the same workspace for the same deployment), and anything
- * else to `unresolved` with one of two reasons, `spoke-refused` or
- * `ambiguous`. The reasons are for `request.log` only; the routes answer both
- * the same way. It lives here rather than under `routes/flows/` because the
- * two flows route files sit in different module slices, and this file is
- * base tree.
- */
-import {
-  resolvedAdapterKind,
-  type ArtifactPrismaClient,
-  type ContentAdapter,
-} from "@working-theory/content-adapters";
-import type { FastifyRequest } from "fastify";
-
-import { config } from "../config/index.js";
-import { getContentAdapter } from "../lib/content-adapter.js";
-
-/** The one request header a spoke names itself with (#7532 D2). */
-const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
-
-/** The longest key the hub will hash; a minted key is 52 characters. */
-const SPOKE_KEY_MAX_LENGTH = 128;
-
-/**
- * Visible ASCII only — the class the visitor-forward key already uses
- * (`packages/api-client` `SAFE_HEADER_TOKEN`; `apps/api` cannot import that
- * package, so this is its own constant). It also refuses the `"a, b"` string
- * Node makes of a duplicated header, because of the space.
- */
-const SAFE_SPOKE_KEY = /^[\x21-\x7e]+$/;
-
-/**
- * Who is calling a spoke-aware public surface (#7532 D3).
- *
- *   anonymous — no spoke key on a deployment that is not a hub (or the
- *               emergency opt-out): resolve exactly as before.
- *   spoke     — a registered, unrevoked spoke; its workspace is the answer.
- *   refused   — resolve to NOTHING. `reason` is for `request.log` only.
- */
-export type CallerSite =
-  | { kind: "anonymous" }
-  | { kind: "spoke"; spokeId: string; workspaceId: string }
-  | {
-      kind: "refused";
-      reason:
-        | "key-required"
-        | "key-malformed"
-        | "no-database"
-        | "key-unknown"
-        | "key-revoked";
-    };
-
-function refuse(
-  request: FastifyRequest,
-  reason: Extract<CallerSite, { kind: "refused" }>["reason"],
-  spokeId?: string,
-): CallerSite {
-  request.log.warn(
-    spokeId === undefined ? { reason } : { reason, spokeId },
-    "[spoke] caller refused",
-  );
-  return { kind: "refused", reason };
-}
-
-/** How long a "not a hub" answer is held (#7633 D3). */
-const NOT_A_HUB_TTL_MS = 30_000;
-/** Set once the registry has shown a row; never cleared in-process. */
-let hubSeen = false;
-/** Until when a "not a hub" answer stands (epoch ms). */
-let notAHubUntil = 0;
-/** Set once a read has answered "not a hub"; what a failed read reuses. */
-let notAHubSeen = false;
-
-/**
- * What a keyless call gets when the hub-status read fails and the process
- * holds no previous answer (#7633 conductor amendment). `"reject"`, the
- * default, lets the error reach the route; `"anonymous"` is for the three
- * lead writes only, so a lead reaches `routeLead`'s outage fallback.
- */
-export interface ResolveCallerOptions {
-  keylessOnRegistryFailure?: "reject" | "anonymous";
-}
-
-/** Whether a keyless call must be refused (#7633 D2, D3). */
-async function hubRequiresKey(
-  request: FastifyRequest,
-  onFailure: "reject" | "anonymous",
-): Promise<boolean> {
-  const mode = config.AILK_HUB_REQUIRE_SPOKE_KEY;
-  if (mode === "off") return false;
-  // Anything but the automatic default refuses: "on", and any value the
-  // parser should never have let through (NFR5).
-  if (mode !== "auto") return true;
-  // No database, no registry — a single-site deployment (NFR1).
-  if (!process.env.DATABASE_URL) return false;
-  if (hubSeen) return true;
-  if (Date.now() < notAHubUntil) return false;
-  let isHub: boolean;
-  try {
-    const { hasRegisteredSpoke } = await import("../lib/spoke-store.js");
-    isHub = await hasRegisteredSpoke();
-  } catch (err) {
-    // Never held: the next call reads again. The error's own message may
-    // name the database, so only its name is logged.
-    const fallback = notAHubSeen ? "previous-answer" : onFailure;
-    if (fallback === "reject") throw err;
-    request.log.error(
-      {
-        reason: "hub-status-read-failed",
-        fallback,
-        err: err instanceof Error ? err.name : "unknown",
-      },
-      "[spoke] hub-status read failed; answering a keyless call as on a non-hub",
-    );
-    return false;
-  }
-  if (isHub) {
-    hubSeen = true;
-    return true;
-  }
-  notAHubSeen = true;
-  notAHubUntil = Date.now() + NOT_A_HUB_TTL_MS;
-  return false;
-}
-
-/** Test seam: forget the held answer (as `lib/site.ts` does for its memo). */
-export function __resetHubStatusForTests(): void {
-  hubSeen = false;
-  notAHubUntil = 0;
-  notAHubSeen = false;
-}
-
-/**
- * Resolve the caller of a spoke-aware public surface. Reads ONE header, the
- * spoke key, and nothing else off the request; see the file header.
- */
-export async function resolveCallerSite(
-  request: FastifyRequest,
-  options: ResolveCallerOptions = {},
-): Promise<CallerSite> {
-  // Optional chain: a bare `{}` request (the resolver's own suite) is a
-  // header-less request.
-  const raw: unknown = request.headers?.[SPOKE_KEY_HEADER];
-
-  if (raw === undefined) {
-    return (await hubRequiresKey(
-      request,
-      options.keylessOnRegistryFailure ?? "reject",
-    ))
-      ? refuse(request, "key-required")
-      : { kind: "anonymous" };
-  }
-
-  // A string[] is refused defensively; Node joins a duplicated custom header
-  // into one "a, b" string, which the visible-ASCII test refuses.
-  const key = typeof raw === "string" ? raw.trim() : "";
-  if (
-    key === "" ||
-    key.length > SPOKE_KEY_MAX_LENGTH ||
-    !SAFE_SPOKE_KEY.test(key)
-  ) {
-    return refuse(request, "key-malformed");
-  }
-
-  if (!process.env.DATABASE_URL) {
-    return refuse(request, "no-database");
-  }
-
-  // Deferred, like `lib/prisma.js` below: loaded on first use only.
-  const { findSpokeByKeyHash, hashSpokeKey } = await import(
-    "../lib/spoke-store.js"
-  );
-  const row = await findSpokeByKeyHash(hashSpokeKey(key));
-  if (!row) return refuse(request, "key-unknown");
-  if (row.revokedAt !== null) return refuse(request, "key-revoked", row.id);
-  return { kind: "spoke", spokeId: row.id, workspaceId: row.workspaceId };
-}
-
-/**
- * The workspace a `/v1/flows` request serves (#7844 D1). `reason` is for
- * `request.log` only; the routes answer both reasons the same way.
- */
-export type CallerWorkspace =
-  | {
-      kind: "resolved";
-      workspaceId: string;
-      viaSpoke: boolean;
-      /** #8771 D3 — set exactly when `viaSpoke` is true: the registered spoke's id. */
-      spokeId?: string;
-    }
-  | { kind: "unresolved"; reason: "spoke-refused" | "ambiguous" };
-
-/**
- * Resolve the workspace a `/v1/flows` request serves. A spoke resolves to its
- * own workspace; a keyless call through `resolveDefaultWorkspaceId`, the
- * predicate `resolvePublicWorkspace` uses (#9145) — on any content adapter,
- * since a flow is a database row whatever serves the pages; a refused caller
- * to nothing. There is no fallback: a spoke never reaches the default
- * workspace (D5).
- *
- * Calls `resolveCallerSite` with no options, so a failed hub-status read on a
- * keyless call rejects (#7844 C1).
- */
-export async function resolveCallerWorkspace(
-  request: FastifyRequest,
-): Promise<CallerWorkspace> {
-  const caller = await resolveCallerSite(request);
-  if (caller.kind === "refused") {
-    return { kind: "unresolved", reason: "spoke-refused" };
-  }
-  if (caller.kind === "spoke") {
-    return {
-      kind: "resolved",
-      workspaceId: caller.workspaceId,
-      viaSpoke: true,
-      spokeId: caller.spokeId,
-    };
-  }
-  // Deferred, like every database import in this file.
-  const { resolveDefaultWorkspaceId } = await import("./default-tenant.js");
-  const workspaceId = await resolveDefaultWorkspaceId();
-  return workspaceId === null
-    ? { kind: "unresolved", reason: "ambiguous" }
-    : { kind: "resolved", workspaceId, viaSpoke: false };
-}
-
-/**
- * The three answers a public read can get. `reason` exists for `request.log`
- * only: the route decides its response from `kind` alone, so no resolution
- * detail reaches an unauthenticated caller (#5852 D7, D8).
- */
-export type PublicSiteResolution =
-  | { kind: "not-required" }
-  | { kind: "resolved"; workspaceId: string }
-  | {
-      kind: "unresolved";
-      reason: "ambiguous" | "host-unmatched" | "spoke-refused";
-    };
-
-/**
- * Resolves the workspace a public read serves, or refuses to.
- *
- * A spoke resolves to its own workspace on any content adapter; a refused
- * caller resolves to nothing; an anonymous caller takes the one-workspace
- * path below, unchanged (#7532 D3).
- */
-export async function resolvePublicWorkspace(
-  request: FastifyRequest,
-): Promise<PublicSiteResolution> {
-  const caller = await resolveCallerSite(request);
-  if (caller.kind === "refused") {
-    return { kind: "unresolved", reason: "spoke-refused" };
-  }
-  if (caller.kind === "spoke") {
-    return { kind: "resolved", workspaceId: caller.workspaceId };
-  }
-
-  if (resolvedAdapterKind() !== "database") {
-    return { kind: "not-required" };
-  }
-
-  // Deferred — see the module-load note in this file's header (#5852 D6).
-  const { resolveDefaultWorkspaceId } = await import("./default-tenant.js");
-  const workspaceId = await resolveDefaultWorkspaceId();
-  if (workspaceId === null) {
-    return { kind: "unresolved", reason: "ambiguous" };
-  }
-  return { kind: "resolved", workspaceId };
-}
-
-/**
- * The adapter a public content read should use, or `null` when it must refuse.
- *
- * This is the ONE place the three-armed resolution collapses into a decision,
- * so a second public read route cannot grow a second copy of it: `resolved`
- * and `not-required` both yield an adapter, `unresolved` yields `null`. The
- * caller answers `null` with its OWN existing not-found body — which is what
- * keeps a refusal byte-identical to a missing page on `get-page`, and keeps
- * each route's 404 shape its own (#5852 D8). The reason is logged here and
- * never leaves the server.
- */
-export async function resolvePublicContentAdapter(
-  request: FastifyRequest,
-): Promise<ContentAdapter | null> {
-  const site = await resolvePublicWorkspace(request);
-  if (site.kind === "unresolved") {
-    request.log.warn(
-      { reason: site.reason },
-      "[Content] no site resolved for public read",
-    );
-    return null;
-  }
-  // A spoke on an MDX-adapter hub resolves a workspace (its meeting types are
-  // per-workspace), but MDX content is not: it keeps reading the shared
-  // source rather than being switched to the database one (#7532 D3).
-  if (site.kind === "not-required" || resolvedAdapterKind() !== "database") {
-    return getContentAdapter();
-  }
-  return workspaceContentAdapter(site.workspaceId);
-}
-
-/**
- * The content adapter holding ONE workspace's own pages, or `null` when no
- * content is that workspace's (#8514 D9, C13). On the database adapter it is
- * that workspace's database adapter. Off it, the shared content is the
- * deployment's one site — the default workspace's — so only that workspace
- * gets it and every other workspace gets `null`, never the hub's pages
- * (SEC-8514-I). The Admin's plan picker reads its offerings through it.
- */
-export async function workspaceContentAdapter(
-  workspaceId: string,
-): Promise<ContentAdapter | null> {
-  if (resolvedAdapterKind() !== "database") {
-    // Deferred — see the module-load note in this file's header (#5852 D6).
-    const { resolveDefaultWorkspaceId } = await import("./default-tenant.js");
-    return (await resolveDefaultWorkspaceId()) === workspaceId ? getContentAdapter() : null;
-  }
-
-  // The database path, and the only one that needs apps/api's client. The
-  // import is deferred for the reason the header gives (#5852 D6), and the
-  // generated client is structurally wider than the narrow read surface the
-  // adapter declares — the cast names that, and nothing else.
-  const { prisma } = await import("../lib/prisma.js");
-  return getContentAdapter({
-    workspaceId,
-    prisma: prisma as unknown as ArtifactPrismaClient,
-  });
-}