fastify-auto-sqlapi 0.1.11 → 0.1.12

package/CHANGELOG.md

@@ -7,6 +7,33 @@ All notable changes to this project are documented here. This project follows
 
 Migration instructions for breaking changes live in **[BREAKING_CHANGES.md](./BREAKING_CHANGES.md)**.
 
+## [0.1.12]
+
+### Fixed
+
+- **Security: `aggregations.by` bypassed `readExclude`.** Every other reference to a
+  read-excluded field (filters, conditions, orderBy, aggregation fields, join selections)
+  is rejected with 400, but the `joinGroup` GROUP BY field was resolved without the check —
+  `aggregations: { by: '<excludedField>', count: [...] }` returned the hidden field's
+  distinct values verbatim in `rows[].by`. The field now goes through the same
+  `validateSchemaField` guard as aggregation fields (400).
+- **Security: HAVING-style conditions and 3-part aggregation `orderBy` could probe
+  read-excluded fields.** `buildAggOrderExpr` validated the aggregation field without the
+  join table's config, skipping the `readExclude` check. The downstream validation in the
+  joinGroup execution masked it — except when the main result set was empty, where that
+  validation is skipped entirely: a condition like `player.sum.<hiddenField> > X` answered
+  400 when at least one row matched and 200 when none did, a binary oracle allowing
+  bisection of the hidden field's aggregates. The check now fires at condition-build time.
+  Found by a full audit of every field-referencing input against `readExclude` (all other
+  paths verified guarded: filters, conditions, orderBy 1/2-part, selections, aggregation
+  fields, compute*, GET).
+
+### Added
+
+- ADR 0008: agent client interface — static grammar (`AGENTS_FRONTEND.md`, same filename by
+  design) + runtime manifest split, density as a feature, loose validation with the
+  structured 400 as the default tool strategy.
+
 ## [0.1.11]
 
 ### Breaking

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;AAwlC3B,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":"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"}

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

@@ -219,7 +219,10 @@ function buildAggOrderExpr(db, dbTables, tableConf, alias, fn, field, joinGroup)
     if (groupReq.aggregations.by && groupReq.aggregations.by !== joinField) {
         err400(`Cannot order by aggregation on joinGroup with 'by' clause on non-FK column: ${alias} (grouped by '${groupReq.aggregations.by}', correlation FK is '${joinField}')`);
     }
-    const fieldCol = validateSchemaField(field, joinSchema);
+    // Pass the join table's conf: without it validateSchemaField skips the readExclude
+    // check, and a HAVING-style condition on a hidden field becomes a 400-vs-200 oracle
+    // (executeJoinGroup's own validation is skipped when the main result set is empty).
+    const fieldCol = validateSchemaField(field, joinSchema, dbTables[joinSchema.tableName]);
     const refs = extractJoinRefs(db, tableConf, joinDef);
     // The subquery FROM is aliased so the correlation to the outer table survives a
     // self-referencing relation; everything inside references the alias.
@@ -555,7 +558,10 @@ function buildByExpression(by, joinSchema, joinTableConf, db) {
         err400(`Invalid 'by' specification: expected a field or computed name`);
     }
     if (by in joinSchema.fields) {
-        return `${db.qi(joinSchema.tableName)}.${db.qi(joinSchema.col(by))}`;
+        // validateSchemaField also enforces readExclude: GROUP BY on a hidden field
+        // would return its distinct values verbatim in `rows[].by`.
+        const col = validateSchemaField(by, joinSchema, joinTableConf);
+        return `${db.qi(joinSchema.tableName)}.${db.qi(col)}`;
     }
     const fn = joinTableConf?.computedFields?.[by];
     if (fn) {

package/docs/adr/0008-agent-client-interface.md

@@ -0,0 +1,66 @@
+# 0008. Agent client interface: static grammar + runtime manifest
+
+- **Status**: accepted
+- **Date**: 2026-07-26
+
+## Context
+
+The plugin doubles as the enforcement layer for LLM clients that drive the API at runtime
+(a chat agent operating on backoffice data: whatever requests the model invents, tenant
+scoping, `readExclude`, `operations` and caps still apply). Such a client needs to be
+told how to call the API — but an LLM prompt has different constraints than human
+documentation: every line costs tokens on every call, and anything deployment-specific
+goes stale the moment the schema changes.
+
+## Decision
+
+The client-facing documentation is split into two halves with different lifecycles:
+
+- **Grammar** — `AGENTS_FRONTEND.md`: HOW to call the API (endpoints, search with the four
+  join families, condition methods with params arity, ordering notations, pagination,
+  writes, error shapes). Static, identical for every deployment, ~110 dense lines designed
+  for a system prompt. It deliberately contains **no tables, fields or aliases**.
+- **Vocabulary** — the manifest (`agentManifest: true` → `GET {prefix}/agent/manifest(.md)`,
+  or `buildAgentManifest()` programmatically): WHAT this deployment exposes — tables,
+  fields with type/required/nullable, enabled operations, join aliases with direction,
+  computed fields. Generated from `DbTables` at startup, so it can never drift from the
+  running configuration.
+
+Three deliberate properties:
+
+1. **The grammar file replaced the old tutorial-style `AGENTS_FRONTEND.md` under the same
+   filename.** The path `node_modules/fastify-auto-sqlapi/AGENTS_FRONTEND.md` is known to
+   consumers' coding agents; a new filename would have broken every existing reference for
+   zero benefit. Do not rename it.
+2. **Density is a feature, not a documentation gap.** The file lives in LLM system
+   prompts: jsonc examples with terse end-of-line comments, no rationale, no repetition —
+   each concept appears exactly once. Normative rules (what returns 400) belong in it;
+   explanations do not. Expanding it with prose and tutorials would revert this decision.
+3. **Loose validation with the structured 400 as retry signal is the default strategy**
+   for LLM tools; strict per-table JSON-Schema tools are opt-in via `agentToolSchemas()`.
+   The plugin's 400 (`fields: [{path, code, message}]`) was designed machine-readable, so
+   a loose generic tool self-corrects in one round trip. This is also why the plugin does
+   not ship an opinionated MCP/tool layer: it provides the pieces (grammar, manifest,
+   schemas), the consumer composes them.
+
+## Alternatives considered
+
+- **One complete document (grammar + tables of a given deployment)** — rejected: the
+  deployment-specific half goes stale on every schema change; the manifest endpoint is
+  the only source that cannot drift.
+- **A new `AGENT_CLIENT.md` alongside the old `AGENTS_FRONTEND.md`** — rejected: near-total
+  content overlap, proven drift risk (a fix had to be applied to both files during the
+  same session that created the second one), and known-path breakage on removal.
+- **Strict JSON-Schema tools as the default** — rejected: the full search schema per
+  table is enormous (conditions, four join families, per-alias shapes); across N tables
+  it explodes prompt size and degrades model performance. Kept as opt-in for hot tables.
+
+## Consequences
+
+- `AGENTS_FRONTEND.md` serves both coding agents (writing client code) and runtime LLM
+  clients; the verbose tutorial content it replaced is covered by the grammar plus
+  Swagger.
+- Contributions that add tables/fields/examples-with-prose to the grammar file, or rename
+  it, should be declined with a pointer to this ADR.
+- New request-shape features must update the grammar (a rule line, not a tutorial) and,
+  when they touch per-table capabilities, the manifest builder.

package/docs/adr/README.md

@@ -22,6 +22,7 @@ not by editing history.
 | [0005](./0005-insert-pipeline-sanitize-before-hooks.md) | Insert pipeline: client payload sanitized before `beforeInsert` |
 | [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 |
 
 ## When to write one
 

package/package.json

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