fastify-auto-sqlapi 0.1.13 → 0.1.14

package/AGENTS_BACKEND.md

@@ -357,6 +357,8 @@ buildRelation(mainSchema, mainField, joinSchema, joinField, options?)
 //   unique?: boolean;         // default false.
 //                             //   false → 1:N (child→main). Allowed in joinMustExist/joinMultiple/joinGroup.
 //                             //   true  → N:1 (parent→main). Allowed in joinLeft only.
+//   fields?: string[];        // allowlist of the target's fields reachable through this relation.
+//                             // Read joins only. Must include joinField. Everything else is 400.
 // }
 ```
 
@@ -367,6 +369,27 @@ buildRelation(mainSchema, mainField, joinSchema, joinField, options?)
 
 **When to declare an explicit `alias`**: only when (a) you join the same table multiple times in the same `allowedReadJoins`/`allowedWriteJoins`, or (b) you want a friendlier name in the public API surface than the SQL table name (e.g. `'orders'` instead of `'customer_order'`). Otherwise omit it — the default is `joinSchema.tableName`.
 
+**⚠️ A relation in `allowedReadJoins` is a read grant on the target table.** The join runs inside the query of the *host* table's route, so the target's `onRequests` never fire and its `operations` whitelist does not apply — a table with `operations: []` is still fully readable through any relation pointing at it. What does cross a join: `readExclude`, `tenantScope`, and the schema the relation was declared with.
+
+To expose a table broadly but keep some of its columns narrow, give the relation a `fields` allowlist:
+
+```typescript
+allowedReadJoins: [
+  buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] }),
+],
+```
+
+The relation is declared against a schema narrowed to that list, so every read surface validates against it — `selection`, `filters`, `conditions`, `orderBy`, aggregations, and the generated request/response schemas. A field outside the list is `400 Unknown field` everywhere, not just missing from the projection, and the default `'*'` selection is spelled out into the allowed columns rather than emitting a real `SELECT *`.
+
+Rules, all enforced at declaration time:
+
+- **Must include the join field** — it is what correlates the fetched rows with the main ones.
+- **Not allowed on `allowedWriteJoins`** — the allowlist restricts reading only; write paths resolve `upsertMap` by schema identity and must write every column the caller sent. Declare two relations if the same pair is joined for reading and for writing.
+- **Computed fields on the target resolve against the narrowed schema** — one that reads a field outside the list is a `400`, so a computed cannot be used to reach past the allowlist. One that stays inside keeps working.
+- **Fail-closed** — a column added to the target later is not reachable through the relation until it is added to `fields`.
+
+`fields` is not a replacement for `readExclude` (which hides a column from the owning table's own routes too). See [ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md) and [ADR 0011](./docs/adr/0011-join-fields-allowlist.md).
+
 **Choosing `unique`**: if `joinField` is the PK (or part of the composite PK) of `joinSchema`, the relation is N:1 — you almost certainly want `unique: true` so the alias is usable in `joinLeft`.
 
 **Owned child tables (translations, `*_info` details): use a writeJoin, not a standalone table.** A table that only exists as a child of a parent — e.g. `product_info` with composite PK `(product_id, lang)` — should be an `allowedWriteJoins` on the parent, not its own `DbTables` entry. The engine auto-fills the FK (`product_id`); add it to `upsertMap` (conflict key = the composite PK) to upsert children passing only their own fields. Avoids redundant endpoints/validators.
@@ -431,6 +454,10 @@ export const TableCustomer = defineTable({
 
 `extraFilters` accepts either a `Type.Object({...})` or a plain `Record<string, TSchema>`. Extra filter fields appear in Swagger but are NOT auto-applied as `WHERE col = value` — they are handled exclusively by the `extendedCondition` callback. The `filters` parameter in the callback is fully typed with autocomplete for all schema fields + extra filter keys.
 
+**Not available on `joinLeft`.** `extendedCondition` writes its own column references, which cannot be qualified with the `LEFT JOIN` alias the parent gets there, so `buildLeftJoinClauses` handles schema and computed fields only. The generated body schema does not advertise the parent's `extraFilters` under `joinLeft.<alias>.filters`, and sending one is a `400` rather than a silent no-op. Use `joinMustExist` on the same relation when you need an extra filter on the parent.
+
+**Unknown filter keys are a `400`** (`Unknown filter field: <key>`), on the main table and on every join. A filter that does not match a schema field, an `extraFilters` key or a computed field is rejected instead of dropped: silently ignoring it would return *more* rows than the caller asked for. The check lives in the engine, so it applies to `sqlApi.search()` too, and it runs before any query — the outcome never depends on whether the main query matched rows.
+
 ---
 
 ## Computed Fields (extension system)
@@ -777,7 +804,7 @@ Tables without `tenantScope` are unaffected — no filtering regardless of `getT
 - **All fields Optional in response**: `RETURNING *` may return any subset. Response schemas use `Type.Partial`.
 - **Nullable columns use `Nullable(T)` (type-array form)**: the generator emits `Type.Optional(Nullable(T))` for nullable columns — `Nullable` (exported by the package) produces `{ type: ['integer', 'null'] }`. Do NOT replace it with `Type.Union([T, Type.Null()])`: under Fastify's default Ajv `coerceTypes` a union corrupts values through its branches (`null` → `0` with the Null branch last, `0`/`""` → `null` with it first), while the type array validates and serializes NULL correctly. A bare `Type.Optional(T)` is also wrong: NULL serializes as `0`/`""`. In `filters`, an explicit `null` on a schema field builds `WHERE col IS NULL`.
 - **`excludeFromCreation`**: **IMPORTANT** — auto-increment PKs (e.g. `id` serial/auto_increment) MUST be listed here, otherwise INSERT will try to send them and fail. The CLI auto-detects this and adds it by default. Also useful for `createdAt`/`updatedAt` columns managed by DB defaults or hooks. It strips **client-supplied** values only: the payload is sanitized before `beforeInsert` runs, so a value the hook assigns to an excluded field (e.g. a server-generated TEXT id) DOES reach the INSERT. Same for the engine's FK auto-fill on secondaries — an excluded FK column does not suppress it. It is an **ergonomics tool for creation, NOT a field-level security mechanism**: it does not apply to updates — every Schema field is updatable by default, by design. Field-level update rules (`isAdmin`, roles, owner/tenant columns, state fields) are product logic: enforce them in `beforeUpdate` (silent strip) or `validate` (loud 400), or move the privileged transition to a dedicated endpoint and keep it off the auto routes via `operations`.
-- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes.
+- **`readExclude`**: fields hidden from every read — not projected by search/get, omitted from read response schemas and from this table's default (`*`) join selection when it is a join target. Referencing one from `filters`, `conditions`, `orderBy`, `joinGroup` aggregations or an explicit join `selection` returns 400: hiding a field from output while allowing it to be filtered would leak its value by bisection. **Writes are unaffected** — insert/update/bulk still accept the field, so a column can be writable but never readable (password hash, access token). Primary keys cannot be excluded. Complementary to trimming the Schema, which removes the column from reads *and* writes. It is **per table and static**: a column hidden here is hidden from every caller, including admins. To keep a column readable on the table's own routes but not through a relation, trim the Schema the *relation* is declared with instead — see the read-grant warning under [buildRelation](#buildrelation-signature).
 - **`upsertMap`**: when present for a schema, INSERT becomes upsert. PostgreSQL: `ON CONFLICT (...) DO UPDATE`. MySQL/MariaDB: `ON DUPLICATE KEY UPDATE`. Applies to both main and secondary tables.
 - **`schemaOverrides`**: override auto-generated schema fields with stricter TypeBox types (e.g. `{ email: Type.String({ format: 'email' }) }`). Overrides are merged into the body schema for insert, update, and bulk-upsert. The original Schema file is never modified. In updates, overridden fields are still wrapped in Optional (validates only when present). Overrides appear in Swagger.
 - **Validation receives camelCase**: `validate` receives the original camelCase record (as sent by the client) and secondaries. Field names match the schema definition, with full TypeScript inference (`main.startDate`, not `main.start_date`). It returns `ValidationError[]` — tuples of `[field, code]` or `[field, code, message]`. If any errors are returned, the request is rejected with 400 before hooks or SQL execute.

package/BREAKING_CHANGES.md

@@ -380,3 +380,78 @@ endpoints previously behaved correctly for you — they are now gone and you mus
 - **First PK column is truly unique on its own?** Then the composite declaration was
   redundant: declare `primary: 'id'` (single) and keep the second column as a plain field —
   every by-id operation comes back.
+
+---
+
+# Breaking Change — unknown filter keys are rejected
+
+`filters` keys that match nothing are now a `400`, on the main table and on every join family.
+Previously they were dropped without a word.
+
+## Why this changed
+
+The engine only ever visited filter keys matching a schema field, an `extraFilters` entry or a
+computed field. Anything else — a typo, a renamed column, a field that exists on the table but
+not on the trimmed Schema a relation was declared with — was never looked at, and the query ran
+as if the filter had not been sent.
+
+That fails in the dangerous direction. A rejected filter returns *more* rows than the caller
+asked for, and nothing in the response says so; in an application where filters are also how
+visibility is narrowed, a typo becomes a data exposure. It was also the odd one out: an unknown
+field in `selection`, `conditions`, `orderBy` or a `joinGroup` aggregation has always been a
+400.
+
+## What changed
+
+| Request | Before | After |
+|---|---|---|
+| `filters: { nosuchfield: 'x' }` | `200`, filter ignored | `400 Unknown filter field: nosuchfield` |
+| `joinMultiple.<alias>.filters: { nosuchfield: 1 }` | `200`, filter ignored | `400 Unknown filter field: nosuchfield` |
+| `joinLeft.<alias>.filters: { <extraFilter> }` | `200`, filter ignored | `400 Filter '<key>' is an extraFilter: …` |
+| `filters: { knownField: undefined }` | ignored | ignored (unchanged) |
+| `filters: { knownField: null }` | `IS NULL` | `IS NULL` (unchanged) |
+
+Two related fixes ship with it:
+
+- The check runs in the engine, not in the route schema, so `sqlApi.search()` behaves the same
+  as the HTTP routes. (A closed `additionalProperties: false` schema would not have worked:
+  Fastify runs Ajv with `removeAdditional: true`, so it would have *stripped* the key and
+  reproduced the same silent behaviour one layer up.)
+- Join filters are validated **before any query runs**. They used to be validated inside the
+  side query, which is skipped entirely when the main result set is empty — so the same request
+  answered 400 or 200 depending on the data it matched.
+
+## Who is affected
+
+Callers that send filter keys the target table does not declare. Over-sending is the common
+case: a frontend that spreads a whole form state into `filters`, or reuses one filter object
+across two tables.
+
+## Migration
+
+Send only keys the table declares. `GET /agent/manifest` and the Swagger body schema both list
+them per table (schema fields + `extraFilters` + computed fields).
+
+For a form-state object, filter it before sending rather than relying on the server to ignore
+the extras:
+
+```typescript
+const ALLOWED = ['name', 'status', 'createdFrom'] as const;
+const filters = Object.fromEntries(
+  Object.entries(formState).filter(([k, v]) => ALLOWED.includes(k) && v !== '')
+);
+```
+
+Passing `undefined` for an absent value is still safe and needs no filtering: only keys with a
+defined value are validated.
+
+## joinLeft and extraFilters
+
+`joinLeft.<alias>.filters` used to advertise the parent table's `extraFilters` in Swagger and
+accept them at runtime, applying nothing: `buildLeftJoinClauses` builds its condition inline and
+never runs the target's `extendedCondition`, whose column references cannot be qualified with
+the `LEFT JOIN` alias the parent gets there. They are no longer advertised, and sending one
+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`.

package/CHANGELOG.md

@@ -9,8 +9,53 @@ Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BR
 
 ## [Unreleased]
 
+### Changed
+
+- **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
+  mistyped filter name came back as an unfiltered (wider) result set with no error: the
+  dangerous direction to fail in, and inconsistent with `selection`, `conditions`, `orderBy`
+  and aggregations, which have always answered 400. The check lives in the engine, so it
+  covers `sqlApi.search()` as well as the HTTP routes. `undefined` values still mean "filter
+  not supplied" and are ignored; an explicit `null` still filters by `IS NULL`. See
+  [BREAKING_CHANGES.md](./BREAKING_CHANGES.md#breaking-change--unknown-filter-keys-are-rejected).
+- **`joinLeft.<alias>.filters` no longer advertises the parent's `extraFilters`.** They were
+  present in the generated body schema and in Swagger, but `buildLeftJoinClauses` never runs
+  the target's `extendedCondition` (its column references cannot be qualified with the
+  `LEFT JOIN` alias), so the filter applied nothing. They are now rejected with a `400` naming
+  the reason and pointing at `joinMustExist` on the same relation.
+
+### Fixed
+
+- **Join validation no longer depends on the main result set.** `joinMultiple` / `joinLeft` /
+  `joinGroup` skip their side query entirely when the main query matched no rows, so everything
+  validated inside it was skipped with it — the same request answered 400 or 200 depending on
+  the data. This covered filter keys and `readExclude` on join filters, an explicit `selection`
+  naming an unknown field, and `joinGroup` aggregation fields including `aggregations.by`. Join
+  filters are now validated up front, and the selection and aggregation lists are resolved
+  before the empty-result bail-out.
+
 ### Added
 
+- **`fields` allowlist on `buildRelation`** — restricts which of the target table's fields are
+  reachable through one relation, without hiding them from the table's own routes the way
+  `readExclude` would. The relation is declared against a schema narrowed to the list, so
+  `selection`, `filters`, `conditions`, `orderBy`, aggregations and the generated
+  request/response schemas all reject anything outside it with `400 Unknown field`; the default
+  `'*'` selection is spelled out into the allowed columns instead of emitting a real `SELECT *`;
+  and computed fields on the target resolve against the narrowed schema, so one reading an
+  excluded column is a 400 rather than a way around the list. Declaration-time checks: the list
+  must include the join field, and is rejected on `allowedWriteJoins` (write paths resolve
+  `upsertMap` by schema identity and must write every column the caller sent). Fail-closed by
+  design — see [ADR 0011](./docs/adr/0011-join-fields-allowlist.md) for allowlist vs blocklist.
+- **[ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md)** — a declared join is a read
+  grant: `onRequests` and `operations` are route-level and do not follow a join, so
+  `allowedReadJoins` grants read access to the target table under the *host* table's
+  authorization. Documents what does cross a join (`readExclude`, `tenantScope`, the relation's
+  schema), the trimmed-schema + explicit-`selection` pattern for column-level narrowing, and
+  the rejected alternatives (`canBeJoined` hook, `selection` as a ceiling).
+
 - **`excludeTables` config option** — blacklist for `sqlapi-generate-schema`. Tables
   listed in `excludeTables` in `sqlapi.config.ts` (exact names or `*` globs, e.g.
   `knex_*`) are skipped during schema generation; their previously generated schema files

package/README.md

@@ -266,6 +266,8 @@ const TableCustomer = defineTable({
     buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
     buildRelation(SchemaSession, 'userId', SchemaUser, 'id', { unique: true }),           // alias = 'user', N:1
     buildRelation(SchemaSession, 'updatedBy', SchemaUser, 'id', { alias: 'updater', unique: true }),
+    // `fields` restricts what this relation exposes of the target — read joins only
+    buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] }),
   ],
   allowedWriteJoins: [
     buildRelation(SchemaCustomer, 'id', SchemaOrder, 'customerId'),                       // alias = 'order'
@@ -423,6 +425,43 @@ are always available to your own code.
 **3. Multi-tenancy** — `getTenantId` + `tenantScope` filter every query by tenant (see
 [Multi-Tenant](#multi-tenant)).
 
+### A declared join is a read grant
+
+⚠️ **Neither of the first two layers follows a join.** `onRequests` and `operations` are
+properties of the routes generated *for* a table; a join is resolved inside the query of the
+**host** table's route, so the target's hooks never run and its `operations` whitelist does not
+apply. A table with `operations: []` — no HTTP routes at all — is still fully readable through
+any relation pointing at it.
+
+So `allowedReadJoins` is a security decision: declaring a relation grants read access to the
+target table under the **host** table's authorization.
+
+What does follow a join: `readExclude`, `tenantScope`, and the schema the relation was declared
+with. To expose a table broadly while keeping some columns narrow, give the relation a `fields`
+allowlist:
+
+```typescript
+allowedReadJoins: [
+  buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', {
+    unique: true,
+    fields: ['id', 'name'],   // everything else on `user` is unreachable here
+  }),
+],
+```
+
+Every read surface validates against it — `selection`, `filters`, `conditions`, `orderBy`,
+aggregations, and the generated request/response schemas — so `email` is `400 Unknown field`
+everywhere, not just missing from the projection. It is fail-closed: a column added to `user`
+later is not reachable through this relation until it is added to the list.
+
+`fields` restricts **reading** only, and only through that relation. It is not a replacement for
+`readExclude` (which hides a column from the table's own routes too) or for `onRequests` (which
+decides who may call them).
+
+Full rationale and the rejected alternatives in
+[ADR 0010](./docs/adr/0010-joins-do-not-run-route-guards.md) and
+[ADR 0011](./docs/adr/0011-join-fields-allowlist.md).
+
 ### Request limits
 
 Two hard caps bound how much work a single request can trigger (defense against accidental or
@@ -439,11 +478,14 @@ capped — they run your own trusted code.
 
 ### Write whitelist
 
-Insert/update/bulk-upsert bodies reject **unknown properties** (`additionalProperties: false`):
-only columns present in the generated Schema (as narrowed by `schemaOverrides` /
-`excludeFromCreation`) can be written. An unexpected field is a `400`, never a silently-written
-column — the Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`)
-to keep sensitive columns out of it.
+Insert/update/bulk-upsert bodies are `additionalProperties: false`: only columns present in the
+generated Schema (as narrowed by `schemaOverrides` / `excludeFromCreation`) can be written. The
+Schema is the write whitelist. Trim the generated Schema (or use `excludeFromCreation`) to keep
+sensitive columns out of it.
+
+An unexpected field is **stripped, not rejected**: Fastify runs Ajv with `removeAdditional: true`,
+so the request succeeds and the column is simply never written. Mass assignment is prevented
+either way, but do not expect a `400` to tell a client its extra field was ignored.
 
 ### Field-level update rules are product logic — use the hooks
 
@@ -543,12 +585,12 @@ Search with filters, advanced conditions, pagination, ordering, joins, and aggre
 }
 ```
 
-- **`filters`** — equality-based, flat key/value. Supports schema fields + `extraFilters`.
+- **`filters`** — equality-based, flat key/value. Supports schema fields, `extraFilters` and computed fields. A key that is none of those is a `400 Unknown filter field: <key>` — a mistyped filter must never come back as a wider result set. An explicit `null` filters by `IS NULL`; `undefined` means "not supplied" and is ignored.
 - **`conditions`** — array of `{ field, method, params }`. Methods: `isEqual`, `isNotEqual`, `isGreater`, `isGreaterOrEqual`, `isLess`, `isLessOrEqual`, `isLike`, `isILike`, `isIn`, `isNotIn`, `isBetween`, `isNotBetween`, `isNull`, `isNotNull`.
 - **`joinMustExist`** — EXISTS-based filter: "main rows where at least one related row matches". Accepts `{ filters, conditions }` (both optional). Aliases must come from `allowedReadJoins` declarations with `unique: false`.
 - **`joinMultiple`** — fetches related child rows in a side query. Accepts `{ filters, conditions, selection }`. Same `unique: false` aliases.
 - **`joinGroup`** — aggregations on the related table. Supports `sum`, `min`, `max`, `avg`, `count`, `distinctCount`, and optional `by` for GROUP BY (a schema field name or a computed-field name declared on the join table — e.g. for date bucketing declare a computed using `db.dateTrunc('month', qiCol('orderDate'))`). Accepts `{ filters, conditions }`. Same `unique: false` aliases.
-- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`.
+- **`joinLeft`** — embeds an N:1 parent. Real `LEFT JOIN` is added on demand (only when the request has `filters`/`conditions` on the parent or uses 2-parti `orderBy` on this alias). Aliases must be declared with `unique: true`. Accepts `{ filters, conditions, selection }`. Its `filters` accept schema and computed fields only: the parent's `extraFilters` need an alias-aware `extendedCondition`, so they are rejected with a `400` here instead of being silently ignored — use `joinMustExist` on the same relation when you need one.
 
 **Dot-notation in `orderBy` and `conditions`**:
 

package/dist/lib/agent/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAgCD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA2CrE"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../../src/lib/agent/manifest.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAOvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2FAA2F;IAC3F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,IAAI,EAAE,KAAK,GAAG,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,uFAAuF;IACvF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,oEAAoE;IACpE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;IAC5B,gFAAgF;IAChF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAgCD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,EAAE,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CA6CrE"}

package/dist/lib/agent/manifest.js

@@ -114,6 +114,8 @@ export function renderAgentManifestMd(manifest) {
         'serverGenerated fields: omit on insert (values from client are ignored).',
         'readJoins aliases: `1:N` → joinMustExist/joinMultiple/joinGroup; `N:1` → joinLeft.',
         'writeJoins aliases: keys for `secondaries`/`deletions` in writes.',
+        'filters: unknown keys are rejected (400), never ignored. extraFilters do not apply ' +
+            'under joinLeft — use joinMustExist on the same relation.',
         '',
     ];
     for (const t of Object.values(manifest.tables)) {

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":"AAOA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAcb,MAAM,mBAAmB,CAAC;AA8lC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CA4HvB"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../../src/lib/engine/search/search.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EAeb,MAAM,mBAAmB,CAAC;AAqoC3B,wBAAsB,YAAY,CAChC,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,YAAY,CAAC,CAqIvB"}

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

@@ -2,7 +2,7 @@ import { ConditionBuilder, Expression } from 'node-condition-builder';
 import { camelcaseObject } from '../../naming.js';
 import { QueryParams } from '../query-params.js';
 import { buildTenantCondition, buildTenantJoin } from '../../tenant.js';
-import { assertReadable, assertFiltersReadable, readableSelectColumns } from '../../read-access.js';
+import { assertReadable, assertFiltersReadable, assertKnownFilterKeys, readableSelectColumns, explicitSelectColumns, } from '../../read-access.js';
 import { primaryAsString } from '../../../types.js';
 // ─── Schema field validation ────────────────────────────────
 function validateSchemaField(field, schema, tableConf) {
@@ -87,6 +87,28 @@ function subqueryAlias(alias, tableConf) {
 function findJoinByAlias(tableConf, alias) {
     return tableConf.allowedReadJoins?.find((j) => j.alias === alias);
 }
+/**
+ * Validate the filter keys of every join reference in a request map.
+ *
+ * Runs up front, before any query: the executors skip their side-query entirely when the
+ * main result set is empty (`ids.length === 0`), so validating there alone would make the
+ * same request answer 400 or 200 depending on the data it happens to match.
+ *
+ * Unknown aliases are left to `requireJoin`, which reports them with its own message.
+ */
+function assertJoinFilterKeys(dbTables, tableConf, refs, allowExtraFilters) {
+    if (!refs)
+        return;
+    for (const [alias, ref] of Object.entries(refs)) {
+        const joinDef = findJoinByAlias(tableConf, alias);
+        if (!joinDef)
+            continue;
+        const joinTableConf = dbTables[joinDef.joinSchema.tableName];
+        const filters = ref?.filters;
+        assertFiltersReadable(filters, joinTableConf);
+        assertKnownFilterKeys(filters, joinDef.joinSchema, joinTableConf, allowExtraFilters);
+    }
+}
 function requireJoin(tableConf, alias, requireUnique) {
     const joinDef = findJoinByAlias(tableConf, alias);
     if (!joinDef) {
@@ -176,9 +198,15 @@ function mapRowsToCamelCase(rows, schema, computedFieldNames) {
  * Build the SELECT columns list for a join fetch: '*' or comma-separated quoted columns.
  * A default '*' selection narrows to the join table's readable columns when it declares
  * `readExclude`; an explicit selection naming an excluded field is rejected with 400.
+ *
+ * On a relation narrowed by a `fields` allowlist the '*' is always spelled out. Emitting a
+ * real `SELECT *` there would fetch the excluded columns and leave them to be dropped by
+ * the response serializer — which does not run for a caller of `sqlApi.search()`.
  */
-function buildSelectionColumns(selection, joinSchema, db, joinTableConf) {
+function buildSelectionColumns(selection, joinSchema, db, joinTableConf, restricted = false) {
     if (selection === '*') {
+        if (restricted)
+            return explicitSelectColumns(joinTableConf, joinSchema, db);
         return readableSelectColumns(joinTableConf, joinSchema, db) ?? '*';
     }
     const table = db.qi(joinSchema.tableName);
@@ -331,7 +359,9 @@ function buildLeftJoinClauses(db, dbTables, tableConf, aliasesNeedingJoin, joinL
             // (so SQL references the LEFT JOIN'd table, not a bare table name).
             // Note: extraFilters declared on joinTableConf are not supported here for
             // joinLeft (they would require alias-aware handlers); only schema fields
-            // and computed fields apply.
+            // and computed fields apply. `assertJoinFilterKeys` rejects them up front rather
+            // than letting them through as a silent no-op, and the generated body schema does
+            // not advertise them for unique:true relations.
             const cb = new ConditionBuilder('AND', db.cbDialect);
             const joinTableConf = dbTables[joinSchema.tableName];
             const computed = joinTableConf?.computedFields;
@@ -487,6 +517,11 @@ async function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMul
         const joinDef = requireJoin(tableConf, alias, false);
         const { joinSchema, joinField, mainField, selection: defaultSelection } = joinDef;
         const joinTableConf = dbTables[joinSchema.tableName];
+        // The selection is resolved before the empty-result bail-out: it is validated against
+        // the join schema, and that rejection must not depend on whether the main query
+        // matched rows.
+        const selection = ref?.selection ?? defaultSelection;
+        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf, joinDef.fields !== undefined);
         const ids = collectIds(mainResults, mainField);
         if (ids.length === 0) {
             result[alias] = [];
@@ -499,8 +534,6 @@ async function executeJoinMultiple(db, dbTables, tableConf, mainResults, joinMul
         appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
         const where = cb.build(1, db.ph);
         const values = cb.getValues();
-        const selection = ref?.selection ?? defaultSelection;
-        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf);
         const rows = await db.select({
             tableName: joinSchema.tableName,
             columns,
@@ -519,6 +552,10 @@ async function executeJoinLeft(db, dbTables, tableConf, mainResults, joinLeft, t
         const joinDef = requireJoin(tableConf, alias, true);
         const { joinSchema, joinField, mainField, selection: defaultSelection } = joinDef;
         const joinTableConf = dbTables[joinSchema.tableName];
+        // Resolved before the bail-out, for the same reason as joinMultiple: an invalid
+        // selection is a 400 whether or not the main query matched anything.
+        const selection = ref?.selection ?? defaultSelection;
+        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf, joinDef.fields !== undefined);
         // For joinLeft (N:1), mainField on main is the FK pointing to joinField (PK) on parent.
         // We collect the FK values from the main results and look up parents by their PK.
         const ids = collectIds(mainResults, mainField);
@@ -533,8 +570,6 @@ async function executeJoinLeft(db, dbTables, tableConf, mainResults, joinLeft, t
         appendJoinTenantScope(db, joinTableConf, tenant, joinSchema.tableName, cb, tenantJoins);
         const where = cb.build(1, db.ph);
         const values = cb.getValues();
-        const selection = ref?.selection ?? defaultSelection;
-        const columns = buildSelectionColumns(selection, joinSchema, db, joinTableConf);
         const rows = await db.select({
             tableName: joinSchema.tableName,
             columns,
@@ -577,10 +612,6 @@ async function executeJoinGroup(db, dbTables, tableConf, mainResults, joinGroup,
         const { joinSchema, joinField, mainField } = joinDef;
         const joinTableConf = dbTables[joinSchema.tableName];
         const ids = collectIds(mainResults, mainField);
-        if (ids.length === 0) {
-            result[alias] = {};
-            continue;
-        }
         const { aggregations, filters: groupFilters, conditions: groupConditions } = groupReq;
         const selectParts = [];
         const groupByParts = [];
@@ -604,7 +635,9 @@ async function executeJoinGroup(db, dbTables, tableConf, mainResults, joinGroup,
         addAgg('sum', aggregations.sum);
         addAgg('avg', aggregations.avg);
         addAgg('count', aggregations.count);
-        if (selectParts.length === 0) {
+        // Bail out only here: `by` and every aggregation field have now been validated against
+        // the join schema, so an unknown or unreachable field is a 400 regardless of the data.
+        if (selectParts.length === 0 || ids.length === 0) {
             result[alias] = {};
             continue;
         }
@@ -676,6 +709,8 @@ function dispatchConditionMethod(cb, method, colOrExpr, params) {
 }
 function buildJoinRefCondition(joinTableConf, joinSchema, ref, db, qualifier) {
     assertFiltersReadable(ref.filters, joinTableConf);
+    // Filter keys are checked by assertJoinFilterKeys, up front in searchEngine — this side
+    // query may never run, so it is not a place a request can be rejected from.
     // Bare table name for plain side-queries; the subquery alias when the condition lands
     // inside an aliased, correlated FROM (there the table name would resolve to the outer query).
     const colQualifier = qualifier ?? joinSchema.tableName;
@@ -690,7 +725,7 @@ function buildJoinRefCondition(joinTableConf, joinSchema, ref, db, qualifier) {
                 continue;
             if (!computed[name])
                 continue;
-            const expr = evaluateComputedField(name, computed[name], joinTableConf.Schema, db, colQualifier, '', true);
+            const expr = evaluateComputedField(name, computed[name], joinSchema, db, colQualifier, '', true);
             cb.isEqual(expr, value);
         }
     }
@@ -702,7 +737,7 @@ function buildJoinRefCondition(joinTableConf, joinSchema, ref, db, qualifier) {
             // Computed fields resolve to an Expression carrying their own bound values, which
             // the ConditionBuilder places together with the compared value.
             const operand = computed?.[c.field]
-                ? evaluateComputedField(c.field, computed[c.field], joinTableConf.Schema, db, colQualifier, '', true)
+                ? evaluateComputedField(c.field, computed[c.field], joinSchema, db, colQualifier, '', true)
                 : `${db.qi(colQualifier)}.${db.qi(validateSchemaField(c.field, joinSchema, joinTableConf))}`;
             dispatchConditionMethod(cb, c.method, operand, c.params ?? []);
         }
@@ -809,8 +844,16 @@ export async function searchEngine(dbTables, params) {
     if (joinLeft)
         for (const a of Object.keys(joinLeft))
             requireJoin(tableConf, a, true);
+    // Join filter keys, validated before any query so the outcome never depends on whether
+    // the main query returned rows. joinLeft is the odd one: its condition is built inline
+    // and never runs the target's extendedCondition, so extraFilters are not accepted there.
+    assertJoinFilterKeys(dbTables, tableConf, joinMustExist, true);
+    assertJoinFilterKeys(dbTables, tableConf, joinMultiple, true);
+    assertJoinFilterKeys(dbTables, tableConf, joinGroup, true);
+    assertJoinFilterKeys(dbTables, tableConf, joinLeft, false);
     // Build main condition
     assertFiltersReadable(filters, tableConf);
+    assertKnownFilterKeys(filters, tableConf.Schema, tableConf);
     const condition = tableConf.filters(filters || {}, db.cbDialect);
     // Filters and conditions targeting computed fields go on the same ConditionBuilder:
     // a computed resolves to an Expression carrying its own values, and the builder is

package/dist/lib/read-access.d.ts

@@ -17,6 +17,26 @@ export declare function assertReadable(tableConf: ITable | undefined, field: str
  * excluded pass through untouched (extraFilters and computed names included).
  */
 export declare function assertFiltersReadable(filters: Record<string, unknown> | undefined, tableConf: ITable | undefined): void;
+/**
+ * Throws 400 when a filter map carries a key the engine would never visit.
+ *
+ * Filters are matched against the schema fields, the table's `extraFilters` and its computed
+ * fields; anything else used to be dropped without a word, so a mistyped key returned MORE
+ * rows than the caller asked for and nothing said so. That is the dangerous direction to fail
+ * in — filters are also how consumers narrow visibility — and it contradicted every
+ * neighbouring path, where an unknown field in `selection`, `conditions`, `orderBy` or an
+ * aggregation is already a 400.
+ *
+ * `schema` is the schema the relation was declared with, which for a join may be a trimmed
+ * copy: a field outside it is unknown here exactly as it is for `selection`.
+ *
+ * `allowExtraFilters` is false on the joinLeft path, whose condition is built inline
+ * (`buildLeftJoinClauses`) and never runs the table's `extendedCondition`.
+ *
+ * Call AFTER `assertFiltersReadable`, so a read-excluded field keeps its own message
+ * instead of being reported as unknown.
+ */
+export declare function assertKnownFilterKeys(filters: Record<string, unknown> | undefined, schema: SchemaDefinition, tableConf: ITable | undefined, allowExtraFilters?: boolean): void;
 /** Schema field names that may be read, in schema declaration order. */
 export declare function readableFieldNames(tableConf: ITable | undefined, schema: SchemaDefinition): string[];
 /**
@@ -28,4 +48,9 @@ export declare function readableFieldNames(tableConf: ITable | undefined, schema
  * would be ambiguous.
  */
 export declare function readableSelectColumns(tableConf: ITable | undefined, schema: SchemaDefinition, db: QueryClient): string | undefined;
+/**
+ * The same list, always spelled out. Used where `*` is not an acceptable fallback: a
+ * relation narrowed by a `fields` allowlist must project the allowlist, not the table.
+ */
+export declare function explicitSelectColumns(tableConf: ITable | undefined, schema: SchemaDefinition, db: QueryClient): string;
 //# sourceMappingURL=read-access.d.ts.map

package/dist/lib/read-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"read-access.d.ts","sourceRoot":"","sources":["../../src/lib/read-access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG5D;;;;;;;;GAQG;AAEH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,IAAI,CAKN;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,GACvB,MAAM,EAAE,CAIV;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,WAAW,GACd,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"read-access.d.ts","sourceRoot":"","sources":["../../src/lib/read-access.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG5D;;;;;;;;GAQG;AAEH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,IAAI,CAKN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC5C,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,UAAO,GACvB,IAAI,CAkBN;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,GACvB,MAAM,EAAE,CAIV;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,WAAW,GACd,MAAM,GAAG,SAAS,CAGpB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,gBAAgB,EACxB,EAAE,EAAE,WAAW,GACd,MAAM,CAKR"}

package/dist/lib/read-access.js

@@ -28,6 +28,46 @@ export function assertFiltersReadable(filters, tableConf) {
         assertReadable(tableConf, key);
     }
 }
+/**
+ * Throws 400 when a filter map carries a key the engine would never visit.
+ *
+ * Filters are matched against the schema fields, the table's `extraFilters` and its computed
+ * fields; anything else used to be dropped without a word, so a mistyped key returned MORE
+ * rows than the caller asked for and nothing said so. That is the dangerous direction to fail
+ * in — filters are also how consumers narrow visibility — and it contradicted every
+ * neighbouring path, where an unknown field in `selection`, `conditions`, `orderBy` or an
+ * aggregation is already a 400.
+ *
+ * `schema` is the schema the relation was declared with, which for a join may be a trimmed
+ * copy: a field outside it is unknown here exactly as it is for `selection`.
+ *
+ * `allowExtraFilters` is false on the joinLeft path, whose condition is built inline
+ * (`buildLeftJoinClauses`) and never runs the table's `extendedCondition`.
+ *
+ * Call AFTER `assertFiltersReadable`, so a read-excluded field keeps its own message
+ * instead of being reported as unknown.
+ */
+export function assertKnownFilterKeys(filters, schema, tableConf, allowExtraFilters = true) {
+    if (!filters)
+        return;
+    for (const [key, value] of Object.entries(filters)) {
+        // `undefined` means "filter not supplied" everywhere else in the engine; an absent
+        // filter cannot be a wrong one. `null` does filter (IS NULL) and is validated.
+        if (value === undefined)
+            continue;
+        if (key in schema.fields)
+            continue;
+        if (tableConf?.computedFields?.[key])
+            continue;
+        if (tableConf?.extraFilters && key in tableConf.extraFilters) {
+            if (allowExtraFilters)
+                continue;
+            throw httpError(400, `Filter '${key}' is an extraFilter: extraFilters are not applied on joinLeft ` +
+                `(only schema fields and computed fields are). Use joinMustExist on the same relation.`);
+        }
+        throw httpError(400, `Unknown filter field: ${key}`);
+    }
+}
 /** Schema field names that may be read, in schema declaration order. */
 export function readableFieldNames(tableConf, schema) {
     const fields = Object.keys(schema.fields);
@@ -46,6 +86,13 @@ export function readableFieldNames(tableConf, schema) {
 export function readableSelectColumns(tableConf, schema, db) {
     if (!tableConf?.readExclude?.length)
         return undefined;
+    return explicitSelectColumns(tableConf, schema, db);
+}
+/**
+ * The same list, always spelled out. Used where `*` is not an acceptable fallback: a
+ * relation narrowed by a `fields` allowlist must project the allowlist, not the table.
+ */
+export function explicitSelectColumns(tableConf, schema, db) {
     const table = db.qi(schema.tableName);
     return readableFieldNames(tableConf, schema)
         .map((f) => `${table}.${db.qi(schema.col(f))}`)

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

@@ -1 +1 @@
-{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAIrE,OAAO,KAAK,EAAE,QAAQ,EAA4B,MAAM,gBAAgB,CAAC;AAyBzE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAuHlF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,GAAE,MAAmC,GAAG,OAAO,CAe9F;AAED,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,kDAAqB,CAAC;AAEzD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAsElF"}
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/lib/schema/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,OAAO,EAAgB,MAAM,mBAAmB,CAAC;AAIrE,OAAO,KAAK,EAAE,QAAQ,EAA4B,MAAM,gBAAgB,CAAC;AAsCzE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CA+HlF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,GAAE,MAAmC,GAAG,OAAO,CAe9F;AAED,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,kDAAqB,CAAC;AAEzD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAsElF"}

package/dist/lib/schema/search.js

@@ -12,6 +12,18 @@ function readableFields(schema, tableConf) {
     }
     return out;
 }
+/**
+ * A `filters` map.
+ *
+ * Deliberately NOT `additionalProperties: false`, unlike the write bodies. Fastify runs Ajv
+ * with `removeAdditional: true`, so a closed schema would silently *strip* an unknown filter
+ * key before the handler ever sees it — reproducing the very bug it looks like it fixes, and
+ * leaving the engine's rejection unreachable over HTTP. Unknown keys are rejected by
+ * `assertKnownFilterKeys` in the engine instead, which also covers `sqlApi.search()`.
+ */
+function filtersObject(fields) {
+    return Type.Partial(Type.Object(fields));
+}
 const JoinGroupResultItem = Type.Object({
     sum: Type.Optional(Type.Record(Type.String(), Type.Any())),
     min: Type.Optional(Type.Record(Type.String(), Type.Any())),
@@ -54,7 +66,7 @@ export function SearchTableBodyPost(dbTables, tableName) {
         ...tableConf.extraFilters,
         ...computedTypes,
     };
-    const filtersSchema = Type.Optional(Type.Partial(Type.Object(filterFields)));
+    const filtersSchema = Type.Optional(filtersObject(filterFields));
     // Per-alias entries split by unique flag:
     //  - unique:false → joinMustExist / joinMultiple / joinGroup
     //  - unique:true  → joinLeft
@@ -82,23 +94,31 @@ export function SearchTableBodyPost(dbTables, tableName) {
                     }
                 }
             }
-            const joinFilterFields = joinTableConf
-                ? { ...readableFields(joinSchema, joinTableConf), ...joinTableConf.extraFilters, ...joinComputedTypes }
+            const joinSchemaFields = joinTableConf
+                ? { ...readableFields(joinSchema, joinTableConf), ...joinComputedTypes }
                 : { ...joinSchema.fields };
+            // `extraFilters` are only honoured where the engine delegates to the join table's
+            // own `filters()` — buildJoinRefCondition, i.e. the unique:false paths. joinLeft
+            // builds its condition inline (buildLeftJoinClauses) and handles schema and computed
+            // fields only, so advertising extraFilters there would promise a silent no-op.
+            const joinFilterFields = { ...joinSchemaFields, ...(joinTableConf?.extraFilters ?? {}) };
             const joinRefShape = {
-                filters: Type.Optional(Type.Partial(Type.Object(joinFilterFields))),
+                filters: Type.Optional(filtersObject(joinFilterFields)),
                 conditions: Type.Optional(Type.Array(conditionItemSchema)),
             };
-            const joinFetchShape = {
-                ...joinRefShape,
-                selection: Type.Optional(Type.String()),
-            };
             if (unique) {
-                joinLeftProps[alias] = Type.Object(joinFetchShape);
+                joinLeftProps[alias] = Type.Object({
+                    filters: Type.Optional(filtersObject(joinSchemaFields)),
+                    conditions: Type.Optional(Type.Array(conditionItemSchema)),
+                    selection: Type.Optional(Type.String()),
+                });
             }
             else {
                 joinMustExistProps[alias] = Type.Object(joinRefShape);
-                joinMultipleProps[alias] = Type.Object(joinFetchShape);
+                joinMultipleProps[alias] = Type.Object({
+                    ...joinRefShape,
+                    selection: Type.Optional(Type.String()),
+                });
                 joinGroupProps[alias] = Type.Object({
                     aggregations: Type.Object({
                         by: Type.Optional(Type.String()),
@@ -109,7 +129,7 @@ export function SearchTableBodyPost(dbTables, tableName) {
                         avg: Type.Optional(Type.Array(Type.String())),
                         count: Type.Optional(Type.Array(Type.String())),
                     }),
-                    filters: Type.Optional(Type.Partial(Type.Object(joinFilterFields))),
+                    filters: Type.Optional(filtersObject(joinFilterFields)),
                     conditions: Type.Optional(Type.Array(conditionItemSchema)),
                 });
             }

package/dist/lib/table-helpers.d.ts

@@ -1,5 +1,5 @@
 import { ConditionBuilder, type ConditionValueOrUndefined } from 'node-condition-builder';
-import type { TSchema, TObject } from '@sinclair/typebox';
+import { type TSchema, type TObject } from '@sinclair/typebox';
 import type { SchemaDefinition, JoinDefinition, TableFilterFn, ITable } from '../types.js';
 type ExtraProps<EF> = EF extends TObject<infer P> ? P : EF extends Record<string, TSchema> ? EF : Record<string, never>;
 export declare function exportTableInfo<F extends Record<string, TSchema>, EF extends TObject | Record<string, TSchema> = Record<never, TSchema>>(Schema: SchemaDefinition<F>, extraFilters?: EF, extendedCondition?: (condition: ConditionBuilder, filters: {
@@ -14,6 +14,21 @@ export interface BuildRelationOptions {
     alias?: string;
     selection?: string;
     unique?: boolean;
+    /**
+     * Allowlist of the target table's fields reachable through this relation.
+     *
+     * The relation is declared against a schema narrowed to these fields, so every read
+     * surface — `selection`, `filters`, `conditions`, `orderBy`, aggregations, and the
+     * generated request/response schemas — rejects anything outside the list with
+     * `400 Unknown field`. Use it to expose a table broadly while keeping some of its
+     * columns out of one relation, without hiding them from the table's own routes the way
+     * `readExclude` would.
+     *
+     * Fail-closed: a column added to the table later is not reachable through the relation
+     * until it is added here. Must include the join field, and is not allowed on a write
+     * join.
+     */
+    fields?: string[];
 }
 export declare function buildRelation<M extends Record<string, TSchema>, J extends Record<string, TSchema>>(mainSchema: SchemaDefinition<M>, mainField: string & keyof M | (string & keyof M)[], joinSchema: SchemaDefinition<J>, joinField: string & keyof J, options?: BuildRelationOptions): JoinDefinition;
 export declare function buildUpsertRule<F extends Record<string, TSchema>>(schema: SchemaDefinition<F>, columns: (string & keyof F)[]): [SchemaDefinition, string[]];

package/dist/lib/table-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EACP,MAAM,aAAa,CAAC;AAarB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAMX;AAkED,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAShB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}
+{"version":3,"file":"table-helpers.d.ts","sourceRoot":"","sources":["../../src/lib/table-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,yBAAyB,EAAiC,MAAM,wBAAwB,CAAC;AACzH,OAAO,EAAQ,KAAK,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,MAAM,EACP,MAAM,aAAa,CAAC;AAarB,KAAK,UAAU,CAAC,EAAE,IAAI,EAAE,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAExH,wBAAgB,eAAe,CAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,EAAE,SAAS,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,EAErE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,YAAY,GAAE,EAAa,EAC3B,iBAAiB,CAAC,EAAE,CAClB,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yBAAyB;CAAE,KAC3E,IAAI,GACR;IAAE,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAAC,OAAO,EAAE,aAAa,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAsChG;AAED,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAChB,MAAM,CAAC,CAAC,CAAC,CAOX;AAqFD,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAgDD,wBAAgB,aAAa,CAC3B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAEjC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,EAClD,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,cAAc,CAWhB;AAED,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/D,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC3B,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,EAAE,GAC5B,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAE9B;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,KAAK,EAAE,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,EAAE,GACvC,GAAG,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC,CAEjC"}

package/dist/lib/table-helpers.js

@@ -1,4 +1,5 @@
 import { ConditionBuilder } from 'node-condition-builder';
+import { Type } from '@sinclair/typebox';
 import { getDialect } from './dialect.js';
 // Quote an identifier using the given ConditionBuilder dialect (or the global
 // default when not provided). Needed so that DB columns with uppercase letters
@@ -46,10 +47,27 @@ export function exportTableInfo(Schema, extraFilters = {}, extendedCondition) {
 export function defineTable(config) {
     validateAliasUniqueness(config.allowedReadJoins, 'allowedReadJoins');
     validateAliasUniqueness(config.allowedWriteJoins, 'allowedWriteJoins');
+    validateWriteJoinsUnrestricted(config.allowedWriteJoins);
     validateComputedFields(config);
     validateReadExclude(config);
     return config;
 }
+/**
+ * `fields` narrows a relation for reading; it has no meaning on a write join and would be
+ * actively harmful there. Write paths resolve the secondary's upsert rule by looking the
+ * schema object up in `upsertMap` **by identity**, and a narrowed relation carries a copy —
+ * the lookup would miss and the upsert would silently degrade to a plain insert. The
+ * narrowed schema would also drop columns the caller legitimately sends.
+ */
+function validateWriteJoinsUnrestricted(joins) {
+    for (const join of joins ?? []) {
+        if (join.fields) {
+            throw new Error(`defineTable: relation '${join.alias}' in allowedWriteJoins declares 'fields'. ` +
+                `The fields allowlist restricts reading only — remove it, and use a separate ` +
+                `buildRelation for the read side if that relation is also in allowedReadJoins.`);
+        }
+    }
+}
 function validateReadExclude(config) {
     const excluded = config.readExclude;
     if (!excluded?.length)
@@ -97,14 +115,50 @@ function validateAliasUniqueness(joins, label) {
         seen.add(j.alias);
     }
 }
+/**
+ * Copy of `schema` exposing only `fields`, in schema declaration order.
+ *
+ * `tableName`, `col` and `colMap` are carried over untouched: the engine resolves the
+ * target's configuration through `dbTables[joinSchema.tableName]`, so a narrowed relation
+ * must still answer to its real table name, and column mapping must keep working for the
+ * fields that survive.
+ */
+function narrowSchemaToFields(schema, fields, joinField) {
+    const declared = Object.keys(schema.fields);
+    for (const field of fields) {
+        if (!declared.includes(field)) {
+            throw new Error(`buildRelation: 'fields' entry '${field}' is not a field of schema ` +
+                `'${schema.tableName}'. Available: ${declared.join(', ')}.`);
+        }
+    }
+    // The join field is what ties the fetched rows back to the main result set. Dropping it
+    // from the projection would hand the caller rows it cannot match to anything.
+    if (!fields.includes(joinField)) {
+        throw new Error(`buildRelation: 'fields' must include the join field '${joinField}' on ` +
+            `'${schema.tableName}' — it is what correlates the joined rows with the main ones.`);
+    }
+    const picked = {};
+    for (const field of declared) {
+        if (fields.includes(field))
+            picked[field] = schema.fields[field];
+    }
+    return {
+        ...schema,
+        fields: picked,
+        validation: Type.Object(picked),
+        partialValidation: Type.Partial(Type.Object(picked)),
+    };
+}
 export function buildRelation(mainSchema, mainField, joinSchema, joinField, options) {
+    const fields = options?.fields;
     return {
-        joinSchema,
+        joinSchema: fields ? narrowSchemaToFields(joinSchema, fields, joinField) : joinSchema,
         joinField,
         mainField,
         alias: options?.alias ?? joinSchema.tableName,
         selection: options?.selection ?? '*',
         unique: options?.unique ?? false,
+        ...(fields ? { fields: [...fields] } : {}),
     };
 }
 export function buildUpsertRule(schema, columns) {

package/dist/types/join.d.ts

@@ -8,6 +8,15 @@ export interface JoinDefinition {
     alias: string;
     selection: string;
     unique: boolean;
+    /**
+     * Allowlist of the target table's fields reachable through this relation, when
+     * `buildRelation` was given one. `joinSchema` is already narrowed to it — this is kept
+     * so the engine can tell a restricted relation from a full one, which is what stops the
+     * default `'*'` selection from falling back to a real `SELECT *`.
+     *
+     * Read joins only: a write join declaring it is rejected by `defineTable`.
+     */
+    fields?: string[];
 }
 export interface AggregationRequest {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"join.d.ts","sourceRoot":"","sources":["../../src/types/join.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,gBAAgB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,UAAU,CAAC,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,kEAAkE;AAClE,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB"}

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

@@ -0,0 +1,100 @@
+# 0010. A declared join is a read grant — joins do not run the target table's route guards
+
+- **Status**: accepted
+- **Date**: 2026-07-30
+
+## Context
+
+`onRequests` and `operations` are configured per table, which reads as "this table's
+protection". They are not. Both are properties of the *routes generated for* a table:
+`mergeOnRequests` composes the global and per-table hooks into `fastify.route({ onRequest })`,
+and `operations` decides which routes get registered at all.
+
+A join is resolved inside the query of the **host** table's route. `searchEngine` validates a
+join alias against the host's `allowedReadJoins` and nothing else — it never looks up the
+target's `operations`, and no Fastify hook fires mid-query. So:
+
+```typescript
+// agent: readable by every employee
+allowedReadJoins: [buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true })],
+
+// user: admins only... except through the join above
+const TableUser = defineTable({
+  ...exportTableInfo(SchemaUser),
+  onRequests: [requireAdmin],
+  operations: [],          // no HTTP routes at all
+});
+```
+
+`POST /search/agent` with `joinLeft: { user: { selection: 'id,email' } }` returns the emails.
+`requireAdmin` never ran, and `operations: []` did not matter: the caller was authorized as a
+reader of `agent`, and the join is part of what `agent` exposes.
+
+Reviewers reach this and read it as a hole to plug. It is a boundary, and the boundary needs
+to be stated rather than discovered.
+
+## Decision
+
+**Declaring a relation in `allowedReadJoins` grants read access to the target table, under
+the authorization of the host table.** The target's own route guards do not apply and are not
+made to apply.
+
+Route-level controls (`onRequests`, `operations`) do not follow joins. Configuration-level
+controls do, and are the ones to use on a join target:
+
+| Control | Follows a join | Granularity |
+|---|---|---|
+| `onRequests` | no | per route |
+| `operations` | no | per route |
+| `readExclude` | yes | per table, static |
+| the relation's `Schema` + `selection` | yes | per relation, static |
+| `tenantScope` + `getTenantId` | yes | per request |
+
+To expose a table broadly while keeping some of its columns narrow, declare the relation
+against a **trimmed copy of the Schema** and give it an explicit `selection`:
+
+```typescript
+const SchemaUserPublic = { ...SchemaUser, fields: { id: SchemaUser.fields.id, name: SchemaUser.fields.name } };
+
+buildRelation(SchemaAgent, 'userId', SchemaUserPublic, 'id', { unique: true, selection: 'id, name' })
+```
+
+Every read surface validates against the schema the relation was declared with — `selection`,
+`filters`, `conditions`, `orderBy`, aggregations — so a field outside it is `400 Unknown
+field`, not a hidden column. The explicit `selection` is not redundant: a relation left at the
+default `'*'` emits a literal `SELECT *` when the target declares no `readExclude`, and the
+extra columns are dropped only by the response serializer — they are still present on the
+programmatic `sqlApi.search()` path.
+
+## Alternatives considered
+
+- **Run the target's `onRequests` when it is joined** — rejected: a Fastify request hook may
+  reply and terminate; there is no coherent meaning for that halfway through building one
+  table's query. It would also fire N times per request with no request lifecycle to attach to.
+- **`canBeJoined?: (request) => Promise<boolean>` on `ITable`** — rejected: wrong granularity.
+  The real cases are "join yes, this column no", which a boolean cannot express, and the
+  refusal has no good answer (a `400` leaks the relation's existence; omitting the join
+  silently is indistinguishable from "no related rows"). It also adds a per-join await and
+  cannot be enforced for programmatic callers.
+- **Make the relation's `selection` a ceiling instead of a default** — rejected: breaking, and
+  it does not solve the case it looks like it solves. A ceiling is still static, and it caps
+  only the projection: the excluded field stays filterable through `conditions`, which is the
+  bisection leak `readExclude` exists to prevent. Trimming the schema closes every surface at
+  once.
+- **Refusing to register a table that is a join target of a less-protected table** — rejected:
+  the plugin has no way to compare two `onRequests` arrays for strictness, and ADR 0002 says
+  auth is the consumer's to model.
+
+## Consequences
+
+- `allowedReadJoins` must be read as a security decision, not just an ergonomics one. Adding a
+  relation widens the reachable data set for everyone authorized on the host table.
+- Column-level protection that depends on the caller's role has no mechanism today.
+  `readExclude` is per table and static; the trimmed schema is per relation and static. The
+  known gap is a request-resolved `readExclude`, which would work without new plumbing at the
+  join sites — every path already resolves it through `dbTables[joinSchema.tableName]` — but
+  requires the generated response and filter schemas to stay the widest set and the runtime to
+  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.

package/docs/adr/0011-join-fields-allowlist.md

@@ -0,0 +1,95 @@
+# 0011. Per-relation field restriction is an allowlist, not a blocklist
+
+- **Status**: accepted
+- **Date**: 2026-07-31
+
+## Context
+
+[ADR 0010](./0010-joins-do-not-run-route-guards.md) establishes that a declared join is a read
+grant, and that the only thing narrowing what a relation exposes is the schema it was declared
+with. The pattern it documented was to hand-write a trimmed copy:
+
+```typescript
+const SchemaUserPublic = { ...SchemaUser, fields: { id: SchemaUser.fields.id, name: SchemaUser.fields.name } };
+```
+
+That works, but the copy is derived state with nothing keeping it in sync. Schemas are
+regenerated from the database as disposable mirrors (ADR 0007), so the copy silently drifts:
+adding a column to `user` leaves `SchemaUserPublic` correct, dropping or renaming one leaves it
+referencing a field that no longer exists, and neither shows up until a request fails.
+
+The restriction belongs in the relation, where someone reading the table configuration is
+already looking. The open question was its polarity.
+
+## Decision
+
+`buildRelation` takes `fields: string[]` — an **allowlist** of the target's fields reachable
+through that relation. The relation is declared against a schema narrowed to that list, so every
+existing check (`field in schema.fields`) enforces it without a parallel code path: `selection`,
+`filters`, `conditions`, `orderBy`, aggregations, `aggregations.by`, and the generated request
+and response schemas.
+
+```typescript
+buildRelation(SchemaAgent, 'userId', SchemaUser, 'id', { unique: true, fields: ['id', 'name'] })
+```
+
+Allowlist, not a `excludeFields` blocklist, because the failure modes are not symmetric. A
+column added to the table later is not reachable through the relation until someone adds it —
+the new column is invisible by default, and the cost of forgetting is a `400`. Under a blocklist
+the same event silently widens every relation that did not anticipate it, and the cost of
+forgetting is disclosure. On a join — a grant handed out under *another* table's authorization —
+fail-closed is the only defensible default. It also reads the same way as `selection`, which is
+already an allowlist.
+
+Three rules follow from making it real rather than cosmetic:
+
+- **It must include the join field.** That column is what correlates the fetched rows with the
+  main ones; omitting it hands the caller rows it cannot match to anything. Rejected at
+  declaration, like `readExclude` refusing to hide a primary key.
+- **It is rejected on `allowedWriteJoins`.** Write paths resolve a secondary's upsert rule by
+  looking its schema up in `upsertMap` **by identity**; a narrowed relation carries a copy, so
+  the lookup would miss and the upsert would quietly degrade to a plain insert. The narrowed
+  schema would also drop columns the caller legitimately sent.
+- **Computed fields on the target resolve against the narrowed schema.** A computed field reads
+  whatever columns it likes; resolving it against the full table schema would leave a documented
+  way around the allowlist (`salaryBand` returning what `salary` says). One that stays inside the
+  list keeps working; one that reaches outside is a `400`.
+
+The default `selection: '*'` is spelled out into the allowed columns on a restricted relation.
+It used to emit a real `SELECT *`, with the extra columns removed only by the response
+serializer — which does not run for a caller of `sqlApi.search()`. An allowlist that leaks on its
+default is not an allowlist.
+
+## Alternatives considered
+
+- **`excludeFields: string[]` (blocklist)** — rejected on the fail-open argument above. It is
+  shorter to write when hiding one column out of twenty, and it would have read like
+  `readExclude`; neither outweighs a new column defaulting to exposed.
+- **`lockSelection: true`, making the declared `selection` a ceiling** — rejected: it caps the
+  projection only. The excluded column stays reachable from `filters`, `conditions` and
+  `orderBy`, which is the bisection leak `readExclude` exists to prevent — a guard that hides a
+  value from the output while leaving it interrogable is worse than none, because it reads as
+  protection.
+- **Making the relation's `selection` a ceiling instead of adding a field** — rejected in
+  ADR 0010: breaking, and still static.
+- **Threading the allowlist through every validation site instead of narrowing the schema** —
+  rejected: it would leave each new read surface to remember the check. Narrowing the schema is
+  closed by construction, which is the property that made the hand-written trimmed copy work in
+  the first place.
+- **Keeping the hand-written trimmed copy as the documented pattern** — rejected: it duplicates
+  regenerated state. It still works, and is the way out if a relation needs a shape `fields`
+  cannot express.
+
+## Consequences
+
+- `fields` restricts **reading** only. It is not a substitute for `readExclude`, which hides a
+  column from the owning table's own routes too, nor for `onRequests`, which is what decides who
+  may call them.
+- It is static, like everything else that crosses a join. Role-dependent column visibility —
+  admins seeing `email`, nobody else — still has no mechanism; the candidate remains a
+  request-resolved `readExclude`, unaffected by this ADR.
+- A relation and its write counterpart can no longer be the same `buildRelation` call when the
+  read side is restricted. Declaring two is the intended answer, not a workaround.
+- The generated agent manifest still describes join targets by table name only, so an LLM client
+  reading it may ask for a field the relation does not expose and get a `400`. Listing a
+  restricted relation's fields in the manifest is a follow-up.

package/docs/adr/README.md

@@ -24,6 +24,8 @@ not by editing history.
 | [0007](./0007-explicit-table-generation.md) | Table generation is explicit — `--all` is a migration helper, not the default |
 | [0008](./0008-agent-client-interface.md) | Agent client interface: static grammar + runtime manifest |
 | [0009](./0009-schema-exclusion-config-blacklist.md) | Schema exclusion is a config blacklist — excluded schemas are removed as orphans |
+| [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 |
 
 ## When to write one
 

package/package.json

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