@everystack/api 0.2.6 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/handler/audit.ts

@@ -0,0 +1,180 @@
+/**
+ * Forensic audit logging at the dispatch choke point.
+ *
+ * Distinct from observability. Observability answers "is the system healthy?" —
+ * counts, latency, errors. Audit answers "did principal X access subject Y's PII?",
+ * the question the platform must be able to answer after an incident. The handler is
+ * the only place the caller's identity, the action, and the params all meet, so the
+ * record is captured here and handed to an app-provided append-only sink.
+ *
+ * Captures the **query, not the response**: who, what (method + table or RPC), which
+ * (the filter and the column *names* a write touched — never values), and the outcome.
+ * No row contents, no before/after — that keeps the trail low-sensitivity and needs no
+ * DB triggers. Every **non-GET** request (writes + RPCs) is recorded when a sink is
+ * configured — not an opt-in list, so there's no forgot-to-declare gap. GET reads are
+ * delegated to RLS (a sound RLS read returns only self-data). See
+ * docs/plans/forensic-audit-spec.md.
+ *
+ * The sink should be append-only with integrity (e.g. S3 Object-Lock / WORM) — an
+ * audit log the app's own DB role can rewrite is not evidence. A sink failure is
+ * logged loudly (a dropped record is never silent) but does not fail the request:
+ * audit outage must not become read outage.
+ */
+
+/** Whether the access was allowed, refused (authz/validation), or faulted (system error). */
+export type AuditOutcome = 'allow' | 'deny' | 'error';
+
+/** What kind of principal made the call. */
+export type PrincipalKind = 'user' | 'client' | 'system' | 'anonymous';
+
+/** One recorded access of the non-GET surface. */
+export interface AuditRecord {
+  /** ISO-8601 timestamp of the access. */
+  ts: string;
+  /** Request correlation id — the trace-id spine. Sourced from the CloudFront
+   *  request id (`x-amz-cf-id`), which matches `x-edge-request-id` in the access log. */
+  requestId?: string;
+  // WHO
+  /** The principal id: the user `sub`, the client id, or null when anonymous. */
+  caller: string | null;
+  /** Whether the principal is a user, a client (machine), system, or anonymous. */
+  principalKind: PrincipalKind;
+  /** The principal's role, when known (from the JWT claims). */
+  role?: string;
+  // WHAT
+  /** The action — `rpc:<fn>` or `rest:<table>`. */
+  action: string;
+  /** For REST: the table and the operation performed. */
+  resource?: { table: string; operation: 'insert' | 'update' | 'delete' | 'select' };
+  /** For REST writes/deletes: the WHERE predicate (query string) — ids, not values. */
+  filter?: string;
+  /** For writes: the column NAMES the body touched. Never values — values can be PII. */
+  columns?: string[];
+  // WHOM
+  /** The subject accessed — the id from the configured RPC subject param, or null. */
+  subject: string | null;
+  // OUTCOME
+  /** allow (succeeded), deny (refused — authz/validation), or error (system fault). */
+  result: AuditOutcome;
+  // provenance
+  /** Stamped from AuditConfig for multi-app/stage trails. */
+  app?: string;
+  stage?: string;
+}
+
+/** Audit configuration. When a `sink` is set, every non-GET request is recorded. */
+export interface AuditConfig {
+  /** Append-only sink for audit records. The app provides a WORM-backed writer
+   *  (e.g. S3 Object-Lock). Awaited per request, so a well-behaved sink gives
+   *  durability before the response; a throwing sink is logged, never fatal. */
+  sink: (record: AuditRecord) => void | Promise<void>;
+  /** Optional subject-extraction hints per RPC — which body param identifies the
+   *  subject. NOT a gate: with a sink set, every non-GET request is audited; this
+   *  only enriches the `subject` field for the SECDEF PII-read functions.
+   *  Example: { get_user: { subject: 'p_user_id' } } */
+  rpc?: Record<string, { subject?: string }>;
+  /** Stamped on every record (multi-app / multi-stage trails). */
+  app?: string;
+  stage?: string;
+}
+
+/**
+ * The request-scoped context threaded to RPC handlers so app code (e.g. job enqueue)
+ * can carry the trace-id spine and the verified actor one hop downstream. The actor is
+ * verified at the handler; a worker inherits it from the job envelope (it can't
+ * re-verify a queued job). See the spec's "self-sufficient record" rule.
+ */
+export interface RequestContext {
+  requestId: string;
+  actor: { kind: PrincipalKind; id: string | null; role?: string };
+}
+
+/** Resolve the principal (and role) from the verified user / identified client. */
+export function resolvePrincipal(
+  user: Record<string, unknown> | null,
+  client: Record<string, unknown> | null,
+): { id: string | null; kind: PrincipalKind; role?: string } {
+  if (user && typeof user.sub === 'string') {
+    return {
+      id: user.sub,
+      kind: 'user',
+      ...(typeof user.role === 'string' ? { role: user.role } : {}),
+    };
+  }
+  if (client) {
+    // App-defined client object; by convention carries `id` (or `clientId`).
+    const raw = client.id ?? client.clientId;
+    return { id: raw == null ? null : String(raw), kind: 'client' };
+  }
+  return { id: null, kind: 'anonymous' };
+}
+
+/** Inputs the dispatch layer hands to emitAudit. */
+export interface AuditInput {
+  /** `rpc` (RPC dispatch) or `rest` (table write). */
+  kind: 'rpc' | 'rest';
+  /** The RPC function name, or the REST table name. */
+  name: string;
+  user: Record<string, unknown> | null;
+  client: Record<string, unknown> | null;
+  result: AuditOutcome;
+  requestId?: string;
+  /** RPC body — used to extract the subject via the AuditConfig hint. */
+  body?: Record<string, unknown>;
+  /** REST: the operation. */
+  operation?: 'insert' | 'update' | 'delete' | 'select';
+  /** REST: the WHERE predicate (query string). */
+  filter?: string;
+  /** REST writes: the column names the body touched. */
+  columns?: string[];
+}
+
+/**
+ * Emit one audit record for a non-GET access. No-op when no sink is configured.
+ * Never throws — a sink failure is logged loudly (never silent) but must not break
+ * the request.
+ */
+export async function emitAudit(audit: AuditConfig | undefined, input: AuditInput): Promise<void> {
+  if (!audit?.sink) return;
+
+  const principal = resolvePrincipal(input.user, input.client);
+
+  // RPC subject from the configured hint; REST has no per-row subject here (the
+  // `filter` is the target descriptor).
+  let subject: string | null = null;
+  if (input.kind === 'rpc') {
+    const param = audit.rpc?.[input.name]?.subject;
+    const raw = param ? input.body?.[param] : undefined;
+    subject = raw == null ? null : String(raw);
+  }
+
+  const record: AuditRecord = {
+    ts: new Date().toISOString(),
+    action: `${input.kind}:${input.name}`,
+    caller: principal.id,
+    principalKind: principal.kind,
+    subject,
+    result: input.result,
+    ...(principal.role ? { role: principal.role } : {}),
+    ...(input.requestId ? { requestId: input.requestId } : {}),
+    ...(input.kind === 'rest' && input.operation
+      ? { resource: { table: input.name, operation: input.operation } }
+      : {}),
+    ...(input.filter ? { filter: input.filter } : {}),
+    ...(input.columns && input.columns.length ? { columns: input.columns } : {}),
+    ...(audit.app ? { app: audit.app } : {}),
+    ...(audit.stage ? { stage: audit.stage } : {}),
+  };
+
+  try {
+    await audit.sink(record);
+  } catch (err) {
+    // A dropped audit record is a forensic gap — make it loud, never silent.
+    // But do not fail the request on an audit-sink outage (availability).
+    console.error(
+      `[everystack/api] audit sink failed; record dropped: `
+      + `action=${record.action} caller=${record.caller} subject=${record.subject}`,
+      err,
+    );
+  }
+}

package/src/handler/index.ts

@@ -8,6 +8,10 @@
  */
 
 import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, and, or, not, asc, desc, sql } from 'drizzle-orm';
+import { emitAudit, resolvePrincipal, type AuditConfig, type RequestContext } from './audit';
+export type { AuditConfig, AuditRecord, RequestContext, AuditOutcome, PrincipalKind } from './audit';
+export { getPublicSurface, assertPublicSurface } from './public-surface';
+export type { PublicSurface } from './public-surface';
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
 type DrizzleDb = any;
@@ -47,11 +51,19 @@ export interface AuthConfig {
   publicRpc?: string[];
   /** Called after successful authentication with the user payload */
   onAuthenticated?: (user: Record<string, unknown>) => void;
-  /** Verify client credentials and return client metadata, or null if invalid.
-   *  When configured, every request must provide client headers OR a Referer/Origin header.
-   *  Called with (clientId, clientSecret, referer) — the callback decides which path to validate:
-   *    - Secret-based (native/server): clientId + clientSecret present
-   *    - Referer-based (web): referer present, no secret */
+  /** Identify the calling app and return client metadata, or null to reject.
+   *  Called with (clientId, clientSecret, referer); the callback picks the path:
+   *    - Secret-based (native/server): clientId + clientSecret — a real shared secret.
+   *    - Referer-based (web): referer/origin only — browsers can't hold a secret.
+   *
+   *  SECURITY: this is *identification*, not a trust boundary. The referer/origin
+   *  path is NOT authentication — Origin/Referer are trivially spoofable by any
+   *  non-browser caller (curl, a script), so a referer-validated client is an
+   *  UNTRUSTED public client and passing here proves nothing about the caller.
+   *  Never gate sensitive data on client auth alone — real authorization is the
+   *  user JWT + RLS (see verifyToken). Anything in `publicRpc` is reachable by the
+   *  whole internet. (Origin is sound only as a CSRF signal on cookie auth — never
+   *  as a data-access gate; the two threat models are different.) */
   verifyClient?: (clientId: string, clientSecret: string, referer?: string) => Promise<Record<string, unknown> | null>;
   /** Custom header names for client credentials.
    *  Defaults: { id: 'X-Client-Id', secret: 'X-Client-Secret' } */
@@ -111,9 +123,11 @@ export interface CacheConfig {
 /** RPC handler — plain function (backward compatible).
  *  Plain handlers dispatch directly: no transaction, no pgSettings — they own
  *  their DB access through whatever they close over, same privilege model as
- *  SSR loaders. The optional 4th argument is only provided to handlers
- *  registered with `settings: true` (see RpcHandlerWithRole). */
-export type RpcHandler = (body: unknown, user?: Record<string, unknown> | null, client?: Record<string, unknown> | null, db?: DrizzleDb) => Promise<unknown>;
+ *  SSR loaders. The optional 4th argument (`db`) is only provided to handlers
+ *  registered with `settings: true` (see RpcHandlerWithRole); plain handlers
+ *  receive `ctx` as the 4th argument instead. The final `ctx` carries the
+ *  trace-id spine (requestId + verified actor) for downstream propagation. */
+export type RpcHandler = (body: unknown, user?: Record<string, unknown> | null, client?: Record<string, unknown> | null, db?: DrizzleDb | RequestContext, ctx?: RequestContext) => Promise<unknown>;
 
 /** RPC handler with per-function role requirement and/or RLS context opt-in */
 export interface RpcHandlerWithRole {
@@ -177,6 +191,11 @@ export interface HandlerOptions {
   /** When true, error messages hide internal details (table names, column names, operators).
    *  Enable in production to prevent schema enumeration. Default: false. */
   hideSchemaErrors?: boolean;
+  /** Forensic audit logging (distinct from observability). When a sink is set,
+   *  records every non-GET request (writes + RPCs) — the query, not the response —
+   *  to an app-provided append-only sink, stamped with the trace-id (`x-amz-cf-id`).
+   *  GET is delegated to RLS. See AuditConfig. */
+  audit?: AuditConfig;
 }
 
 function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): DrizzleColumn | null {
@@ -437,13 +456,23 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
     const pathSegments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
     const method = request.method.toUpperCase();
 
-    // Phase 1: Client auth (if configured) — identifies which app is calling
-    // Supports two validation paths:
-    //   1. Header-based (native/server): X-Client-Id + X-Client-Secret
-    //   2. Referer-based (web): Referer or Origin header (no secrets in browser source)
-    // The verifyClient callback receives all three and decides which path to validate.
-    // Skipped for publicRoutes methods (e.g. GET) — no credentials needed.
-    // publicRpc skips JWT verification only, NOT client auth.
+    // The trace-id spine. Source from the CloudFront request id (`x-amz-cf-id`,
+    // added to every origin request) so the handler audit joins straight to the
+    // access log's `x-edge-request-id`. Falls back to trace/request ids off-CDN.
+    const requestId = request.headers.get('x-amz-cf-id')
+      ?? request.headers.get('x-amzn-trace-id')
+      ?? request.headers.get('x-request-id') ?? undefined;
+
+    // Phase 1: Client *identification* (if configured) — which app is calling.
+    // NOT a trust boundary. Two paths:
+    //   1. Secret-based (native/server): X-Client-Id + X-Client-Secret — a real secret.
+    //   2. Referer/Origin (web): the browser can't hold a secret, so this path has none.
+    //      Origin/Referer are spoofable by any non-browser caller, so a referer-only
+    //      client is UNTRUSTED — passing here proves nothing about the caller.
+    // Real authorization is Phase 2 (JWT + role) + RLS; client auth must never be the
+    // sole gate for sensitive data. Skipped for publicRoutes methods (e.g. GET).
+    // publicRpc skips JWT verification only, NOT client identification — so a publicRpc
+    // backed by this alone is internet-reachable. Treat the publicRpc list as public.
     let user: Record<string, unknown> | null = null;
     let client: Record<string, unknown> | null = null;
     const isPublicRoute = options?.auth?.publicRoutes?.includes(method) ?? false;
@@ -514,6 +543,11 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
 
         const fn = isObjectForm ? entry.fn : entry;
         const body = method === 'POST' ? await request.json().catch(() => ({})) : {};
+        // Request-scoped context for the trace-id spine — RPC handlers receive it
+        // as a trailing arg (plain: 4th; settings: 5th, after tx) so app code can
+        // carry requestId + the verified actor one hop into jobs. Existing fns that
+        // ignore the extra arg are unaffected.
+        const ctx: RequestContext = { requestId: requestId ?? '', actor: resolvePrincipal(user, client) };
         try {
           // Plain RPCs dispatch directly — wrapping them in the settings
           // transaction deadlocks single-connection pools (the fn's queries
@@ -524,21 +558,33 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
             ? await executeWithSettings(
                 db,
                 options?.pgSettings?.(user, client),
-                (tx) => fn(body, user, client, tx),
+                (tx) => fn(body, user, client, tx, ctx),
               )
-            : await fn(body, user, client);
+            : await fn(body, user, client, ctx);
+          // Forensic audit: every non-GET is recorded when a sink is configured.
+          await emitAudit(options?.audit, {
+            kind: 'rpc', name: fnName, user, client,
+            result: 'allow', requestId, body: body as Record<string, unknown>,
+          });
           return json(result, 200);
         } catch (error) {
-          if (error instanceof HandlerError) {
-            return json({ message: error.message }, error.status);
-          }
-          const message = error instanceof Error ? error.message : 'RPC execution failed';
           const pgCode = (error as any)?.code;
           let status = 500;
           if (pgCode === '28P01') status = 401;
           else if (pgCode === '42501') status = 403;
           else if (pgCode === '23505') status = 409;
           else if (pgCode === '22023' || pgCode === 'P0001') status = 422;
+          // Split the outcome: an authz/validation refusal (4xx) is `deny`; a
+          // system fault (5xx) is `error`. Conflating them blinds an investigation.
+          const refused = error instanceof HandlerError ? error.status < 500 : status < 500;
+          await emitAudit(options?.audit, {
+            kind: 'rpc', name: fnName, user, client,
+            result: refused ? 'deny' : 'error', requestId, body: body as Record<string, unknown>,
+          });
+          if (error instanceof HandlerError) {
+            return json({ message: error.message }, error.status);
+          }
+          const message = error instanceof Error ? error.message : 'RPC execution failed';
           if (options?.hideSchemaErrors && status === 500) {
             return json({ message: 'Internal Server Error' }, 500);
           }
@@ -583,8 +629,24 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
     const settings = options?.pgSettings?.(user, client);
     const table = schema[tableName];
 
+    // Forensic audit of the non-GET table surface (writes). Capture the query, not
+    // the response: the operation, the WHERE predicate, and the body's column NAMES
+    // (never values — values can be PII). GET is delegated to RLS, never audited.
+    const isWrite = method === 'POST' || method === 'PATCH' || method === 'DELETE';
+    const auditOp: 'insert' | 'update' | 'delete' =
+      method === 'POST' ? 'insert' : method === 'PATCH' ? 'update' : 'delete';
+    const auditFilter = url.searchParams.toString() || undefined;
+    let auditColumns: string[] | undefined;
+    if (isWrite && options?.audit?.sink && method !== 'DELETE') {
+      // Cheap clone (writes are low-volume) so the handler still reads the body.
+      const cloned = await request.clone().json().catch(() => null);
+      if (cloned && typeof cloned === 'object' && !Array.isArray(cloned)) {
+        auditColumns = Object.keys(cloned as Record<string, unknown>);
+      }
+    }
+
     try {
-      return await executeWithSettings(db, settings, async (dbOrTx) => {
+      const response = await executeWithSettings(db, settings, async (dbOrTx) => {
         if (method === 'GET') {
           const cacheControl = getCacheControl(options);
           return handleGet(dbOrTx, schema, table, tableName, url.searchParams, request, options, cacheControl);
@@ -604,7 +666,22 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
 
         return json({ message: `Method ${method} not allowed` }, 405);
       });
+      if (isWrite) {
+        await emitAudit(options?.audit, {
+          kind: 'rest', name: tableName, user, client,
+          result: response.status < 400 ? 'allow' : response.status < 500 ? 'deny' : 'error',
+          requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
+        });
+      }
+      return response;
     } catch (error) {
+      if (isWrite) {
+        await emitAudit(options?.audit, {
+          kind: 'rest', name: tableName, user, client,
+          result: isPermissionDenied(error) ? 'deny' : 'error',
+          requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
+        });
+      }
       if (isPermissionDenied(error)) {
         return sanitizeError('Permission denied', 403, options);
       }

package/src/handler/public-surface.ts

@@ -0,0 +1,74 @@
+/**
+ * Public-surface guard.
+ *
+ * `publicRoutes` (HTTP methods that skip auth) and `publicRpc` (RPC names that skip
+ * JWT) are the explicitly internet-reachable surface. Client auth is NOT a gate for
+ * them — Origin/Referer is spoofable, so anything here is reachable by the whole
+ * internet (see verifyClient). This guard makes that surface a signed-off registry:
+ * snapshot the approved set in a test and any silent addition fails it. Each entry
+ * is a deliberate "safe to hand the whole internet" decision, not an accident.
+ *
+ *   import { assertPublicSurface } from '@everystack/api';
+ *   it('public surface is signed off', () => {
+ *     assertPublicSurface(handlerOptions, {
+ *       publicRoutes: ['GET'],
+ *       publicRpc: ['health', 'signup', 'signin'],  // each reviewed as internet-safe
+ *     });
+ *   });
+ */
+
+/** The explicitly internet-reachable surface. */
+export interface PublicSurface {
+  /** HTTP methods served without authentication. */
+  publicRoutes: string[];
+  /** RPC function names served without a JWT. */
+  publicRpc: string[];
+}
+
+/** Minimal structural view of the parts of HandlerOptions this reads. */
+type PublicSurfaceSource = {
+  auth?: { publicRoutes?: string[]; publicRpc?: string[] };
+} | undefined;
+
+/** Extract the live public surface from handler options (sorted, deduped-by-source). */
+export function getPublicSurface(options: PublicSurfaceSource): PublicSurface {
+  return {
+    publicRoutes: [...(options?.auth?.publicRoutes ?? [])].sort(),
+    publicRpc: [...(options?.auth?.publicRpc ?? [])].sort(),
+  };
+}
+
+function diff(live: string[], approved: string[]): { added: string[]; removed: string[] } {
+  return {
+    added: live.filter(x => !approved.includes(x)),
+    removed: approved.filter(x => !live.includes(x)),
+  };
+}
+
+/**
+ * Assert the live public surface equals the approved set. Throws on ANY drift —
+ * an addition (new internet-reachable surface that wasn't signed off) or a removal
+ * (the approved list is stale). Use as a test gate so the attack surface can't grow
+ * silently.
+ */
+export function assertPublicSurface(options: PublicSurfaceSource, approved: PublicSurface): void {
+  const live = getPublicSurface(options);
+  const routes = diff(live.publicRoutes, [...approved.publicRoutes].sort());
+  const rpc = diff(live.publicRpc, [...approved.publicRpc].sort());
+
+  const problems: string[] = [];
+  if (routes.added.length) problems.push(`publicRoutes added (internet-reachable, unsigned): ${routes.added.join(', ')}`);
+  if (rpc.added.length) problems.push(`publicRpc added (internet-reachable, unsigned): ${rpc.added.join(', ')}`);
+  if (routes.removed.length) problems.push(`publicRoutes in the approved set but no longer live: ${routes.removed.join(', ')}`);
+  if (rpc.removed.length) problems.push(`publicRpc in the approved set but no longer live: ${rpc.removed.join(', ')}`);
+
+  if (problems.length) {
+    throw new Error(
+      '[everystack/api] public surface drift — the internet-reachable surface changed '
+      + 'without sign-off:\n  ' + problems.join('\n  ')
+      + '\nEvery publicRoutes/publicRpc entry is reachable by the whole internet with no '
+      + 'JWT (client auth is not a gate). Update the approved set only after confirming '
+      + 'each entry is safe to expose.',
+    );
+  }
+}