fastify-auto-sqlapi 0.1.12 → 0.1.14

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

@@ -23,6 +23,9 @@ not by editing history.
 | [0006](./0006-raw-db-errors.md) | Raw DB errors surface as 500 — no SQLSTATE→HTTP mapping |
 | [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.12",
+  "version": "0.1.14",
   "description": "Fastify plugin for automatic CRUD API generation from PostgreSQL, MySQL and MariaDB tables",
   "type": "module",
   "main": "./dist/index.js",