fastify-auto-sqlapi 0.2.0 → 0.2.1

package/dist/routes/auto/route-helpers.js

@@ -1,4 +1,5 @@
 import { ensureSqlApiDecorator } from '../../lib/sql-api-decorator.js';
+import { sanitizeRouteError } from '../../lib/errors.js';
 import { isCompositePrimary } from '../../types.js';
 function mergeOnRequests(options, tableConf) {
     return [...(options.onRequests || []), ...(tableConf.onRequests || [])];
@@ -75,9 +76,17 @@ export async function registerForAllTables(fastify, options, spec) {
             schema: buildRouteSchema(tableName, tableConf, spec, schemas),
             onRequest: mergeOnRequests(options, tableConf),
             handler: async (request, reply) => {
-                const result = await spec.handle(fastify, tableName, tableConf, request, reply);
-                if (!reply.sent)
-                    reply.status(spec.successStatus).send(result);
+                try {
+                    const result = await spec.handle(fastify, tableName, tableConf, request, reply);
+                    if (!reply.sent)
+                        reply.status(spec.successStatus).send(result);
+                }
+                catch (err) {
+                    const safe = sanitizeRouteError(err, request.id, options.exposeDebugInfo);
+                    if (safe !== err)
+                        request.log.error({ err }, 'sqlapi: unhandled error');
+                    throw safe;
+                }
             },
         });
     }

package/dist/types/plugin.d.ts

@@ -35,6 +35,25 @@ export interface SqlApiPluginOptions {
      * routes run behind the same global `onRequests` hooks as the data routes.
      */
     agentManifest?: boolean;
+    /**
+     * Attach a `debugInfo` payload — the driver message, its `code`/`constraint`/`detail`,
+     * the stack — to the `500` an error the plugin did not raise itself produces (a
+     * constraint violation, a hook throwing without a `statusCode`).
+     *
+     * **Development only**: it hands whoever triggers an error a description of the schema,
+     * and the auto routes are open by default (ADR 0002). Off unless set. It is additive —
+     * `statusCode`, `error`, `message` and `requestId` keep the shape they have in production,
+     * so client-side error handling does not fork between environments.
+     *
+     * Without it the response carries no database detail, and the original error is still
+     * reachable: logged through `request.log.error` under the same `reqId` the body reports as
+     * `requestId`, and attached as the `cause` of the error a consumer `setErrorHandler`
+     * receives — which is where policy such as unique-violation → `409` belongs (ADR 0006).
+     *
+     * Nothing derives this: not `debug` (whoever registers the plugin decides that one, and
+     * may wire it to an environment variable), not `NODE_ENV`. See ADR 0013.
+     */
+    exposeDebugInfo?: boolean;
 }
 /** Default row cap for search (page size and no-paginator LIMIT). Override via `maxItemsPerPage`. */
 export declare const DEFAULT_MAX_ITEMS_PER_PAGE = 1000;

package/dist/types/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/types/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC;IACnC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,OAAO,CAAC,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,qGAAqG;AACrG,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,OAAO,CAAC"}

package/dist/types/tenant.d.ts

@@ -11,9 +11,33 @@ export interface TenantScopeIndirect {
         foreignField: string;
     };
 }
-export type TenantScope = TenantScopeDirect | TenantScopeIndirect;
+/**
+ * A row owned by several parties, visible to any of them: a message (`sender_id` /
+ * `recipient_id`), a transfer (`from_account_id` / `to_account_id`), a shift swap. Reads test
+ * every listed column with an OR, so a row matches when *any* of them holds a tenant id.
+ *
+ * Writes cannot auto-inject a tenant the way a single-column scope does — the plugin has no way
+ * to know which party the caller is meant to be — so the payload must anchor the row itself:
+ * see `assertTenantAnchor`. Columns are DB column names, like `TenantScopeDirect.column`.
+ *
+ * Not combinable with `column`/`through`: an entry reached through a parent FK would need its
+ * own join per entry, and is rejected at `defineTable` time rather than half-supported.
+ */
+export interface TenantScopeAnyOf {
+    anyOf: string[];
+}
+export type TenantScope = TenantScopeDirect | TenantScopeIndirect | TenantScopeAnyOf;
+/**
+ * Who the caller is, for this request — plus how the table currently being addressed is scoped.
+ *
+ * `ids` is request-level: it is resolved once from `getTenantId` and stays valid for every table
+ * the request touches. `scope` is table-level and therefore **optional**: the addressed table may
+ * declare no scope of its own while a table it reaches through a relation does. Absent `scope`
+ * means "no filtering on this table", never "no tenant" — `tenantForTable` re-targets the same
+ * ids onto a related table's own scope.
+ */
 export interface TenantContext {
     ids: TenantId[];
-    scope: TenantScope;
+    scope?: TenantScope;
 }
 //# sourceMappingURL=tenant.d.ts.map

package/dist/types/tenant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,MAAM,EAAE,gBAAgB,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,mBAAmB,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB"}
+{"version":3,"file":"tenant.d.ts","sourceRoot":"","sources":["../../src/types/tenant.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QACP,MAAM,EAAE,gBAAgB,CAAC;QACzB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,QAAQ,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB"}

package/docs/GLOSSARY.md

@@ -19,7 +19,9 @@ existing concept makes search fail and the concept get built twice.
 | Extra filter | Non-column search filter declared per table. (not: custom filter) |
 | Extended condition | Consumer-supplied SQL fragment merged into a search WHERE. |
 | Dotted notation | `orderBy`/condition key counted in parts: 1-part `field`, 2-part `alias.field`, 3-part `alias.fn.field`. (not: parti) |
-| Tenant scope | Row-level isolation: `direct` (own column) or `indirect` (via FK). |
+| Tenant scope | Row-level isolation: `direct` (own column), `indirect` (via FK) or `anyOf`. |
+| `anyOf` scope | Tenant scope over several owner columns: the row is visible to any of them. |
+| Anchor | The owner column an `anyOf` write names to tie a new row to the caller. |
 | Engine | Dialect-agnostic function performing one operation. (not: service, handler) |
 | Route | Fastify plugin exposing an engine over HTTP. (not: controller) |
 | Dialect | Per-DB SQL differences (`postgres` \| `mysql`). |

package/docs/adr/0006-raw-db-errors.md

@@ -1,6 +1,7 @@
 # 0006. Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping
 
-- **Status**: accepted
+- **Status**: accepted on the mapping; message exposure narrowed by
+  [0013](./0013-sanitized-db-errors.md)
 - **Date**: 2026-07-23 (confirmed by the maintainer in June 2026)
 
 ## Context

package/docs/adr/0010-joins-do-not-run-route-guards.md

@@ -97,4 +97,7 @@ programmatic `sqlApi.search()` path.
   narrow. Not decided here.
 - `tenantScope` remains the one request-derived protection that crosses joins, and is the
   precedent for the shape any future one should take: table configuration plus a plugin-level
-  resolver, not a route hook.
+  resolver, not a route hook. It crosses joins **unconditionally** only since the tenant stopped
+  being resolved from the addressed table alone; before that, a host declaring no scope of its
+  own carried none into its join targets, which made the row above true only when the host
+  happened to be scoped too (see BREAKING_CHANGES.md).

package/docs/adr/0013-sanitized-db-errors.md

@@ -0,0 +1,114 @@
+# 0013. Database error messages are sanitized on the wire by default
+
+- **Status**: accepted — narrows [0006](./0006-raw-db-errors.md)
+- **Date**: 2026-08-05
+
+## Context
+
+[ADR 0006](./0006-raw-db-errors.md) rejected two distinct proposals in one decision: mapping
+SQLSTATE codes to HTTP semantics, and sanitizing driver messages. The first rejection holds
+— the mapping is dialect-specific and encodes product decisions the plugin should not make.
+The second rested on "hiding details is an environment policy, and Fastify already gives
+consumers the hook for it", and three facts undermine it:
+
+- The plugin installs its own `setErrorHandler` in the routes' child scope
+  (`src/routes/auto/plugin.ts`), and it sends `error.message` verbatim for any status code.
+  A consumer handler registered on the parent scope never sees these errors, so the escape
+  route 0006 points at does not exist for the main-plugin path.
+- The posture is inconsistent with the rest of the codebase. `maxItemsPerPage`,
+  `maxBulkItems`, prototype-key filtering and the join field allowlist are all guards the
+  plugin applies by default where the cost is zero. A constraint name describing the schema
+  to whoever triggered a duplicate is the same class of free hardening.
+- [ADR 0002](./0002-open-by-default.md) amplifies the exposure: the scenario the plugin
+  optimizes for — internal scaffolding wired up in five minutes — is exactly the one where
+  nobody wrote an error handler.
+
+The failure mode is silent. A consumer who never thinks about it ships the leak and gets no
+signal.
+
+## Decision
+
+Errors escaping an auto-generated route handler are replaced with a bare
+`500 Internal Server Error` carrying no database detail. Errors the plugin raises itself are
+deliberate `4xx` with messages written for clients (`httpError`, `validationErrors`) and pass
+through untouched — the rule is `statusCode` in `[400, 500)`, nothing else.
+
+No status code is remapped: a `500` stays a `500`. ADR 0006 stands on that point.
+
+Nothing is lost. The original error is logged through `request.log.error` and attached as the
+`cause` of the error the consumer's `setErrorHandler` receives, so unique-violation → `409`
+remains implementable, and remains the consumer's decision. The sanitized body carries
+`requestId` — the same value Fastify binds as `reqId` on the request logger — so the client
+can name the log line holding the real error instead of describing a `500` that happened
+"around then".
+
+Developing against the API is a real need the log does not serve — a client building on it,
+an agent especially, may have no way to read the server's log, and a round trip per failure
+is expensive. `exposeDebugInfo: true` answers it by **adding** a `debugInfo` payload (driver
+message, `code`, `constraint`/`detail`, stack) beside the fields above, which keep the shape
+they have in production. Client-side error handling therefore does not fork between
+environments — the difference is extra data, not different data.
+
+`exposeDebugInfo` derives from nothing. Not `debug`, not `NODE_ENV`, not the log level. The
+deciding argument is that **`debug` belongs to the consumer**: whoever registers the plugin
+decides how it is wired — a constant in one deployment, an environment variable flipped
+during an incident in another — so the library cannot assume its lifecycle, and an option
+whose value the library does not control must not decide what leaves the server. Beyond that,
+`debug` writes to the log, an access-controlled internal channel; the response body is
+external, and under ADR 0002 often unauthenticated. And the posture wanted during a
+production incident — log everything, tell clients nothing — stops being expressible the
+moment one switch drives both.
+
+The guard sits in the handler built by `registerForAllTables`
+(`src/routes/auto/route-helpers.ts`) — the single choke point every auto route passes
+through, including route plugins registered standalone without the main plugin. The
+`debugInfo` payload is copied from the driver error by allowlist, never spread: an error
+object that starts carrying the connection config must not reach a client through it.
+
+## Alternatives considered
+
+- **`fastify.setErrorHandler` in the plugin** — rejected: the plugin is registered through
+  `fp()`, so a handler installed at that level would hijack error rendering for the
+  consumer's entire application, not just the auto routes.
+- **Sanitizing inside the existing child-scope handler in `plugin.ts`** — rejected: route
+  plugins registered standalone (`searchRoutes` alone, per AGENTS_BACKEND.md "Register only
+  specific routes") never reach that handler, and would keep leaking.
+- **Leaving it to the consumer, as 0006 decided** — rejected for the three reasons in
+  Context; the deciding one is that the plugin's own child-scope handler makes the
+  prescribed consumer remedy unreachable.
+- **Deriving the behaviour from `debug`** — rejected, for the reasons in Decision: the
+  consumer owns that option and may wire it to an environment variable, it currently governs
+  an internal channel only, and coupling makes "verbose log, silent response" unexpressible.
+  An override (`debug: true` + an explicit opt-out) would keep the combination reachable but
+  leaves the default pointing the dangerous way, which is the failure mode this ADR exists to
+  close.
+- **Keying it on `NODE_ENV`** — rejected. `NODE_ENV !== 'production'` is fail-open: the
+  variable is unset often enough in real deployments (a bare `node dist/server.js`, many
+  container images, systemd units) that the leak would come back precisely where nothing was
+  configured. `NODE_ENV === 'development'` would at least fail closed, but a security-relevant
+  response decided by the shell instead of by the registration call is action at a distance.
+- **Replacing `message` with the driver text instead of adding `debugInfo`** — rejected: it
+  makes one field mean different things in different environments, so client error handling
+  has to be written twice. The additive payload costs nothing and carries more, structured.
+- **Echoing only the SQLSTATE code** (`23505`, no names) — rejected: a third middle mode is
+  harder to reason about than a boolean, and reading meaning into SQLSTATE is the direction
+  0006 closed.
+- **Sending the detail only to localhost callers** — rejected: it makes the response depend
+  on network topology, which reverse proxies routinely flatten.
+
+## Consequences
+
+- Constraint violations reach clients as `{"statusCode":500,"error":"Internal Server
+  Error","message":"Internal Server Error","requestId":"…"}`. Diagnosing one requires the
+  server log — which is where the error was already going, under that same id.
+- Behavioural breaking change for consumers who parsed driver messages out of `500` bodies.
+  They read `debugInfo` instead, and only where the deployment opted in.
+- Development needs one more line (`exposeDebugInfo: true`) than it did. That is the price of
+  the option meaning exactly one thing: what a client sees is readable from the registration
+  call alone, without knowing how `debug` or the environment happen to be wired.
+- A deployment that leaves `exposeDebugInfo` on by mistake is back to disclosing schema
+  detail. The name is the mitigation: `expose` is the word that makes a reader stop, which
+  `debug` is not.
+- Errors thrown by consumer `onRequests` hooks are outside the handler and unaffected: that
+  is consumer code running before the plugin's SQL surface, and its messages are the
+  consumer's to write.

package/docs/adr/README.md

@@ -27,6 +27,7 @@ not by editing history.
 | [0010](./0010-joins-do-not-run-route-guards.md) | A declared join is a read grant — joins do not run the target table's route guards |
 | [0011](./0011-join-fields-allowlist.md) | Per-relation field restriction is an allowlist, not a blocklist |
 | [0012](./0012-anti-duplication-tooling.md) | Repository rules are enforced by executable gates, not by documentation |
+| [0013](./0013-sanitized-db-errors.md) | Database error messages are sanitized on the wire by default (narrows 0006) |
 
 ## When to write one
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastify-auto-sqlapi",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",