@antasphere/chassis-server 1.0.0

package/src/apikeys/peppers.ts

@@ -0,0 +1,118 @@
+/**
+ * Versioned API-key peppers — the seam that lets API keys survive an
+ * AUTH_SECRET rotation (ADR 008).
+ *
+ * Version 1 is ALWAYS the pepper that hashed keys before versioning existed:
+ * the resolved auth secret, used verbatim as `sha256(secret + pepper)`. With
+ * no `API_KEY_PEPPERS` set the registry is exactly `{ 1: authSecret }` and
+ * new keys mint at version 1 — byte-identical to the pre-versioning
+ * behaviour, nothing to migrate.
+ *
+ * `API_KEY_PEPPERS` supplies additional versions as `<version>:<secret>`
+ * entries joined by `;` (e.g. `1:<old secret>;2:<new pepper>`). Entries
+ * override the defaults, so pinning `1:<value>` freezes version 1
+ * independently of the live AUTH_SECRET — the first step of the rotation
+ * runbook in internal/security-runbooks.md. LOUD RULE: whenever version 1 is pinned, its
+ * value MUST be the historical AUTH_SECRET-derived pepper (the secret that
+ * was live when the version-1 keys were minted), or every existing key stops
+ * resolving. New keys always mint under the HIGHEST version in the registry.
+ *
+ * Resolution looks up the pepper by the key row's stored `pepper_version`
+ * and FAILS CLOSED on a version the registry does not contain — same 401 as
+ * a revoked key, never a fallback to another pepper.
+ */
+
+/** `pepper_version` is a Postgres smallint. */
+export const MAX_PEPPER_VERSION = 32767;
+
+/** Peppers hold the same bar as AUTH_SECRET. */
+const MIN_PEPPER_LENGTH = 32;
+
+export interface PepperRegistry {
+  /** The version new keys are minted under — the highest defined. */
+  readonly current: number;
+  /** True when API_KEY_PEPPERS explicitly pins version 1 (rotation-safe). */
+  readonly v1Pinned: boolean;
+  /** The pepper for a stored version, or undefined — the caller MUST fail closed. */
+  get(version: number): string | undefined;
+  /**
+   * Every registered version, ascending. For credentials that carry no
+   * version indicator (share-token secrets, whose sha256 IS the DB lookup
+   * key), resolution computes the candidate hash under EACH version — the
+   * registry has one entry per rotation, so this stays O(rotations).
+   */
+  readonly versions: readonly number[];
+}
+
+/**
+ * Parse the `API_KEY_PEPPERS` value into a version→secret map. Throws a
+ * readable Error on any malformed entry — surfaced by the env schema, so a
+ * bad value refuses boot instead of silently mis-hashing keys.
+ */
+export function parseApiKeyPeppers(raw: string): Map<number, string> {
+  const map = new Map<number, string>();
+  // Trailing/duplicated separators are operator noise, not errors.
+  const entries = raw
+    .split(';')
+    .map((e) => e.trim())
+    .filter((e) => e.length > 0);
+  if (entries.length === 0) {
+    throw new Error('API_KEY_PEPPERS is set but contains no <version>:<secret> entries');
+  }
+  for (const entry of entries) {
+    // Split at the FIRST colon only — the secret itself may contain colons.
+    const colon = entry.indexOf(':');
+    if (colon <= 0) {
+      throw new Error(`API_KEY_PEPPERS entry "${describeEntry(entry)}" is not <version>:<secret>`);
+    }
+    const versionPart = entry.slice(0, colon).trim();
+    const secret = entry.slice(colon + 1);
+    if (!/^[0-9]+$/.test(versionPart)) {
+      // A reversed `<secret>:<version>` entry makes versionPart the whole
+      // secret — truncate so a misconfiguration doesn't echo it to stderr.
+      throw new Error(`API_KEY_PEPPERS version "${describeEntry(versionPart)}" is not a positive integer`);
+    }
+    const version = Number(versionPart);
+    if (version < 1 || version > MAX_PEPPER_VERSION) {
+      throw new Error(`API_KEY_PEPPERS version ${version} is out of range (1..${MAX_PEPPER_VERSION})`);
+    }
+    if (map.has(version)) {
+      throw new Error(`API_KEY_PEPPERS defines version ${version} twice`);
+    }
+    if (secret.length < MIN_PEPPER_LENGTH) {
+      throw new Error(
+        `API_KEY_PEPPERS version ${version} secret is shorter than ${MIN_PEPPER_LENGTH} characters`
+      );
+    }
+    map.set(version, secret);
+  }
+  return map;
+}
+
+/** Error context that never echoes a possible secret: version side only. */
+function describeEntry(entry: string): string {
+  const head = entry.slice(0, Math.min(8, entry.length));
+  return entry.length > 8 ? `${head}…` : head;
+}
+
+/**
+ * Build the registry from the resolved auth secret plus the optional
+ * `API_KEY_PEPPERS` value (already format-validated by the env schema; this
+ * re-parses so direct callers get the same guarantees).
+ */
+export function buildPepperRegistry(authSecret: string, apiKeyPeppers?: string): PepperRegistry {
+  const peppers = new Map<number, string>([[1, authSecret]]);
+  let v1Pinned = false;
+  if (apiKeyPeppers !== undefined) {
+    const parsed = parseApiKeyPeppers(apiKeyPeppers);
+    v1Pinned = parsed.has(1);
+    for (const [version, secret] of parsed) peppers.set(version, secret);
+  }
+  const current = Math.max(...peppers.keys());
+  return {
+    current,
+    v1Pinned,
+    get: (version) => peppers.get(version),
+    versions: [...peppers.keys()].sort((a, b) => a - b)
+  };
+}

package/src/apikeys/service.ts

@@ -0,0 +1,223 @@
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { and, eq, gt, isNull, or, sql } from 'drizzle-orm';
+import { apiKeys, type Db } from '@antasphere/chassis-db';
+import type { Principal } from '@antasphere/chassis-contract';
+import {
+  isWorkspaceSelector,
+  resolveMembership,
+  type OnWorkspaceMiss
+} from '../identity/resolve-membership.js';
+import type { PepperRegistry } from './peppers.js';
+
+/**
+ * API keys: `<prefix>_<keyId8>_<secret>`.
+ *
+ * The prefix is the TOOL's (`identity.apiKeyPrefix`, e.g. a product called
+ * Acme might use `acm`): a constructor value with no default, so the chassis
+ * spells none. The shape is fixed: keyId gives an O(1)
+ * indexed lookup, the secret is stored as sha256(secret + pepper) and
+ * compared constant-time. The pepper defaults to the server auth secret, so
+ * a leaked database alone cannot validate keys — and it is VERSIONED
+ * (peppers.ts, ADR 008): each row records the pepper version that hashed it,
+ * mint uses the registry's current version, and resolution uses the stored
+ * version's pepper or fails closed. Keys are minted by sessions only.
+ *
+ * A key is a USER credential (user-scoped credential model): it acts as its
+ * creator, and the target workspace resolves per request through the shared
+ * resolveMembership rule — the X-Workspace-Id header, else the creator's
+ * default membership. `workspace_id` on the row is an OPTIONAL PIN (least
+ * privilege, and the grandfathered binding of pre-model-change keys): a
+ * pinned key resolves ONLY its pinned workspace, and a request naming a
+ * DIFFERENT one is rejected loudly (WorkspaceMismatchError → 403).
+ */
+const KEY_ID_BYTES = 6; // 8 chars base64url
+const SECRET_BYTES = 32; // 43 chars base64url
+
+/** The prefix is a literal in the pattern: every RegExp metacharacter in it is escaped. */
+const escapeRegExp = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The key shape for one prefix: `<prefix>_<keyId8>_<secret>`, two capture groups. */
+const keyPattern = (prefix: string): RegExp =>
+  new RegExp(`^${escapeRegExp(prefix)}_([A-Za-z0-9_-]{8})_([A-Za-z0-9_-]{20,})$`);
+
+/**
+ * A VALID pinned key presented with an X-Workspace-Id naming a different
+ * workspace — a client bug or a confused-deputy attempt. Distinct from a
+ * plain resolution miss (null → 401) so the middleware can answer the loud
+ * 403 the pinned model always answered.
+ */
+export class WorkspaceMismatchError extends Error {
+  constructor() {
+    super('This credential is pinned to a different workspace');
+    this.name = 'WorkspaceMismatchError';
+  }
+}
+
+function hashSecret(secret: string, pepper: string): string {
+  return createHash('sha256')
+    .update(secret + pepper)
+    .digest('hex');
+}
+
+export interface MintedKey {
+  id: string;
+  keyId: string;
+  /** The full key — returned once, never stored. */
+  key: string;
+}
+
+export class ApiKeyService {
+  private readonly keyRe: RegExp;
+
+  constructor(
+    private readonly db: Db,
+    private readonly peppers: PepperRegistry,
+    /** The tool's key prefix, without the underscore (`identity.apiKeyPrefix`). Required: no chassis default. */
+    private readonly prefix: string,
+    /** Cloud only: one cached reconcile on a well-formed selector miss. */
+    private readonly onWorkspaceMiss?: OnWorkspaceMiss | undefined
+  ) {
+    if (!prefix) throw new Error('ApiKeyService: the key prefix is required');
+    this.keyRe = keyPattern(prefix);
+  }
+
+  /** Distinguishes an API-key credential from other bearers (the shape only, no lookup). */
+  readonly isToken = (token: string): boolean => this.keyRe.test(token);
+
+  async mint(opts: {
+    /** Optional workspace PIN — omitted/null mints a user-scoped key. */
+    workspaceId?: string | null;
+    createdBy: string;
+    name: string;
+    scopes: string[];
+    expiresAt?: Date | null;
+  }): Promise<MintedKey> {
+    const keyId = randomBytes(KEY_ID_BYTES).toString('base64url');
+    const secret = randomBytes(SECRET_BYTES).toString('base64url');
+    // Mint always hashes under the CURRENT pepper version and records which
+    // one, so resolution can keep verifying old keys across pepper rotations.
+    const pepperVersion = this.peppers.current;
+    const pepper = this.peppers.get(pepperVersion);
+    if (pepper === undefined) throw new Error(`pepper registry has no current version ${pepperVersion}`);
+    const [row] = await this.db
+      .insert(apiKeys)
+      .values({
+        workspaceId: opts.workspaceId ?? null,
+        keyId,
+        secretHash: hashSecret(secret, pepper),
+        pepperVersion,
+        name: opts.name,
+        scopes: opts.scopes,
+        createdBy: opts.createdBy,
+        expiresAt: opts.expiresAt ?? null
+      })
+      .returning({ id: apiKeys.id });
+    if (!row) throw new Error('api key insert failed');
+    return { id: row.id, keyId, key: `${this.prefix}_${keyId}_${secret}` };
+  }
+
+  /**
+   * Resolve a presented key to a live principal, or null. The key dies with
+   * its creator: a live active membership is required (same re-check
+   * discipline as sessions).
+   *
+   * `requested` is the request's X-Workspace-Id (or null). An UNPINNED key
+   * selects with it exactly like a session (fail closed on non-membership);
+   * a PINNED key always resolves its pin and THROWS WorkspaceMismatchError
+   * when `requested` names a different workspace — never silently serves
+   * the pinned one.
+   */
+  async resolve(token: string, requested: string | null): Promise<Principal | null> {
+    const match = this.keyRe.exec(token);
+    if (!match) return null;
+    const [, keyId, secret] = match;
+    if (!keyId || !secret) return null;
+
+    const [row] = await this.db
+      .select({
+        id: apiKeys.id,
+        secretHash: apiKeys.secretHash,
+        pepperVersion: apiKeys.pepperVersion,
+        workspaceId: apiKeys.workspaceId,
+        scopes: apiKeys.scopes,
+        createdBy: apiKeys.createdBy,
+        expiresAt: apiKeys.expiresAt
+      })
+      .from(apiKeys)
+      .where(
+        and(
+          eq(apiKeys.keyId, keyId),
+          isNull(apiKeys.revokedAt),
+          // Expired = same lookup miss as revoked — one fail-closed 401, no
+          // behavioural fork. DB clock, not app clock.
+          or(isNull(apiKeys.expiresAt), gt(apiKeys.expiresAt, sql`now()`))
+        )
+      )
+      .limit(1);
+    if (!row) return null;
+
+    // Verify under the pepper version THIS row was hashed with — never the
+    // current one, never a fallback. An unknown version (e.g. the operator
+    // dropped a retired pepper from API_KEY_PEPPERS while such keys remain)
+    // FAILS CLOSED: same null → same 401 as a revoked or expired key.
+    const pepper = this.peppers.get(row.pepperVersion);
+    if (pepper === undefined) return null;
+
+    const presented = Buffer.from(hashSecret(secret, pepper), 'hex');
+    const stored = Buffer.from(row.secretHash, 'hex');
+    if (presented.length !== stored.length || !timingSafeEqual(presented, stored)) return null;
+
+    // Live membership through the shared selection rule. A pinned key's pin
+    // IS the selector (fail-closed on the live membership, as always); an
+    // unpinned key selects like a session. Guest capability limits (D2) bind
+    // machine credentials too — the origin of the LIVE membership rides the
+    // principal, and accountRef carries the projection id the cloud live
+    // gate keys on (internal/federation.md).
+    const selector = row.workspaceId ?? requested;
+    let member = await resolveMembership(this.db, row.createdBy, selector);
+    if (!member && selector && this.onWorkspaceMiss && isWorkspaceSelector(selector)) {
+      // Unknown-workspace retry (cloud): the KEY verified above — the miss
+      // may be a hub org granted since the last reconcile pass. One cached
+      // reconcile, one re-run of the SAME lookup — no recursion. Covers the
+      // pin too: a pinned key into a freshly granted hub org resolves.
+      await this.onWorkspaceMiss(row.createdBy, selector);
+      member = await resolveMembership(this.db, row.createdBy, selector);
+    }
+    if (!member) return null;
+    // A valid PINNED key + a header naming another workspace: reject loudly
+    // (the pre-model-change contract). Checked after the membership resolves
+    // so a dead key/membership stays the uniform 401, exactly as before. The
+    // header may name the pinned workspace by its LOCAL id or by the id of
+    // the hub organization it projects (the resolved row's accountRef,
+    // PRDCT-2947): both are the same workspace, neither is a mismatch.
+    if (row.workspaceId && requested) {
+      const named = requested.toLowerCase();
+      const isPin =
+        named === row.workspaceId.toLowerCase() ||
+        (member.accountRef !== null && named === member.accountRef.toLowerCase());
+      if (!isPin) throw new WorkspaceMismatchError();
+    }
+
+    // Advisory only — never correctness-load-bearing (statelessness invariant).
+    void this.db
+      .update(apiKeys)
+      .set({ lastUsedAt: sql`now()` })
+      .where(eq(apiKeys.id, row.id))
+      .catch(() => {});
+
+    return {
+      userId: row.createdBy,
+      email: member.email,
+      name: member.name,
+      workspaceId: member.workspaceId,
+      role: member.role,
+      origin: member.origin,
+      via: 'api_key',
+      scopes: new Set(row.scopes),
+      apiKeyId: row.id,
+      ...(row.expiresAt ? { apiKeyExpiresAt: row.expiresAt.toISOString() } : {}),
+      ...(member.accountRef ? { accountRef: member.accountRef } : {}),
+      ...(row.workspaceId ? { pinned: true as const } : {})
+    };
+  }
+}

package/src/app.ts

@@ -0,0 +1,228 @@
+import { Hono } from 'hono';
+import type { MiddlewareHandler } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import type { OpenAPIHono } from '@hono/zod-openapi';
+import { serveStatic } from '@hono/node-server/serve-static';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Logger } from './logger.js';
+import type { RuntimeState } from './util/index.js';
+import { requestId } from './middleware/index.js';
+import { buildCsp, inlineScriptHashes, securityHeaders } from './middleware/index.js';
+import { healthRoutes } from './routes/index.js';
+
+export interface AppDeps {
+  logger: Logger;
+  state: RuntimeState;
+  /** Directory holding the built dashboard SPA. */
+  publicDir: string;
+  /** The tool's name on the no-dashboard page, title and heading alike (`identity.displayName`). */
+  displayName: string;
+  /** The versioned API, mounted at /api/v1. */
+  api: OpenAPIHono;
+  /** The bundled MCP endpoint, mounted at /mcp (M6). */
+  mcp?: Hono;
+  /** Root-level OAuth discovery documents (/.well-known/*, M6). */
+  wellKnown?: Hono;
+  /**
+   * The tool's public routes (e.g. a public share-link viewer,
+   * /v/{secret}, Phase 4 / ADR 012). Mounted in the public-route slot:
+   * OUTSIDE /api/v1, outside the auth/scope middleware — token recipients
+   * are anonymous, the path secret is the whole credential, and every
+   * user-content response it emits is locked under `CSP: sandbox` (see
+   * viewer/routes.ts in the app).
+   */
+  publicRoutes?: Hono | undefined;
+  /** Observability middlewares + the /metrics route (M5). */
+  metricsMiddleware?: MiddlewareHandler;
+  metricsRoutes?: Hono;
+  otelMiddleware?: MiddlewareHandler;
+  /**
+   * Live readiness probe for the backing store (routes/health.ts). Omitted =
+   * /readyz keeps reporting the boot-time storage result forever.
+   */
+  probeStorage?: () => Promise<void>;
+  /** `Strict-Transport-Security` value (security-headers.ts `hstsValue`); null/absent = no HSTS. */
+  hsts?: string | null;
+  /**
+   * The tool's root middleware, installed after the metrics middleware and
+   * BEFORE every mount. E.g. a tool with VIEWER_BASE_URL (PRDCT-1352): when
+   * present, the host gate (middleware/host-gate.ts in the app) — the viewer
+   * hostname answers only `/v/*`, `/api/v1/viewer/*` and the probes, every
+   * other hostname redirects `/v/*` there. Absent = single-origin behaviour,
+   * gate not installed.
+   */
+  rootMiddleware?: MiddlewareHandler | undefined;
+  /** Extra `frame-src` origins of the dashboard CSP (e.g. a tool's viewer origin, for the preview). */
+  cspFrameSrc?: readonly string[] | undefined;
+  /** Extra `img-src` sources of the dashboard CSP (e.g. `blob:` for a tool whose dashboard shows images it fetched). */
+  cspImgSrc?: readonly string[] | undefined;
+}
+
+/**
+ * The SQLSTATE of a thrown Postgres error, when it is one. node-postgres puts
+ * it on `.code`; drizzle re-throws the same object untouched.
+ */
+export function postgresErrorCode(error: unknown): string | undefined {
+  if (typeof error !== 'object' || error === null) return undefined;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === 'string' ? code : undefined;
+}
+
+/**
+ * Assemble the single Hono app. Route precedence is load-bearing and fixed:
+ * health → (api, mcp, well-known — mounted here as the platform grows) →
+ * static assets → SPA index fallback LAST. A slot deliberately remains open
+ * before the fallback for products that add public content routes.
+ */
+export async function createApp({
+  logger,
+  state,
+  publicDir,
+  displayName,
+  api,
+  mcp,
+  wellKnown,
+  publicRoutes,
+  metricsMiddleware,
+  metricsRoutes,
+  otelMiddleware,
+  probeStorage,
+  hsts,
+  rootMiddleware,
+  cspFrameSrc,
+  cspImgSrc
+}: AppDeps): Promise<Hono> {
+  const app = new Hono();
+
+  // The SPA fallback is read first: its inline bootstrap script hashes feed
+  // the CSP that guards every HTML response.
+  let indexHtml: string | null = null;
+  try {
+    indexHtml = await readFile(join(publicDir, 'index.html'), 'utf8');
+  } catch {
+    logger.warn({ publicDir }, 'no dashboard build found — serving a placeholder at /');
+  }
+  const csp = buildCsp(indexHtml ? inlineScriptHashes(indexHtml) : [], {
+    frameSrc: [...(cspFrameSrc ?? [])],
+    imgSrc: [...(cspImgSrc ?? [])]
+  });
+
+  app.use('*', requestId(logger));
+  app.use('*', securityHeaders({ csp, state, hsts: hsts ?? null }));
+  // PRDCT-1809: a fail-closed boot verdict closes the whole surface — the
+  // operator-facing probes stay so the verdict is visible (/readyz carries
+  // the reason) and the process is not restarted into the same state.
+  app.use('*', async (c, next) => {
+    if (state.closed === null) return next();
+    const path = c.req.path;
+    if (path === '/healthz' || path === '/readyz' || path === '/metrics') return next();
+    return c.json(
+      {
+        error: {
+          code: 'service_closed',
+          message: 'This instance refuses to serve until an operator resolves a boot verdict; see /readyz'
+        }
+      },
+      503
+    );
+  });
+  if (otelMiddleware) app.use('*', otelMiddleware);
+  if (metricsMiddleware) app.use('*', metricsMiddleware);
+  // PRDCT-1352: the viewer-origin host gate, BEFORE every mount below — the
+  // boundary between the two hostnames must be decided before any route
+  // (and any cookie-reading middleware) runs.
+  if (rootMiddleware) app.use('*', rootMiddleware);
+
+  // Uncaught handler errors: log with the request id, answer the wire shape.
+  app.onError((error, c) => {
+    // Malformed request bodies first: Hono's body validators throw
+    // HTTPException(400) on unparseable JSON ("Malformed JSON in request
+    // body") or broken multipart BEFORE zod runs, so the zod-openapi
+    // defaultHook never sees them — and Hono routes a thrown error straight
+    // here from the throwing handler's own dispatch frame, so an upstream
+    // try/catch middleware never observes it either. This is therefore THE
+    // seam: map the framework's 400s to the wire shape with a stable
+    // machine code instead of amplifying a pre-auth-reachable client
+    // mistake into a 500 + an error-level log. Only hono's validators throw
+    // HTTPException(400) on this app (the MCP sub-app handles its own).
+    if (error instanceof HTTPException && error.status === 400) {
+      const isJson = error.message.includes('JSON');
+      return c.json(
+        {
+          error: {
+            code: isJson ? 'invalid_json' : 'invalid_body',
+            message: isJson ? 'Request body is not valid JSON' : 'Malformed request body'
+          }
+        },
+        400
+      );
+    }
+    // A NUL byte (or any byte the server encoding cannot represent) that
+    // reaches Postgres inside a text value raises 22021 / 22P05. It is a
+    // CLIENT mistake, anonymously drivable on every free-text sink, but the
+    // pg error object carries the offending statement AND its bound
+    // parameters — so left alone it becomes a 500 whose error-level log line
+    // prints the SQL and the values. Contract-level `noNulString` rejects the
+    // known sinks at validation time; this is the backstop for the ones a
+    // product forgets, and it must answer 400 with no log.
+    const pgCode = postgresErrorCode(error);
+    if (pgCode === '22021' || pgCode === '22P05') {
+      return c.json(
+        {
+          error: {
+            code: 'invalid_characters',
+            message: 'Request contains characters that cannot be stored (e.g. a NUL byte)'
+          }
+        },
+        400
+      );
+    }
+    // JSON.stringify is recursive: a deeply nested body blows the V8 stack
+    // (`RangeError`) or exceeds the maximum string length. Both are client
+    // input, not server faults. middleware/json-depth.ts rejects these at the
+    // edge; this is the backstop for anything that builds a deep structure
+    // downstream. Narrow on the two known messages — a RangeError from
+    // anywhere else is a real bug and must stay a 500.
+    if (
+      error instanceof RangeError &&
+      /maximum call stack size exceeded|invalid string length/i.test(error.message)
+    ) {
+      return c.json(
+        { error: { code: 'payload_too_deep', message: 'Request payload is nested too deeply' } },
+        400
+      );
+    }
+    (c.get('logger') ?? logger).error({ err: error }, 'unhandled error');
+    return c.json({ error: { code: 'internal', message: 'Internal server error' } }, 500);
+  });
+
+  app.route(
+    '/',
+    healthRoutes(state, {
+      ...(probeStorage ? { probeStorage } : {}),
+      onStorageFailure: (err) => logger.error({ err }, 'storage probe failed — reporting not ready')
+    })
+  );
+  if (metricsRoutes) app.route('/', metricsRoutes);
+
+  app.route('/api/v1', api);
+  if (mcp) app.route('/mcp', mcp);
+  if (wellKnown) app.route('/', wellKnown);
+
+  // The public-route slot: the share-link viewer lives here — before the
+  // static assets and the SPA fallback, after every credentialed surface.
+  if (publicRoutes) app.route('/', publicRoutes);
+
+  app.use('*', serveStatic({ root: publicDir }));
+
+  app.get('*', (c) => {
+    if (indexHtml) return c.html(indexHtml);
+    return c.html(
+      `<!doctype html><title>${displayName}</title><h1>${displayName} API is running</h1>` +
+        '<p>No dashboard build found. API health: <a href="/healthz">/healthz</a></p>'
+    );
+  });
+
+  return app;
+}

package/src/audit/filters.ts

@@ -0,0 +1,101 @@
+import { and, eq, gte, ilike, inArray, isNull, like, lte, or, type SQL } from 'drizzle-orm';
+import { AUDIT_ACTOR_SYSTEM, type AuditListQuery, type AuditVia } from '@antasphere/chassis-contract';
+import { auditLog, user as userTable } from '@antasphere/chassis-db';
+
+/**
+ * The audit list's WHERE, from the validated query. Every value arrives as
+ * a bound parameter (drizzle's `eq`/`like`/`ilike` never interpolate), and
+ * the free-text ones are escaped as LIKE patterns first, so a `%` or `_` in
+ * what the admin typed matches itself rather than anything.
+ */
+
+/** A LIKE pattern for "contains this text", the wildcards of the text itself escaped. */
+export function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+
+/**
+ * The `action` list, split and de-duplicated: an item ending in `.` is a
+ * family (a prefix), any other item is one action. The contract has already
+ * bounded the count and the alphabet; empty items are dropped here.
+ */
+export function parseActionList(value: string): { exact: string[]; families: string[] } {
+  const exact = new Set<string>();
+  const families = new Set<string>();
+  for (const raw of value.split(',')) {
+    const item = raw.trim();
+    if (!item) continue;
+    if (item.endsWith('.')) families.add(item);
+    else exact.add(item);
+  }
+  return { exact: [...exact], families: [...families] };
+}
+
+/** The `actorVia` list, split and de-duplicated (the contract pinned the alphabet). */
+export function parseViaList(value: string): AuditVia[] {
+  return [...new Set(value.split(',').map((v) => v.trim()))].filter((v): v is AuditVia =>
+    ['session', 'api_key', 'oauth', 'system'].includes(v)
+  );
+}
+
+/**
+ * The cursor, or null when absent, malformed or out of range. Malformed
+ * cursors serve page 1; out-of-range ones are refused the same way, since
+ * Number('99999999999999999999') is finite but past bigint precision, and
+ * sending it to the `lt(id, …)` comparison overflows in Postgres.
+ * Safe-integer is the honest bound for a JS-roundtripped bigserial id.
+ */
+export function cursorId(cursor: string | undefined): number | null {
+  const parsed = cursor ? Number(cursor) : null;
+  return parsed !== null && Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+/**
+ * The filter conditions (the workspace scope and the cursor are the
+ * caller's): one AND-ed list, each member a parameterised comparison.
+ * Returns an empty list when nothing filters.
+ */
+export function auditFilterConditions(query: AuditListQuery): SQL[] {
+  const conditions: SQL[] = [];
+
+  if (query.q) {
+    const pattern = `%${escapeLike(query.q)}%`;
+    const either = or(ilike(userTable.email, pattern), ilike(auditLog.action, pattern));
+    if (either) conditions.push(either);
+  }
+
+  if (query.action) {
+    const { exact, families } = parseActionList(query.action);
+    const alternatives: SQL[] = [];
+    if (exact.length) alternatives.push(inArray(auditLog.action, exact));
+    for (const family of families) alternatives.push(like(auditLog.action, `${escapeLike(family)}%`));
+    const anyOf = alternatives.length ? or(...alternatives) : undefined;
+    if (anyOf) conditions.push(anyOf);
+  }
+
+  if (query.actorVia) {
+    const vias = parseViaList(query.actorVia);
+    if (vias.length) conditions.push(inArray(auditLog.actorVia, vias));
+  }
+
+  if (query.actor) {
+    conditions.push(
+      query.actor === AUDIT_ACTOR_SYSTEM
+        ? isNull(auditLog.actorUserId)
+        : eq(auditLog.actorUserId, query.actor)
+    );
+  }
+
+  if (query.resourceType) conditions.push(eq(auditLog.resourceType, query.resourceType));
+  if (query.resourceId) conditions.push(eq(auditLog.resourceId, query.resourceId));
+  if (query.from) conditions.push(gte(auditLog.createdAt, new Date(query.from)));
+  if (query.to) conditions.push(lte(auditLog.createdAt, new Date(query.to)));
+
+  return conditions;
+}
+
+/** The whole WHERE: the scope, the filters, and the keyset cursor when there is one. */
+export function auditWhere(scope: SQL, filters: SQL[], cursor: SQL | null): SQL {
+  const all = [scope, ...filters, ...(cursor ? [cursor] : [])];
+  return and(...all) ?? scope;
+}

package/src/audit/index.ts

@@ -0,0 +1,9 @@
+export {
+  auditFilterConditions,
+  auditWhere,
+  cursorId,
+  escapeLike,
+  parseActionList,
+  parseViaList
+} from './filters.js';
+export { AuditService, type AuditWrite, auditMiddleware } from './service.js';