fastify-auto-sqlapi 0.1.14 → 0.2.1

package/dist/lib/tenant.js

@@ -3,31 +3,113 @@ import { httpError } from './errors.js';
 function isIndirect(scope) {
     return 'through' in scope;
 }
+function isAnyOf(scope) {
+    return 'anyOf' in scope;
+}
+/**
+ * The tenant columns living on the scoped table itself, in declaration order: one for a direct
+ * scope, several for an `anyOf` one. Never called for an indirect scope, whose column belongs to
+ * the through table.
+ */
+function ownColumns(scope) {
+    return isAnyOf(scope) ? scope.anyOf : [scope.column];
+}
+/**
+ * Whether this request could touch a scoped row at all: the addressed table is scoped, or one of
+ * the tables it can reach through a declared relation is.
+ *
+ * Relations are what makes the second case necessary — a relation is a read grant on its target
+ * and a write join a write grant, so a deliberately public host must still carry its neighbours'
+ * scopes into the joins and secondaries it drives. One level is the whole reach: joins resolve
+ * from the addressed table's own `allowedReadJoins`/`allowedWriteJoins` and never chain further.
+ *
+ * When nothing scoped is in reach, `getTenantId` is not called at all — a request that cannot
+ * read or write a scoped row should not pay for resolving a tenant, and consumer code that
+ * assumes an authenticated request should not run on routes that never needed one.
+ */
+function scopeInReach(tableConf, dbTables) {
+    if (tableConf.tenantScope)
+        return true;
+    if (!dbTables)
+        return false;
+    const relations = [...(tableConf.allowedReadJoins ?? []), ...(tableConf.allowedWriteJoins ?? [])];
+    return relations.some((join) => dbTables[join.joinSchema.tableName]?.tenantScope !== undefined);
+}
 export async function resolveTenant(options, tableConf, request) {
     if (!options.getTenantId)
         return undefined;
-    if (!tableConf.tenantScope)
+    if (!scopeInReach(tableConf, options.DbTables))
         return undefined;
     const raw = await options.getTenantId(request);
     if (raw == null)
         return undefined; // admin
     const ids = Array.isArray(raw) ? raw : [raw];
+    // `scope` stays undefined for an unscoped host: the ids still travel, so the tables it reaches
+    // enforce their own scopes, while the host itself keeps no filter.
     return { ids, scope: tableConf.tenantScope };
 }
+/**
+ * The read predicate for a scope, as a fragment every caller appends to its own WHERE.
+ *
+ * An `anyOf` scope returns an OR-mode builder — the row is visible when any listed column holds
+ * a tenant id — and every caller appends it, so the group keeps its own parentheses. A NULL
+ * column simply fails to match, which is the wanted behaviour: the other party still decides.
+ */
 export function buildTenantCondition(db, scope, tenantIds, ownTable) {
-    const col = scope.column;
-    let qualifier;
     if (isIndirect(scope)) {
         const throughTable = scope.through.schema.tableName;
-        qualifier = `${db.qi(throughTable)}.${db.qi(col)}`;
+        const cb = new ConditionBuilder('AND', db.cbDialect);
+        cb.isIn(`${db.qi(throughTable)}.${db.qi(scope.column)}`, tenantIds);
+        return cb;
     }
-    else {
-        // Qualify with the table the scope column lives on: the statement may carry
-        // joins, and a bare column shared with a joined table would be ambiguous.
-        qualifier = `${db.qi(ownTable)}.${db.qi(col)}`;
+    // Qualify with the table the scope columns live on: the statement may carry
+    // joins, and a bare column shared with a joined table would be ambiguous.
+    const cols = ownColumns(scope);
+    const cb = new ConditionBuilder(cols.length > 1 ? 'OR' : 'AND', db.cbDialect);
+    for (const col of cols) {
+        cb.isIn(`${db.qi(ownTable)}.${db.qi(col)}`, tenantIds);
     }
+    return cb;
+}
+/**
+ * Re-target a tenant context onto a related table: the caller's tenant ids paired with that
+ * table's OWN scope. A child table declares its own `tenantScope`, which may differ in shape
+ * from the main table's, so a write to it must be checked against its own column/through-FK.
+ *
+ * Returns undefined for the two cases that must stay unscoped — no tenant context (admin) and
+ * a table that declares no scope — mirroring `appendJoinTenantScope` on the read side.
+ */
+export function tenantForTable(tenant, tableConf) {
+    const scope = tableConf?.tenantScope;
+    if (!tenant || !scope)
+        return undefined;
+    return { ids: tenant.ids, scope };
+}
+/**
+ * Tenant guard as a self-contained boolean fragment, for the positions where the scope cannot
+ * be expressed as an extra INNER JOIN: a child DELETE, a LEFT JOIN's ON clause, and the
+ * correlated subquery of an aggregation. A direct scope compares the table's own column; an
+ * indirect one tests the through table with a correlated EXISTS rather than a join.
+ *
+ * `tableRef` is the name the scoped rows go by in that statement — the table name in a DELETE,
+ * the join alias in an ON clause, the subquery alias inside a correlated SELECT. Returns
+ * undefined without a tenant context (admin) or when the table carries no scope.
+ */
+export function buildTenantRowGuard(db, tenant, tableRef) {
+    const scope = tenant?.scope;
+    if (!tenant || !scope)
+        return undefined;
     const cb = new ConditionBuilder('AND', db.cbDialect);
-    cb.isIn(qualifier, tenantIds);
+    if (!isIndirect(scope)) {
+        cb.append(buildTenantCondition(db, scope, tenant.ids, tableRef));
+        return cb;
+    }
+    const { through, column } = scope;
+    const throughRef = db.qi(through.schema.tableName);
+    const markers = tenant.ids.map(() => '?').join(', ');
+    cb.raw(`EXISTS (SELECT 1 FROM ${throughRef} WHERE ` +
+        `${throughRef}.${db.qi(through.foreignField)} = ${db.qi(tableRef)}.${db.qi(through.localField)} AND ` +
+        `${throughRef}.${db.qi(column)} IN (${markers}))`, tenant.ids);
     return cb;
 }
 export function buildTenantJoin(db, scope, mainTableName) {
@@ -36,6 +118,30 @@ export function buildTenantJoin(db, scope, mainTableName) {
     const foreignField = scope.through.foreignField;
     return `INNER JOIN ${db.qi(throughTable)} ON ${db.qi(mainTableName)}.${db.qi(localField)} = ${db.qi(throughTable)}.${db.qi(foreignField)}`;
 }
+/**
+ * The insert-side rule for an `anyOf` scope: the payload must anchor the row itself.
+ *
+ * Nothing is auto-injected — with several owner columns the plugin cannot know which party the
+ * caller is meant to be, and guessing would either invent a relationship or refuse a legitimate
+ * one. So the record must name at least one listed column, and at least one of the named ones
+ * must hold a tenant id. The *other* parties are deliberately left alone: a swap request points
+ * at a colleague by definition, and requiring every listed column to match would make the shape
+ * unusable.
+ *
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
+export function assertTenantAnchor(record, scope, tenantIds) {
+    const present = scope.anyOf.filter((col) => record[col] != null);
+    if (!present.length) {
+        throw httpError(400, `Missing tenant anchor: one of ${scope.anyOf.join(', ')} must be set`);
+    }
+    if (!present.some((col) => tenantIds.includes(record[col]))) {
+        throw httpError(403, 'Access denied: tenant value does not match');
+    }
+}
+/** Writes the tenant value into a record according to its scope.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export function injectTenantValue(record, scope, tenantIds) {
     if (isIndirect(scope))
         return;
@@ -52,6 +158,9 @@ export function injectTenantValue(record, scope, tenantIds) {
     }
     throw httpError(400, 'Ambiguous tenant: specify the tenant value');
 }
+/** Checks that an indirect-scope FK really belongs to the tenant.
+ * @testonly Exported only so unit tests can exercise it directly.
+ */
 export async function validateTenantFK(db, scope, tenantIds, fkValues) {
     if (!fkValues.length)
         return;
@@ -75,16 +184,18 @@ export async function validateTenantFK(db, scope, tenantIds, fkValues) {
 }
 /**
  * Build WHERE clause for DELETE with tenant filtering.
- * Handles both direct (simple AND) and indirect (subquery via JOIN) scopes.
+ * Handles both direct (simple AND) and indirect (subquery via JOIN) scopes; a tenant whose
+ * addressed table declares no scope yields the plain primary-key clause.
  */
 export function buildTenantDeleteWhere(db, tableName, pkCol, pkValue, tenant) {
-    if (isIndirect(tenant.scope)) {
+    const scope = tenant.scope;
+    if (scope && isIndirect(scope)) {
         const innerCb = new ConditionBuilder('AND', db.cbDialect);
         innerCb.isIn(`${db.qi(tableName)}.${db.qi(pkCol)}`, (Array.isArray(pkValue) ? pkValue : [pkValue]));
-        innerCb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableName));
+        innerCb.append(buildTenantCondition(db, scope, tenant.ids, tableName));
         const innerWhere = innerCb.build(1, db.ph);
         const values = innerCb.getValues();
-        const joinSql = buildTenantJoin(db, tenant.scope, tableName);
+        const joinSql = buildTenantJoin(db, scope, tableName);
         const where = `${db.qi(pkCol)} IN (SELECT ${db.qi(tableName)}.${db.qi(pkCol)} FROM ${db.qi(tableName)} ${joinSql} WHERE ${innerWhere})`;
         return { where, values };
     }
@@ -95,7 +206,8 @@ export function buildTenantDeleteWhere(db, tableName, pkCol, pkValue, tenant) {
     else {
         cb.isEqual(db.qi(pkCol), pkValue);
     }
-    cb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableName));
+    if (scope)
+        cb.append(buildTenantCondition(db, scope, tenant.ids, tableName));
     const where = cb.build(1, db.ph);
     const values = cb.getValues();
     return { where, values };
@@ -112,7 +224,8 @@ export function buildTenantDeleteWhere(db, tableName, pkCol, pkValue, tenant) {
  * any conflict column are skipped (they can only INSERT, never hit a conflict).
  */
 export async function assertTenantOwnsConflicts(db, tenant, tableName, conflictCols, records) {
-    if (!tenant || !conflictCols.length)
+    const scope = tenant?.scope;
+    if (!tenant || !scope || !conflictCols.length)
         return;
     // Collect distinct, fully-specified conflict-key tuples.
     const tuples = [];
@@ -153,19 +266,35 @@ export async function assertTenantOwnsConflicts(db, tenant, tableName, conflictC
     }
     // Tenant-mismatch clause: rows whose tenant is NOT one the caller owns.
     let joinSql = '';
-    let tenantCol;
-    if (isIndirect(tenant.scope)) {
-        joinSql = ` ${buildTenantJoin(db, tenant.scope, tableName)}`;
-        tenantCol = `${db.qi(tenant.scope.through.schema.tableName)}.${db.qi(tenant.scope.column)}`;
+    let tenantCols;
+    if (isIndirect(scope)) {
+        joinSql = ` ${buildTenantJoin(db, scope, tableName)}`;
+        tenantCols = [`${db.qi(scope.through.schema.tableName)}.${db.qi(scope.column)}`];
+    }
+    else {
+        tenantCols = ownColumns(scope).map((c) => `${qTable}.${db.qi(c)}`);
+    }
+    const inClause = (col) => {
+        const phs = tenant.ids.map((id) => {
+            values.push(id);
+            return db.ph(values.length);
+        });
+        return `${col} IN (${phs.join(', ')})`;
+    };
+    let mismatchSql;
+    if (tenantCols.length === 1) {
+        mismatchSql = `${tenantCols[0]} NOT IN (${tenant.ids.map((id) => {
+            values.push(id);
+            return db.ph(values.length);
+        }).join(', ')})`;
     }
     else {
-        tenantCol = `${qTable}.${db.qi(tenant.scope.column)}`;
+        // A NULL party makes `IN` return NULL, and `NOT NULL` is not TRUE — a plain negation would
+        // let a row with one party NULL and the other owned by a stranger pass the probe unflagged.
+        // COALESCE turns "unknown" into "not visible to me", which is what the read side already
+        // does implicitly by never matching a NULL.
+        mismatchSql = `NOT COALESCE(${tenantCols.map(inClause).join(' OR ')}, FALSE)`;
     }
-    const tenantPhs = tenant.ids.map((id) => {
-        values.push(id);
-        return db.ph(values.length);
-    });
-    const mismatchSql = `${tenantCol} NOT IN (${tenantPhs.join(', ')})`;
     const sql = `SELECT 1 FROM ${qTable}${joinSql} WHERE ${matchSql} AND ${mismatchSql} LIMIT 1`;
     const r = await db.query(sql, values);
     if (r.rows.length > 0) {
@@ -182,24 +311,27 @@ export async function assertTenantOwnsConflicts(db, tenant, tableName, conflictC
  * `updateFields` keys are DB column names (snake_case), matching `through.localField`.
  */
 export async function enforceTenantFKOnUpdate(db, tenant, updateFields) {
-    if (!tenant || !isIndirect(tenant.scope))
+    if (!tenant?.scope || !isIndirect(tenant.scope))
         return;
-    const localCol = tenant.scope.through.localField;
+    const scope = tenant.scope;
+    const localCol = scope.through.localField;
     if (!(localCol in updateFields))
         return;
     const newValue = updateFields[localCol];
     if (newValue == null)
         return;
-    await validateTenantFK(db, tenant.scope, tenant.ids, [newValue]);
+    await validateTenantFK(db, scope, tenant.ids, [newValue]);
 }
 /**
- * Mutates `fields` in-place: removes the tenant column from a SET payload (direct scopes only).
- * No-op for indirect or no scope.
+ * Mutates `fields` in-place: removes the tenant columns from a SET payload (scopes whose columns
+ * live on the table itself). An `anyOf` scope drops *every* listed column — neither party can be
+ * reassigned, the same spirit as "a tenant cannot move its own row". No-op for indirect scopes.
  */
 export function stripTenantColumn(fields, scope) {
     if (isIndirect(scope))
         return;
-    delete fields[scope.column];
+    for (const col of ownColumns(scope))
+        delete fields[col];
 }
 /**
  * For insert/bulk-upsert: enforce tenant on records that are about to be written.
@@ -208,15 +340,38 @@ export function stripTenantColumn(fields, scope) {
  * Throws 400 (ambiguous tenant) or 403 (mismatch) on violation. No-op when `tenant` is undefined.
  */
 export async function enforceTenantOnWrites(db, tenant, records) {
-    if (!tenant)
+    const scope = tenant?.scope;
+    if (!tenant || !scope)
         return;
-    if (isIndirect(tenant.scope)) {
-        const fkCol = tenant.scope.through.localField;
-        await validateTenantFK(db, tenant.scope, tenant.ids, records.map((r) => r[fkCol]));
+    if (isIndirect(scope)) {
+        const fkCol = scope.through.localField;
+        await validateTenantFK(db, scope, tenant.ids, records.map((r) => r[fkCol]));
+        return;
+    }
+    if (isAnyOf(scope)) {
+        for (const r of records)
+            assertTenantAnchor(r, scope, tenant.ids);
         return;
     }
     for (const r of records)
-        injectTenantValue(r, tenant.scope, tenant.ids);
+        injectTenantValue(r, scope, tenant.ids);
+}
+/**
+ * Columns an UPSERT must leave alone when it lands on an existing row.
+ *
+ * `stripTenantColumn` does this for a plain UPDATE, but an upsert's payload doubles as the
+ * INSERT branch, where the owner columns are exactly what anchors a new row — they cannot simply
+ * be dropped. So they are excluded from the `DO UPDATE SET` instead: state which party you are
+ * to create the row, and that statement is ignored when the row already exists.
+ *
+ * Only `anyOf` scopes need this. A direct scope injects the caller's own tenant, so writing it
+ * back onto a row the conflict guard already proved theirs is a no-op; an indirect one keeps its
+ * owner on another table entirely.
+ */
+export function tenantImmutableColumns(tenant) {
+    if (!tenant?.scope || !isAnyOf(tenant.scope))
+        return [];
+    return tenant.scope.anyOf;
 }
 /**
  * For update: builds the optional `extraCondition` ConditionBuilder for direct tenants.
@@ -224,13 +379,17 @@ export async function enforceTenantOnWrites(db, tenant, records) {
  * (indirect uses pre-check via `assertTenantOwnership`).
  */
 export function buildTenantUpdateExtra(db, tenant) {
-    if (!tenant || isIndirect(tenant.scope))
+    const scope = tenant?.scope;
+    if (!scope || isIndirect(scope))
         return undefined;
-    const cb = new ConditionBuilder('AND', db.cbDialect);
-    if (tenant.ids.length === 1)
-        cb.isEqual(tenant.scope.column, tenant.ids[0]);
-    else
-        cb.isIn(tenant.scope.column, tenant.ids);
+    const cols = ownColumns(scope);
+    const cb = new ConditionBuilder(cols.length > 1 ? 'OR' : 'AND', db.cbDialect);
+    for (const col of cols) {
+        if (tenant.ids.length === 1)
+            cb.isEqual(col, tenant.ids[0]);
+        else
+            cb.isIn(col, tenant.ids);
+    }
     return cb;
 }
 /**
@@ -239,14 +398,15 @@ export function buildTenantUpdateExtra(db, tenant) {
  * No-op for direct or no-tenant — those are enforced via `extraCondition` in the UPDATE itself.
  */
 export async function assertTenantOwnership(db, tenant, tableName, pkCol, pkValue) {
-    if (!tenant || !isIndirect(tenant.scope))
+    if (!tenant?.scope || !isIndirect(tenant.scope))
         return;
+    const scope = tenant.scope;
     const cb = new ConditionBuilder('AND', db.cbDialect);
     const cols = Array.isArray(pkCol) ? pkCol : [pkCol];
     const vals = Array.isArray(pkValue) ? pkValue : [pkValue];
     cols.forEach((c, i) => cb.isEqual(`${db.qi(tableName)}.${db.qi(c)}`, vals[i]));
-    cb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableName));
-    const sql = `SELECT 1 FROM ${db.qi(tableName)} ${buildTenantJoin(db, tenant.scope, tableName)} WHERE ${cb.build(1, db.ph)} LIMIT 1`;
+    cb.append(buildTenantCondition(db, scope, tenant.ids, tableName));
+    const sql = `SELECT 1 FROM ${db.qi(tableName)} ${buildTenantJoin(db, scope, tableName)} WHERE ${cb.build(1, db.ph)} LIMIT 1`;
     const r = await db.query(sql, cb.getValues());
     if (r.rows.length === 0) {
         throw httpError(404, 'Record not found');
@@ -259,13 +419,14 @@ export async function assertTenantOwnership(db, tenant, tableName, pkCol, pkValu
  * `beforeBulkDelete` hook, so user code never runs against rows the caller cannot access.
  */
 export async function assertTenantOwnsAll(db, tenant, tableName, pkCol, ids) {
-    if (!tenant || !ids.length)
+    const scope = tenant?.scope;
+    if (!tenant || !scope || !ids.length)
         return;
     const qualifiedPk = `${db.qi(tableName)}.${db.qi(pkCol)}`;
     const cb = new ConditionBuilder('AND', db.cbDialect);
     cb.isIn(qualifiedPk, ids);
-    cb.append(buildTenantCondition(db, tenant.scope, tenant.ids, tableName));
-    const join = isIndirect(tenant.scope) ? ` ${buildTenantJoin(db, tenant.scope, tableName)}` : '';
+    cb.append(buildTenantCondition(db, scope, tenant.ids, tableName));
+    const join = isIndirect(scope) ? ` ${buildTenantJoin(db, scope, tableName)}` : '';
     const sql = `SELECT DISTINCT ${qualifiedPk} AS pk FROM ${db.qi(tableName)}${join} WHERE ${cb.build(1, db.ph)}`;
     const r = await db.query(sql, cb.getValues());
     const uniqueRequested = new Set(ids.map((v) => String(v))).size;

package/dist/routes/auto/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAc7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;kCAuD/C,eAAe,WACf,mBAAmB,KAC3B,OAAO,CAAC,IAAI,CAAC;AAHhB,wBA6DoC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAC;AAc7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;kCAuD/C,eAAe,WACf,mBAAmB,KAC3B,OAAO,CAAC,IAAI,CAAC;AAHhB,wBAsEoC"}

package/dist/routes/auto/plugin.js

@@ -82,10 +82,16 @@ export default fp(async function fastifyAutoSqlApi(fastify, options) {
                 });
             }
             const statusCode = error.statusCode || 500;
+            // A sanitized error carries the request id so the client can point at the log line
+            // holding the real cause, and — under `exposeDebugInfo` — the description of that
+            // cause (ADR 0013). Both are additive: the fields above never change shape.
+            const sanitized = error;
             reply.status(statusCode).send({
                 statusCode,
                 error: error.name || 'Error',
                 message: error.message,
+                ...(sanitized.requestId ? { requestId: sanitized.requestId } : {}),
+                ...(sanitized.debugInfo ? { debugInfo: sanitized.debugInfo } : {}),
             });
         });
         if (options.swagger) {

package/dist/routes/auto/route-helpers.d.ts

@@ -1,7 +1,5 @@
 import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
 import type { ITable, SqlApiPluginOptions, DbTables, TableOperation } from '../../types.js';
-type RequestHook = (request: FastifyRequest, reply: FastifyReply) => Promise<void | FastifyReply>;
-export declare function mergeOnRequests(options: SqlApiPluginOptions, tableConf: ITable): RequestHook[];
 export declare function buildWriteDescription(action: string, tableName: string, tableConf: ITable): string;
 interface RouteSchema {
     body?: any;
@@ -31,11 +29,6 @@ export interface AutoRouteSpec {
      * the registrar will reply.status(successStatus).send(returnValue). */
     handle: (fastify: FastifyInstance, tableName: string, tableConf: ITable, request: FastifyRequest, reply: FastifyReply) => Promise<unknown>;
 }
-/**
- * Iterates over every table in `options.DbTables` and registers one Fastify route for it
- * following `spec`. Centralizes onRequest hook merging, tags, schema response wrapping,
- * default reply when handler returns a value.
- */
 export declare function registerForAllTables(fastify: FastifyInstance, options: SqlApiPluginOptions, spec: AutoRouteSpec): Promise<void>;
 export {};
 //# sourceMappingURL=route-helpers.d.ts.map

package/dist/routes/auto/route-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAE5F,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,GAAG,YAAY,CAAC,CAAC;AAElG,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,EAAE,CAE9F;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CAkDf"}
+{"version":3,"file":"route-helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/auto/route-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI7E,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQ5F,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAQlG;AAED,UAAU,WAAW;IAEnB,IAAI,CAAC,EAAE,GAAG,CAAC;IAEX,MAAM,CAAC,EAAE,GAAG,CAAC;IAEb,WAAW,CAAC,EAAE,GAAG,CAAC;IAElB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC1C,gFAAgF;IAChF,GAAG,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,aAAa,EAAE,GAAG,GAAG,GAAG,CAAC;IACzB,wIAAwI;IACxI,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,WAAW,CAAC;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,KAAK,MAAM,CAAC;IACpF;2EACuE;IACvE,MAAM,EAAE,CACN,OAAO,EAAE,eAAe,EACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,YAAY,KAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AA6DD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,IAAI,CAAC,CA6Bf"}

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

@@ -1,6 +1,7 @@
 import { ensureSqlApiDecorator } from '../../lib/sql-api-decorator.js';
+import { sanitizeRouteError } from '../../lib/errors.js';
 import { isCompositePrimary } from '../../types.js';
-export function mergeOnRequests(options, tableConf) {
+function mergeOnRequests(options, tableConf) {
     return [...(options.onRequests || []), ...(tableConf.onRequests || [])];
 }
 export function buildWriteDescription(action, tableName, tableConf) {
@@ -17,51 +18,75 @@ export function buildWriteDescription(action, tableName, tableConf) {
  * following `spec`. Centralizes onRequest hook merging, tags, schema response wrapping,
  * default reply when handler returns a value.
  */
+/**
+ * Whether this table is addressable by the spec's route shape.
+ *
+ * A single-PK route cannot address a composite-PK table. Skipping is the default, but when
+ * the consumer explicitly listed the operation it is a configuration error: failing at
+ * startup beats a route that silently never exists.
+ */
+function isTableRoutable(tableName, tableConf, spec) {
+    // operations acts as a whitelist; when omitted every operation is exposed.
+    if (tableConf.operations && !tableConf.operations.includes(spec.operation))
+        return false;
+    if (!spec.singlePkOnly || !isCompositePrimary(tableConf.primary))
+        return true;
+    if (tableConf.operations?.includes(spec.operation)) {
+        throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
+            `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
+            `Remove it from "operations", or handle the table via search/update or a custom route.`);
+    }
+    return false;
+}
+/**
+ * Fastify route schema for one table.
+ *
+ * Only keys that are actually defined are included: Fastify checks for key *presence*
+ * (not an undefined value) to decide whether to emit FSTWRN001.
+ */
+function buildRouteSchema(tableName, tableConf, spec, schemas) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const schema = {
+        tags: [`SqlAPI-${tableName}`],
+        summary: `${spec.summary} ${tableName}`,
+        description: spec.description(tableName, tableConf, schemas),
+    };
+    if (schemas.body !== undefined)
+        schema.body = schemas.body;
+    if (schemas.params !== undefined)
+        schema.params = schemas.params;
+    if (schemas.querystring !== undefined)
+        schema.querystring = schemas.querystring;
+    if (schemas.response !== undefined)
+        schema.response = { [spec.successStatus]: schemas.response };
+    return schema;
+}
 export async function registerForAllTables(fastify, options, spec) {
     // Granular composition support: when a route plugin is registered without the
     // main plugin, no ancestor has decorated `sqlApi` — create it in this scope.
     ensureSqlApiDecorator(fastify, options);
     const { DbTables } = options;
     for (const [tableName, tableConf] of Object.entries(DbTables)) {
-        // operations acts as a whitelist; when omitted every operation is exposed.
-        if (tableConf.operations && !tableConf.operations.includes(spec.operation))
-            continue;
-        // Single-PK routes cannot address composite-PK tables — skip them (default) or,
-        // when the consumer explicitly asked for the operation, fail loudly at startup.
-        if (spec.singlePkOnly && isCompositePrimary(tableConf.primary)) {
-            if (tableConf.operations?.includes(spec.operation)) {
-                throw new Error(`Table "${tableName}" has a composite primary key (${tableConf.primary.join(', ')}): ` +
-                    `operation "${spec.operation}" addresses records by a single PK value and cannot be exposed. ` +
-                    `Remove it from "operations", or handle the table via search/update or a custom route.`);
-            }
+        if (!isTableRoutable(tableName, tableConf, spec))
             continue;
-        }
         const schemas = spec.schemas(DbTables, tableName, tableConf);
-        // Only include schema keys that are actually defined: Fastify checks for key
-        // *presence* (not undefined value) to decide whether to emit FSTWRN001.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const schema = {
-            tags: [`SqlAPI-${tableName}`],
-            summary: `${spec.summary} ${tableName}`,
-            description: spec.description(tableName, tableConf, schemas),
-        };
-        if (schemas.body !== undefined)
-            schema.body = schemas.body;
-        if (schemas.params !== undefined)
-            schema.params = schemas.params;
-        if (schemas.querystring !== undefined)
-            schema.querystring = schemas.querystring;
-        if (schemas.response !== undefined)
-            schema.response = { [spec.successStatus]: schemas.response };
         fastify.route({
             method: spec.method,
             url: spec.url(tableConf),
-            schema,
+            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/routes/auto/search.routes.js

@@ -15,7 +15,6 @@ export default async function searchRoutes(fastify, options) {
         }),
         summary: 'Search',
         description: (name, _tc, schemas) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const body = schemas.body;
             const multiAliases = Object.keys(body?.properties?.joinMultiple?.properties || {});
             const leftAliases = Object.keys(body?.properties?.joinLeft?.properties || {});

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/table.d.ts

@@ -30,7 +30,7 @@ export interface ITable<F extends Record<string, TSchema> = Record<string, TSche
     extraFilters: Record<string, TSchema>;
     /**
      * Virtual fields produced by a SQL expression. Usable like schema fields in
-     * `filters`, `conditions` (non-dotted), `orderBy` (1-parte),
+     * `filters`, `conditions` (non-dotted), `orderBy` (1-part),
      * `computeMin/Max/Sum/Avg`, and (opt-in) in `selectComputed` for the main
      * response. Each entry MUST declare `type` for Swagger and validation.
      *

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