@everystack/api 0.2.12 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to `@everystack/api` are documented here.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+### Added
+
+- auto-generated changelogs from conventional commits
+- automate the version-drift check — a manual note is not a gate
+
+## [0.4.0] - 2026-07-14
+
+### Added
+
+- forward-port afterRpc + read-replica routing from the 0.2.x line
+
+### Fixed
+
+- surface caught 5xx exceptions to the observability sink
+- verify tokens opportunistically on public RPCs, like public table routes
+- RPC responses carry the same Cache-Control discipline as table GETs
+- multi-word tables route under both naming domains
+
+## [0.2.8] - 2026-06-18
+
+### Added
+
+- forensic audit capture for every non-GET request (trace-id spine)
+
+## [0.2.7] - 2026-06-18
+
+### Added
+
+- forensic audit capture, public-surface guard, honest verifyClient framing
+
+## [0.2.6] - 2026-06-17
+
+### Removed
+
+- remove onMutation callback — events replaces it
+
+### Added
+
+- add Drizzle relational query (JOIN) support for relation embedding
+- add CloudFront KVS cache versioning with CLI purge and auto-invalidation
+- add pgSettings for PostgreSQL RLS context injection
+- add not operator negation and or()/and() logical groups
+- add aggregate queries with GROUP BY support
+- add per-table lifecycle hooks for mutations
+- add optional two-tier client credentials auth
+- add JSON path filtering for JSONB columns
+- add negation and logical group helpers
+- add RBAC and snake_case naming convention
+- add CloudFront edge auth, response caching, and CDN docs
+- configurable per-origin cache headers + image EXIF fix
+- add exposedTables and hiddenColumns options
+- support referer-based client auth for web apps
+- RPC-backed row actions on the show view
+- extensibility, unified view, observability + Track B rollup
+
+### Fixed
+
+- add SET LOCAL ROLE to executeWithSettings for RLS enforcement
+- resolve 5 pre-production security blockers from red team audit
+- resolve 7 high-priority security findings from red team audit
+- resolve 7 medium-priority security findings from red team audit
+- resolve 9 low/medium-priority security findings from red team audit
+- skip client auth for publicRoutes methods
+- pin all dependency versions to lockfile-resolved values
+- pgSettings on RPC, publicRpc client auth bypass, logs:tail log group resolution
+- catch PostgreSQL errors in RPC execution path
+- opportunistic auth on public routes, hiddenColumns ordering
+- enforce client auth on publicRpc endpoints
+- RPCs run unwrapped by default; opt into pgSettings via settings:true
+
+### Changed
+
+- split expo-stack into discrete packages and remove @jest/globals imports
+- consolidate authorization to PostgreSQL as single source of truth
+- drop type module from all packages, switch Jest to CJS mode
+- consolidate Jest configs into shared base
+
+### Documentation
+
+- rewrite documentation around V1→V2→V3 progressive complexity model
+- update all documentation to reflect full API surface
+- prepare documentation for open-source release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.12",
+  "version": "0.4.1",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",
@@ -18,14 +18,17 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "exports": {
     "./handler": {
+      "source": "./src/handler/index.ts",
       "types": "./src/handler/index.ts",
       "default": "./src/handler/index.ts"
     },
     "./client": {
+      "source": "./src/client/index.ts",
       "types": "./src/client/index.ts",
       "default": "./src/client/index.ts"
     }
@@ -38,6 +41,7 @@
     "@types/node": "22.19.18",
     "drizzle-orm": "0.41.0",
     "jest": "29.7.0",
+    "postgres": "3.4.9",
     "ts-jest": "29.4.9",
     "typescript": "5.9.3"
   },

package/src/handler/index.ts

@@ -471,15 +471,24 @@ function transformResponse(data: unknown, options?: HandlerOptions): unknown {
   return transformKeys(data, toSnakeCase);
 }
 
-/** Strip protected fields from a request body before insert/update (mass assignment prevention). */
+/**
+ * Strip protected fields from a request body before insert/update (mass assignment prevention).
+ * Recurses per-row on an array body (bulk insert — db.insert(table).values() accepts one) so it
+ * comes back as an array, not `{...body}`'s indexed-object flattening of it (mirrors
+ * stripHiddenColumns below, which already gets this right on the response side).
+ */
 function stripProtectedFields(
-  body: Record<string, unknown>,
+  body: unknown,
   tableName: string,
   options?: HandlerOptions,
-): Record<string, unknown> {
+): unknown {
   const fields = options?.protectedFields?.[tableName];
   if (!fields || fields.length === 0) return body;
-  const result = { ...body };
+  if (Array.isArray(body)) return body.map(row => stripProtectedFields(row, tableName, options));
+  if (body === null || typeof body !== 'object') {
+    throw new HandlerError(400, `Invalid row in request body: expected an object, got ${JSON.stringify(body)}`);
+  }
+  const result = { ...(body as Record<string, unknown>) };
   for (const field of fields) {
     delete result[field];
   }
@@ -507,9 +516,14 @@ function stripHiddenColumns(
   return data;
 }
 
-function transformBodyKeys(body: Record<string, unknown>, table: DrizzleTable): Record<string, unknown> {
+/** Same array-preserving recursion as stripProtectedFields, for the same reason. */
+function transformBodyKeys(body: unknown, table: DrizzleTable): unknown {
+  if (Array.isArray(body)) return body.map(row => transformBodyKeys(row, table));
+  if (body === null || typeof body !== 'object') {
+    throw new HandlerError(400, `Invalid row in request body: expected an object, got ${JSON.stringify(body)}`);
+  }
   const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(body)) {
+  for (const [key, value] of Object.entries(body as Record<string, unknown>)) {
     if (table[key]) {
       result[key] = value;
     } else if (key.includes('_')) {
@@ -522,8 +536,131 @@ function transformBodyKeys(body: Record<string, unknown>, table: DrizzleTable):
   return result;
 }
 
-export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOptions): Handler {
+/**
+ * A JSON request body carries dates as plain strings (or epoch-millis numbers) — JSON has no
+ * Date type. Drizzle's date/timestamp/timestamptz columns default to "date" mode, where
+ * `mapToDriverValue` calls `value.toISOString()` unconditionally (see node_modules/drizzle-orm/
+ * pg-core/columns/{date,timestamp}.js) — anything else blows up there with `TypeError:
+ * value.toISOString is not a function`, surfacing as an opaque 500. Converts the value to a
+ * Date for exactly those columns before it ever reaches Drizzle; reads are untouched. Throws a
+ * HandlerError (the same convention hooks below already use) naming the field when the value
+ * doesn't parse, so the caller gets a 400 instead of that 500.
+ *
+ * A row of a bulk-insert array body is coerced independently, recursively — the shape (array
+ * or single row) must come back exactly as it went in, since `db.insert(table).values(...)`
+ * accepts either and a naive `{ ...body }` on an array silently corrupts it into
+ * `{"0": row0, "1": row1, ...}` (JS object-spread of an array indexes by position).
+ *
+ * String values are required to be ISO 8601, WITH an explicit offset/Z whenever a time-of-day is
+ * present — the bare `new Date(str)` constructor also accepts two ambiguous shapes that would
+ * silently store the WRONG instant with no error raised (the one outcome worse than the crash
+ * this function replaces): locale-dependent formats (`new Date('01/02/2020')` is 2 Jan, not the
+ * 1 Feb a DD/MM caller meant), and an offset-less datetime, which the spec parses as the
+ * SERVER's local time rather than UTC (verified: `TZ=America/New_York new
+ * Date('2020-01-01T00:00:00').toISOString()` → `2020-01-01T05:00:00.000Z`, 5 hours off, with no
+ * error). A bare date has no time-of-day to be ambiguous about, so it stays offset-optional. A
+ * number is unambiguous (epoch millis) and skips this check entirely.
+ */
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;
+
+function coerceDateColumnValues(body: unknown, table: DrizzleTable): unknown {
+  if (Array.isArray(body)) return body.map(row => coerceDateColumnValues(row, table));
+  if (body === null || typeof body !== 'object') {
+    throw new HandlerError(400, `Invalid row in request body: expected an object, got ${JSON.stringify(body)}`);
+  }
+
+  const result: Record<string, unknown> = { ...(body as Record<string, unknown>) };
+  for (const [key, value] of Object.entries(result)) {
+    if (typeof value !== 'string' && typeof value !== 'number') continue;
+    const column = getColumn(table, key);
+    if (!column || column.dataType !== 'date') continue;
+    if (typeof value === 'string' && !ISO_DATE_RE.test(value)) {
+      throw new HandlerError(400, `Invalid date value for "${key}": expected ISO 8601, got ${JSON.stringify(value)}`);
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new HandlerError(400, `Invalid date value for "${key}": ${JSON.stringify(value)}`);
+    }
+    result[key] = parsed;
+  }
+  return result;
+}
+
+/** The name a drizzle pgTable knows itself by in SQL, or null for a non-table export. */
+function sqlNameOf(value: unknown): string | null {
+  if (!value || typeof value !== 'object') return null;
+  const name = (value as Record<symbol, unknown>)[Symbol.for('drizzle:Name')];
+  return typeof name === 'string' ? name : null;
+}
+
+/** Export-key ↔ SQL-name pairs for every table whose two spellings differ. */
+function tableNamePairs(schema: Schema): Array<{ exportKey: string; sqlName: string }> {
+  const pairs: Array<{ exportKey: string; sqlName: string }> = [];
+  for (const [exportKey, value] of Object.entries(schema)) {
+    const sqlName = sqlNameOf(value);
+    if (sqlName && sqlName !== exportKey) pairs.push({ exportKey, sqlName });
+  }
+  return pairs;
+}
+
+/** The schema with each table reachable under BOTH spellings (existing keys win). */
+function expandSchema(schema: Schema, pairs: Array<{ exportKey: string; sqlName: string }>): Schema {
+  if (pairs.length === 0) return schema;
+  const expanded: Schema = { ...schema };
+  for (const { exportKey, sqlName } of pairs) {
+    if (!(sqlName in expanded)) expanded[sqlName] = schema[exportKey];
+  }
+  return expanded;
+}
+
+/**
+ * Table-keyed options written in EITHER naming domain apply to both spellings.
+ * `deriveHandlerConfig` emits SQL names; hand-written configs use export keys —
+ * each key gains its twin (same value reference), so neither authoring style
+ * can strand a table behind the other domain's gate.
+ */
+function expandTableKeyedOptions(
+  options: HandlerOptions | undefined,
+  pairs: Array<{ exportKey: string; sqlName: string }>,
+): HandlerOptions | undefined {
+  if (!options || pairs.length === 0) return options;
+  const twin = (name: string): string | undefined =>
+    pairs.find((p) => p.exportKey === name)?.sqlName ?? pairs.find((p) => p.sqlName === name)?.exportKey;
+  const expandList = (list: string[]): string[] =>
+    [...new Set(list.flatMap((name) => { const t = twin(name); return t ? [name, t] : [name]; }))];
+  const expandMap = <T,>(map: Record<string, T>): Record<string, T> => {
+    const out: Record<string, T> = { ...map };
+    for (const key of Object.keys(map)) {
+      const t = twin(key);
+      if (t && !(t in out)) out[t] = map[key];
+    }
+    return out;
+  };
+  return {
+    ...options,
+    ...(options.exposedTables ? { exposedTables: expandList(options.exposedTables) } : {}),
+    ...(options.hiddenColumns ? { hiddenColumns: expandMap(options.hiddenColumns) } : {}),
+    ...(options.protectedFields ? { protectedFields: expandMap(options.protectedFields) } : {}),
+    ...(options.rowOwnership ? { rowOwnership: expandMap(options.rowOwnership) } : {}),
+    ...(options.relations ? { relations: expandMap(options.relations) } : {}),
+    ...(options.hooks ? { hooks: expandMap(options.hooks) } : {}),
+    ...(options.softDelete?.tables
+      ? { softDelete: { ...options.softDelete, tables: expandList(options.softDelete.tables) } }
+      : {}),
+  };
+}
+
+export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: HandlerOptions): Handler {
+  // The naming seam: URLs, exposedTables, and relation targets historically mixed
+  // drizzle export keys (`texturePacks`) with SQL names (`texture_packs`), and any
+  // multi-word table failed one gate or the other — both spellings 404'd. Collapse
+  // the two domains here, once: both spellings route, and options in either domain
+  // apply. The root listing below stays one entry per table (the SQL name).
+  const namePairs = tableNamePairs(rawSchema);
+  const schema = expandSchema(rawSchema, namePairs);
+  const options = expandTableKeyedOptions(rawOptions, namePairs);
   const tableNames = new Set(Object.keys(schema));
+  const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
@@ -583,11 +720,12 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
       }
     }
 
-    // Root path — table listing, always public
+    // Root path — table listing, always public. One entry per table (SQL name),
+    // regardless of how many spellings route to it.
     if (pathSegments.length === 0) {
       const tables = options?.exposedTables
-        ? Array.from(tableNames).filter(t => options.exposedTables!.includes(t))
-        : Array.from(tableNames);
+        ? canonicalTables.filter(t => options.exposedTables!.includes(t))
+        : canonicalTables;
       return json({ tables }, 200);
     }
 
@@ -1441,14 +1579,20 @@ async function handlePost(
     return json({ message: 'Invalid JSON body' }, 400);
   }
 
-  // Map body keys to Drizzle property names when naming convention is active
-  if (options?.naming === 'snake_case') {
-    body = transformBodyKeys(body, table);
+  try {
+    // Map body keys to Drizzle property names when naming convention is active
+    if (options?.naming === 'snake_case') {
+      body = transformBodyKeys(body, table) as Record<string, unknown>;
+    }
+    // Strip protected fields before mutation (mass assignment prevention)
+    body = stripProtectedFields(body, tableName, options) as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof HandlerError) {
+      return json({ message: err.message }, err.status);
+    }
+    throw err;
   }
 
-  // Strip protected fields before mutation (mass assignment prevention)
-  body = stripProtectedFields(body, tableName, options);
-
   const hook = options?.hooks?.[tableName];
 
   if (hook?.beforeCreate) {
@@ -1462,7 +1606,17 @@ async function handlePost(
     }
   }
 
-  const rows = await db.insert(table).values(body).returning();
+  let coerced: unknown;
+  try {
+    coerced = coerceDateColumnValues(body, table);
+  } catch (err) {
+    if (err instanceof HandlerError) {
+      return json({ message: err.message }, err.status);
+    }
+    throw err;
+  }
+
+  const rows = await db.insert(table).values(coerced as Record<string, unknown>).returning();
 
   if (hook?.afterCreate && rows.length > 0) {
     try { await hook.afterCreate(rows[0], user, client); } catch {}
@@ -1488,14 +1642,20 @@ async function handlePatch(
     return json({ message: 'Invalid JSON body' }, 400);
   }
 
-  // Map body keys to Drizzle property names when naming convention is active
-  if (options?.naming === 'snake_case') {
-    body = transformBodyKeys(body, table);
+  try {
+    // Map body keys to Drizzle property names when naming convention is active
+    if (options?.naming === 'snake_case') {
+      body = transformBodyKeys(body, table) as Record<string, unknown>;
+    }
+    // Strip protected fields before mutation (mass assignment prevention)
+    body = stripProtectedFields(body, tableName, options) as Record<string, unknown>;
+  } catch (err) {
+    if (err instanceof HandlerError) {
+      return json({ message: err.message }, err.status);
+    }
+    throw err;
   }
 
-  // Strip protected fields before mutation (mass assignment prevention)
-  body = stripProtectedFields(body, tableName, options);
-
   const hook = options?.hooks?.[tableName];
 
   if (hook?.beforeUpdate) {
@@ -1531,7 +1691,17 @@ async function handlePatch(
     }
   }
 
-  let query: any = db.update(table).set(body);
+  let coerced: unknown;
+  try {
+    coerced = coerceDateColumnValues(body, table);
+  } catch (err) {
+    if (err instanceof HandlerError) {
+      return json({ message: err.message }, err.status);
+    }
+    throw err;
+  }
+
+  let query: any = db.update(table).set(coerced as Record<string, unknown>);
 
   if (conditions.length === 1) {
     query = query.where(conditions[0]);