@everystack/api 0.4.2 → 0.4.4

package/src/handler/index.ts

@@ -7,8 +7,10 @@
  *   // 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 } from 'drizzle-orm';
+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 { emitAudit, resolvePrincipal, type AuditConfig, type RequestContext } from './audit';
+import { isServiceUnavailable, SERVICE_UNAVAILABLE_MESSAGE } from './service-unavailable';
+import { isPermissionDenied, safeRead, UNREADABLE } from './thrown';
 export type { AuditConfig, AuditRecord, RequestContext, AuditOutcome, PrincipalKind } from './audit';
 export { getPublicSurface, assertPublicSurface } from './public-surface';
 export type { PublicSurface } from './public-surface';
@@ -41,12 +43,21 @@ export class HandlerError extends Error {
  */
 export interface HandlerFault {
   requestId?: string;
-  /** 'rpc' for /rpc/<name>; 'rest' for a table operation. */
-  kind: 'rpc' | 'rest';
-  /** RPC function name or table name. */
+  /**
+   * 'rpc' for /rpc/<name>; 'rest' for a table operation; 'hook' for an
+   * after-hook that threw after its write (the response stayed 2xx).
+   */
+  kind: 'rpc' | 'rest' | 'hook';
+  /**
+   * RPC function name or table name. For 'hook': '<table>.afterCreate',
+   * '<table>.afterUpdate', '<table>.afterDelete' or 'rpc.<fn>.afterRpc'.
+   */
   name: string;
   method: string;
-  /** Always >= 500 here — refusals (4xx) never raise a fault. */
+  /**
+   * Always >= 500 here — refusals (4xx) never raise a fault. For 'hook' it is
+   * the fault's severity (500), not the response status.
+   */
   status: number;
   message: string;
   stack?: string;
@@ -68,6 +79,99 @@ async function emitFault(
   }
 }
 
+/**
+ * Report an after-hook that threw. It ran after its write was committed, so
+ * the caller still answers 2xx; the hook's failure goes to onError only.
+ * Never throws.
+ */
+async function reportHookFault(
+  onError: HandlerOptions['onError'],
+  at: { requestId?: string; name: string; method: string },
+  error: unknown,
+): Promise<void> {
+  const { message, ...rest } = describeError(error);
+  await emitFault(onError, {
+    ...at, kind: 'hook', status: 500, ...rest,
+    message: `after-hook failed after the write: ${message}`,
+  });
+}
+
+/**
+ * Work a write handler queues to run once executeWithSettings has returned: with
+ * pgSettings, after the transaction has ended, so nothing here holds the connection.
+ * `always` runs for every outcome, a failed commit included; it is a before-hook
+ * fault, and the hook did fail. Otherwise it is a table after-hook and runs only
+ * for a 2xx.
+ */
+interface Deferred {
+  always: boolean;
+  run: () => Promise<void>;
+}
+
+/** Queue a table after-hook. Its throw is reported as kind 'hook', never re-thrown. */
+function deferAfterHook(
+  deferred: Deferred[],
+  onError: HandlerOptions['onError'],
+  at: { requestId?: string; name: string; method: string },
+  run: () => Promise<void>,
+): void {
+  deferred.push({
+    always: false,
+    run: async () => {
+      try {
+        await run();
+      } catch (err) {
+        await reportHookFault(onError, at, err);
+      }
+    },
+  });
+}
+
+/**
+ * Look up a config entry by a name the request supplied. Only an own key
+ * counts: a plain object also answers `constructor`, `toString` and
+ * `__proto__` from Object.prototype.
+ */
+function ownEntry<T>(obj: Record<string, T> | undefined, key: string): T | undefined {
+  return obj && Object.hasOwn(obj, key) ? obj[key] : undefined;
+}
+
+/** Name a fault after a declared RPC only; any other path segment is caller text. */
+function declaredRpcName(rpc: HandlerOptions['rpc'], name: string | undefined): string {
+  return name && rpc && Object.hasOwn(rpc, name) ? name : '';
+}
+
+/**
+ * Report an auth outage (the token or client verifier could not reach its
+ * backing service). It answers a returned 503, so no catch reports it. The
+ * client gets the fixed body; the driver's message goes here only.
+ * A no-op when `outage` is undefined (the auth failure was a 401/403).
+ * Never throws: the 503 must not turn into a rejection.
+ */
+async function emitAuthOutage(
+  onError: HandlerOptions['onError'],
+  where: Pick<HandlerFault, 'requestId' | 'kind' | 'name' | 'method'>,
+  outage: unknown,
+): Promise<void> {
+  if (!onError || outage === undefined) return;
+  await emitFault(onError, { ...where, status: 503, ...describeError(outage) });
+}
+
+/**
+ * The message, stack and code of anything thrown, for a fault. Never throws:
+ * String() throws on a null-prototype object, and a getter can throw.
+ */
+function describeError(error: unknown): Pick<HandlerFault, 'message' | 'stack' | 'pgCode'> {
+  const [message, stack, code] = [safeRead(error, 'message'), safeRead(error, 'stack'), safeRead(error, 'code')];
+  let text: string;
+  try { text = typeof message === 'string' ? message : String(error); } catch { text = 'unreadable error'; }
+  return {
+    message: text,
+    stack: typeof stack === 'string' ? stack : undefined,
+    pgCode: typeof code === 'string' ? code : undefined,
+  };
+}
+
 /** Replace schema-revealing error details with a generic message when hideSchemaErrors is enabled. */
 function sanitizeError(message: string, status: number, options?: HandlerOptions): Response {
   if (options?.hideSchemaErrors) {
@@ -129,6 +233,13 @@ export interface SoftDeleteConfig {
   column?: string;
   /** Tables with soft-delete enabled. If omitted, all tables with the column are treated as soft-delete. */
   tables?: string[];
+  /** Who may restore through PATCH, per table: table name -> role names. Keyed like `tables`.
+   *  PATCH honours `?deleted=include|only` only when the caller's role claim (`auth.roleField`,
+   *  default `role`) is in the table's list: exact string match, no hierarchy, no case folding.
+   *  Anyone else gets live rows only, as if the param were absent. A restore body must be
+   *  exactly `{ <column>: null }`, or 400. Omitted: no one restores through the API.
+   *  This is a backstop. RLS must also keep other roles off deleted rows (docs/handler.md). */
+  restore?: Record<string, string[]>;
 }
 
 export interface HookConfig {
@@ -244,8 +355,8 @@ export interface HandlerOptions {
    *  If omitted, all tables in the schema are exposed (current behavior). */
   exposedTables?: string[];
   /** Per-table list of column names to strip from all responses.
-   *  Columns are removed after query execution, before JSON serialization.
-   *  Does NOT affect query filtering — hidden columns can still be used in WHERE clauses. */
+   *  Explicit references in query parameters are refused before database access.
+   *  Does not prevent writes to these columns; use protectedFields for that. */
   hiddenColumns?: Record<string, string[]>;
   /** Per-table list of fields stripped from POST/PATCH request bodies before mutation.
    *  Prevents mass assignment / privilege escalation on sensitive columns. */
@@ -259,8 +370,14 @@ export interface HandlerOptions {
   /** Per-table row ownership for IDOR protection on PATCH/DELETE.
    *  Auto-appends WHERE <column> = user[<userField>] to mutations.
    *  GET/POST are unaffected — reads use RLS, creates use hooks.
-   *  Example: { posts: { column: 'authorId', userField: 'sub' } } */
-  rowOwnership?: Record<string, { column: string; userField: string }>;
+   *  Example: { posts: { column: 'authorId', userField: 'sub' } }
+   *
+   *  `exceptRoles` lists roles that skip the clause, e.g. an admin RLS lets write any row.
+   *  It mirrors an RLS policy and never stands alone: RLS still decides the write.
+   *  The caller's role is read from `auth.roleField` (default `role`) and must match a
+   *  listed role exactly. No hierarchy, no case folding. A missing role keeps the clause.
+   *  The role claim must be trusted: keep `role` out of anything a user can write. */
+  rowOwnership?: Record<string, { column: string; userField: string; exceptRoles?: string[] }>;
   /** When true, error messages hide internal details (table names, column names, operators).
    *  Enable in production to prevent schema enumeration. Default: false. */
   hideSchemaErrors?: boolean;
@@ -285,6 +402,17 @@ function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): Dri
   return getColumn(table, colName);
 }
 
+/**
+ * The soft-delete condition for a GET or PATCH: ?deleted=include adds none, ?deleted=only
+ * matches deleted rows, anything else (absent or unknown) matches live rows. DELETE does
+ * not use it: it always matches live rows only.
+ */
+function softDeleteCondition(sdCol: DrizzleColumn, params: URLSearchParams): SQL | null {
+  const mode = params.get('deleted');
+  if (mode === 'include') return null;
+  return mode === 'only' ? isNotNull(sdCol) : isNull(sdCol);
+}
+
 function isSoftDeleteTable(tableName: string, table: DrizzleTable, options?: HandlerOptions): boolean {
   if (!options?.softDelete) return false;
   if (options.softDelete.tables) {
@@ -294,19 +422,6 @@ function isSoftDeleteTable(tableName: string, table: DrizzleTable, options?: Han
   return getSoftDeleteColumn(table, options) != null;
 }
 
-/**
- * Detect PostgreSQL permission denied errors (code 42501).
- * Used to convert Postgres GRANT/RLS denials into clean 403 responses.
- */
-function isPermissionDenied(error: unknown): boolean {
-  if (error && typeof error === 'object') {
-    const e = error as Record<string, unknown>;
-    if (e.code === '42501') return true;
-    if (typeof e.message === 'string' && e.message.includes('permission denied')) return true;
-  }
-  return false;
-}
-
 /**
  * Execute a function with pgSettings applied in the same transaction.
  *
@@ -345,6 +460,16 @@ async function executeWithSettings<T>(
 }
 
 
+/**
+ * The caller's role claim, or '' when it is missing or not a string. pgSettings compares
+ * the claim strictly, so a claim such as ['admin'] must never read as 'admin' here.
+ * Every role gate reads the claim through this one function.
+ */
+function readRoleClaim(user: Record<string, unknown>, roleField: string): string {
+  const claim = user[roleField];
+  return typeof claim === 'string' ? claim : '';
+}
+
 /**
  * Check whether userRole meets or exceeds requiredRole in the hierarchy.
  * Both in hierarchy → index comparison. Otherwise → exact string match.
@@ -354,6 +479,7 @@ function hasRole(
   requiredRole: string,
   hierarchy: string[],
 ): boolean {
+  if (!userRole || !requiredRole) return false;
   const requiredIndex = hierarchy.indexOf(requiredRole);
   const userIndex = hierarchy.indexOf(userRole);
   if (requiredIndex !== -1 && userIndex !== -1) {
@@ -362,6 +488,17 @@ function hasRole(
   return userRole === requiredRole;
 }
 
+/**
+ * The result of an auth check. `outage` is the caught error when the verifier
+ * was unreachable (error is then the 503); a caller that returns `error`
+ * passes it to emitAuthOutage.
+ */
+interface AuthResult {
+  user: Record<string, unknown> | null;
+  error: Response | null;
+  outage?: unknown;
+}
+
 /**
  * Extract Bearer token from request and verify it.
  * Returns { user, error } — error is a Response (401) if auth fails.
@@ -369,7 +506,7 @@ function hasRole(
 async function verifyUserToken(
   request: Request,
   auth: AuthConfig,
-): Promise<{ user: Record<string, unknown> | null; error: Response | null }> {
+): Promise<AuthResult> {
   const authHeader = request.headers.get('Authorization');
   const token = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : null;
 
@@ -380,7 +517,11 @@ async function verifyUserToken(
   let user: Record<string, unknown> | null;
   try {
     user = await auth.verifyToken(token);
-  } catch {
+  } catch (err) {
+    // An unreachable verifier is not a bad token: 401 would log the user out.
+    if (isServiceUnavailable(err)) {
+      return { user: null, error: serviceUnavailableResponse(), outage: err };
+    }
     return { user: null, error: json({ message: 'Authentication failed: invalid or expired token' }, 401) };
   }
 
@@ -402,7 +543,7 @@ async function checkRoleAuth(
   requiredRole: string,
   request: Request,
   auth: AuthConfig,
-): Promise<{ user: Record<string, unknown> | null; error: Response | null }> {
+): Promise<AuthResult> {
   if (requiredRole === 'public') {
     return { user: null, error: null };
   }
@@ -417,8 +558,7 @@ async function checkRoleAuth(
 
   // Named role: check hierarchy
   const hierarchy = auth.roleHierarchy ?? ['public', 'authenticated', 'admin'];
-  const roleField = auth.roleField ?? 'role';
-  const userRole = String(result.user![roleField] ?? '');
+  const userRole = readRoleClaim(result.user!, auth.roleField ?? 'role');
 
   if (!hasRole(userRole, requiredRole, hierarchy)) {
     return {
@@ -608,7 +748,7 @@ function expandSchema(schema: Schema, pairs: Array<{ exportKey: string; sqlName:
   if (pairs.length === 0) return schema;
   const expanded: Schema = { ...schema };
   for (const { exportKey, sqlName } of pairs) {
-    if (!(sqlName in expanded)) expanded[sqlName] = schema[exportKey];
+    if (!Object.hasOwn(expanded, sqlName)) expanded[sqlName] = schema[exportKey];
   }
   return expanded;
 }
@@ -632,7 +772,7 @@ function expandTableKeyedOptions(
     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];
+      if (t && !Object.hasOwn(out, t)) out[t] = map[key];
     }
     return out;
   };
@@ -644,12 +784,114 @@ function expandTableKeyedOptions(
     ...(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) } }
+    ...(options.softDelete
+      ? {
+        softDelete: {
+          ...options.softDelete,
+          ...(options.softDelete.tables ? { tables: expandList(options.softDelete.tables) } : {}),
+          ...(options.softDelete.restore ? { restore: expandMap(options.softDelete.restore) } : {}),
+        },
+      }
       : {}),
   };
 }
 
+/**
+ * Every table the options name outside rowOwnership, in snake_case so that `userPosts`
+ * and `user_posts` in two maps of the same options match.
+ */
+function declaredTables(options: HandlerOptions): Set<string> {
+  const names = [
+    ...(options.exposedTables ?? []),
+    ...Object.keys(options.hiddenColumns ?? {}),
+    ...Object.keys(options.protectedFields ?? {}),
+    ...Object.keys(options.hooks ?? {}),
+    ...Object.keys(options.relations ?? {}),
+    ...Object.values(options.relations ?? {}).flatMap(rels => Object.values(rels).map(rel => rel.table)),
+    ...(options.softDelete?.tables ?? []),
+  ];
+  return new Set(names.map(toSnakeCase));
+}
+
+/**
+ * Refuse to start on a rowOwnership config the handler cannot enforce. The owner clause
+ * needs a user, so rowOwnership without auth is an error. An entry whose column does not
+ * resolve (same resolver as request time) is an error. An entry for a table this handler
+ * does not serve is accepted only when the options declare that table elsewhere: derived
+ * configs name every table while a handler serves a few. Otherwise it is a typo that would
+ * leave the real table unscoped, and an error. An entry with exceptRoles needs pgSettings:
+ * without SET LOCAL ROLE no RLS policy backs the exemption, only the JWT role claim.
+ */
+function validateRowOwnership(schema: Schema, options: HandlerOptions | undefined): void {
+  const entries = Object.entries(options?.rowOwnership ?? {});
+  if (entries.length === 0) return;
+  if (!options?.auth) {
+    throw new Error('[everystack/api] rowOwnership requires auth: the owner clause needs an authenticated user');
+  }
+  const declared = declaredTables(options);
+  for (const [tableName, entry] of entries) {
+    const table = schema[tableName];
+    if (!table) {
+      if (declared.has(toSnakeCase(tableName))) continue;
+      throw new Error(
+        `[everystack/api] rowOwnership.${tableName}: table "${tableName}" is not in the schema and is not declared anywhere else in the handler options (exposedTables, relations, hiddenColumns, protectedFields, softDelete, hooks). Fix the name or remove the entry.`,
+      );
+    }
+    if (getColumn(table, entry.column) === null) {
+      throw new Error(
+        `[everystack/api] rowOwnership.${tableName}.column "${entry.column}" does not resolve to a column of table "${tableName}"`,
+      );
+    }
+    if ((entry.exceptRoles?.length ?? 0) > 0 && !options.pgSettings) {
+      throw new Error(
+        `[everystack/api] rowOwnership.${tableName}.exceptRoles requires options.pgSettings: without SET LOCAL ROLE the exemption trusts the JWT role claim alone and no RLS policy backs it. Add pgSettings or remove exceptRoles.`,
+      );
+    }
+  }
+}
+
+/**
+ * Refuse to start on a softDelete.restore config the handler cannot honour. Every entry
+ * must name a soft-delete table. A restorable table must not list the soft-delete column
+ * in protectedFields: the strip would leave every restore body empty. Takes the expanded
+ * options, so both spellings of a table are checked.
+ */
+function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | undefined): void {
+  const softDelete = options?.softDelete;
+  const colName = softDelete?.column || 'deletedAt';
+  for (const [tableName, roles] of Object.entries(softDelete?.restore ?? {})) {
+    const table = schema[tableName];
+    const isSoftDelete = table
+      ? isSoftDeleteTable(tableName, table, options)
+      : (softDelete?.tables?.includes(tableName) ?? false);
+    if (!isSoftDelete) {
+      throw new Error(
+        `[everystack/api] softDelete.restore.${tableName}: table "${tableName}" is not a soft-delete table. Add it to softDelete.tables or remove the entry.`,
+      );
+    }
+    const sameColumn = (field: string): boolean => (table
+      ? getColumn(table, field) !== null && getColumn(table, field) === getColumn(table, colName)
+      : toSnakeCase(field) === toSnakeCase(colName));
+    if (roles.length > 0 && (options?.protectedFields?.[tableName] ?? []).some(sameColumn)) {
+      throw new Error(
+        `[everystack/api] softDelete.restore.${tableName}: the soft-delete column "${colName}" is in protectedFields.${tableName}, so every restore body is stripped to {}. Remove it from protectedFields.${tableName} or remove the restore entry.`,
+      );
+    }
+  }
+}
+
+/**
+ * True when the caller may restore on this table: its role claim is an exact member of
+ * softDelete.restore[tableName]. Fail closed: no option, no list, no user, or a missing or
+ * non-string role claim is not a member.
+ */
+function mayRestore(tableName: string, options: HandlerOptions | undefined, user: Record<string, unknown> | null): boolean {
+  const roles = options?.softDelete?.restore?.[tableName];
+  if (!roles?.length || !user) return false;
+  const role = readRoleClaim(user, options?.auth?.roleField ?? 'role');
+  return role !== '' && roles.includes(role);
+}
+
 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
@@ -659,6 +901,19 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
   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.',
+        );
+      }
+    }
+  }
+  validateRowOwnership(schema, rawOptions);
+  validateSoftDeleteRestore(schema, options);
   const tableNames = new Set(Object.keys(schema));
   const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
@@ -707,7 +962,17 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
 
       try {
         client = await options.auth.verifyClient(clientId ?? '', clientSecret ?? '', referer ?? undefined);
-      } catch {
+      } catch (err) {
+        if (isServiceUnavailable(err)) {
+          // The route is not resolved yet: name what the path asks for, but
+          // only a declared table or RPC. Any other segment is caller text.
+          const [first, second] = pathSegments;
+          const where = first === 'rpc'
+            ? { kind: 'rpc' as const, name: declaredRpcName(options.rpc, second) }
+            : { kind: 'rest' as const, name: first && tableNames.has(first) ? first : '' };
+          await emitAuthOutage(options.onError, { requestId, method, ...where }, err);
+          return serviceUnavailableResponse();
+        }
         return json({ message: 'Client authentication failed: invalid client credentials' }, 401);
       }
 
@@ -737,14 +1002,23 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           && options.auth.publicRpc?.includes(pathSegments[1]);
         if (!isPublicMethod && !isPublicRpc) {
           const result = await verifyUserToken(request, options.auth);
-          if (result.error) return result.error;
+          if (result.error) {
+            await emitAuthOutage(options.onError, { requestId, kind: 'rpc', name: declaredRpcName(options.rpc, pathSegments[1]), method }, result.outage);
+            return result.error;
+          }
           user = result.user;
         } else if (request.headers.get('authorization')) {
           // Public RPC with token present — verify opportunistically, same
           // policy as public table routes below. If valid, the request runs
           // as authenticated (RLS self-visibility, PII self-tiers). If
-          // invalid, ignore and fall through as anonymous.
+          // invalid, ignore and fall through as anonymous. If the verifier
+          // is down, answer 503: running a signed-in caller as anonymous
+          // would hand them anonymous data as if it were theirs.
           const result = await verifyUserToken(request, options.auth);
+          if (result.error && result.outage !== undefined) {
+            await emitAuthOutage(options.onError, { requestId, kind: 'rpc', name: declaredRpcName(options.rpc, pathSegments[1]), method }, result.outage);
+            return result.error;
+          }
           if (!result.error) user = result.user;
         }
         if (user && options.auth.onAuthenticated) {
@@ -753,14 +1027,17 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
 
       const fnName = pathSegments[1];
-      if (options?.rpc && fnName && options.rpc[fnName]) {
-        const entry = options.rpc[fnName];
+      const entry = fnName ? ownEntry(options?.rpc, fnName) : undefined;
+      if (fnName && entry) {
         const isObjectForm = typeof entry !== 'function';
 
         // Per-RPC role check (object syntax: { fn, role })
         if (isObjectForm && entry.role && options?.auth) {
           const roleResult = await checkRoleAuth(entry.role, request, options.auth);
-          if (roleResult.error) return roleResult.error;
+          if (roleResult.error) {
+            await emitAuthOutage(options.onError, { requestId, kind: 'rpc', name: fnName, method }, roleResult.outage);
+            return roleResult.error;
+          }
           user = roleResult.user;
         } else if (isObjectForm && entry.role && !options?.auth) {
           // Role required but no auth configured — deny
@@ -802,7 +1079,11 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           // webhooks). Swallow errors — a side-effect failure must not fail the
           // write, exactly like the after* REST hooks. Success path only.
           if (options?.afterRpc) {
-            try { await options.afterRpc(result, fnName, body, user, client, ctx); } catch {}
+            try {
+              await options.afterRpc(result, fnName, body, user, client, ctx);
+            } catch (err) {
+              await reportHookFault(options.onError, { requestId, name: `rpc.${fnName}.afterRpc`, method }, err);
+            }
           }
           // Same cache discipline as table GETs: with pgSettings configured the
           // response can vary by identity (opportunistic auth on public RPCs),
@@ -813,9 +1094,18 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           const rpcCacheControl = getCacheControl(options);
           return json(result, 200, rpcCacheControl ? { 'Cache-Control': rpcCacheControl } : undefined);
         } catch (error) {
-          const pgCode = (error as any)?.code;
+          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;
+          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);
           let status = 500;
-          if (pgCode === '28P01') status = 401;
+          if (unavailable) status = 503;
           else if (pgCode === '42501') status = 403;
           else if (pgCode === '23505') status = 409;
           else if (pgCode === '22023' || pgCode === 'P0001') status = 422;
@@ -833,15 +1123,14 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
             await emitFault(options?.onError, {
               requestId, kind: 'rpc', name: fnName, method,
               status: error instanceof HandlerError ? error.status : status,
-              message: error instanceof Error ? error.message : String(error),
-              stack: error instanceof Error ? error.stack : undefined,
-              pgCode,
+              ...describeError(error),
             });
           }
           if (error instanceof HandlerError) {
             return json({ message: error.message }, error.status);
           }
-          const message = error instanceof Error ? error.message : 'RPC execution failed';
+          if (unavailable) return serviceUnavailableResponse();
+          const message = !hostile && error instanceof Error ? text : 'RPC execution failed';
           if (options?.hideSchemaErrors && status === 500) {
             return json({ message: 'Internal Server Error' }, 500);
           }
@@ -867,13 +1156,21 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       const isPublicMethod = options.auth.publicRoutes.includes(method);
       if (!isPublicMethod) {
         const result = await verifyUserToken(request, options.auth);
-        if (result.error) return result.error;
+        if (result.error) {
+          await emitAuthOutage(options.onError, { requestId, kind: 'rest', name: tableName, method }, result.outage);
+          return result.error;
+        }
         user = result.user;
       } else if (request.headers.get('authorization')) {
         // Public route with token present — verify opportunistically.
         // If valid, the request runs as authenticated (better RLS access).
-        // If invalid, ignore and fall through as anonymous.
+        // If invalid, ignore and fall through as anonymous. If the verifier
+        // is down, answer 503, as the public RPC branch above does.
         const result = await verifyUserToken(request, options.auth);
+        if (result.error && result.outage !== undefined) {
+          await emitAuthOutage(options.onError, { requestId, kind: 'rest', name: tableName, method }, result.outage);
+          return result.error;
+        }
         if (!result.error) user = result.user;
       }
 
@@ -882,16 +1179,15 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
     }
 
-    // Compute pgSettings after auth (user now resolved)
-    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.
+    // (never values — values can be PII). Unresolved embed policies also record
+    // GET denials; other reads are delegated to RLS.
     const isWrite = method === 'POST' || method === 'PATCH' || method === 'DELETE';
-    const auditOp: 'insert' | 'update' | 'delete' =
-      method === 'POST' ? 'insert' : method === 'PATCH' ? 'update' : 'delete';
+    const auditOp: 'insert' | 'update' | 'delete' | 'select' =
+      method === 'GET' ? 'select' : method === 'POST' ? 'insert' : method === 'PATCH' ? 'update' : 'delete';
     const auditFilter = url.searchParams.toString() || undefined;
     let auditColumns: string[] | undefined;
     if (isWrite && options?.audit?.sink && method !== 'DELETE') {
@@ -909,27 +1205,89 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
     const routedDb = method === 'GET' && !user && options?.readDb ? options.readDb : db;
 
     try {
-      const response = await executeWithSettings(routedDb, settings, async (dbOrTx) => {
-        if (method === 'GET') {
-          const cacheControl = getCacheControl(options);
-          return handleGet(dbOrTx, schema, table, tableName, url.searchParams, request, options, cacheControl);
+      // 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 auditReadDenial = false;
+      for (const selectParam of url.searchParams.getAll('select')) {
+        const maxEmbedDepth = options?.maxEmbedDepth ?? 3;
+        const depth = getEmbedDepth(selectParam);
+        if (depth > maxEmbedDepth) {
+          queryError = `Embed depth ${depth} exceeds maximum of ${maxEmbedDepth}`;
+          break;
         }
+      }
 
-        if (method === 'POST') {
-          return handlePost(dbOrTx, table, tableName, request, options, user, client);
+      // 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) {
+        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') {
+            queryError = 'Invalid query';
+            auditReadDenial = method === 'GET' && withClause === 'unresolvedHiddenColumns';
+            break;
+          }
         }
+      }
 
-        if (method === 'PATCH') {
-          return handlePatch(dbOrTx, table, tableName, request, url.searchParams, options, user, client);
-        }
+      // pgSettings runs once per request. The settings map is known only here, so the
+      // check that it backs an ownership exemption runs here, before any transaction.
+      const settings = queryError ? undefined : options?.pgSettings?.(user, client);
+      const unbacked = queryError ? null : unbackedExemptionRefusal(method, tableName, options, user, settings);
+      // A returned 500 skips the catch below, so report it to onError here.
+      if (unbacked) {
+        await emitFault(options?.onError, { requestId, kind: 'rest', name: tableName, method, status: 500, message: unbacked });
+      }
+      // Work queued by the write. It runs only once executeWithSettings has
+      // returned or thrown (with pgSettings, after the transaction has ended).
+      // A before-hook fault runs in the finally, for any outcome: the hook failed
+      // even when the commit then fails too. A table after-hook runs only for a
+      // 2xx; a throw (a failed commit) skips it, since the write did not happen.
+      // A retry wrapper around db.transaction must reset `deferred` per attempt,
+      // or the hooks of an aborted attempt would run too.
+      const deferred: Deferred[] = [];
+      let response: Response;
+      try {
+        response = queryError ? json({ message: queryError }, 400)
+          : unbacked ? json({ message: unbacked }, 500) : await executeWithSettings(routedDb, settings, async (dbOrTx) => {
+          if (method === 'GET') {
+            const cacheControl = getCacheControl(options);
+            return handleGet(dbOrTx, schema, table, tableName, url.searchParams, request, options, cacheControl);
+          }
 
-        if (method === 'DELETE') {
-          return handleDelete(dbOrTx, table, tableName, url.searchParams, options, user, client);
-        }
+          if (method === 'POST') {
+            return handlePost(dbOrTx, table, tableName, request, options, user, client, requestId, deferred);
+          }
 
-        return json({ message: `Method ${method} not allowed` }, 405);
-      });
-      if (isWrite) {
+          if (method === 'PATCH') {
+            return handlePatch(dbOrTx, table, tableName, request, url.searchParams, options, user, client, requestId, deferred);
+          }
+
+          if (method === 'DELETE') {
+            return handleDelete(dbOrTx, table, tableName, url.searchParams, options, user, client, requestId, deferred);
+          }
+
+          return json({ message: `Method ${method} not allowed` }, 405);
+        });
+      } finally {
+        // emitFault never throws, so this cannot replace the error in flight.
+        for (const item of deferred) if (item.always) await item.run();
+      }
+      if (response.status >= 200 && response.status < 300) {
+        // The contract: a side effect fires only for a successful write. The guard is
+        // unreachable today (every refusal returns before the write queues a hook) and
+        // stays for the next write path. Each queued hook reports its own throw, so
+        // none can fail the response.
+        for (const item of deferred) if (!item.always) await item.run();
+      }
+      if (isWrite || auditReadDenial) {
         await emitAudit(options?.audit, {
           kind: 'rest', name: tableName, user, client,
           result: response.status < 400 ? 'allow' : response.status < 500 ? 'deny' : 'error',
@@ -948,56 +1306,106 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       if (isPermissionDenied(error)) {
         return sanitizeError('Permission denied', 403, options);
       }
-      // 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 4xx status is a
-      // deliberate refusal from a hook, not a fault — leave it alone.
+      // 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);
+      // 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
+      // 4xx status is a deliberate refusal from a hook, not a fault — leave it alone.
       if (!(error instanceof HandlerError) || error.status >= 500) {
         await emitFault(options?.onError, {
           requestId, kind: 'rest', name: tableName, method,
-          status: error instanceof HandlerError ? error.status : 500,
-          message: error instanceof Error ? error.message : String(error),
-          stack: error instanceof Error ? error.stack : undefined,
-          pgCode: (error as any)?.code,
+          status: error instanceof HandlerError ? error.status : unavailable ? 503 : 500,
+          ...describeError(error),
         });
       }
+      if (unavailable) return serviceUnavailableResponse();
       throw error;
     }
   };
 }
 
-/**
- * Convert parsed embeds to Drizzle's `with` clause format for relational queries.
- * { name: 'author', columns: null } → { author: true }
- * { name: 'author', columns: ['name'] } → { author: { columns: { name: true } } }
- */
+/** Drizzle selections use schema property names, even when the API uses SQL names. */
+function columnPropertyName(table: DrizzleTable | undefined, name: string): string | undefined {
+  if (!table) return undefined;
+  const column = getColumn(table, name);
+  const columns = Object.entries(getTableColumns(table));
+  return columns.find(([, value]) => value === column)?.[0]
+    ?? columns.find(([, value]) => (value as DrizzleColumn).name === name)?.[0];
+}
+
+/** Build each relation's projection before Drizzle reads its values. */
 function buildWithClause(
   embeds: EmbedRequest[],
   tableRelations: Record<string, RelationConfig>,
-): Record<string, any> | undefined {
+  schema: Schema,
+  options?: HandlerOptions,
+): Record<string, any> | undefined | null | 'unresolvedHiddenColumns' {
   if (embeds.length === 0) return undefined;
 
   const withClause: Record<string, any> = {};
   let hasEmbedded = false;
 
   for (const embed of embeds) {
-    if (!tableRelations[embed.name]) continue;
+    const relation = tableRelations[embed.name];
+    if (!relation) continue;
     hasEmbedded = true;
-
-    if (embed.columns === null) {
-      withClause[embed.name] = true;
-    } else {
-      const columns: Record<string, boolean> = {};
-      for (const col of embed.columns) {
-        columns[col] = true;
-      }
-      withClause[embed.name] = { columns };
+    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 config: Record<string, any> = {};
+    if (embed.columns !== null) {
+      // Drop names that are not columns of a known table: Drizzle ignores them,
+      // and throws when nothing else is left. An emptied list is the 400 below.
+      config.columns = Object.fromEntries(embed.columns
+        .map(name => (table ? columnPropertyName(table, name) : name))
+        .filter((name): name is string => name !== undefined && !hidden.has(name))
+        .map(name => [name, true]));
+      if (Object.keys(config.columns).length === 0) return null;
+    } else if (hidden.size > 0) {
+      config.columns = Object.fromEntries([...hidden].map(name => [name, false]));
     }
+    withClause[embed.name] = Object.keys(config).length > 0 ? config : true;
   }
 
   return hasEmbedded ? withClause : undefined;
 }
 
+/** Follow only parsed relations: a similarly named JSON key is not a table column. */
+function stripEmbeddedHiddenColumns(
+  data: unknown,
+  embeds: EmbedRequest[],
+  tableName: string,
+  schema: Schema,
+  options?: HandlerOptions,
+): unknown {
+  if (embeds.length === 0 || data === null || typeof data !== 'object') return data;
+  if (Array.isArray(data)) {
+    return data.map(row => stripEmbeddedHiddenColumns(row, embeds, tableName, schema, options));
+  }
+  const result = { ...(data as Record<string, unknown>) };
+  for (const embed of embeds) {
+    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 },
+    });
+    result[key] = stripEmbeddedHiddenColumns(related, embed.embeds, relation.table, schema, options);
+  }
+  return result;
+}
+
 /**
  * Convert column names array to Drizzle's `columns` selection format.
  * ['id', 'title'] → { id: true, title: true }
@@ -1100,17 +1508,8 @@ async function handleGet(
   const prefer = request.headers.get('Prefer') || '';
   const wantExactCount = prefer.includes('count=exact');
 
-  // Enforce maximum embed depth to prevent DoS from deeply nested relation queries
-  if (selectParam) {
-    const maxEmbedDepth = options?.maxEmbedDepth ?? 3;
-    const depth = getEmbedDepth(selectParam);
-    if (depth > maxEmbedDepth) {
-      return json({ message: `Embed depth ${depth} exceeds maximum of ${maxEmbedDepth}` }, 400);
-    }
-  }
-
   // Parse select parameter for relation embedding and aggregates
-  let { columns, embeds, aggregates } = parseSelectParam(selectParam, options?.relations?.[tableName], options?.relations);
+  let { columns, embeds, aggregates } = parseSelectParam(selectParam, ownEntry(options?.relations, tableName), options?.relations);
 
   // Resolve snake_case select column names to Drizzle camelCase properties
   if (options?.naming === 'snake_case' && columns) {
@@ -1132,13 +1531,8 @@ async function handleGet(
   if (isSoftDeleteTable(tableName, table, options)) {
     const sdCol = getSoftDeleteColumn(table, options);
     if (sdCol) {
-      const deletedParam = params.get('deleted');
-      if (deletedParam === 'only') {
-        conditions.push(isNotNull(sdCol));
-      } else if (deletedParam !== 'include') {
-        // Default: exclude deleted records
-        conditions.push(isNull(sdCol));
-      }
+      const condition = softDeleteCondition(sdCol, params);
+      if (condition) conditions.push(condition);
     }
   }
 
@@ -1197,7 +1591,7 @@ async function handleGet(
   }
 
   // Detect if Drizzle relational query (JOINs) should be used
-  const tableRelations = options?.relations?.[tableName];
+  const tableRelations = ownEntry(options?.relations, tableName);
   const useRelationalQuery = embeds.length > 0
     && tableRelations
     && options?.drizzleRelations
@@ -1215,7 +1609,10 @@ async function handleGet(
     const colSelection = buildColumnsSelection(columns);
     if (colSelection) queryOptions.columns = colSelection;
 
-    const withClause = buildWithClause(embeds, tableRelations!);
+    const withClause = buildWithClause(embeds, tableRelations!, schema, options);
+    if (withClause === null || withClause === 'unresolvedHiddenColumns') {
+      return json({ message: 'Invalid query' }, 400);
+    }
     if (withClause) queryOptions.with = withClause;
 
     if (conditions.length === 1) {
@@ -1304,7 +1701,8 @@ async function handleGet(
   };
   if (cacheControl) getHeaders['Cache-Control'] = cacheControl;
 
-  return new Response(JSON.stringify(stripHiddenColumns(transformResponse(responseData, options), tableName, options)), {
+  const transformed = stripHiddenColumns(transformResponse(responseData, options), tableName, options);
+  return new Response(JSON.stringify(stripEmbeddedHiddenColumns(transformed, embeds, tableName, schema, options)), {
     status: 200,
     headers: getHeaders,
   });
@@ -1374,12 +1772,12 @@ function parseSelectParam(
     }
 
     const embedMatch = part.match(/^(\w+)\((.+)\)$/);
-    if (embedMatch && tableRelations && embedMatch[1] in tableRelations) {
+    if (embedMatch && tableRelations && Object.hasOwn(tableRelations, embedMatch[1])) {
       const name = embedMatch[1];
       const innerSelect = embedMatch[2].trim();
       // Recursively parse sub-embeds using the target table's relations
       const targetTableName = tableRelations[name].table;
-      const targetRelations = allRelations?.[targetTableName];
+      const targetRelations = ownEntry(allRelations, targetTableName);
       const inner = parseSelectParam(innerSelect, targetRelations, allRelations);
       embeds.push({
         name,
@@ -1431,6 +1829,71 @@ function splitSelectParam(param: string): string[] {
   return parts;
 }
 
+/** Check explicit query references, including each related table's own policy. */
+function requestUsesHiddenColumn(
+  schema: Schema,
+  tableName: string,
+  params: URLSearchParams,
+  options?: HandlerOptions,
+): boolean {
+  if (!options?.hiddenColumns) return false;
+
+  const isHidden = (sourceTable: string, reference: string): boolean => {
+    let targetName = sourceTable;
+    let columnName = parseJsonPath(reference)?.baseColumn ?? reference;
+    // Prefer a real source column. The relation fallback only rejects hidden
+    // references; the filter and order builders do not support relation paths.
+    if (!getColumn(schema[targetName], columnName)) {
+      const parts = columnName.split('.');
+      while (parts.length > 1) {
+        const relation = ownEntry(ownEntry(options.relations, targetName), parts.shift()!);
+        if (!relation || !schema[relation.table]) return false;
+        targetName = relation.table;
+      }
+      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);
+    });
+  };
+
+  const selectUsesHidden = (sourceTable: string, select: string): boolean => {
+    // Walk the raw selection: parseSelectParam collapses `*,secret` to a
+    // wildcard and discards aggregates inside embeds, losing explicit names.
+    return splitSelectParam(select).some(part => {
+      const aggregate = part.match(AGG_REGEX);
+      if (aggregate) return aggregate[2] ? isHidden(sourceTable, aggregate[2]) : false;
+      const embed = part.match(/^(\w+)\((.+)\)$/);
+      const relation = embed && ownEntry(ownEntry(options.relations, sourceTable), embed[1]);
+      if (embed && relation && schema[relation.table]) {
+        return selectUsesHidden(relation.table, embed[2]);
+      }
+      return part !== '*' && isHidden(sourceTable, part);
+    });
+  };
+
+  for (const [key, value] of params) {
+    if (key === 'select') {
+      if (selectUsesHidden(tableName, value)) return true;
+    } else if (key === 'order') {
+      if (value.split(',').some(order => {
+        const dot = order.lastIndexOf('.');
+        return isHidden(tableName, (dot < 0 ? order : order.slice(0, dot)).trim());
+      })) return true;
+    } else if (key === 'or' || key === 'and') {
+      if (parseLogicalGroup(value).some(filter => isHidden(tableName, filter.column))) return true;
+    } else if (!RESERVED_QUERY_PARAMS.has(key) && isHidden(tableName, key)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Resolve relation embeds by fetching related rows and nesting them.
  */
@@ -1442,7 +1905,7 @@ async function resolveEmbeds(
   embeds: EmbedRequest[],
   options: HandlerOptions,
 ): Promise<Record<string, unknown>[]> {
-  const tableRelations = options.relations?.[tableName];
+  const tableRelations = ownEntry(options.relations, tableName);
   if (!tableRelations) return rows;
 
   // Clone rows to avoid mutation
@@ -1563,6 +2026,37 @@ function pickColumns(row: Record<string, unknown>, columns: string[]): Record<st
   return result;
 }
 
+/**
+ * The response for a before-hook that threw. A HandlerError keeps its own status and
+ * message. An outage (the hook could not reach the database) answers the fixed 503,
+ * like every other outage path. Anything else is a generic 500 so the hook's text
+ * never reaches the client. A 5xx is a fault and goes to onError; a 4xx HandlerError
+ * is a refusal and does not. The fault is queued, not sent: with pgSettings the hook
+ * ran inside the transaction, and a slow onError must not hold it open.
+ */
+function beforeHookFailure(
+  err: unknown,
+  options: HandlerOptions | undefined,
+  at: { requestId?: string; name: string; method: string },
+  deferred: Deferred[],
+): Response {
+  const report = (fault: HandlerFault): void => {
+    deferred.push({ always: true, run: () => emitFault(options?.onError, fault) });
+  };
+  if (err instanceof HandlerError) {
+    if (err.status >= 500) {
+      report({ ...at, kind: 'rest', status: err.status, message: err.message });
+    }
+    return json({ message: err.message }, err.status);
+  }
+  if (isServiceUnavailable(err)) {
+    report({ ...at, kind: 'rest', status: 503, ...describeError(err) });
+    return serviceUnavailableResponse();
+  }
+  report({ ...at, kind: 'rest', status: 500, ...describeError(err) });
+  return json({ message: 'Hook error' }, 500);
+}
+
 async function handlePost(
   db: DrizzleDb,
   table: DrizzleTable,
@@ -1571,6 +2065,8 @@ async function handlePost(
   options?: HandlerOptions,
   user: Record<string, unknown> | null = null,
   client: Record<string, unknown> | null = null,
+  requestId?: string,
+  deferred: Deferred[] = [],
 ): Promise<Response> {
   let body: Record<string, unknown>;
   try {
@@ -1599,10 +2095,7 @@ async function handlePost(
     try {
       body = await hook.beforeCreate(body, user, client);
     } catch (err) {
-      if (err instanceof HandlerError) {
-        return json({ message: err.message }, err.status);
-      }
-      return json({ message: 'Hook error' }, 500);
+      return beforeHookFailure(err, options, { requestId, name: tableName, method: 'POST' }, deferred);
     }
   }
 
@@ -1619,7 +2112,9 @@ async function handlePost(
   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 {}
+    const { afterCreate } = hook;
+    deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterCreate`, method: 'POST' },
+      () => afterCreate.call(hook, rows[0], user, client));
   }
 
   return json(stripHiddenColumns(transformResponse(rows[0], options), tableName, options), 201);
@@ -1634,13 +2129,20 @@ async function handlePatch(
   options?: HandlerOptions,
   user: Record<string, unknown> | null = null,
   client: Record<string, unknown> | null = null,
+  requestId?: string,
+  deferred: Deferred[] = [],
 ): Promise<Response> {
+  // Ownership refusal first: before the body, the filter, or any hook is examined.
+  const scope = ownershipScope(table, tableName, options, user);
+  if ('refusal' in scope) return scope.refusal;
+
   let body: Record<string, unknown>;
   try {
     body = await request.json();
   } catch {
     return json({ message: 'Invalid JSON body' }, 400);
   }
+  const clientBody = body;
 
   try {
     // Map body keys to Drizzle property names when naming convention is active
@@ -1656,40 +2158,68 @@ async function handlePatch(
     throw err;
   }
 
+  // Restore: ?deleted=include|only is honoured only for a role in softDelete.restore for
+  // this table. Anyone else is matched to live rows, as if the param were absent.
+  const sdCol = isSoftDeleteTable(tableName, table, options) ? getSoftDeleteColumn(table, options) : null;
+  const restoring = sdCol !== null && mayRestore(tableName, options, user);
+  const deletedMode = params.get('deleted');
+  if (restoring && (deletedMode === 'include' || deletedMode === 'only')) {
+    // Checked after the protectedFields strip, so a body stripped to {} is refused here.
+    const key = columnPropertyName(table, options?.softDelete?.column || 'deletedAt');
+    const isRestoreBody = body !== null && typeof body === 'object' && !Array.isArray(body)
+      && Object.keys(body).length === 1 && key !== undefined && Object.hasOwn(body, key) && body[key] === null;
+    if (!isRestoreBody) {
+      const column = options?.softDelete?.column || 'deletedAt';
+      const wire = options?.naming === 'snake_case' ? toSnakeCase(column) : column;
+      return json({ message: `restore accepts only { ${wire}: null }` }, 400);
+    }
+  }
+
+  // With the ownership backstop lifted, an unfiltered PATCH would write every row the
+  // role's RLS allows. Refuse it, the same filter test DELETE applies to every caller.
+  const ownership = options?.rowOwnership?.[tableName];
+  if (user && options && ownership && isOwnershipExempt(ownership, user, options)
+    && buildsNoFilter(table, params)) {
+    return json({ message: 'PATCH requires at least one filter when the ownership backstop is lifted for your role' }, 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) {
+    const key = ownerReassignmentKey(table, ownership, user, clientBody, body);
+    if (key !== null) return json({ message: `Cannot change ownership column "${key}"` }, 403);
+  }
+
   const hook = options?.hooks?.[tableName];
 
   if (hook?.beforeUpdate) {
     try {
       body = await hook.beforeUpdate(body, user, client);
     } catch (err) {
-      if (err instanceof HandlerError) {
-        return json({ message: err.message }, err.status);
-      }
-      return json({ message: 'Hook error' }, 500);
+      return beforeHookFailure(err, options, { requestId, name: tableName, method: 'PATCH' }, deferred);
     }
   }
 
+  // The final body, after the strip and the hook, must have something to write: an empty
+  // SET is a 500 from PostgreSQL. A hook may fill a body the strip emptied, so check here.
+  if (body === null || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).length === 0) {
+    return json({ message: 'No writable fields in request body' }, 400);
+  }
+
   const filterResult = buildAllConditions(table, params);
   if ('error' in filterResult) {
     return sanitizeError(filterResult.error, 400, options);
   }
   const conditions = filterResult.conditions;
 
-  // Soft-delete: exclude deleted records from updates
-  if (isSoftDeleteTable(tableName, table, options)) {
-    const sdCol = getSoftDeleteColumn(table, options);
-    if (sdCol) conditions.push(isNull(sdCol));
+  // Soft-delete: update live records, unless a restore role sent ?deleted=include|only
+  if (sdCol) {
+    const condition = restoring ? softDeleteCondition(sdCol, params) : isNull(sdCol);
+    if (condition) conditions.push(condition);
   }
 
-  // Row ownership: auto-append WHERE <column> = user[<userField>] for IDOR protection
-  if (user && options?.rowOwnership?.[tableName]) {
-    const ownership = options.rowOwnership[tableName];
-    const ownerCol = getColumn(table, ownership.column);
-    const userValue = user[ownership.userField];
-    if (ownerCol && userValue != null) {
-      conditions.push(eq(ownerCol, userValue));
-    }
-  }
+  // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection
+  if (scope.condition) conditions.push(scope.condition);
 
   let coerced: unknown;
   try {
@@ -1712,12 +2242,115 @@ async function handlePatch(
   const rows = await query.returning();
 
   if (hook?.afterUpdate && rows.length > 0) {
-    try { await hook.afterUpdate(rows, user, client); } catch {}
+    const { afterUpdate } = hook;
+    deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterUpdate`, method: 'PATCH' },
+      () => afterUpdate.call(hook, rows, user, client));
   }
 
   return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
 }
 
+/**
+ * True when the caller's role is an exact member of the entry's `exceptRoles`, so the
+ * ownership clause is skipped. Fail closed: no list, an empty list, a missing or
+ * non-string role claim, or any other role keeps the clause.
+ */
+function isOwnershipExempt(
+  ownership: { exceptRoles?: string[] },
+  user: Record<string, unknown>,
+  options: HandlerOptions,
+): boolean {
+  if (!ownership.exceptRoles?.length) return false;
+  const role = readRoleClaim(user, options.auth?.roleField ?? 'role');
+  return role !== '' && ownership.exceptRoles.includes(role);
+}
+
+/**
+ * The refusal message (sent with a 500) for a PATCH or DELETE whose ownership exemption
+ * fires while the request's pgSettings map has no role, or null. executeWithSettings runs
+ * SET LOCAL ROLE only for a truthy `role`; without it the connection stays on the table
+ * owner, RLS does not apply, and the JWT role claim alone would lift the owner clause. A
+ * caller who is not excepted keeps the clause, so it is never refused here.
+ */
+function unbackedExemptionRefusal(
+  method: string,
+  tableName: string,
+  options: HandlerOptions | undefined,
+  user: Record<string, unknown> | null,
+  settings: Record<string, string> | undefined,
+): string | null {
+  if (method !== 'PATCH' && method !== 'DELETE') return null;
+  const ownership = options?.rowOwnership?.[tableName];
+  if (!options || !ownership || !user || !isOwnershipExempt(ownership, user, options)) return null;
+  if (settings?.['role']) return null;
+  const message = `rowOwnership.${tableName}.exceptRoles: pgSettings returned no role for this request, so SET LOCAL ROLE did not run and no RLS policy backs the exemption. Write refused.`;
+  console.error(`[everystack/api] ${message}`);
+  return message;
+}
+
+/**
+ * The key, as the client spelled it, that would set the owner column to a value other
+ * than the caller's own, or null. A key matches when it resolves to the owner column
+ * object, so either spelling counts. The decision reads `body` (transformed and
+ * stripped: what would be written); the reported key comes from `clientBody`, so the
+ * message echoes only what the client sent. Null, an object or any other value is a
+ * change; the caller's own value, compared as a string, is a no-op.
+ */
+function ownerReassignmentKey(
+  table: DrizzleTable,
+  ownership: { column: string; userField: string },
+  user: Record<string, unknown>,
+  clientBody: unknown,
+  body: unknown,
+): string | null {
+  const ownerCol = getColumn(table, ownership.column);
+  const owner = String(user[ownership.userField]);
+  const changesOwner = ([key, value]: [string, unknown]): boolean =>
+    getColumn(table, key) === ownerCol
+    && (value === null || typeof value === 'object' || String(value) !== owner);
+  const written = Object.entries(body ?? {}).find(changesOwner);
+  if (!written) return null;
+  return Object.entries(clientBody ?? {}).find(changesOwner)?.[0] ?? written[0];
+}
+
+type OwnershipScope = { refusal: Response } | { condition: SQL | null };
+
+/**
+ * The owner clause for a PATCH or DELETE, or the refusal when it cannot be built. Fails
+ * closed for a table with a rowOwnership entry and a caller who is not excepted: no
+ * user is 401, a null, undefined or empty owner value is 403, an owner column that does not
+ * resolve is 403 (startup validation makes that unreachable; logged, never echoed).
+ * No entry, or an excepted role, yields no clause.
+ */
+function ownershipScope(
+  table: DrizzleTable,
+  tableName: string,
+  options: HandlerOptions | undefined,
+  user: Record<string, unknown> | null,
+): OwnershipScope {
+  const ownership = options?.rowOwnership?.[tableName];
+  if (!options || !ownership) return { condition: null };
+  if (!user) {
+    return { refusal: json({ message: 'Unauthorized: this table requires an authenticated owner' }, 401) };
+  }
+  if (isOwnershipExempt(ownership, user, options)) return { condition: null };
+  const forbidden = (): OwnershipScope => ({
+    refusal: json({ message: 'Forbidden: row ownership cannot be verified for this request' }, 403),
+  });
+  const userValue = user[ownership.userField];
+  // An empty string is not an owner: it would scope the write to rows owned by ''.
+  // A numeric 0 is a legal owner value, so only null, undefined and '' refuse.
+  if (userValue == null || userValue === '') return forbidden();
+  const ownerCol = getColumn(table, ownership.column);
+  if (!ownerCol) {
+    console.error(
+      `[everystack/api] rowOwnership.${tableName}.column "${ownership.column}" does not resolve to a column of table "${tableName}"; write refused`,
+    );
+    return forbidden();
+  }
+  return { condition: eq(ownerCol, userValue) };
+}
+
 async function handleDelete(
   db: DrizzleDb,
   table: DrizzleTable,
@@ -1726,12 +2359,15 @@ async function handleDelete(
   options?: HandlerOptions,
   user: Record<string, unknown> | null = null,
   client: Record<string, unknown> | null = null,
+  requestId?: string,
+  deferred: Deferred[] = [],
 ): Promise<Response> {
-  const filters = parseFilters(params);
-  const hasLogicalGroup = params.has('or') || params.has('and');
+  // Ownership refusal first, so it never reveals whether the filter was valid.
+  const scope = ownershipScope(table, tableName, options, user);
+  if ('refusal' in scope) return scope.refusal;
 
   // Safety: require at least one filter to prevent accidental mass deletion
-  if (filters.length === 0 && !hasLogicalGroup) {
+  if (buildsNoFilter(table, params)) {
     return json({ message: 'DELETE requires at least one filter to prevent accidental mass deletion' }, 400);
   }
 
@@ -1741,10 +2377,7 @@ async function handleDelete(
     try {
       await hook.beforeDelete(user, client);
     } catch (err) {
-      if (err instanceof HandlerError) {
-        return json({ message: err.message }, err.status);
-      }
-      return json({ message: 'Hook error' }, 500);
+      return beforeHookFailure(err, options, { requestId, name: tableName, method: 'DELETE' }, deferred);
     }
   }
 
@@ -1754,15 +2387,8 @@ async function handleDelete(
   }
   const conditions = filterResult.conditions;
 
-  // Row ownership: auto-append WHERE <column> = user[<userField>] for IDOR protection
-  if (user && options?.rowOwnership?.[tableName]) {
-    const ownership = options.rowOwnership[tableName];
-    const ownerCol = getColumn(table, ownership.column);
-    const userValue = user[ownership.userField];
-    if (ownerCol && userValue != null) {
-      conditions.push(eq(ownerCol, userValue));
-    }
-  }
+  // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection
+  if (scope.condition) conditions.push(scope.condition);
 
   // Soft-delete: convert DELETE to UPDATE SET deleted_at = NOW()
   if (isSoftDeleteTable(tableName, table, options)) {
@@ -1782,7 +2408,9 @@ async function handleDelete(
       const rows = await query.returning();
 
       if (hook?.afterDelete && rows.length > 0) {
-        try { await hook.afterDelete(rows, user, client); } catch {}
+        const { afterDelete } = hook;
+        deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
+          () => afterDelete.call(hook, rows, user, client));
       }
 
       return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
@@ -1801,7 +2429,9 @@ async function handleDelete(
   const rows = await query.returning();
 
   if (hook?.afterDelete && rows.length > 0) {
-    try { await hook.afterDelete(rows, user, client); } catch {}
+    const { afterDelete } = hook;
+    deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
+      () => afterDelete.call(hook, rows, user, client));
   }
 
   return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
@@ -2049,12 +2679,13 @@ function buildOrderBy(table: DrizzleTable, orderParam: string): any {
   return direction === 'desc' ? desc(column) : asc(column);
 }
 
+const RESERVED_QUERY_PARAMS = new Set(['limit', 'offset', 'order', 'select', 'deleted', 'or', 'and']);
+
 function parseFilters(params: URLSearchParams): Filter[] {
   const filters: Filter[] = [];
-  const reserved = new Set(['limit', 'offset', 'order', 'select', 'deleted', 'or', 'and']);
 
   for (const [key, value] of params.entries()) {
-    if (reserved.has(key)) continue;
+    if (RESERVED_QUERY_PARAMS.has(key)) continue;
 
     // Check for NOT modifier: not.eq.value → negated=true, operator=eq
     let negated = false;
@@ -2172,6 +2803,27 @@ function buildAllConditions(table: DrizzleTable, params: URLSearchParams): { con
   return { conditions };
 }
 
+/**
+ * True when the request's own filters build no SQL condition, so the write would run
+ * with no WHERE. A param that parses but builds nothing (`or=`, `or=()`, `and=junk`,
+ * `id=is.x`) is not a filter. Only user filters count: the soft-delete and ownership
+ * clauses the handler adds are not part of this test. A filter error is left to the
+ * caller's own buildAllConditions, which reports it.
+ */
+function buildsNoFilter(table: DrizzleTable, params: URLSearchParams): boolean {
+  const result = buildAllConditions(table, params);
+  return !('error' in result) && result.conditions.length === 0;
+}
+
+/**
+ * The outage answer. no-store keeps a CDN from caching it: CloudFront holds an
+ * origin 5xx for about 10 seconds, so a protected GET could get a stale 503
+ * after the database recovers.
+ */
+function serviceUnavailableResponse(): Response {
+  return json({ message: SERVICE_UNAVAILABLE_MESSAGE }, 503, { 'Cache-Control': 'no-store' });
+}
+
 function json(data: unknown, status: number, headers?: Record<string, string>): Response {
   return new Response(JSON.stringify(data), {
     status,