@everystack/api 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.7",
+  "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

@@ -7,66 +7,163 @@
  * 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.
  */
 
-/** One recorded access of a sensitive surface. */
+/** 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;
-  /** The action — the RPC function name. */
-  action: string;
-  /** The authenticated caller (user `sub`), or null if unauthenticated. */
+  /** 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;
-  /** The subject accessed — the id from the configured subject param, or 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;
-  /** Whether the call succeeded ('allow') or errored/was denied ('deny'). */
-  result: 'allow' | 'deny';
-  /** Optional request correlation id. */
-  requestId?: string;
+  // 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. Records are emitted only for the RPCs listed in `rpc`. */
+/** 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>;
-  /** Which RPC functions are sensitive, and how to derive the subject id from the
-   *  request body. The surfaces that bypass RLS (SECDEF PII reads: get_user,
-   *  export_user_data, …) belong here by default.
+  /** 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;
 }
 
 /**
- * Emit an audit record for a sensitive RPC, if one is configured for `action`.
- * No-op when the function isn't audited. Never throws — a sink failure is logged
- * loudly (never silent) but must not break the request.
+ * 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 async function emitRpcAudit(
-  audit: AuditConfig | undefined,
-  action: string,
+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,
-  body: Record<string, unknown> | undefined,
-  result: 'allow' | 'deny',
-  requestId?: string,
-): Promise<void> {
-  const entry = audit?.rpc?.[action];
-  if (!audit || !entry) return;
+  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[];
+}
 
-  const rawSubject = entry.subject ? body?.[entry.subject] : undefined;
+/**
+ * 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,
-    caller: typeof user?.sub === 'string' ? user.sub : null,
-    subject: rawSubject == null ? null : String(rawSubject),
-    result,
-    ...(requestId ? { requestId } : {}),
+    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 {

package/src/handler/index.ts

@@ -8,8 +8,8 @@
  */
 
 import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, and, or, not, asc, desc, sql } from 'drizzle-orm';
-import { emitRpcAudit, type AuditConfig } from './audit';
-export type { AuditConfig, AuditRecord } from './audit';
+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';
 
@@ -123,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 {
@@ -189,9 +191,10 @@ 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 for sensitive RPCs (distinct from observability).
-   *  Records (caller, action, subject, result, ts) to an app-provided append-only
-   *  sink for the listed functions — the surfaces that bypass RLS. See AuditConfig. */
+  /** 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;
 }
 
@@ -453,6 +456,13 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
     const pathSegments = pathname.replace(/^\/+/, '').split('/').filter(Boolean);
     const method = request.method.toUpperCase();
 
+    // 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.
@@ -533,8 +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(() => ({})) : {};
-        const auditReqId = request.headers.get('x-amzn-trace-id')
-          ?? request.headers.get('x-request-id') ?? undefined;
+        // 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
@@ -545,25 +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);
-          // Forensic audit: record access of a sensitive surface (no-op unless configured).
-          await emitRpcAudit(options?.audit, fnName, user, body as Record<string, unknown>, 'allow', auditReqId);
+            : 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) {
-          // A denied/errored access is forensically relevant too — record it.
-          await emitRpcAudit(options?.audit, fnName, user, body as Record<string, unknown>, 'deny', auditReqId);
-          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);
           }
@@ -608,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);
@@ -629,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);
       }