From b5cdf3d48fac4a9cb3e7dd2f6161375a153b2e48 Mon Sep 17 00:00:00 2001 From: Maurice Date: Tue, 17 Nov 2026 21:44:32 +0100 Subject: [PATCH] fix(db): refuse raw SQL everywhere under src/, not only in the repositories The ESLint walls against raw(), the sql tag and SQL text handed to execute/run/all/get applied to src/db/repositories and src/db/seeders only. A service, job, guard or MCP tool could send its own SQLite-only SQL through em.getConnection().execute(...), which the Postgres probe never runs, since it only calls the repositories. The walls now cover all of src/. The dialect layer, the engines and the migrations stay the homes of raw SQL, and the four boot-time lifecycle files that hold SQL text today are named and pinned to their count. --- server/CLAUDE.md | 4 +- server/eslint.config.mjs | 110 +++++++++++++----- .../restricted-syntax-selectors.test.ts | 75 +++++++++++- 3 files changed, 158 insertions(+), 31 deletions(-) diff --git a/server/CLAUDE.md b/server/CLAUDE.md index 5ef1c30a6..36d3cd8cf 100644 --- a/server/CLAUDE.md +++ b/server/CLAUDE.md @@ -88,7 +88,7 @@ Nest owns everything. Every domain is a DI module under `src/nest//` (`c - **Thin controller → injectable provider.** Never resurrect a plain function-module service; don't grow god services — split a domain into several modules when it outgrows one class (trips and auth already are). - **Inject, don't reach for module globals.** No imports of the global `db` proxy from `nest/` layers at all any more — the last production importer converted onto a repository, and the export now survives only so ~190 test files' `vi.mock('…/db/database', …)` factories keep typechecking; no new code depending on the `ws` singleton or event-sink globals. There is no `DatabaseService` to inject either — take the repository(ies) you need plus `UnitOfWork` for transactions. Modules must be importable without side effects. -- **Transactions are not optional.** Multi-statement writes go in `await this.uow.transactional(async () => …)` (`UnitOfWork` from `nest/database`, provided by the global `OrmModule`); never hand-roll `BEGIN`/`COMMIT` and never call `db.transaction()` (the Phase 1 async sweep removes it). The sequence lives in the service, never in a controller, MCP tool or RPC handler, so every surface calls the one method that holds the transaction (`ReservationsService.createWithCost` is the shape: side effects such as broadcasts come back to the caller and go out after the commit). A position or id taken as `MAX(...) + 1` is read inside the same transaction as the insert that uses it: the transaction holds the connection, so two requests at once cannot read the same MAX. On Postgres, where a pool runs transactions side by side, `UnitOfWork` first takes one advisory lock for the database (`DatabaseEngine.serializeWrites`), so the same holds; a transaction opened any other way does not get it. So no other transaction is opened under `src/`: ESLint (`trek/transactions-through-unit-of-work`, `eslint-rules/transactions-through-unit-of-work.mjs`, held by `lint:warnings`) refuses `em.transactional`, a repository's own `getEntityManager().transactional`, `em.begin()`, a connection's `transactional` and Kysely's `transaction()` everywhere but `src/db/engine/` and the boot-time `src/db/email-case-index.ts` and `src/db/legacy-baseline.ts`. Code outside the Nest container (the demo seed and reset) opens the same transaction with `writeTransaction` (`src/db/engine/write-transaction.ts`), which `UnitOfWork` wraps. Every check a write relies on (a count under a cap, a name or a row that must not exist yet, the last admin, a one-time token) is read inside the transaction that writes, and a repository method that holds such a check (`upsertValueCapped`, `upsertTaskCapped`) runs inside its caller's unit of work instead of opening one; a claim that has to be single (`markConsumed`, `claimReminder`) is one conditional statement. `lint:tx` holds the rest. Every DB-touching method is `async`; `@typescript-eslint/no-floating-promises` and `no-misused-promises` are errors, so an unawaited call or a `Promise` in a condition fails lint. Bind values with `?`; identifiers only via a literal allow-list. In `src/db/repositories/` and `src/db/seeders/`, ESLint refuses raw SQL in any spelling: `raw()`, the `sql` tag, and SQL text handed to `execute`/`run`/`all`/`get`. Build the statement with the query builder; `MaintenanceRepository`, `AdminSeeder` and `CategorySeeder` are the named exceptions in `eslint.config.mjs`, and `tests/unit/eslint-rules/restricted-syntax-selectors.test.ts` pins how many SQL strings each still holds, so they can only lose SQL, never gain it. An insert that needs the new id reads it with `.returning('id')`: `InsertResult.insertId` is SQLite's `last_insert_rowid` and undefined on Postgres, and ESLint refuses it in `src/db/repositories/` and `src/db/seeders/`. +- **Transactions are not optional.** Multi-statement writes go in `await this.uow.transactional(async () => …)` (`UnitOfWork` from `nest/database`, provided by the global `OrmModule`); never hand-roll `BEGIN`/`COMMIT` and never call `db.transaction()` (the Phase 1 async sweep removes it). The sequence lives in the service, never in a controller, MCP tool or RPC handler, so every surface calls the one method that holds the transaction (`ReservationsService.createWithCost` is the shape: side effects such as broadcasts come back to the caller and go out after the commit). A position or id taken as `MAX(...) + 1` is read inside the same transaction as the insert that uses it: the transaction holds the connection, so two requests at once cannot read the same MAX. On Postgres, where a pool runs transactions side by side, `UnitOfWork` first takes one advisory lock for the database (`DatabaseEngine.serializeWrites`), so the same holds; a transaction opened any other way does not get it. So no other transaction is opened under `src/`: ESLint (`trek/transactions-through-unit-of-work`, `eslint-rules/transactions-through-unit-of-work.mjs`, held by `lint:warnings`) refuses `em.transactional`, a repository's own `getEntityManager().transactional`, `em.begin()`, a connection's `transactional` and Kysely's `transaction()` everywhere but `src/db/engine/` and the boot-time `src/db/email-case-index.ts` and `src/db/legacy-baseline.ts`. Code outside the Nest container (the demo seed and reset) opens the same transaction with `writeTransaction` (`src/db/engine/write-transaction.ts`), which `UnitOfWork` wraps. Every check a write relies on (a count under a cap, a name or a row that must not exist yet, the last admin, a one-time token) is read inside the transaction that writes, and a repository method that holds such a check (`upsertValueCapped`, `upsertTaskCapped`) runs inside its caller's unit of work instead of opening one; a claim that has to be single (`markConsumed`, `claimReminder`) is one conditional statement. `lint:tx` holds the rest. Every DB-touching method is `async`; `@typescript-eslint/no-floating-promises` and `no-misused-promises` are errors, so an unawaited call or a `Promise` in a condition fails lint. Bind values with `?`; identifiers only via a literal allow-list. Everywhere under `src/`, ESLint refuses raw SQL in any spelling: `raw()`, the `sql` tag, and SQL text handed to `execute`/`run`/`all`/`get`, so SQL lives in a repository, where the Postgres probe runs it, and a service, job, guard or tool never sends its own. Build the statement with the query builder. Raw SQL has three homes, `src/db/dialect/`, `src/db/engine/` and `src/db/migrations/`; besides them the boot-time lifecycle files `email-case-index.ts`, `legacy-baseline.ts`, `migration-utils.ts` and `pre-migrate-snapshot.ts` in `src/db/`, and `MaintenanceRepository`, `AdminSeeder` and `CategorySeeder` for SQL text, are the named exceptions in `eslint.config.mjs`, and `tests/unit/eslint-rules/restricted-syntax-selectors.test.ts` pins how many SQL strings each still holds, so they can only lose SQL, never gain it. An insert that needs the new id reads it with `.returning('id')`: `InsertResult.insertId` is SQLite's `last_insert_rowid` and undefined on Postgres, and ESLint refuses it in `src/db/repositories/` and `src/db/seeders/`. - **Migrations are append-only.** A migration is identified by its class name in `mikro_orm_migrations`, and files sort by the timestamp in that name. Never rename or delete one that has shipped, and never edit its body; add a new one. No env interpolation in SQL. (The old positional `schema_version` array and the hand-kept `db/migrations.ts` test builder are both gone; the numbered migrations are the only schema history, for tests too.) A new foreign key comes with an index that leads with its column(s), or deleting the parent scans the child table (a partial index counts only when its WHERE clause is `IS NOT NULL` on those columns); `tests/unit/db/foreign-key-indexes.test.ts` fails on one without. - **Every write endpoint validates** through the Zod pipe with a schema from `@trek/shared` — no `Record` + ad-hoc checks. Also verify every referenced id exists and belongs to the same trip. A number bound for an integer column (`p.integer()`, `bigint` on Postgres) takes `.int()`: SQLite would store a fraction as a REAL where Postgres rounds or refuses it. INTCOL (`tests/unit/contracts/integer-columns.test.ts`) reads the integer columns from the entities and fails on a DTO field or an inline MCP tool field of that name without it; a field that only shares the name goes into its `NOT_A_COLUMN` with the reason. A value that really is fractional (a half day) gets a REAL/`double precision` column instead. - **Every outbound `fetch`** gets a timeout, a response-size cap and boundary validation: no `as`-casting provider responses, no silent `catch → null`. User-influenced URLs go through the SSRF guard. Never fall back to another user's API key. ESLint requires an init with a `signal` on `fetch`, `safeFetch`, `safeFetchFollow` and `safeFetchAdminConfigured` alike, or a literal `timeoutMs` in the options object of `safeFetch`/`safeFetchFollow`; an init spelled `undefined`, `null` or `void 0` counts as none (`safeFetchLlm` takes `LLM_TIMEOUT_MS` inside). Behind that, the guarded wrappers (`utils/ssrfGuard.ts`) cap every body at `DEFAULT_MAX_RESPONSE_BYTES` (64 MB) and, for a call without a signal, wait `DEFAULT_RESPONSE_TIMEOUT_MS` (30 s) for the headers. Pass a tighter `maxBytes` when you buffer a small answer, `timeoutMs` for a deadline over the whole exchange, and `maxBytes: null` only where the body is streamed on or counted by the caller (`pipeAsset`, the doc-sync transfers, the Ollama pull). @@ -100,7 +100,7 @@ Nest owns everything. Every domain is a DI module under `src/nest//` (`c SQLite is the default engine and Postgres the second (`TREK_DB_URL`, see Engines above). Code under `src/` is written so that an engine difference only adds a branch to the dialect layer, never a sweep through the repositories: -- **Build statements, don't spell them.** Use the entity methods or `this.kysely>()` on the generated table types. Repositories and seeders may not hold SQL text at all (ESLint), and `lint:dialect` holds every other file to its baseline. +- **Build statements, don't spell them.** Use the entity methods or `this.kysely>()` on the generated table types. Nothing under `src/` outside the dialect layer, the engines, the migrations and the named lifecycle files may hold SQL text (ESLint), and `lint:dialect` holds every file to its baseline. - **Which query API.** New repository code picks by the shape of the statement, not by what the file already uses: - **Kysely** (`this.kysely>()`) for every read that joins, aggregates, groups or projects columns across tables, and for set-based writes (a statement over many rows, a subquery, `RETURNING`). Its types come from the migrated schema, so a renamed column fails `tsc`. - **The entity methods** (`findOne`/`find`/`count`/`insert`/`nativeUpdate`/`nativeDelete`/`upsert`) for single-table CRUD by key or by a plain filter. They carry the `TrekRepository` request-context check and the identity-map default. diff --git a/server/eslint.config.mjs b/server/eslint.config.mjs index 6c587bb38..5be7a1ff0 100644 --- a/server/eslint.config.mjs +++ b/server/eslint.config.mjs @@ -38,17 +38,11 @@ const ENV_SELECTORS = [ }, ]; +const RAW_SQL_MESSAGE = + 'Dialect SQL goes through src/db/dialect/sql-functions.ts, which dispatches on the live MikroORM platform. Code outside src/db/dialect/ and src/db/engine/ must not spell raw SQL: build the statement in a repository with the query builder, where the Postgres probe runs it.'; const RAW_SQL_SELECTORS = [ - { - selector: "CallExpression[callee.name='raw']", - message: - 'Dialect SQL goes through src/db/dialect/sql-functions.ts, which dispatches on the live MikroORM platform. A repository must not spell raw SQL.', - }, - { - selector: "TaggedTemplateExpression[tag.name='sql']", - message: - 'Dialect SQL goes through src/db/dialect/sql-functions.ts, which dispatches on the live MikroORM platform. A repository must not spell raw SQL.', - }, + { selector: "CallExpression[callee.name='raw']", message: RAW_SQL_MESSAGE }, + { selector: "TaggedTemplateExpression[tag.name='sql']", message: RAW_SQL_MESSAGE }, ]; // Kysely fills InsertResult.insertId from SQLite's last_insert_rowid. Postgres @@ -109,7 +103,37 @@ const FETCH_SELECTORS = [ // the method name keeps `qb.execute('run')` (a result mode, not SQL) legal. const SQL_TEXT = String.raw`/^\s*(SELECT|INSERT|UPDATE|DELETE|REPLACE|WITH|PRAGMA|VACUUM|CREATE|DROP|ALTER|ATTACH|BEGIN|COMMIT)\b/i`; const SQL_STRING_MESSAGE = - 'A SQL string handed to the connection is raw SQL too. Build it with the query builder (this.kysely(), em.createQueryBuilder) and route dialect functions through src/db/dialect/sql-functions.ts.'; + 'A SQL string handed to the connection is raw SQL too. Build it in a repository with the query builder (this.kysely(), the entity methods), where the Postgres probe runs it, and route dialect functions through src/db/dialect/sql-functions.ts.'; + +// Where raw SQL may be spelled under src/: the dialect layer and the engines +// (each engine's own SQL), the migrations (frozen, and held by lint:dialect), +// and the boot-time lifecycle files named here, which run before or beside the +// migrator on the raw connection. tests/unit/eslint-rules/restricted-syntax-selectors.test.ts +// pins how many SQL strings each named file holds, so the list can only shrink. +// The repositories and seeders have blocks of their own below. +const RAW_SQL_HOMES = ['src/db/dialect/**', 'src/db/engine/**', 'src/db/migrations/**']; +const RAW_SQL_LIFECYCLE_FILES = [ + 'src/db/email-case-index.ts', + 'src/db/legacy-baseline.ts', + 'src/db/migration-utils.ts', + 'src/db/pre-migrate-snapshot.ts', +]; + +// The files the config-access guard leaves out (see the src/** block below). +const ENV_EXEMPT_FILES = [ + // The config layer itself. + 'src/app-config/**', + 'src/nest/app-config/**', + // Key-material resolution (file persistence + runtime rotation), not env config. + 'src/config.ts', + // Scrubbed plugin child process — must not import app-config. + 'src/nest/plugins/runtime/plugin-host-entry.ts', + // Child-env whitelist block: the env there is an IPC channel to the sandbox. + 'src/nest/plugins/supervisor/plugin-supervisor.ts', + // Dynamic-key caps (process.env[name] with a computed name). + 'src/nest/plugins/host/daily-budget.ts', + 'src/nest/plugins/host/plugin-audit.ts', +]; const STRING_SQL_SELECTORS = [ { @@ -271,25 +295,55 @@ export default tseslint.config( // (readEnv() / derive functions / registerAs tokens). Direct process.env // access is banned outside the documented exemptions below — see // src/app-config/README.md for the rationale behind each. + // + // The same block holds the raw-SQL wall for all of src/: SQL text outside a + // repository reaches Postgres unchecked, since the probe only runs what the + // repositories send. files: ['src/**/*.ts'], - ignores: [ - // The config layer itself. - 'src/app-config/**', - 'src/nest/app-config/**', - // Key-material resolution (file persistence + runtime rotation), not env config. - 'src/config.ts', - // Scrubbed plugin child process — must not import app-config. - 'src/nest/plugins/runtime/plugin-host-entry.ts', - // Child-env whitelist block: the env there is an IPC channel to the sandbox. - 'src/nest/plugins/supervisor/plugin-supervisor.ts', - // Dynamic-key caps (process.env[name] with a computed name). - 'src/nest/plugins/host/daily-budget.ts', - 'src/nest/plugins/host/plugin-audit.ts', - ], + ignores: ENV_EXEMPT_FILES, + rules: { + 'no-restricted-syntax': [ + 'error', + ...ENV_SELECTORS, + ...FETCH_SELECTORS, + ...APP_SETTING_SELECTORS, + ...RAW_SQL_SELECTORS, + ...STRING_SQL_SELECTORS, + ], + }, + }, + { + // The homes of raw SQL (RAW_SQL_HOMES, RAW_SQL_LIFECYCLE_FILES): the block + // above restated without the raw-SQL wall. + files: [...RAW_SQL_HOMES, ...RAW_SQL_LIFECYCLE_FILES], + ignores: ENV_EXEMPT_FILES, rules: { 'no-restricted-syntax': ['error', ...ENV_SELECTORS, ...FETCH_SELECTORS, ...APP_SETTING_SELECTORS], }, }, + { + // The files the config-access guard leaves out still hold no raw SQL. + files: ENV_EXEMPT_FILES, + rules: { + 'no-restricted-syntax': ['error', ...RAW_SQL_SELECTORS, ...STRING_SQL_SELECTORS], + }, + }, + { + // The two seeders that still write their rows as SQL text (see the + // repository and seeder block below, which leaves them out): the block + // above without the SQL string rule, raw() and the sql tag still refused. + files: ['src/db/seeders/AdminSeeder.ts', 'src/db/seeders/CategorySeeder.ts'], + rules: { + 'no-restricted-syntax': [ + 'error', + ...ENV_SELECTORS, + ...FETCH_SELECTORS, + ...APP_SETTING_SELECTORS, + ...RAW_SQL_SELECTORS, + ...INSERT_ID_SELECTORS, + ], + }, + }, { // Every transaction goes through UnitOfWork.transactional (or writeTransaction, // which it wraps), the only ones that take the engine's write lock: on @@ -311,8 +365,8 @@ export default tseslint.config( }, }, { - // Restates the config-access and app-setting guards above for *.mcp.ts - // (a later block's options replace an earlier one's) and adds the + // Restates the config-access, app-setting and raw-SQL guards above for + // *.mcp.ts (a later block's options replace an earlier one's) and adds the // demo-gate wall. files: ['src/**/*.mcp.ts'], rules: { @@ -321,6 +375,8 @@ export default tseslint.config( ...ENV_SELECTORS, ...FETCH_SELECTORS, ...APP_SETTING_SELECTORS, + ...RAW_SQL_SELECTORS, + ...STRING_SQL_SELECTORS, ...MCP_DEMO_SELECTORS, ], }, diff --git a/server/tests/unit/eslint-rules/restricted-syntax-selectors.test.ts b/server/tests/unit/eslint-rules/restricted-syntax-selectors.test.ts index a26d99f24..f432f7018 100644 --- a/server/tests/unit/eslint-rules/restricted-syntax-selectors.test.ts +++ b/server/tests/unit/eslint-rules/restricted-syntax-selectors.test.ts @@ -192,9 +192,80 @@ void safeFetch(url);`, } }); - it('does not reach outside src/db', async () => { + const RAW_MESSAGE_PREFIX = 'Dialect SQL goes through'; + const rawHits = (options: unknown[], code: string) => + messages( + options, + `${SQL}\ndeclare function raw(s: string): unknown;\ndeclare const sql: (s: TemplateStringsArray) => unknown;\n${code}`, + ).filter((m) => m.startsWith(SQL_MESSAGE_PREFIX) || m.startsWith(RAW_MESSAGE_PREFIX)); + + // A service with SQLite-only SQL of its own: no repository, so the Postgres + // probe never sends it, and only a lane suite that happens to reach it would. + const SERVICE_SQL = + "void connection.execute('SELECT trip_id, group_concat(name, \\', \\') AS names, ifnull(SUM(cost), 0) AS total FROM places WHERE trip_id = ? GROUP BY trip_id', [1]);"; + + it.each([ + 'src/nest/trips/trip-stats.service.ts', + 'src/nest/demo/demo-reset.job.ts', + 'src/nest/auth/auth.guard.ts', + 'src/nest/trips/trips.mcp.ts', + 'src/utils/probe.ts', + 'src/db/probe.ts', + 'src/app-config/probe.ts', + 'src/nest/plugins/host/plugin-audit.ts', + ])('refuses raw SQL in %s, outside the repositories', async (file) => { + const options = await selectorsFor(file); + expect(rawHits(options, SERVICE_SQL), file).toHaveLength(1); + expect(rawHits(options, "void raw('now()');"), file).toHaveLength(1); + expect(rawHits(options, 'void sql`select 1`;'), file).toHaveLength(1); + expect(rawHits(options, "void qb.execute('run'); void repo.get('key');"), file).toEqual([]); + }); + + // Where SQL may be spelled outside the repositories and seeders: the homes + // (each engine's own SQL, the migrations) and the boot-time lifecycle files, + // with the SQL strings each holds today. A count may only go down. + const SQL_HOMES = ['src/db/dialect/', 'src/db/engine/', 'src/db/migrations/']; + const LIFECYCLE_SQL_STRINGS: Record = { + 'src/db/email-case-index.ts': 3, + 'src/db/legacy-baseline.ts': 3, + 'src/db/migration-utils.ts': 6, + 'src/db/pre-migrate-snapshot.ts': 3, + }; + + it('leaves out exactly the homes of raw SQL and the pinned lifecycle files, and keeps the other guards there', async () => { + const exempt: string[] = []; + const outside = filesUnder('src').filter( + (file) => !file.startsWith('src/db/repositories/') && !file.startsWith('src/db/seeders/'), + ); + for (const file of outside) { + // A file ESLint ignores altogether (generated, gitignored) is linted by nothing. + if (await eslint.isPathIgnored(path.join(serverRoot, file))) continue; + const options = (await selectorsFor(file)) as { message?: string }[]; + if (!options.some((o) => o.message?.startsWith(SQL_MESSAGE_PREFIX))) exempt.push(file); + } + const unexpected = exempt.filter( + (file) => !SQL_HOMES.some((home) => file.startsWith(home)) && !(file in LIFECYCLE_SQL_STRINGS), + ); + expect(unexpected).toEqual([]); + for (const file of Object.keys(LIFECYCLE_SQL_STRINGS)) { + expect(exempt, file).toContain(file); + const options = await selectorsFor(file); + expect(messages(options, `${PRELUDE}\nvoid safeFetch(url);`), file).toContain(TIMEOUT); + } + }); + + it('holds each lifecycle file to the SQL strings it has today', async () => { const options = await selectorsFor('src/nest/memories/probe.service.ts'); - expect(hits(options, "void connection.execute('SELECT 1');")).toEqual([]); + const counts: Record = {}; + for (const file of Object.keys(LIFECYCLE_SQL_STRINGS)) { + const source = fs.readFileSync(path.join(serverRoot, file), 'utf8'); + counts[file] = messages(options, source).filter( + (m) => m.startsWith(SQL_MESSAGE_PREFIX) || m.startsWith(RAW_MESSAGE_PREFIX), + ).length; + } + expect(counts, 'new SQL text in a lifecycle file fails; after removing some, lower its pin').toEqual( + LIFECYCLE_SQL_STRINGS, + ); }); });