@everystack/api 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.6] - 2026-10-16
+
+### BREAKING CHANGES
+
+- an undeclared embed in select now answers 400 instead of a 200 with the embed dropped
+- a JSON-path filter that cannot be built now answers 400 instead of being dropped; a DELETE or PATCH with such a filter used to run on the remaining filters alone
+
+### Added
+
+- cs, cd and ov array filter operators on text[] and varchar[] columns
+
+### Fixed
+
+- map integrity errors to safe client refusals
+- preserve legacy errors alongside integrity mapping
+- protect integrity diagnostics across failing tables
+- show integrity errors under matching form fields
+- the integrity mapper follows nested causes and keeps legacy hostile-value answers
+
+## [0.4.5] - 2026-10-15
+
+### BREAKING CHANGES
+
+- a PATCH with no row filter is now refused with 400, like DELETE; it used to update every row. Pass a filter such as ?id=eq.1
+- hiddenColumns hides a column under every spelling (security); an entry that names no column, or a table not in the schema, now makes createHandler throw at startup instead of logging a warning
+
+### Added
+
+- clean HTML columns on write and signal the change
+- state the sanitizer contract and bound promise handling
+
+### Fixed
+
+- sanitize on write review fixes: hidden signal, no raw HTML in faults
+- keep input lines out of the sanitizer fault stack
+- the sanitizer fault carries no error text or stack
+- contain hostile thrown values and thenables in the sanitizer guard
+
 ## [0.4.4] - 2026-10-15
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/client/index.ts

@@ -27,6 +27,9 @@ export interface ClientOptions {
 export interface ClientError {
   status: number;
   message: string;
+  code?: string;
+  constraint?: string;
+  column?: string;
 }
 
 export interface ClientResponse<T> {
@@ -337,7 +340,13 @@ function parseContentRange(header: string | null): number {
 
 async function parseError(response: Response): Promise<ClientError> {
   const body = await response.json().catch(() => ({}));
-  return { status: response.status, message: body.message || response.statusText };
+  return {
+    status: response.status,
+    message: body.message || response.statusText,
+    ...(typeof body.code === 'string' ? { code: body.code } : {}),
+    ...(typeof body.constraint === 'string' ? { constraint: body.constraint } : {}),
+    ...(typeof body.column === 'string' ? { column: body.column } : {}),
+  };
 }
 
 function buildUrl(

package/src/handler/array-literal.ts

@@ -0,0 +1,58 @@
+/** Most elements an array filter value may list. A longer list is refused. */
+export const ARRAY_LITERAL_MAX_ELEMENTS = 100;
+/** Most characters one element may hold, after unescaping. A longer one is refused. */
+export const ARRAY_LITERAL_MAX_ELEMENT_LENGTH = 200;
+
+const UNQUOTED_FORBIDDEN = new Set(['{', '}', '"', '\\']);
+
+/**
+ * Parse the PostgREST array value of a cs/cd/ov filter: `{a,b}`, `{"a,b","c\"d"}`, `{}`.
+ *
+ * An element is either unquoted (non-empty; no comma, brace, double quote, backslash or
+ * edge whitespace) or double-quoted, where `\"` and `\\` are the only escapes. Returns
+ * null for anything else, or past the element and length caps. The caller binds the
+ * result as one parameter; this text never reaches SQL.
+ */
+export function parseArrayLiteral(value: string): string[] | null {
+  if (value.length < 2 || value[0] !== '{' || value[value.length - 1] !== '}') return null;
+  const body = value.slice(1, -1);
+  if (body === '') return [];
+
+  const elements: string[] = [];
+  let i = 0;
+  for (;;) {
+    if (elements.length === ARRAY_LITERAL_MAX_ELEMENTS) return null;
+    let element = '';
+    if (body[i] === '"') {
+      i++;
+      for (;;) {
+        if (i >= body.length) return null;
+        const char = body[i];
+        if (char === '"') { i++; break; }
+        if (char === '\\') {
+          const next = body[i + 1];
+          if (next !== '"' && next !== '\\') return null;
+          element += next;
+          i += 2;
+        } else {
+          element += char;
+          i++;
+        }
+        if (element.length > ARRAY_LITERAL_MAX_ELEMENT_LENGTH) return null;
+      }
+    } else {
+      const start = i;
+      while (i < body.length && body[i] !== ',') {
+        if (UNQUOTED_FORBIDDEN.has(body[i])) return null;
+        i++;
+      }
+      element = body.slice(start, i);
+      if (element === '' || /^\s|\s$/.test(element)) return null;
+      if (element.length > ARRAY_LITERAL_MAX_ELEMENT_LENGTH) return null;
+    }
+    elements.push(element);
+    if (i === body.length) return elements;
+    if (body[i] !== ',') return null;
+    i++;
+  }
+}

package/src/handler/index.ts

@@ -7,7 +7,8 @@
  *   // Mount as Expo Router API route or any Web Standard handler
  */
 
-import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, and, or, not, asc, desc, sql, getTableColumns, type SQL } from 'drizzle-orm';
+import { eq, ne, gt, gte, lt, lte, like, ilike, isNull, isNotNull, inArray, arrayContains, arrayContained, arrayOverlaps, and, or, not, asc, desc, sql, getTableColumns, Param, type SQL } from 'drizzle-orm';
+import { parseArrayLiteral, ARRAY_LITERAL_MAX_ELEMENTS, ARRAY_LITERAL_MAX_ELEMENT_LENGTH } from './array-literal';
 import { emitAudit, resolvePrincipal, type AuditConfig, type RequestContext } from './audit';
 import { isServiceUnavailable, SERVICE_UNAVAILABLE_MESSAGE } from './service-unavailable';
 import { isPermissionDenied, safeRead, UNREADABLE } from './thrown';
@@ -60,6 +61,9 @@ export interface HandlerFault {
    */
   status: number;
   message: string;
+  /** SQL names of the cell when a sanitizeColumns cleaner fails. */
+  table?: string;
+  column?: string;
   stack?: string;
   /** Postgres SQLSTATE code when the error carried one. */
   pgCode?: string;
@@ -361,6 +365,14 @@ export interface HandlerOptions {
   /** Per-table list of fields stripped from POST/PATCH request bodies before mutation.
    *  Prevents mass assignment / privilege escalation on sensitive columns. */
   protectedFields?: Record<string, string[]>;
+  /** HTML columns to clean on POST/PATCH after before-hooks. Table and column
+   *  names accept SQL or Drizzle spelling. Requires sanitize when non-empty.
+   *  Changed bytes are stored and signalled by X-Sanitized-Columns. */
+  sanitizeColumns?: Record<string, string[]>;
+  /** Injected HTML cleaner for sanitizeColumns. Context names are SQL names.
+   *  Must return a string synchronously, ideally a fixed point. Throws or non-string returns
+   *  refuse the entire write with 500 and report through onError. */
+  sanitize?: (html: string, ctx: { table: string; column: string }) => string;
   /** Maximum nesting depth for relation embedding via ?select=rel(sub_rel(...)).
    *  Prevents DoS from deeply nested relation queries. Default: 3. */
   maxEmbedDepth?: number;
@@ -381,6 +393,9 @@ 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;
+  /** App-approved messages keyed by PostgreSQL constraint name. These may expose an
+   *  optional column even with hideSchemaErrors; hiddenColumns always wins. */
+  constraintMessages?: Record<string, string | { message: string; column?: string }>;
   /** 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`).
@@ -781,6 +796,7 @@ function expandTableKeyedOptions(
     ...(options.exposedTables ? { exposedTables: expandList(options.exposedTables) } : {}),
     ...(options.hiddenColumns ? { hiddenColumns: expandMap(options.hiddenColumns) } : {}),
     ...(options.protectedFields ? { protectedFields: expandMap(options.protectedFields) } : {}),
+    ...(options.sanitizeColumns ? { sanitizeColumns: expandMap(options.sanitizeColumns) } : {}),
     ...(options.rowOwnership ? { rowOwnership: expandMap(options.rowOwnership) } : {}),
     ...(options.relations ? { relations: expandMap(options.relations) } : {}),
     ...(options.hooks ? { hooks: expandMap(options.hooks) } : {}),
@@ -892,6 +908,167 @@ function mayRestore(tableName: string, options: HandlerOptions | undefined, user
   return role !== '' && roles.includes(role);
 }
 
+/** Refuse a cleaning policy that cannot be enforced, including conflicting table aliases. */
+function validateSanitizeColumns(schema: Schema, options: HandlerOptions | undefined): void {
+  const configured = new Map<DrizzleTable, Set<string>>();
+  for (const [tableName, columns] of Object.entries(options?.sanitizeColumns ?? {})) {
+    const prefix = `[everystack/api] sanitizeColumns.${tableName}:`;
+    const table = schema[tableName];
+    if (!table || sqlNameOf(table) === null) {
+      throw new Error(`${prefix} table "${tableName}" is not in the schema (columns ${JSON.stringify(columns)})`);
+    }
+    if (typeof options?.sanitize !== 'function') {
+      throw new Error(`${prefix} columns ${JSON.stringify(columns)} require a sanitize function`);
+    }
+    const resolved = new Set<string>();
+    const tableColumns = getTableColumns(table);
+    for (const name of columns) {
+      const key = columnPropertyName(table, name);
+      if (key === undefined) {
+        throw new Error(`${prefix} column "${name}" does not resolve on table "${tableName}"`);
+      }
+      const wire = options?.naming === 'snake_case' ? toSnakeCase(key) : key;
+      if (!/^[A-Za-z0-9_]+$/.test(wire)) {
+        throw new Error(`${prefix} column "${name}" has a name that cannot appear safely in X-Sanitized-Columns (use letters, digits and underscore)`);
+      }
+      if (tableColumns[key].dataType !== 'string') {
+        throw new Error(`${prefix} column "${name}" must be a string column`);
+      }
+      resolved.add(key);
+    }
+    const prior = configured.get(table);
+    if (prior && (prior.size !== resolved.size || [...prior].some(key => !resolved.has(key)))) {
+      throw new Error(`${prefix} different column lists conflict for the two table spellings: ${JSON.stringify([...prior])} and ${JSON.stringify([...resolved])}`);
+    }
+    configured.set(table, resolved);
+  }
+}
+
+/** Resolve hidden columns once so every read uses the same column spellings. */
+function resolveHiddenColumns(schema: Schema, options?: HandlerOptions): HandlerOptions | undefined {
+  if (!options?.hiddenColumns) return options;
+  const byTable = new Map<DrizzleTable, Set<string>>();
+  for (const [tableName, names] of Object.entries(options.hiddenColumns)) {
+    const table = schema[tableName];
+    const hidden = byTable.get(table) ?? new Set<string>();
+    for (const name of names) {
+      const property = columnPropertyName(table, name);
+      if (property === undefined) {
+        throw new Error(`[everystack/api] hiddenColumns.${tableName}: "${name}" does not resolve to a column`);
+      }
+      const column = getTableColumns(table)[property] as DrizzleColumn;
+      for (const spelling of [property, column.name, toSnakeCase(property), toCamelCase(column.name)]) {
+        hidden.add(spelling);
+      }
+    }
+    byTable.set(table, hidden);
+  }
+  const hiddenColumns = Object.fromEntries(Object.keys(options.hiddenColumns)
+    .map(tableName => [tableName, [...byTable.get(schema[tableName])!]]));
+  return { ...options, hiddenColumns };
+}
+
+/** Safe, fixed client messages. Never derive these from PostgreSQL text or detail. */
+const INTEGRITY_ERRORS: Record<string, { status: number; message: string }> = {
+  '23514': { status: 422, message: 'Value does not meet a constraint' },
+  '23502': { status: 422, message: 'A required value is missing' },
+  '23503': { status: 422, message: 'Related record does not exist' },
+  '23000': { status: 422, message: 'Value violates an integrity constraint' },
+  '23505': { status: 409, message: 'Value already exists' },
+  '23P01': { status: 409, message: 'Value conflicts with an existing record' },
+  '22P02': { status: 422, message: 'Invalid value format' },
+  '22001': { status: 422, message: 'Value is too long' },
+  '22003': { status: 422, message: 'Value is out of range' },
+};
+
+type IntegrityAnswer = { status: number; body: {
+  message: string; code: string; constraint?: string; column?: string;
+} };
+
+/** How many `cause` links the integrity mapper follows from the thrown value. */
+const MAX_CAUSE_HOPS = 3;
+
+/**
+ * Both dispatch catches use this after their transaction has rolled back. A throwing
+ * diagnostic getter invalidates the whole classification, including a wrapped cause.
+ * undefined means unclassified; UNREADABLE preserves the caller's 500 fault path.
+ */
+function mapIntegrityError(
+  error: unknown,
+  tableName: string | undefined,
+  options?: HandlerOptions,
+): IntegrityAnswer | typeof UNREADABLE | undefined {
+  // Drizzle drivers may throw directly or wrap the driver's error as cause, and a
+  // query wrapper can wrap again. The first string code on the chain decides.
+  // Classify before touching diagnostics, so unrelated codes keep their old answer.
+  const chain: unknown[] = [error];
+  let code = safeRead(error, 'code');
+  while (typeof code !== 'string' && chain.length <= MAX_CAUSE_HOPS) {
+    if (code === UNREADABLE) return UNREADABLE;
+    const cause = safeRead(chain[chain.length - 1], 'cause');
+    if (cause === UNREADABLE) return UNREADABLE;
+    if (cause === null || typeof cause !== 'object' || chain.includes(cause)) break;
+    chain.push(cause);
+    code = safeRead(cause, 'code');
+  }
+  if (code === UNREADABLE) return UNREADABLE;
+  if (typeof code !== 'string' || !Object.hasOwn(INTEGRITY_ERRORS, code)) return undefined;
+  const read = (value: unknown) => ({
+    message: safeRead(value, 'message'), cause: safeRead(value, 'cause'),
+    constraint: safeRead(value, 'constraint') ?? safeRead(value, 'constraint_name'),
+    column: safeRead(value, 'column') ?? safeRead(value, 'column_name'),
+    table: safeRead(value, 'table') ?? safeRead(value, 'table_name'),
+  });
+  // Diagnostics come only from the object that carried the code (the last link).
+  // Wrapper messages and fields are read only to refuse a hostile value.
+  let fields!: ReturnType<typeof read>;
+  for (const value of chain) {
+    fields = read(value);
+    if (Object.values(fields).includes(UNREADABLE)) return UNREADABLE;
+  }
+  const mapped = INTEGRITY_ERRORS[code];
+  const constraint = typeof fields.constraint === 'string' ? fields.constraint : undefined;
+  const declared = constraint === undefined ? undefined : ownEntry(options?.constraintMessages, constraint);
+  const body: IntegrityAnswer['body'] = { message: mapped.message, code };
+  if (declared !== undefined) {
+    body.message = typeof declared === 'string' ? declared : declared.message;
+    body.constraint = constraint;
+    if (typeof declared !== 'string' && declared.column !== undefined) body.column = declared.column;
+  } else if (!options?.hideSchemaErrors) {
+    if (constraint !== undefined) body.constraint = constraint;
+    if (code === '23502' && typeof fields.column === 'string') body.column = fields.column;
+  }
+  // A failing trigger or FK action can name a different table than the URL.
+  // Missing driver tables (and unknown RPC policies) use every configured list.
+  const driverTable = typeof fields.table === 'string' ? fields.table : undefined;
+  const hiddenColumns = options?.hiddenColumns ?? {};
+  const driverHidden = driverTable === undefined
+    || (tableName === undefined && !Object.hasOwn(hiddenColumns, driverTable))
+    ? Object.values(hiddenColumns).flat() : ownEntry(hiddenColumns, driverTable) ?? [];
+  const hidden = [
+    ...(tableName !== undefined ? ownEntry(hiddenColumns, tableName) ?? [] : []),
+    ...driverHidden,
+  ];
+  if (body.column !== undefined && hidden.includes(body.column)) delete body.column;
+  return { status: mapped.status, body };
+}
+
+function validateConstraintMessages(options?: HandlerOptions): void {
+  if (options?.constraintMessages === undefined) return;
+  if (options.constraintMessages === null || typeof options.constraintMessages !== 'object'
+    || Array.isArray(options.constraintMessages)) {
+    throw new Error('[everystack/api] constraintMessages must be a record');
+  }
+  for (const [constraint, entry] of Object.entries(options.constraintMessages)) {
+    const object = entry !== null && typeof entry === 'object' && !Array.isArray(entry);
+    const message = typeof entry === 'string' ? entry : object ? entry.message : undefined;
+    if (typeof message !== 'string' || message.trim().length === 0
+      || (object && entry.column !== undefined && typeof entry.column !== 'string')) {
+      throw new Error(`[everystack/api] constraintMessages.${constraint}: expected a non-empty message and optional string column`);
+    }
+  }
+}
+
 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
@@ -900,20 +1077,11 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
   // 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);
-  // Validate configured entries, not their generated table-name twins.
-  for (const [tableName, columns] of Object.entries(rawOptions?.hiddenColumns ?? {})) {
-    for (const column of columns) {
-      if (columnPropertyName(schema[tableName], column) === undefined) {
-        console.warn(
-          `[everystack/api] invalid hiddenColumns entry: table=${tableName} column=${column}; `
-          + 'JOIN-path embeds of this table return 400 until the entry is fixed.',
-        );
-      }
-    }
-  }
+  const options = resolveHiddenColumns(schema, expandTableKeyedOptions(rawOptions, namePairs));
+  validateConstraintMessages(options);
   validateRowOwnership(schema, rawOptions);
   validateSoftDeleteRestore(schema, options);
+  validateSanitizeColumns(schema, options);
   const tableNames = new Set(Object.keys(schema));
   const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
@@ -1094,20 +1262,22 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           const rpcCacheControl = getCacheControl(options);
           return json(result, 200, rpcCacheControl ? { 'Cache-Control': rpcCacheControl } : undefined);
         } catch (error) {
+          // App answers and outages take precedence over integrity classification.
+          const unavailable = !(error instanceof HandlerError) && isServiceUnavailable(error);
+          const integrity = error instanceof HandlerError || unavailable
+            ? undefined : mapIntegrityError(error, undefined, options);
           const code = safeRead(error, 'code');
           const text = safeRead(error, 'message');
-          // A value whose getter throws is hostile: classify nothing from it
-          // and echo nothing of it. It answers the generic 500 (or an outage's 503).
-          const hostile = code === UNREADABLE || text === UNREADABLE || safeRead(error, 'cause') === UNREADABLE;
+          // A value whose getter throws is hostile: classify nothing from it and echo
+          // nothing of it, whatever its code (the mapper reads cause only for its codes).
+          const hostile = integrity === UNREADABLE || code === UNREADABLE || text === UNREADABLE
+            || safeRead(error, 'cause') === UNREADABLE;
           const pgCode = hostile ? undefined : code;
-          // An outage: answer 503 with a fixed body. The driver's message
-          // carries host and port; it goes to onError only. A HandlerError's
-          // own answer still wins: its return below runs first.
-          const unavailable = isServiceUnavailable(error);
+          const mapped = !hostile ? integrity : undefined;
           let status = 500;
           if (unavailable) status = 503;
+          else if (mapped) status = mapped.status;
           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.
@@ -1130,6 +1300,8 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
             return json({ message: error.message }, error.status);
           }
           if (unavailable) return serviceUnavailableResponse();
+          if (hostile) return json({ message: options?.hideSchemaErrors ? 'Internal Server Error' : 'RPC execution failed' }, 500);
+          if (mapped) return json(mapped.body, mapped.status);
           const message = !hostile && error instanceof Error ? text : 'RPC execution failed';
           if (options?.hideSchemaErrors && status === 500) {
             return json({ message: 'Internal Server Error' }, 500);
@@ -1208,6 +1380,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       // Bound every select before the hidden-column guard walks it. The guard
       // reads duplicates and runs for writes too, so a GET-only check is too late.
       let queryError: string | undefined;
+      let queryErrorEchoesInput = false;
       let auditReadDenial = false;
       for (const selectParam of url.searchParams.getAll('select')) {
         const maxEmbedDepth = options?.maxEmbedDepth ?? 3;
@@ -1218,20 +1391,33 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
         }
       }
 
+      // A part with parentheses is an aggregate or a declared embed. Anything
+      // else cannot be honored, so refuse it rather than drop it from the rows.
+      const tableRelations = ownEntry(options?.relations, tableName);
+      if (!queryError) {
+        for (const selectParam of url.searchParams.getAll('select')) {
+          const { undeclared } = parseSelectParam(selectParam, tableRelations, options?.relations);
+          if (undeclared !== undefined) {
+            queryError = undeclaredSelectPartMessage(undeclared);
+            queryErrorEchoesInput = true;
+            break;
+          }
+        }
+      }
+
       // Refusals share the response audit below without opening a transaction.
       // Response stripping cannot prevent value oracles or aggregate alias reads.
       if (!queryError && requestUsesHiddenColumn(schema, tableName, url.searchParams, options)) {
         queryError = 'Invalid query';
       }
-      // Refuse projections we cannot enforce on the common pre-DB audit path.
-      const tableRelations = ownEntry(options?.relations, tableName);
-      if (!queryError && options?.drizzleRelations && tableRelations) {
+      // Refuse projections neither read path can enforce, on the common pre-DB audit path.
+      if (!queryError && tableRelations) {
         for (const selectParam of url.searchParams.getAll('select')) {
-          const { embeds } = parseSelectParam(selectParam, tableRelations, options.relations);
-          const withClause = buildWithClause(embeds, tableRelations, schema, options);
-          if (withClause === null || withClause === 'unresolvedHiddenColumns') {
+          const { embeds } = parseSelectParam(selectParam, tableRelations, options?.relations);
+          const refused = refusedEmbedProjection(embeds, tableRelations, schema, options);
+          if (refused !== undefined) {
             queryError = 'Invalid query';
-            auditReadDenial = method === 'GET' && withClause === 'unresolvedHiddenColumns';
+            auditReadDenial = method === 'GET' && refused === 'unresolvedHiddenColumns';
             break;
           }
         }
@@ -1255,7 +1441,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       const deferred: Deferred[] = [];
       let response: Response;
       try {
-        response = queryError ? json({ message: queryError }, 400)
+        response = queryError ? (queryErrorEchoesInput ? sanitizeError(queryError, 400, options) : json({ message: queryError }, 400))
           : unbacked ? json({ message: unbacked }, 500) : await executeWithSettings(routedDb, settings, async (dbOrTx) => {
           if (method === 'GET') {
             const cacheControl = getCacheControl(options);
@@ -1296,20 +1482,21 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
       return response;
     } catch (error) {
+      const appError = error instanceof HandlerError;
+      const unavailable = !appError && isServiceUnavailable(error);
+      const integrity = appError || unavailable ? undefined : mapIntegrityError(error, tableName, options);
+      const hostile = integrity === UNREADABLE;
+      const mapped = integrity !== UNREADABLE ? integrity : undefined;
+      const permissionDenied = !appError && !unavailable && !hostile && isPermissionDenied(error);
       if (isWrite) {
         await emitAudit(options?.audit, {
           kind: 'rest', name: tableName, user, client,
-          result: isPermissionDenied(error) ? 'deny' : 'error',
+          result: mapped || permissionDenied ? 'deny' : 'error',
           requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
         });
       }
-      if (isPermissionDenied(error)) {
-        return sanitizeError('Permission denied', 403, options);
-      }
-      // An outage answers 503 with a fixed body; the driver's message (host and
-      // port) goes to onError only. A HandlerError is the app's own answer and
-      // never an outage.
-      const unavailable = !(error instanceof HandlerError) && isServiceUnavailable(error);
+      if (mapped) return json(mapped.body, mapped.status);
+      if (permissionDenied) return sanitizeError('Permission denied', 403, options);
       // Other table faults re-throw to the Lambda boundary (which logs to
       // CloudWatch), but that path never reaches the S3 archive. Surface the
       // cause here too so a write 5xx is in logs:errors. A HandlerError with a
@@ -1353,12 +1540,8 @@ function buildWithClause(
     if (!relation) continue;
     hasEmbedded = true;
     const table = schema[relation.table];
-    const hidden = new Set<string>();
-    for (const name of options?.hiddenColumns?.[relation.table] ?? []) {
-      const property = columnPropertyName(table, name);
-      if (property === undefined) return 'unresolvedHiddenColumns';
-      hidden.add(property);
-    }
+    const names = new Set(options?.hiddenColumns?.[relation.table] ?? []);
+    const hidden = new Set(table ? Object.keys(getTableColumns(table)).filter(name => names.has(name)) : []);
     const config: Record<string, any> = {};
     if (embed.columns !== null) {
       // Drop names that are not columns of a known table: Drizzle ignores them,
@@ -1394,13 +1577,7 @@ function stripEmbeddedHiddenColumns(
     const relation = ownEntry(ownEntry(options?.relations, tableName), embed.name);
     const key = options?.naming === 'snake_case' ? toSnakeCase(embed.name) : embed.name;
     if (!relation || !(key in result)) continue;
-    const hidden = (options?.hiddenColumns?.[relation.table] ?? []).flatMap(name => {
-      const property = columnPropertyName(schema[relation.table], name);
-      return [name, toSnakeCase(name), ...(property ? [property, toSnakeCase(property)] : [])];
-    });
-    const related = stripHiddenColumns(result[key], relation.table, {
-      hiddenColumns: { [relation.table]: hidden },
-    });
+    const related = stripHiddenColumns(result[key], relation.table, options);
     result[key] = stripEmbeddedHiddenColumns(related, embed.embeds, relation.table, schema, options);
   }
   return result;
@@ -1747,7 +1924,7 @@ function parseSelectParam(
   selectParam: string | null,
   tableRelations?: Record<string, RelationConfig>,
   allRelations?: Record<string, Record<string, RelationConfig>>,
-): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[] } {
+): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[]; undeclared?: string } {
   if (!selectParam) {
     return { columns: null, embeds: [], aggregates: [] };
   }
@@ -1756,6 +1933,9 @@ function parseSelectParam(
   const columns: string[] = [];
   const aggregates: AggregateField[] = [];
   let hasWildcard = false;
+  // The first part with parentheses that is neither an aggregate nor a declared
+  // embed, at any depth. The caller refuses the select; it is never a column.
+  let undeclared: string | undefined;
 
   // Parse: split on commas, but respect parentheses
   const parts = splitSelectParam(selectParam);
@@ -1779,11 +1959,14 @@ function parseSelectParam(
       const targetTableName = tableRelations[name].table;
       const targetRelations = ownEntry(allRelations, targetTableName);
       const inner = parseSelectParam(innerSelect, targetRelations, allRelations);
+      undeclared ??= inner.undeclared;
       embeds.push({
         name,
         columns: inner.columns,
         embeds: inner.embeds,
       });
+    } else if (part.includes('(')) {
+      undeclared ??= part;
     } else if (part === '*') {
       hasWildcard = true;
     } else {
@@ -1795,9 +1978,39 @@ function parseSelectParam(
     columns: hasWildcard ? null : (columns.length > 0 ? columns : null),
     embeds,
     aggregates,
+    ...(undeclared === undefined ? {} : { undeclared }),
   };
 }
 
+/** The 400 for an undeclared select part. It echoes client input only, capped. */
+function undeclaredSelectPartMessage(part: string): string {
+  const chars = Array.from(part);
+  const shown = chars.length > 200 ? `${chars.slice(0, 200).join('')}…` : part;
+  return `Select part is not a declared embed or an aggregate: ${shown}`;
+}
+
+/**
+ * An embed list left empty once unknown and hidden names are removed, at any
+ * depth. Both read paths refuse it the same way, before any DB call.
+ */
+function refusedEmbedProjection(
+  embeds: EmbedRequest[],
+  tableRelations: Record<string, RelationConfig>,
+  schema: Schema,
+  options?: HandlerOptions,
+): null | 'unresolvedHiddenColumns' | undefined {
+  const withClause = buildWithClause(embeds, tableRelations, schema, options);
+  if (withClause === null || withClause === 'unresolvedHiddenColumns') return withClause;
+  for (const embed of embeds) {
+    const relation = ownEntry(tableRelations, embed.name);
+    const targetRelations = relation && ownEntry(options?.relations, relation.table);
+    if (embed.embeds.length === 0 || !targetRelations) continue;
+    const nested = refusedEmbedProjection(embed.embeds, targetRelations, schema, options);
+    if (nested !== undefined) return nested;
+  }
+  return undefined;
+}
+
 /**
  * Split select param respecting parentheses:
  * "id,title,author(name,email),comments(*)" → ["id", "title", "author(name,email)", "comments(*)"]
@@ -1852,14 +2065,7 @@ function requestUsesHiddenColumn(
       }
       columnName = parts[0];
     }
-    const table = schema[targetName];
-    const column = getColumn(table, columnName);
-    return (options.hiddenColumns?.[targetName] ?? []).some(hidden => {
-      const hiddenColumn = getColumn(table, hidden);
-      return column && hiddenColumn
-        ? column === hiddenColumn
-        : toCamelCase(columnName) === toCamelCase(hidden);
-    });
+    return (options.hiddenColumns?.[targetName] ?? []).includes(columnName);
   };
 
   const selectUsesHidden = (sourceTable: string, select: string): boolean => {
@@ -2057,6 +2263,95 @@ function beforeHookFailure(
   return json({ message: 'Hook error' }, 500);
 }
 
+function errorKind(err: unknown): string {
+  try {
+    return err instanceof TypeError ? 'TypeError'
+      : err instanceof RangeError ? 'RangeError'
+      : err instanceof SyntaxError ? 'SyntaxError'
+      : err instanceof ReferenceError ? 'ReferenceError'
+      : err instanceof EvalError ? 'EvalError'
+      : err instanceof URIError ? 'URIError'
+      : err instanceof AggregateError ? 'AggregateError'
+      : err instanceof Error ? 'Error' : 'non-Error';
+  } catch {
+    return 'Error';
+  }
+}
+
+function consumeThenable(value: unknown, depth = 4): void {
+  if (depth === 0) return;
+  try {
+    const then = (value as { then?: unknown } | null | undefined)?.then;
+    if (typeof then !== 'function') return;
+    const next = then.call(value, () => {}, () => {});
+    consumeThenable(next, depth - 1);
+  } catch {
+    // A throwing getter or then must not prevent the refusal.
+  }
+}
+
+/** Clean every submitted cell before the caller can start a write. */
+function sanitizeWriteBody(
+  body: unknown,
+  table: DrizzleTable,
+  tableName: string,
+  options: HandlerOptions | undefined,
+  at: { requestId?: string; name: string; method: string },
+  deferred: Deferred[],
+): { body: unknown; changed: string[] } | { refusal: Response } {
+  const columns = options?.sanitizeColumns?.[tableName];
+  if (!columns?.length) return { body, changed: [] };
+  const keys = [...new Set(columns.map(name => columnPropertyName(table, name)!))];
+  const hidden = new Set((options?.hiddenColumns?.[tableName] ?? []).map(name => columnPropertyName(table, name)));
+  const refuse = (message: string, column: string): { refusal: Response } => {
+    const fault: HandlerFault = {
+      ...at, kind: 'rest', status: 500, table: sqlNameOf(table)!, column, message,
+    };
+    deferred.push({ always: true, run: () => emitFault(options?.onError, fault) });
+    return { refusal: json({ message: 'Sanitizer error' }, 500) };
+  };
+  const bulk = Array.isArray(body);
+  const rows = bulk ? body : [body];
+  const cleaned: unknown[] = [];
+  const changed: string[] = [];
+  for (const [index, row] of rows.entries()) {
+    // Leave body-shape checks to coerceDateColumnValues.
+    if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+      cleaned.push(row);
+      continue;
+    }
+    const result: Record<string, unknown> = { ...row };
+    for (const key of keys) {
+      if (!Object.hasOwn(result, key) || result[key] === null) continue;
+      const value = result[key];
+      const wire = options?.naming === 'snake_case' ? toSnakeCase(key) : key;
+      if (typeof value !== 'string') {
+        return { refusal: sanitizeError(`Column "${wire}" must be a string`, 400, options) };
+      }
+      let sanitized: unknown;
+      try {
+        sanitized = options!.sanitize!(value, { table: sqlNameOf(table)!, column: table[key].name });
+      } catch (err) {
+        consumeThenable(err);
+        return refuse(`Sanitizer threw (${errorKind(err)})`, table[key].name);
+      }
+      if (typeof sanitized !== 'string') {
+        // An async cleaner is invalid; rejection handling is bounded and best effort.
+        consumeThenable(sanitized);
+        return refuse('Sanitizer returned a non-string', table[key].name);
+      }
+      result[key] = sanitized;
+      if (sanitized !== value && !hidden.has(key)) changed.push(bulk ? `${wire}[${index}]` : wire);
+    }
+    cleaned.push(result);
+  }
+  return { body: bulk ? cleaned : cleaned[0], changed };
+}
+
+function sanitizedHeaders(changed: string[]): Record<string, string> | undefined {
+  return changed.length > 0 ? { 'X-Sanitized-Columns': changed.join(',') } : undefined;
+}
+
 async function handlePost(
   db: DrizzleDb,
   table: DrizzleTable,
@@ -2099,6 +2394,11 @@ async function handlePost(
     }
   }
 
+  const sanitized = sanitizeWriteBody(body, table, tableName, options,
+    { requestId, name: tableName, method: 'POST' }, deferred);
+  if ('refusal' in sanitized) return sanitized.refusal;
+  body = sanitized.body as Record<string, unknown>;
+
   let coerced: unknown;
   try {
     coerced = coerceDateColumnValues(body, table);
@@ -2117,7 +2417,8 @@ async function handlePost(
       () => afterCreate.call(hook, rows[0], user, client));
   }
 
-  return json(stripHiddenColumns(transformResponse(rows[0], options), tableName, options), 201);
+  return json(stripHiddenColumns(transformResponse(rows[0], options), tableName, options), 201,
+    rows.length > 0 ? sanitizedHeaders(sanitized.changed) : undefined);
 }
 
 async function handlePatch(
@@ -2183,6 +2484,11 @@ async function handlePatch(
     return json({ message: 'PATCH requires at least one filter when the ownership backstop is lifted for your role' }, 400);
   }
 
+  // Safety: require at least one filter to prevent accidental mass update
+  if (buildsNoFilter(table, params)) {
+    return json({ message: 'PATCH requires at least one filter to prevent accidental mass update' }, 400);
+  }
+
   // The owner clause proves the caller owns the row, not that they may give it away.
   // A caller it scopes may not set the owner column to anyone else. RLS stays primary.
   if (scope.condition && user && ownership) {
@@ -2206,6 +2512,11 @@ async function handlePatch(
     return json({ message: 'No writable fields in request body' }, 400);
   }
 
+  const sanitized = sanitizeWriteBody(body, table, tableName, options,
+    { requestId, name: tableName, method: 'PATCH' }, deferred);
+  if ('refusal' in sanitized) return sanitized.refusal;
+  body = sanitized.body as Record<string, unknown>;
+
   const filterResult = buildAllConditions(table, params);
   if ('error' in filterResult) {
     return sanitizeError(filterResult.error, 400, options);
@@ -2247,7 +2558,8 @@ async function handlePatch(
       () => afterUpdate.call(hook, rows, user, client));
   }
 
-  return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
+  return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200,
+    rows.length > 0 ? sanitizedHeaders(sanitized.changed) : undefined);
 }
 
 /**
@@ -2530,6 +2842,7 @@ function buildJsonCondition(table: DrizzleTable, filter: Filter): any {
   const jp = filter.jsonPath!;
   const baseCol = getColumn(table, jp.baseColumn);
   if (!baseCol) return { __filterError: `Unknown column: '${jp.baseColumn}'` };
+  if (ARRAY_OPERATORS.has(filter.operator)) return arrayOperatorRefusal(filter.operator, jp.baseColumn);
 
   // Validate all JSON path keys before interpolation
   for (const step of jp.steps) {
@@ -2576,6 +2889,7 @@ function buildJsonCondition(table: DrizzleTable, filter: Filter): any {
     case 'is':
       if (filter.value === 'null') condition = sql`${expr} IS NULL`;
       else if (filter.value === 'not.null') condition = sql`${expr} IS NOT NULL`;
+      else return { __filterError: `Invalid value for 'is': expected null or not.null` };
       break;
     case 'in': {
       const values = filter.value.replace(/^\(/, '').replace(/\)$/, '').split(',');
@@ -2584,7 +2898,8 @@ function buildJsonCondition(table: DrizzleTable, filter: Filter): any {
       break;
     }
     default:
-      return null;
+      // Refused, never dropped: a dropped filter widens the answer.
+      return { __filterError: `Unknown filter operator: '${filter.operator.slice(0, 100)}'` };
   }
 
   if (condition && filter.negated) {
@@ -2597,7 +2912,35 @@ function buildJsonCondition(table: DrizzleTable, filter: Filter): any {
   return condition;
 }
 
-const VALID_OPERATORS = new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike', 'is', 'in']);
+const ARRAY_OPERATORS = new Set(['cs', 'cd', 'ov']);
+const VALID_OPERATORS = new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'like', 'ilike', 'is', 'in', ...ARRAY_OPERATORS]);
+const TEXT_ARRAY_ELEMENT_TYPES = new Set(['PgText', 'PgVarchar']);
+
+function arrayOperatorRefusal(operator: string, column: string): { __filterError: string } {
+  return { __filterError: `Unknown filter operator: '${operator}' for column '${column}' (cs, cd and ov need a text[] or varchar[] column)` };
+}
+
+/**
+ * cs (@>), cd (<@) and ov (&&) on a text[] or varchar[] column. The parsed list is
+ * bound as ONE parameter through the column's own encoder. Passing a Param, not the
+ * bare array, keeps the empty set: drizzle's helpers throw on an empty JS array, and
+ * `{}` must keep PostgreSQL's own meaning.
+ */
+function buildArrayCondition(column: DrizzleColumn, filter: Filter): any {
+  const element = (column as { baseColumn?: { columnType?: string } }).baseColumn?.columnType;
+  if (column.dataType !== 'array' || !element || !TEXT_ARRAY_ELEMENT_TYPES.has(element)) {
+    return arrayOperatorRefusal(filter.operator, filter.column);
+  }
+  const values = parseArrayLiteral(filter.value);
+  if (!values) {
+    return { __filterError: `Invalid array value for '${filter.operator}' on column '${filter.column}': expected {a,b} with at most ${ARRAY_LITERAL_MAX_ELEMENTS} elements of at most ${ARRAY_LITERAL_MAX_ELEMENT_LENGTH} characters` };
+  }
+  const list = new Param(values, column);
+  const condition = filter.operator === 'cs' ? arrayContains(column, list)
+    : filter.operator === 'cd' ? arrayContained(column, list)
+      : arrayOverlaps(column, list);
+  return filter.negated ? not(condition) : condition;
+}
 
 function buildCondition(table: DrizzleTable, filter: Filter): any {
   if (filter.jsonPath) {
@@ -2610,6 +2953,7 @@ function buildCondition(table: DrizzleTable, filter: Filter): any {
   if (!VALID_OPERATORS.has(filter.operator)) {
     return { __filterError: `Unknown filter operator: '${filter.operator}'` };
   }
+  if (ARRAY_OPERATORS.has(filter.operator)) return buildArrayCondition(column, filter);
 
   let condition: any = null;
 
@@ -2715,6 +3059,44 @@ function parseFilters(params: URLSearchParams): Filter[] {
   return filters;
 }
 
+/** A group part reading `column.[not.]cs.` so far: a `{` here opens an array value. */
+const ARRAY_VALUE_OPENING = /^[^.]+\.(?:not\.)?(?:cs|cd|ov)\.$/;
+
+/**
+ * Split a group's content on commas, except inside the `{...}` value of a cs/cd/ov
+ * filter, where a comma, or a brace inside a double-quoted element, is data. Every
+ * other operator splits on every comma, as it always has (`in.(a,b)` included).
+ */
+function splitLogicalGroup(content: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let inArray = false;
+  let inQuote = false;
+  for (let i = 0; i < content.length; i++) {
+    const char = content[i];
+    if (inArray) {
+      if (inQuote && char === '\\') {
+        current += char + (content[i + 1] ?? '');
+        i++;
+        continue;
+      }
+      if (char === '"') inQuote = !inQuote;
+      else if (char === '}' && !inQuote) inArray = false;
+      current += char;
+      continue;
+    }
+    if (char === ',') {
+      parts.push(current);
+      current = '';
+      continue;
+    }
+    if (char === '{' && ARRAY_VALUE_OPENING.test(current)) inArray = true;
+    current += char;
+  }
+  parts.push(current);
+  return parts;
+}
+
 /**
  * Parse a logical group value into individual filters.
  * Input: "(status.eq.draft,status.eq.pending)" → [{column:'status', operator:'eq', value:'draft'}, ...]
@@ -2726,7 +3108,7 @@ function parseLogicalGroup(value: string): Filter[] {
   }
 
   const filters: Filter[] = [];
-  for (const part of content.split(',')) {
+  for (const part of splitLogicalGroup(content)) {
     const dotIndex = part.indexOf('.');
     if (dotIndex === -1) continue;