@everystack/api 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [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
+
+- PATCH honours ?deleted=include|only so a soft-deleted row can be restored
+
+### Fixed
+
+- refuse a JOIN embed list that names no real column
+- restore through PATCH is off unless softDelete.restore names the caller's role
+- a PATCH whose final body has nothing to write answers 400, not 500
+
 ## [0.4.3] - 2026-10-14
 
 ### BREAKING CHANGES

package/package.json

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

@@ -39,6 +39,9 @@ export interface CountResponse<T> extends ClientResponse<T> {
   total: number;
 }
 
+/** Soft-delete scope: `include` reads or writes live and deleted rows, `only` deleted rows. */
+export type DeletedMode = 'include' | 'only';
+
 export interface QueryBuilder {
   eq(column: string, value: string): QueryBuilder;
   neq(column: string, value: string): QueryBuilder;
@@ -68,6 +71,9 @@ export interface QueryBuilder {
   order(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
   limit(count: number): QueryBuilder;
   offset(count: number): QueryBuilder;
+  /** Soft-delete tables: ?deleted=include|only on select and update. `.deleted('only').update({ deletedAt: null })` restores,
+   *  for a role the handler lists in `softDelete.restore`; for anyone else update ignores it. */
+  deleted(mode: DeletedMode): QueryBuilder;
   execute(): Promise<ClientResponse<unknown[]>>;
   executeWithCount(): Promise<CountResponse<unknown[]>>;
   single(): Promise<ClientResponse<unknown>>;
@@ -123,6 +129,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
   let orderParam: string | null = null;
   let limitParam: number | null = null;
   let offsetParam: number | null = null;
+  let deletedParam: DeletedMode | null = null;
 
   const builder: QueryBuilder = {
     eq(column, value) { filters.push([column, `eq.${value}`]); return builder; },
@@ -151,9 +158,10 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     order(column, direction = 'asc') { orderParam = `${column}.${direction}`; return builder; },
     limit(count) { limitParam = count; return builder; },
     offset(count) { offsetParam = count; return builder; },
+    deleted(mode) { deletedParam = mode; return builder; },
 
     async execute(): Promise<ClientResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam, deletedParam);
       const headers = await buildHeaders(options);
       const { response, retried } = await fetchWithRetry(url, { method: 'GET', headers }, options);
 
@@ -168,7 +176,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     },
 
     async executeWithCount(): Promise<CountResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam, deletedParam);
       const headers = await buildHeaders(options);
       headers['Prefer'] = 'count=exact';
 
@@ -220,7 +228,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     },
 
     async update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null, deletedParam);
       const headers = await buildHeaders(options);
       headers['Content-Type'] = 'application/json';
 
@@ -340,6 +348,7 @@ function buildUrl(
   order: string | null,
   limit: number | null,
   offset: number | null,
+  deleted: DeletedMode | null = null,
 ): string {
   const path = `${baseUrl}/${table}`;
   const base = typeof globalThis.location !== 'undefined' ? globalThis.location.origin : undefined;
@@ -355,6 +364,7 @@ function buildUrl(
   if (order) url.searchParams.set('order', order);
   if (limit !== null) url.searchParams.set('limit', String(limit));
   if (offset !== null) url.searchParams.set('offset', String(offset));
+  if (deleted) url.searchParams.set('deleted', deleted);
 
   return url.toString();
 }

package/src/handler/index.ts

@@ -60,6 +60,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;
@@ -233,6 +236,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 {
@@ -354,6 +364,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;
@@ -395,6 +413,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) {
@@ -763,11 +792,18 @@ 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) } : {}),
-    ...(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) } : {}),
+        },
+      }
       : {}),
   };
 }
@@ -826,6 +862,108 @@ function validateRowOwnership(schema: Schema, options: HandlerOptions | undefine
   }
 }
 
+/**
+ * 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);
+}
+
+/** 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 };
+}
+
 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
@@ -834,19 +972,10 @@ 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));
   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))];
 
@@ -1286,17 +1415,15 @@ 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,
+      // and throws when nothing else is left. An emptied list is the 400 below.
       config.columns = Object.fromEntries(embed.columns
-        .map(name => columnPropertyName(table, name) ?? name)
-        .filter(name => !hidden.has(name))
+        .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) {
@@ -1325,13 +1452,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;
@@ -1462,13 +1583,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);
     }
   }
 
@@ -1788,14 +1904,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 => {
@@ -1993,6 +2102,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,
@@ -2035,6 +2233,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);
@@ -2053,7 +2256,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(
@@ -2094,6 +2298,23 @@ 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];
@@ -2102,6 +2323,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) {
@@ -2119,16 +2345,27 @@ async function handlePatch(
     }
   }
 
+  // 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 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);
   }
   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: AND WHERE <column> = user[<userField>] for IDOR protection
@@ -2160,7 +2397,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);
 }
 
 /**