From 9fd77b04fa02f7aa2634d37874a2b6ab2c359719 Mon Sep 17 00:00:00 2001 From: Maurice Date: Tue, 17 Nov 2026 22:28:44 +0100 Subject: [PATCH] docs(db): describe the layers that hold plugin SQL on Postgres and the NUL rule for plugin data The plugin-sdk README, the Postgres wiki page and server/CLAUDE.md now name the layers as the code enforces them: the refusal on a privileged role and the boot log line, the guard (the reg* types, INTO after the statement's own INSERT or MERGE only, TEMP only where it makes a temporary object), the targets Postgres resolves before an ALTER, DROP, REFRESH, TRUNCATE or CREATE INDEX, one statement per round trip, pg_temp last, and the quota over every relation with the object cap. They also say that a plugin argument holding NUL is refused on Postgres and bound exactly on SQLite. --- plugin-sdk/README.md | 55 ++++++++++++++++++++++++++++++--------- server/CLAUDE.md | 4 +-- wiki/Database-Postgres.md | 15 ++++++++--- 3 files changed, 57 insertions(+), 17 deletions(-) diff --git a/plugin-sdk/README.md b/plugin-sdk/README.md index b66d94593..2cf7efdda 100644 --- a/plugin-sdk/README.md +++ b/plugin-sdk/README.md @@ -193,21 +193,41 @@ What changes on Postgres: of `AUTOINCREMENT`, `now()` instead of `datetime('now')`, `ON CONFLICT` works on both. A `bigint` comes back as a number, and one past 2^53 is refused. A boolean comes back as `true`/`false`, not `1`/`0`. +- **Not on a privileged role.** While TREK connects to Postgres as a superuser, a member of + one, or another role that could reach the database server (the same roles TREK refuses + restores for), every `ctx.db` call fails with an error that starts `Plugin databases + (db:own) are refused on Postgres`, and TREK's boot log says so. Your SQL would run as + that role. The admin fixes it by connecting TREK as a role that owns its database and is + not a superuser; your plugin needs no change. - **Your SQL stays in your schema.** Only your schema is on the `search_path`, and a statement is refused before it runs when it names another schema (`public.users`, another plugin's), anything starting with `pg_` or `information_schema`, or a function that runs SQL from a string, reads settings or reaches an object by a name in a string - (`query_to_xml`, `ts_stat`, `set_config`, `current_setting`, `nextval`, `setval`, the - `reg*` casts, `lo_*`, `dblink`). An alias that shares a schema's name is refused too, so - pick another. + (`query_to_xml`, `ts_stat`, `set_config`, `current_setting`, `nextval`, `setval`, + `has_table_privilege` and the other `has_*_privilege` functions, `currtid2`, `to_reg*`, + `lo_*`, `dblink`). The types that look an object up by name are refused in every + spelling: `regclass`, `regtype`, `regproc`, `regprocedure`, `regoper`, `regoperator`, + `regconfig`, `regdictionary`, `regnamespace`, `regrole`, `regcollation` and their arrays + (`'x'::regtype`, `CAST('x' AS regtype)`, `regtype 'x'`). An alias that shares a schema's + name is refused too, so pick another. +- **You change your own objects only.** Right before an `ALTER`, `DROP`, `REFRESH`, + `TRUNCATE` or `CREATE INDEX ... ON` runs, Postgres resolves the object it names (and the + tables a `CREATE`/`ALTER TABLE` ties to with `REFERENCES`, `INHERITS`, `PARTITION OF`, + `ATTACH`/`DETACH PARTITION` or `INHERIT`), and the statement is refused unless each one + that exists is in your schema. Postgres searches its catalog before your schema, so + `ALTER TYPE int4 ...` or `DROP TYPE text` names the built-in type and is refused; name + your own types so they do not clash with built-in ones. - **Statements**: `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `WITH`, `VALUES`, `TABLE`, `TRUNCATE`, `REFRESH`, and `CREATE`/`ALTER`/`DROP` of a table, index, view, - materialized view, sequence or type. No functions, triggers, procedures, `DO` blocks, - temporary tables, `SELECT ... INTO`, `COPY`, `SET`, transaction control (`tx()` makes a - batch atomic), `WITH RECURSIVE`, and no `ALTER` of a schema, owner or tablespace. - Dollar-quoted strings, `E'...'` and `U&'...'` are refused; write plain single-quoted - strings. The words `TEMP` and `TEMPORARY` are refused anywhere outside a string (quote a - column named `"temp"`), and so is `INTO` anywhere but `INSERT INTO` and `MERGE INTO`. + materialized view, sequence or type (a composite, enum or range type, `CREATE TYPE x AS + ...`). No functions, triggers, procedures, `DO` blocks, base types, temporary tables, + `SELECT ... INTO`, `COPY`, `SET`, transaction control (`tx()` makes a batch atomic), + `WITH RECURSIVE`, and no `ALTER` of a schema, owner or tablespace. Dollar-quoted strings, + `E'...'` and `U&'...'` are refused; write plain single-quoted strings. `CREATE TEMP` and + `CREATE TEMPORARY` (also after `OR REPLACE`, `LOCAL` or `GLOBAL`) are refused, and so is + `INTO` anywhere but right after the `INSERT` or `MERGE` that is the statement's verb (or + the verb of a `WITH` query's body): `SELECT 1 insert INTO t` is refused, because `insert` + there is a column alias. A column named `temp` needs no quoting. Numbers are decimal: `0x1F`, `0o17`, `0b1` and `1_000` are refused, because Postgres before 16 reads them differently. Outside strings, quoted names and comments, whitespace is space, tab, newline, carriage return or form feed; any other control character or non-ASCII @@ -216,11 +236,22 @@ What changes on Postgres: - **One statement at a time.** Each statement goes to Postgres on its own, over the protocol that runs exactly one: `query` and each `tx` entry take one statement, and an `exec` script is split at its semicolons and sent statement by statement. +- **No NUL in text.** Postgres text cannot hold the character U+0000. A bound argument + holding one (a string, or a string in an array) and a `migrate` id holding one are refused + with an error that names it, and so is SQL text with one anywhere, a string literal + included; TREK never drops or changes the character, since `'a\0b'` and `'ab'` are + different keys. Bind binary data as a `Buffer` into a `bytea` column, and use another + separator for composite keys. On SQLite your arguments are bound exactly as you send + them, NUL included, as they always were. - **Limits**: the same row cap and quota as on SQLite. The 2 s budget is a `statement_timeout` here, so it also stops a single long statement, and an `exec` with - bound args is held to it too; `migrate` stays untimed. A write that takes your schema past - 256 MB and grows it is rolled back; a delete still runs. Rows deleted or rolled back keep - their space until Postgres vacuums them. + bound args is held to it too; `migrate` stays untimed. The quota counts every relation of + your schema (tables, indexes, sequences, materialized views and each table's TOAST + storage), and a schema may hold at most 5,000 catalog objects (relations, types, each + table brings its row type and that type's array, constraints and enum labels). A write + that takes your schema past 256 MB or past 5,000 objects and grows it there is rolled + back; a delete or a drop still runs. Rows deleted or rolled back keep their space until + Postgres vacuums them. ## Settings diff --git a/server/CLAUDE.md b/server/CLAUDE.md index 3e0055163..b178fdb2c 100644 --- a/server/CLAUDE.md +++ b/server/CLAUDE.md @@ -79,7 +79,7 @@ Nest owns everything. Every domain is a DI module under `src/nest//` (`c - **Realtime**: `/ws` is a Nest gateway in `src/nest/realtime/`. Inject `RealtimeService`; tests hand in a `FakeRealtimeService` (`tests/helpers/fake-realtime.ts`) or spy on the container's instance instead of mocking the transport module. Trip mutations forward `X-Socket-Id` so the originating client doesn't echo its own change. - **MCP**: `src/nest-mcp/` is the decorator/registry layer (`@McpController`/`@Tool`/`@Resource`/`@Prompt`; see its `README.md`); tools live in `.mcp.ts` files beside each module; the HTTP transport is `src/nest/mcp-transport/`; `src/mcp/` holds process-wide state only (scopes, session manager, boot policy). Every tool invocation writes an audit row through the registry's `onInvoke` seam. The demo-mode write block is the registry's `toolGate` (`trekDemoToolGate`): every tool not annotated read-only refuses a demo account there (except the write tools in `DEMO_UNGATED_WRITE_TOOLS`, which never had a demo check), so a tool never checks demo mode itself (ESLint refuses it in `*.mcp.ts`). MCP tools are adapters over the same services and permission checks as REST — a change on one side lands on the other in the same change. - **Scheduling**: `src/nest/scheduling/` (`CronRegistrarService`) is the one way to schedule a cron. Jobs are `*.job.ts` providers in their owning domain. The registrar refuses to schedule under `NODE_ENV=test` (an integration test pins it). **Never use a `@Cron` decorator**: it bypasses that gate. Every tick first takes the job's row in `scheduler_leases` (`SchedulerLeasesRepository.acquire`, one conditional upsert that decides the race), renews it while it runs and keeps it for a short settle window afterwards, so two processes on one database never run the same tick; a job needs nothing of its own for this. Claims on individual rows (the reminder jobs' `claimReminder`) stay where they are: the lease decides who runs a tick, the claim what a tick may send. -- **Plugins** (`src/nest/plugins/`): the child-process runtime (`supervisor/`, `runtime/plugin-host-entry.ts`, `protocol/envelope.ts`) is **intentionally not Nest**; it is the security boundary. `host/rpc-host.ts` registers an RPC method at spawn only if the plugin holds the unlocking permission (registration = authorization). Install-time gates live in `install/`; the manifest's `trek` version range fails closed, and `TREK_PLUGINS_IGNORE_TREK_RANGE` downgrades that to a warning. The protocol tables in `protocol/envelope.ts` (+ `src/plugin-event-sink.ts`) are **generated** into `plugin-sdk/` and `shared/`: run `gen:plugin-facts` after touching them and commit the output. What a plugin gets back is `protocol/output-contract.ts`: every wire method has an entry, and an entity result (`trips.getById`, `todos.list`, `vacay.mine`, ...) is cut down to its published fields in `rpc-host.ts` on the way out, together with every child row it carries whose field is listed in `PLUGIN_ENTITY_NESTED` (a day's `notes_items`, a reservation's `endpoints`). A new column on any whole-row table behind those entities, child tables included, fails `tests/unit/plugins/output-contract.schema.test.ts` until it is listed as published or withheld (the SDK's `PLUGIN_ENTITY_FIELDS` and `PLUGIN_ENTITY_NESTED` are generated from it); a method left as `readModel` must return a value built field by field from named columns. A plugin's own SQL (`host/plugin-data.service.ts`) is held to a row cap, and `query`, `tx` and an `exec` script to a time budget checked between rows and statements (`migrate` is deliberately not timed). Where that data lives is the engine's: `PLUGIN_DATA` (`src/nest/plugins/host/plugin-data.backend.ts`) binds the SQLite file per plugin, or on Postgres a schema per plugin (`trek_plugin_`, `src/db/engine/postgres/plugin-data-store.ts`) whose SQL `src/db/engine/postgres/plugin-sql-guard.ts` keeps inside that schema before it runs (its header names the three layers: the guard, which refuses what it would read differently from the Postgres lexer; one statement per round trip over the extended query protocol, which the store sends on a pool client it checks out for each call and runs its transaction on directly; and `pg_temp` last on the plugin's and on every pool connection's `search_path`, `session-search-path.ts`, with the store dropping its client's temporary tables and other session state before the client goes back to the pool); the plugin's SQL is never translated, and `db.engine` tells the plugin which dialect to write. Backups and restores carry the plugin schemas the role owns (`pg-tools.ts`). `runtime/egress-policy.ts` is a hand-kept mirror guarded by a parity test in `plugin-sdk/`; change both sides together. +- **Plugins** (`src/nest/plugins/`): the child-process runtime (`supervisor/`, `runtime/plugin-host-entry.ts`, `protocol/envelope.ts`) is **intentionally not Nest**; it is the security boundary. `host/rpc-host.ts` registers an RPC method at spawn only if the plugin holds the unlocking permission (registration = authorization). Install-time gates live in `install/`; the manifest's `trek` version range fails closed, and `TREK_PLUGINS_IGNORE_TREK_RANGE` downgrades that to a warning. The protocol tables in `protocol/envelope.ts` (+ `src/plugin-event-sink.ts`) are **generated** into `plugin-sdk/` and `shared/`: run `gen:plugin-facts` after touching them and commit the output. What a plugin gets back is `protocol/output-contract.ts`: every wire method has an entry, and an entity result (`trips.getById`, `todos.list`, `vacay.mine`, ...) is cut down to its published fields in `rpc-host.ts` on the way out, together with every child row it carries whose field is listed in `PLUGIN_ENTITY_NESTED` (a day's `notes_items`, a reservation's `endpoints`). A new column on any whole-row table behind those entities, child tables included, fails `tests/unit/plugins/output-contract.schema.test.ts` until it is listed as published or withheld (the SDK's `PLUGIN_ENTITY_FIELDS` and `PLUGIN_ENTITY_NESTED` are generated from it); a method left as `readModel` must return a value built field by field from named columns. A plugin's own SQL (`host/plugin-data.service.ts`) is held to a row cap, and `query`, `tx` and an `exec` script to a time budget checked between rows and statements (`migrate` is deliberately not timed). Where that data lives is the engine's: `PLUGIN_DATA` (`src/nest/plugins/host/plugin-data.backend.ts`) binds the SQLite file per plugin, or on Postgres a schema per plugin (`trek_plugin_`, `src/db/engine/postgres/plugin-data-store.ts`) whose SQL is kept inside that schema in layers that `src/db/engine/postgres/plugin-sql-guard.ts`'s header names, the ones after the guard enforced by the database: no plugin SQL at all while TREK's role is privileged in the sense of `PRIVILEGED_ROLE_SQL` (`src/db/engine/postgres/plugin-data-checks.ts`, read once per pool connection, and the boot log says why); the guard, which refuses what it would read differently from the Postgres lexer, other schemas, the catalogs, temporary objects, `SELECT ... INTO`, the `reg*` types and the functions that look an object up by name; the objects an ALTER, DROP, REFRESH, TRUNCATE or CREATE INDEX changes, resolved by Postgres (`to_regclass`/`to_regtype`) right before the statement and refused outside the plugin's schema, so an unqualified `int4` is `pg_catalog`'s and refused even on a superuser connection; one statement per round trip over the extended query protocol, which the store sends on a pool client it checks out for each call and runs its transaction on directly; `pg_temp` last on the plugin's and on every pool connection's `search_path`, `session-search-path.ts`, with the store dropping its client's temporary tables and other session state before the client goes back to the pool; and a quota over every relation of the schema with its TOAST table plus a cap on its catalog objects (`PLUGIN_SCHEMA_MAX_OBJECTS`). A plugin argument holding NUL is refused there, since Postgres text cannot hold it, while the plugin's SQLite file binds it exactly; the plugin's SQL is never translated, and `db.engine` tells the plugin which dialect to write. Backups and restores carry the plugin schemas the role owns (`pg-tools.ts`). `runtime/egress-policy.ts` is a hand-kept mirror guarded by a parity test in `plugin-sdk/`; change both sides together. - **Storage**: `src/nest/storage/` is the upload driver abstraction (local / S3 / mirror behind one interface, with an admin surface and a usage job). Domain services never touch the filesystem or the S3 SDK directly. Where the data lives (`data/`, `uploads/`, backups, logs, key files, the DB file) is resolved in one place, `src/app-config/data-paths.ts`; a provider that reads one injects `DataPathsService`, plain helper modules shared with code outside the container call `resolveDataPaths()` (the list is in `src/app-config/README.md`), and nothing anchors a data path on its own `__dirname` or on `process.cwd()`. - **DB** (`src/db/`): `better-sqlite3`, WAL, FK on. `database.ts` only holds the connection and applies pragmas. It does not build a schema, and importing it opens nothing (the first reader does). The connection's lifecycle belongs to the `DatabaseLifecycle` provider (`nest/database/database-lifecycle.service.ts`): `buildApp()` opens it through `open()` (which binds the ORM to later swaps and runs the schema bootstrap below), the shutdown closes it through `close()`, and a restore or the demo reset swaps the file only through the database backup port, `DATABASE_BACKUP` (`nest/database/database-backup.interface.ts`; the SQLite implementation is `nest/backup/sqlite-database-backup.ts`: `VACUUM INTO` snapshot, close, atomic file swap, `reopen()`). The port works on `DatabaseLifecycle.file`, the one resolved path (`TREK_DB_FILE` or `data/travel.db`), and a snapshot that fails fails the backup rather than archiving the live file. `MaintenanceRepository` is provided only by `MaintenanceModule`'s factory and injected everywhere else; no consumer constructs it. A provider that has to follow every reopen (the demo reset job saves the first demo baseline after a restore's re-bootstrap seeded the example trips) registers with `DatabaseLifecycle.onReopened()`, which runs after the reopen's schema bootstrap; a listener contains its own failures, since one that throws fails the reopen. MikroORM's migrations (`db/migrations/`) are the only schema source, **including for tests**: the hand-kept `schema.ts`/`migrations.ts`/`seeds.ts` builders and the parity test that guarded them are gone. Seeding is the MikroORM seeders in `db/seeders/`, applied by `db/orm.ts` from `buildApp()` before anything reads. An install the retired positional runner migrated (a `schema_version` row, no `mikro_orm_migrations` rows) is baselined by `db/legacy-baseline.ts`: the migrations whose `Legacy migration step N` docstring is ≤ its version are recorded as executed (never replayed) in the same transaction as the migrator run, while the baseline migration itself still runs first, as the legacy runner's `createTables()` did on every boot. It refuses the boot when `schema_version` is not exactly one row holding an integer ≥ 1, or is above the last mapped step (258); a value from 1 to 258 is read as dev's steps of those numbers, so a pre-ORM feature-branch database whose steps differ is not detected (the Tours branch is the one case it cuts back). Recorded `mikro_orm_migrations` names this build does not ship refuse it too (`refuseNewerDatabase`), whether a newer release or a development build wrote them. 4.3.x and earlier have no such check and start on a database 5.x migrated. Before a boot applies pending migrations to a file database that holds anything, `db/pre-migrate-snapshot.ts` writes a `VACUUM INTO` copy next to it (`pre-migrate--