fastify-auto-sqlapi 0.2.0 → 0.2.1

package/AGENTS_BACKEND.md

@@ -275,6 +275,8 @@ export const TableCustomer = defineTable({
   //   column: 'organization_id',
   //   through: { schema: SchemaCustomer, localField: 'customerId', foreignField: 'id' },
   // },
+  // OR anyOf: several owner columns, the row is visible to any of them
+  // tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
 
   // SCHEMA OVERRIDES — tighten auto-generated schema validation without editing Schema files
   schemaOverrides: {
@@ -771,6 +773,46 @@ Behavior:
 - **Update**: pre-check via SELECT with INNER JOIN (404 if not found). If the payload also changes the through-FK (`localField`), the new value is re-validated against the tenant — moving a record into another tenant's scope is rejected (403).
 - **Delete**: subquery `DELETE WHERE pk IN (SELECT ... INNER JOIN ... WHERE tenant IN (...))`
 
+### Shared tenant (`anyOf`: several owner columns)
+
+For a row owned by two parties and visible to either — a message (`sender_id` / `recipient_id`),
+a transfer (`from_account_id` / `to_account_id`), a shift swap:
+
+```typescript
+const TableShiftSwapRequest = defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaShiftSwapRequest),
+  tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
+});
+```
+
+Behavior:
+- **Read** (search, get, delete, bulk-delete): adds
+  `AND (requester_agent_id IN ($N) OR target_agent_id IN ($M))`. A `NULL` column does not match
+  and does not stop the other column from matching. A row with every listed column `NULL` is
+  visible to nobody but an admin.
+- **Joins**: the predicate crosses every join family — `joinMultiple`, `joinGroup`,
+  `joinMustExist`, and `joinLeft` (in the `ON` clause, alias-qualified, so `LEFT` semantics
+  survive) — exactly as a single-column scope does, including from a host table that declares no
+  scope of its own.
+- **Insert**: no auto-injection. The payload must **anchor** the row: at least one listed column
+  present and holding a tenant id → `400` if none is present, `403` if present but all foreign.
+  The other parties are stored exactly as sent. A multi-id caller is never ambiguous here,
+  because nothing is being guessed.
+- **Update**: strips **every** listed column from the `SET` — neither party can be re-assigned —
+  and adds the OR predicate to the `WHERE`. A row outside the scope answers `404`.
+- **Bulk upsert**: the anchor rule applies to every item (so an upsert must name a party even
+  when it only means to update), and the listed columns are excluded from the `DO UPDATE SET`,
+  so an upsert onto an existing row cannot take over the other party's slot. The conflict guard
+  rejects (`403`) a conflict key matching a row visible to neither party — including a row whose
+  parties are `NULL`.
+- **Secondaries**: a table with an `anyOf` scope written through another table's
+  `allowedWriteJoins` follows the same anchor rule. The parent's FK is auto-filled but is not an
+  owner, so the child payload must still name a party.
+
+Not combinable with `column` or `through` — `defineTable` throws at startup. An `anyOf` entry
+reached through a parent FK is not supported; declare the scope on the parent instead.
+
 ### Multi-tenant users
 
 ```typescript
@@ -793,8 +835,10 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 ### Error codes
 
 - **403** — Record doesn't belong to tenant, or explicit tenant value doesn't match
-- **400** — Multi-tenant user on insert without explicit tenant value (ambiguous)
-- **404** — Update with indirect tenant, record not found for this tenant
+- **400** — Multi-tenant user on insert without explicit tenant value (ambiguous), or an
+  `anyOf` write naming no owner column at all
+- **404** — Update with indirect tenant, record not found for this tenant; get/update/delete of
+  an `anyOf`-scoped row outside the scope
 
 ---
 
@@ -812,8 +856,9 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 - **All hooks and validators receive camelCase records**: `validate` and the whole hook matrix (`beforeInsert`/`afterInsert`, `beforeUpdate`/`afterUpdate`, `beforeDelete`/`afterDelete`, `beforeBulkDelete`/`afterBulkDelete`) get records keyed by schema field names (camelCase). Mutations propagate to the SQL (plugin converts to DB column format via `colMap` after the hook). The engine internally uses `snakecaseRecord(..., schema)` after user mutations to map field names to actual DB columns.
 - **Filters validation**: TypeBox schemas use `additionalProperties: false`. By default Fastify strips unknown fields silently. For 400 errors on unknown filters: `Fastify({ ajv: { customOptions: { removeAdditional: false } } })`.
 - **Write-body whitelist**: insert/update/bulk-upsert bodies (`main` + secondaries items) are `additionalProperties: false`. Unknown properties are rejected with 400 — only columns in the generated Schema (as narrowed by `schemaOverrides`/`excludeFromCreation`) can be written, so no mass assignment of unexposed columns. Trim the Schema to keep sensitive columns unwritable.
+- **Error responses**: errors the plugin raises itself are `4xx` with messages written for clients (validation, not found, tenant). Anything else — a driver constraint violation, a hook throwing without a `statusCode` — answers a fixed `{"statusCode":500,"error":"Internal Server Error","message":"Internal Server Error"}`: driver messages name tables, columns and constraints, and they stay on the server. **No status code is remapped** (a unique violation is a `500`, not a `409` — that mapping is product logic). The body carries `requestId` (the `reqId` Fastify logs on every line) so the real error is one grep away in the log, where it is also written via `request.log.error` — and attached as `err.cause`, so a consumer `setErrorHandler` can map `err.cause.code === '23505'` to `409` itself. **`exposeDebugInfo: true` is the only way to get the driver detail on the wire** — set it while developing, where a client building against the API cannot always read your log: the `500` then also carries `debugInfo` (`message`, `code`, `constraint`, `detail`, `stack`), additively, so the four fields above keep their production shape. Nothing else flips it: not `debug` (server-side only, and it belongs to whoever registers the plugin), not `NODE_ENV`. Errors thrown by `onRequests` hooks run before the handler and are unaffected.
 - **Request limits**: `maxItemsPerPage` (default 1000) caps the search page size and is applied as the `LIMIT` even when no paginator is sent (so an empty-body search can't dump a whole table); over-limit `itemsPerPage` → 400. `maxBulkItems` (default 1000) caps the bulk array length via schema `maxItems` → 400. Programmatic `sqlApi.*` calls are uncapped.
-- **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause).
+- **Tenant filtering**: when `tenantScope` is set on a table and `getTenantId` is provided in plugin options, all CRUD operations are automatically scoped to the tenant. `getTenantId` returning `null`/`undefined` = admin (no filter). Returning an array = multi-tenant user (IN clause). The tenant belongs to the *request*, not to the table it addresses: a scoped table is filtered even when reached as a join target or written as a secondary of an unscoped host, so `getTenantId` must tolerate a request with no authenticated user (`req.user?.x ?? null`).
 
 ---
 

package/BREAKING_CHANGES.md

@@ -455,3 +455,84 @@ returns a `400` naming the reason.
 
 Use `joinMustExist` on the same relation when you need an extra filter on the parent — that path
 delegates to the target's own `filters()` and does run `extendedCondition`.
+
+---
+
+# Breaking Change — the tenant follows the request, not the table it addresses
+
+`tenantScope` on a table is now enforced even when the request was addressed to a **different**
+table that reaches it through a relation. Previously the tenant was resolved from the addressed
+table alone: if that table declared no `tenantScope`, no predicate was applied anywhere — not to
+it, and not to the scoped tables it joined or wrote into.
+
+## Why this changed
+
+A relation in `allowedReadJoins` is a read grant on its target, and one in `allowedWriteJoins` is
+a write grant (see [ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)). `tenantScope`
+was documented as the one request-derived protection that crosses a join — the cap that makes a
+relation safe to declare. It did not cross when the *host* was open:
+
+```typescript
+// shift is public on purpose: everyone may see who works when.
+shift: {
+  ...exportTableInfo(SchemaShift),
+  allowedReadJoins: [buildRelation(SchemaShift, 'id', SchemaSwapRequest, 'shiftId', { alias: 'swap' })],
+},
+// …but why somebody wants to change the roster is not public.
+shift_swap_request: {
+  ...exportTableInfo(SchemaSwapRequest),
+  tenantScope: { column: 'agent_id' },
+},
+```
+
+```sql
+-- POST /search/shift  { "joinMultiple": { "swap": {} } }   — before
+SELECT … FROM shift_swap_request WHERE (shift_id IN ($1))
+-- after
+SELECT … FROM shift_swap_request WHERE (shift_id IN ($1) AND (agent_id IN ($2)))
+```
+
+Every scoped row of the neighbour was readable through the open host, and writable through it as
+a secondary. The declaration said "scoped"; the deployment was not. Nothing in the response said
+so, which is the dangerous direction — the same reasoning as unknown filter keys above.
+
+## What changed
+
+- `TenantContext.scope` is now **optional**. `ids` is request-level and travels with the request;
+  `scope` is table-level and absent when the addressed table declares none. Absent `scope` means
+  "no filter on *this* table", never "no tenant" — related tables still enforce their own.
+- `getTenantId` is now called for a request addressed to an unscoped table **when one of that
+  table's declared relations points at a scoped table**. It is still not called when nothing
+  scoped is in reach, so genuinely tenant-free routes are unaffected. Reach is one level: joins
+  and secondaries resolve from the addressed table's own relations and never chain further.
+
+## Who is affected
+
+- **You declare `tenantScope` on a table that another table joins or writes into, where that
+  other table has no scope of its own.** Those requests now return fewer rows and can now answer
+  `403`. This is the fix: the rows were never yours to serve. Check any UI that displayed them.
+- **Your `getTenantId` assumes an authenticated request.** It now runs on routes that previously
+  skipped it — a public host with a scoped neighbour. A body like
+  `(request) => request.user.organizationId` throws there, turning a `200` into a `500`.
+- **You read `tenant.scope` in TypeScript** (custom routes using the exported `TenantContext`).
+  Its type is now `TenantScope | undefined`.
+
+Not affected: tables with no `tenantScope` anywhere in reach, deployments without `getTenantId`,
+admins (`getTenantId` → `null`), and every table that already declared its own scope — their SQL
+is unchanged.
+
+## Migration
+
+Make `getTenantId` total. It already had to return `null` for admins, so the null case exists:
+
+```typescript
+// Before — throws on a route that never had a user
+getTenantId: (request) => request.user.organizationId,
+
+// After — an absent user is simply an unscoped caller
+getTenantId: (request) => request.user?.organizationId ?? null,
+```
+
+Then decide, for each open table that relates to a scoped one, whether the relation was meant to
+be a read grant at all. If it was not, remove it from `allowedReadJoins` — a relation is the
+grant, and the scope is only the cap on it.

package/CHANGELOG.md

@@ -9,8 +9,65 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ## [Unreleased]
 
+### Added
+
+- **`tenantScope` over several owner columns — `{ anyOf: [...] }`.** A row that belongs to two
+  parties and is visible to either — a message (`sender_id` / `recipient_id`), a transfer
+  (`from_account_id` / `to_account_id`), a shift swap — could not be expressed before, leaving
+  the table open or the route hand-written. Reads add
+  `AND (colA IN (…) OR colB IN (…))`, alias-qualified, and the predicate crosses every join
+  family including `joinLeft`, where it lands in the `ON` clause so `LEFT` semantics survive.
+  A `NULL` column does not match and does not stop the other one from matching.
+  Writes cannot auto-inject an owner, so the payload **anchors** the row instead: at least one
+  listed column present and holding a tenant id, otherwise `400` (nothing to anchor to) or `403`
+  (present but foreign); the other party is stored exactly as sent. Updates strip every listed
+  column from the `SET`, and upserts exclude them from the `DO UPDATE` — neither party can be
+  re-assigned. The upsert conflict guard is null-safe for this shape: a row whose parties are
+  all `NULL` is visible to nobody, where a plain `NOT IN` would have read "unknown" as "not
+  foreign" and handed it over. Purely additive: `{ column }` and `{ column, through }` produce
+  byte-identical SQL. The three forms do not mix — `defineTable` throws at startup on `anyOf`
+  combined with `column` or `through`, on an empty or malformed `anyOf`, and on a scope
+  declaring no owner column at all.
+- `QueryClient.bulkInsertOrUpdate` takes an optional trailing `immutableCols`: columns written
+  on insert but left untouched when the statement lands on an existing row. Additive.
+
 ### Changed
 
+- **BREAKING: the tenant follows the request, not the table it addresses.** `tenantScope` on a
+  table is now enforced even when the request was addressed to a different table that reaches it
+  through a relation. Previously the tenant was resolved from the addressed table alone, so a
+  host declaring no scope of its own carried no predicate into the scoped tables it joined or
+  wrote into — every scoped row of the neighbour was readable through the open host, and writable
+  through it as a secondary, while the declaration said otherwise. A relation is a read grant and
+  a write join a write grant ([ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)), and
+  `tenantScope` is documented as the cap that makes them safe to declare; it now actually is.
+  `TenantContext.scope` becomes optional — `ids` is request-level, `scope` is table-level and
+  absent means "no filter on this table", never "no tenant". `getTenantId` is now consulted for a
+  request addressed to an unscoped table when one of its declared relations points at a scoped
+  one; it is still never called when nothing scoped is in reach. Tables that already declared
+  their own scope emit unchanged SQL. Migration — including the `getTenantId` body that now needs
+  to tolerate an unauthenticated request — in
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--the-tenant-follows-the-request-not-the-table-it-addresses).
+- **Database errors no longer reach clients verbatim.** Any error escaping an auto-generated
+  route that the plugin did not raise itself now answers `{"statusCode":500,"error":"Internal
+  Server Error","message":"Internal Server Error"}` instead of the driver message, which names
+  tables, columns and constraints (`duplicate key value violates unique constraint
+  "users_email_key"`). Errors the plugin raises are deliberate `4xx` written for clients and
+  are untouched; **no status code is remapped** — a unique violation is still a `500`, per
+  [ADR 0006](./docs/adr/0006-raw-db-errors.md). The original error is logged through
+  `request.log.error` and attached as `err.cause`, so a consumer `setErrorHandler` can still
+  apply its own policy (`23505` → `409`). The guard covers route plugins registered standalone
+  as well. The sanitized body carries `requestId` — the `reqId` Fastify logs on every line — so
+  the entry holding the real error is one grep away. While developing — where a client building
+  against the API (an agent especially) may have no way to read the server log — the new
+  **`exposeDebugInfo: true`** attaches the driver error (message, `code`, `constraint`, stack)
+  as a `debugInfo` payload. It is additive: `statusCode`, `error`, `message` and `requestId`
+  keep their production shape, so client-side error handling does not fork between
+  environments. Nothing else flips it — not `debug`, not `NODE_ENV`: `debug` belongs to the
+  consumer, who may wire it to an environment variable, and it governs the log (access
+  controlled) rather than the response body (not, and these routes are open by default). See
+  [ADR 0013](./docs/adr/0013-sanitized-db-errors.md).
+
 - **Unknown `filters` keys are now rejected with `400 Unknown filter field: <key>`** instead
   of being dropped in silence — on the main table and on every join family. The engine only
   ever visited keys matching a schema field, an `extraFilters` entry or a computed field, so a

package/README.md

@@ -37,7 +37,7 @@ Writes read the same way — *"sync these clients and their tags: update the one
 
 Conflict keys are declared server-side (`upsertMap`: here customer on `email`, tag on `(customerId, tag)`), so re-sending the same payload updates rows instead of duplicating them — client-side sync without hand-written diffing.
 
-And multi-tenancy is one plugin option (`getTenantId: (req) => req.user.organizationId`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
+And multi-tenancy is one plugin option (`getTenantId: (req) => req.user?.organizationId ?? null`), enforced on reads *and* writes with zero code in handlers. Rows of other tenants are simply invisible (`404`); here a caller in org B tries to re-point one of their own orders to a customer belonging to org A:
 
 ```jsonc
 // PUT /api/rest/order — order 7 is mine, customer 41 belongs to another tenant
@@ -368,7 +368,8 @@ await app.register(fastifyAutoSqlApi, {
 | `getTenantId` | `(req) => id \| null` | No | Tenant resolver for multi-tenant |
 | `maxItemsPerPage` | `number` | No | Max search page size, and the row `LIMIT` applied when no paginator is sent (default: `1000`) |
 | `maxBulkItems` | `number` | No | Max number of items accepted by the bulk endpoints (default: `1000`) |
-| `debug` | `boolean` | No | Log all SQL queries to console |
+| `debug` | `boolean` | No | Log all SQL queries to console (server-side only — it never changes a response) |
+| `exposeDebugInfo` | `boolean` | No | **Development only.** Attach the driver error (message, `code`, `constraint`, stack) to `500` responses as `debugInfo` (default: `false`) |
 
 The plugin picks up the connection from the Fastify instance: `fastify.pg` for PostgreSQL
 (what `@fastify/postgres` decorates) or `fastify.mysql` for MySQL/MariaDB. For MySQL,
@@ -476,6 +477,69 @@ malicious resource exhaustion — relevant precisely because the API is open by
 Both are configurable in the plugin options. The programmatic `fastify.sqlApi.*` methods are not
 capped — they run your own trusted code.
 
+### Error responses don't describe your schema
+
+Driver messages name tables, columns and constraints (`duplicate key value violates unique
+constraint "users_email_key"`). Any error the plugin did not raise itself is replaced with a
+bare `500` before it reaches the client:
+
+```json
+{ "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error", "requestId": "req-3" }
+```
+
+`requestId` is the `reqId` Fastify logs on every line, so the entry holding the real error is
+one grep away — without the error itself travelling to the client.
+
+Errors the plugin raises are deliberate `4xx` with messages written for clients (validation,
+not found, tenant violations) and are untouched. **No status code is remapped**: a unique
+violation is still a `500`, not a `409` — deciding otherwise is product logic, and this is
+where you do it:
+
+```typescript
+app.setErrorHandler((err, request, reply) => {
+  if (err.cause?.code === '23505') {
+    return reply.status(409).send({ statusCode: 409, error: 'Conflict', message: 'Already exists' });
+  }
+  reply.send(err);
+});
+```
+
+The original error is never lost: it is logged through `request.log.error` and attached as
+`err.cause`. Errors thrown by your own `onRequests` hooks run before the handler and are
+unaffected.
+
+**While developing, you probably want the detail on the wire** — an agent or a frontend
+building against the API cannot always read your server log, and one round trip per failure
+adds up. Say so explicitly:
+
+```typescript
+await app.register(fastifyAutoSqlApi, {
+  DbTables: dbTables,
+  exposeDebugInfo: true,   // development only — see below
+});
+```
+
+```json
+{
+  "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error",
+  "requestId": "req-3",
+  "debugInfo": {
+    "message": "duplicate key value violates unique constraint \"users_email_key\"",
+    "code": "23505", "constraint": "users_email_key", "stack": "…"
+  }
+}
+```
+
+It is **additive**: `statusCode`, `error`, `message` and `requestId` keep the shape they have
+in production, so your client-side error handling doesn't fork between environments.
+
+Nothing else flips it — not `debug`, not `NODE_ENV`. `debug` is yours to wire (a constant in
+one deployment, an environment variable in another), so the plugin cannot let it decide what
+leaves the server: it writes to your log, which is access-controlled, while a response body is
+not — and these routes are open by default. What a client sees is readable from the
+registration call alone. See [ADR 0013](./docs/adr/0013-sanitized-db-errors.md) and
+[ADR 0006](./docs/adr/0006-raw-db-errors.md).
+
 ### Write whitelist
 
 Insert/update/bulk-upsert bodies are `additionalProperties: false`: only columns present in the
@@ -717,6 +781,18 @@ Both schema-level (TypeBox/Ajv) and custom (`validate` / `validateBulk`) errors
 
 Custom validators return tuples `[field, code]` or `[field, code, message]` — `message` defaults to `code` if omitted. `validateBulk` replaces per-item `validate` in bulk-upsert requests.
 
+### Server errors (500)
+
+Anything the plugin did not raise itself — a constraint violation, a hook failing — answers
+with a fixed body carrying no database detail; `requestId` points at the log line with the
+real error. Constraint names and driver messages stay on the server unless the deployment
+opts in with `exposeDebugInfo: true`: see
+[Error responses don't describe your schema](#error-responses-dont-describe-your-schema).
+
+```json
+{ "statusCode": 500, "error": "Internal Server Error", "message": "Internal Server Error", "requestId": "req-3" }
+```
+
 ## Multi-Tenant
 
 Automatic row-level isolation on all CRUD operations. Configure once, no code in handlers.
@@ -730,6 +806,12 @@ await app.register(fastifyAutoSqlApi, {
 
 When `getTenantId` returns `null`, no filtering is applied (admin mode).
 
+The tenant belongs to the **request**, not to the table it addresses: a scoped table is filtered
+even when it is reached as a join target, or written as a secondary, of a host table that
+declares no scope of its own — a relation is a read grant, and `tenantScope` is the cap on it. So
+`getTenantId` must tolerate a request with no authenticated user; return `null` there. It is not
+called at all when neither the addressed table nor anything it relates to is scoped.
+
 ### Direct tenant (column on the table)
 
 ```typescript
@@ -753,6 +835,31 @@ defineTable({
 });
 ```
 
+### Shared tenant (several owner columns)
+
+Some rows belong to two parties and either may see them — a message (`sender_id` /
+`recipient_id`), a transfer (`from_account_id` / `to_account_id`), a shift swap. `anyOf`
+declares that shape:
+
+```typescript
+defineTable({
+  primary: 'id',
+  ...exportTableInfo(SchemaShiftSwapRequest),
+  tenantScope: { anyOf: ['requester_agent_id', 'target_agent_id'] },
+});
+```
+
+Reads add `AND (requester_agent_id IN (…) OR target_agent_id IN (…))`. A `NULL` column simply
+does not match; the other party still decides. Writes cannot auto-inject an owner — the plugin
+cannot know which party the caller is — so the payload must **anchor** the row: at least one
+listed column present and holding a tenant id, otherwise `400` (nothing to anchor to) or `403`
+(present but foreign). The other party is left exactly as sent, which is the point: a swap
+request names a colleague by definition. Updates strip every listed column from the `SET` and
+upserts leave them out of the `DO UPDATE` — neither party can be re-assigned.
+
+The three forms do not mix: `defineTable` throws at startup on `anyOf` combined with `column`
+or `through`.
+
 Tables without `tenantScope` are unaffected.
 
 ### Isolation guarantees on writes

package/dist/index.d.ts

@@ -34,5 +34,5 @@ export { BulkDeleteTableBody, BulkDeleteTableResponse } from './lib/schema/bulk-
 export { default as bulkDeleteRoutes } from './routes/auto/bulk-delete.routes.js';
 export { Type, type Static } from '@sinclair/typebox';
 export { ConditionBuilder, Expression } from 'node-condition-builder';
-export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, TransactionQueryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, TableOperation, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, ComputedFieldFn, ComputedFieldContext, ComputedFieldExpr, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantContext, ValidationError, ValidatorFn, BulkValidatorItem, BulkValidatorFn, } from './types.js';
+export type { SqlApiConfig, ColumnInfo, TableMap, Queryable, TransactionQueryable, SqlResult, DbRecord, DbRecordValue, SelectOptions, SchemaDefinition, JoinDefinition, ITable, TableOperation, DbTables, SqlApiPluginOptions, SwaggerOptions, SearchParams, SearchResult, Paginator, PaginationResult, TableFilterFn, ExtendedConditionFn, FilterRecord, AggregationRequest, JoinGroupRequest, ComputedFieldFn, ComputedFieldContext, ComputedFieldExpr, GetParams, GetResult, DeleteParams, DeleteResult, InsertParams, InsertResult, BulkUpsertItem, BulkUpsertParams, BulkUpsertResult, BulkDeleteParams, BulkDeleteResult, ConditionMethod, SearchCondition, UpdateParams, UpdateResult, TenantId, TenantScope, TenantScopeDirect, TenantScopeIndirect, TenantScopeAnyOf, TenantContext, ValidationError, ValidatorFn, BulkValidatorItem, BulkValidatorFn, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/db.d.ts

@@ -37,7 +37,12 @@ export declare class QueryClient {
     insert(table: string, record: DbRecord, pkCol: string | string[]): Promise<Record<string, unknown>>;
     insertOrUpdate(table: string, record: DbRecord, conflictKeys: string[], pkCol: string | string[]): Promise<Record<string, unknown>>;
     bulkInsert(table: string, records: DbRecord[], pkCol: string | string[], chunkSize?: number): Promise<Record<string, unknown>[]>;
-    bulkInsertOrUpdate(table: string, records: DbRecord[], conflictKeys: string[], pkCol: string | string[], chunkSize?: number): Promise<Record<string, unknown>[]>;
+    /**
+     * `immutableCols` are written when the row is inserted but left untouched when the statement
+     * lands on an existing row — like the conflict keys, which are never in the update set either.
+     * Used by tenant isolation to keep an upsert from re-assigning a row's owner.
+     */
+    bulkInsertOrUpdate(table: string, records: DbRecord[], conflictKeys: string[], pkCol: string | string[], chunkSize?: number, immutableCols?: string[]): Promise<Record<string, unknown>[]>;
     update(table: string, record: DbRecord, where: DbRecord, extraCondition?: ConditionBuilder): Promise<number>;
     delete(table: string, where: DbRecord, extraCondition?: ConditionBuilder): Promise<number>;
     select<T = Record<string, unknown>>({ tableName, columns, where, values, limit, orderBy, joins, distinct, }: SelectOptions): Promise<T[]>;

package/dist/lib/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/lib/db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/lib/db.ts"],"names":[],"mappings":"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"}

package/dist/lib/db.js

@@ -195,11 +195,17 @@ export class QueryClient {
         }
         return results;
     }
-    async bulkInsertOrUpdate(table, records, conflictKeys, pkCol, chunkSize = DEFAULT_CHUNK_SIZE) {
+    /**
+     * `immutableCols` are written when the row is inserted but left untouched when the statement
+     * lands on an existing row — like the conflict keys, which are never in the update set either.
+     * Used by tenant isolation to keep an upsert from re-assigning a row's owner.
+     */
+    async bulkInsertOrUpdate(table, records, conflictKeys, pkCol, chunkSize = DEFAULT_CHUNK_SIZE, immutableCols = []) {
         if (!records.length)
             return [];
         const fields = Object.keys(records[0]);
-        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, conflictKeys));
+        const keepAsIs = immutableCols.length ? [...conflictKeys, ...immutableCols] : conflictKeys;
+        const upsertClause = this.dialect.upsertSql(this.#q(conflictKeys), this.dialect.upsertUpdateSet(fields, keepAsIs));
         const returning = this.dialect.returningPk(this.#quotedPkCols(pkCol));
         const results = [];
         for (let i = 0; i < records.length; i += chunkSize) {

package/dist/lib/engine/bulk/bulk-upsert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AA4D3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}
+{"version":3,"file":"bulk-upsert.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/bulk/bulk-upsert.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAEV,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAC;AA+D3B,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA0C5F"}

package/dist/lib/engine/bulk/bulk-upsert.js

@@ -1,6 +1,6 @@
 import { camelcaseObject } from '../../naming.js';
 import { processSecondaries, processDeletions, prepareInsertRecord } from '../write-helpers.js';
-import { enforceTenantOnWrites, assertTenantOwnsConflicts } from '../../tenant.js';
+import { enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../../tenant.js';
 import { runBulkValidation } from '../validate.js';
 import { primaryAsCols } from '../../../types.js';
 /** One bulk statement for every main row, returning the PKs only. */
@@ -12,9 +12,10 @@ function upsertMains(params, preparedMains, pkCol) {
         return db.bulkInsert(schema.tableName, preparedMains, pkCol);
     }
     const conflictCols = upsertKeys.map((k) => schema.col(k));
-    // Tenant isolation: a conflicting upsert must not overwrite rows owned by another tenant.
+    // Tenant isolation: a conflicting upsert must not overwrite rows owned by another tenant, nor
+    // re-assign the owner of a row it legitimately updates.
     return assertTenantOwnsConflicts(db, tenant, schema.tableName, conflictCols, preparedMains)
-        .then(() => db.bulkInsertOrUpdate(schema.tableName, preparedMains, conflictCols, pkCol));
+        .then(() => db.bulkInsertOrUpdate(schema.tableName, preparedMains, conflictCols, pkCol, undefined, tenantImmutableColumns(tenant)));
 }
 /** Secondaries, deletions and the afterInsert hook for one upserted item. */
 async function finalizeUpsertedItem(params, item, inputMain, pkRow) {

package/dist/lib/engine/rest/get.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/get.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9D,wBAAsB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAsCrE"}
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/rest/get.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9D,wBAAsB,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAuCrE"}

package/dist/lib/engine/rest/get.js

@@ -15,10 +15,11 @@ export async function getEngine(params) {
     // shared with the through table would be ambiguous.
     cb.isEqual(`${db.qi(tableConf.Schema.tableName)}.${db.qi(pkCol)}`, id);
     const joins = [];
-    if (tenant) {
-        cb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableConf.Schema.tableName));
-        if ('through' in tenant.scope) {
-            joins.push(buildTenantJoin(db, tenant.scope, tableConf.Schema.tableName));
+    if (tenant?.scope) {
+        const scope = tenant.scope;
+        cb.append(buildTenantCondition(db, scope, tenant.ids, tableConf.Schema.tableName));
+        if ('through' in scope) {
+            joins.push(buildTenantJoin(db, scope, tableConf.Schema.tableName));
         }
     }
     const where = cb.build(1, db.ph);

package/dist/lib/engine/rest/update.js

@@ -54,7 +54,7 @@ export async function updateEngine(params) {
     // 6. Strip tenant column (user cannot change tenant of an existing record).
     //    For indirect scopes the tenant link is the through-FK (localField): it may be changed,
     //    but only to another value the caller owns — re-validate the new FK against the tenant.
-    if (tenant) {
+    if (tenant?.scope) {
         stripTenantColumn(updateFields, tenant.scope);
         await enforceTenantFKOnUpdate(db, tenant, updateFields);
     }

package/dist/lib/engine/search/search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAwP3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAsFvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAGb,MAAM,mBAAmB,CAAC;AAyP3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAsFvB"}

package/dist/lib/engine/search/search.js

@@ -153,10 +153,11 @@ function buildMainCondition(params) {
         applyConditions(condition, conditions, tableConf.Schema, tableConf, db);
     }
     const tenantJoins = [];
-    if (tenant) {
-        condition.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableConf.Schema.tableName));
-        if ('through' in tenant.scope) {
-            tenantJoins.push(buildTenantJoin(db, tenant.scope, tableConf.Schema.tableName));
+    if (tenant?.scope) {
+        const scope = tenant.scope;
+        condition.append(buildTenantCondition(db, scope, tenant.ids, tableConf.Schema.tableName));
+        if ('through' in scope) {
+            tenantJoins.push(buildTenantJoin(db, scope, tableConf.Schema.tableName));
         }
     }
     return { condition, tenantJoins };

package/dist/lib/engine/write-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/write-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAQ5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAGR,aAAa,EACd,MAAM,gBAAgB,CAAC;AAqDxB,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAmCD,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACvD,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAe7E;AAkCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACrD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAiDpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAoBpD"}
+{"version":3,"file":"write-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/engine/write-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS5C,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAGR,aAAa,EACd,MAAM,gBAAgB,CAAC;AAqDxB,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GACpB,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAmCD,UAAU,UAAU;IAClB,EAAE,EAAE,WAAW,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EACvD,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC,CAe7E;AAkCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,aAAa,EACnB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACrD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAkDpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,GACnD,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAoBpD"}

package/dist/lib/engine/write-helpers.js

@@ -1,6 +1,6 @@
 import { camelcaseObject, snakecaseRecord } from '../naming.js';
 import { runValidation } from './validate.js';
-import { tenantForTable, buildTenantRowGuard, enforceTenantOnWrites, assertTenantOwnsConflicts, } from '../tenant.js';
+import { tenantForTable, buildTenantRowGuard, enforceTenantOnWrites, assertTenantOwnsConflicts, tenantImmutableColumns, } from '../tenant.js';
 /**
  * Resolve the write join an alias names, or undefined when the table does not declare it.
  *
@@ -148,7 +148,7 @@ export function processSecondaries(pass, secondaries) {
             // A conflicting upsert must not overwrite — or re-parent — a child row owned by
             // another tenant, which the ON CONFLICT key alone would happily match.
             await assertTenantOwnsConflicts(db, childTenant, joinSchema.tableName, conflictCols, preparedRecords);
-            pkRows = await db.bulkInsertOrUpdate(joinSchema.tableName, preparedRecords, conflictCols, childPkCol);
+            pkRows = await db.bulkInsertOrUpdate(joinSchema.tableName, preparedRecords, conflictCols, childPkCol, undefined, tenantImmutableColumns(childTenant));
         }
         else {
             pkRows = await db.bulkInsert(joinSchema.tableName, preparedRecords, childPkCol);

package/dist/lib/errors.d.ts

@@ -8,4 +8,28 @@
 export declare function httpError(statusCode: number, message: string): Error & {
     statusCode: number;
 };
+/**
+ * Replace an error escaping a route handler with one that carries no database detail.
+ *
+ * Driver messages name tables, columns and constraints, and the route error handler sends
+ * `error.message` verbatim — so a unique violation describes the schema to whoever
+ * triggered it. Errors the plugin raises itself are deliberate `4xx` with messages written
+ * for clients (`httpError`, `validationErrors`) and pass through untouched; everything
+ * else becomes a bare `500`.
+ *
+ * The original is attached as `cause`, so a consumer `setErrorHandler` can still apply its
+ * own policy — mapping SQLSTATE to a status code stays the consumer's decision (ADR 0006).
+ * No status code is remapped here: a `500` stays a `500`.
+ *
+ * `requestId` is carried on the sanitized error and rendered in the response body: it is the
+ * same value Fastify logs as `reqId` on every line, so the log entry holding the real error
+ * is one grep away from the client's `500`.
+ *
+ * With `exposeDebugInfo`, the original is also described in a `debugInfo` payload rendered
+ * beside those fields — additive, so the response a client codes against is the same one it
+ * gets in production. It is off by default and derived from nothing: `debug` belongs to the
+ * consumer, who may wire it to an environment variable, and no option may open an external
+ * channel as a side effect of meaning something internal. See ADR 0013.
+ */
+export declare function sanitizeRouteError(err: unknown, requestId?: string, exposeDebugInfo?: boolean): unknown;
 //# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAI7F"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/lib/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,KAAK,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAI7F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,SAAS,CAAC,EAAE,MAAM,EAClB,eAAe,UAAQ,GACtB,OAAO,CAcT"}