@everystack/api 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "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,83 @@
+/**
+ * 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.
+ *
+ * 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. */
+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. */
+  caller: string | null;
+  /** The subject accessed — the id from the configured 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;
+}
+
+/** Audit configuration. Records are emitted only for the RPCs listed in `rpc`. */
+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.
+   *  Example: { get_user: { subject: 'p_user_id' } } */
+  rpc?: Record<string, { subject?: 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.
+ */
+export async function emitRpcAudit(
+  audit: AuditConfig | undefined,
+  action: string,
+  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;
+
+  const rawSubject = entry.subject ? body?.[entry.subject] : undefined;
+
+  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 } : {}),
+  };
+
+  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 { emitRpcAudit, type AuditConfig } from './audit';
+export type { AuditConfig, AuditRecord } 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' } */
@@ -177,6 +189,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. */
+  audit?: AuditConfig;
 }
 
 function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): DrizzleColumn | null {
@@ -437,13 +453,16 @@ 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.
+    // 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 +533,8 @@ 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;
         try {
           // Plain RPCs dispatch directly — wrapping them in the settings
           // transaction deadlocks single-connection pools (the fn's queries
@@ -527,8 +548,12 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
                 (tx) => fn(body, user, client, tx),
               )
             : 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);
           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);
           }

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.',
+    );
+  }
+}