fix(plugins): hold plugin data on Postgres to its own schema and to one contract on both engines

The plugin SQL guard now refuses what still reached outside a plugin's
schema or depended on the server:
- reads of the system columns (xmin, xmax, cmin, cmax, ctid, tableoid),
  which show transaction ids and storage layout and do not exist on
  SQLite; a value of the plugin's own may still be named xmin with AS
- the xid and xid8 types wherever the word stands for the type, since
  age() of an xid is the cluster's transaction counter
- the text search functions that coerce a text argument to regconfig, a
  catalog lookup by name, which leave the allowlist
- collations and access methods outside the set every server has, which
  could tell whether a locale or an extension exists

Every plugin transaction pins, with SET LOCAL, the settings that decide
how values print and parse (TimeZone UTC, DateStyle, the C locales, float,
bytea and xml output, the text search configuration), so a plugin's output
neither depends on nor reveals the server's configuration.

Both stores now keep one contract. Its texts and caps live once, in
plugin-data-contract.ts, and both stores throw only those: NUL in SQL,
an argument or a migration id is refused on SQLite as on Postgres,
transaction control is refused in every call on both engines (tx() is
how a batch becomes atomic), a closed store refuses every call, and the
Postgres store answers the cases better-sqlite3 names with its words.
The SQLite store moves beside the Postgres one as SqlitePluginDataStore
in db/engine/sqlite, takes its file from the backend so src/db never
imports src/nest, and no longer needs the driver exemption. A contract
test runs every violation on both stores and fails when they answer
differently. The Postgres lane holds the allowlist, the pinned settings
and the SQL plugins commonly write against a real database.
This commit is contained in:
Maurice
2026-11-18 13:20:07 +01:00
parent cc0fe6ce2b
commit c970245e0d
26 changed files with 1932 additions and 513 deletions
@@ -10,6 +10,11 @@
* store on a real database is the Postgres lane's
* tests/postgres/plugin-data.test.ts.
*/
import {
PLUGIN_DATA_ERRORS,
PLUGIN_SQL_NUL_REFUSAL,
PLUGIN_VALUE_NUL_REFUSAL,
} from '../../../../../src/db/engine/plugin-data-contract';
import { PRIVILEGED_ROLE_PLUGIN_REFUSAL } from '../../../../../src/db/engine/postgres/plugin-data-checks';
import {
dropPluginSchema,
@@ -19,6 +24,7 @@ import {
PostgresPluginDataStore,
type PluginSqlClient,
} from '../../../../../src/db/engine/postgres/plugin-data-store';
import { PLUGIN_SESSION_SETTINGS } from '../../../../../src/db/engine/postgres/plugin-session';
import { PRIVILEGED_ROLE_SQL } from '../../../../../src/db/engine/postgres/server-checks';
import type { Kysely } from 'kysely';
@@ -144,7 +150,7 @@ function pgError(code: string, message: string): Error {
}
describe('Postgres plugin data store', () => {
it('PGSTORE-001: a query runs in a transaction that makes the schema, scopes the search_path and sets the budget', async () => {
it('PGSTORE-001: a query runs in a transaction that makes the schema, scopes the search_path, pins the settings and sets the budget', async () => {
const { store: s, log } = store({
rows: { 'SELECT body FROM notes': [{ body: 'a' }, { body: 'b' }, { body: 'c' }] },
});
@@ -157,7 +163,24 @@ describe('Postgres plugin data store', () => {
'create schema if not exists "trek_plugin_notes"',
'create table if not exists "trek_plugin_notes"._plugin_migrations (id text primary key, applied_at bigint)',
'set local search_path to "trek_plugin_notes", pg_temp',
'set local standard_conforming_strings to on',
"set local TimeZone to 'UTC'",
"set local DateStyle to 'ISO, MDY'",
"set local IntervalStyle to 'postgres'",
"set local timezone_abbreviations to 'Default'",
"set local lc_monetary to 'C'",
"set local lc_numeric to 'C'",
"set local lc_time to 'C'",
"set local extra_float_digits to '1'",
"set local bytea_output to 'hex'",
"set local xmlbinary to 'base64'",
"set local xmloption to 'content'",
"set local default_text_search_config to 'pg_catalog.simple'",
"set local standard_conforming_strings to 'on'",
"set local backslash_quote to 'safe_encoding'",
"set local array_nulls to 'on'",
"set local transform_null_equals to 'off'",
"set local quote_all_identifiers to 'off'",
"set local gin_fuzzy_search_limit to '0'",
'set local statement_timeout to 2000',
].join(';\n'),
'SELECT body FROM notes',
@@ -166,6 +189,13 @@ describe('Postgres plugin data store', () => {
]);
});
it('PGSTORE-020: every pinned setting is a plain name and value, set with SET LOCAL', () => {
for (const [name, value] of Object.entries(PLUGIN_SESSION_SETTINGS)) {
expect(name).toMatch(/^[A-Za-z_]+$/);
expect(value).not.toMatch(/['\\]/);
}
});
it("PGSTORE-002: a qualified name is checked against the database's schemas before the statement runs", async () => {
const { store: s, log } = store({ schemas: ['public', 'auth', 'trek_plugin_notes'] });
await expect(s.query('SELECT x FROM auth.secret')).rejects.toThrow(/"auth" is another schema/);
@@ -252,7 +282,7 @@ describe('Postgres plugin data store', () => {
await expect(s.tx([])).resolves.toEqual({ results: [] });
await expect(s.tx(Array.from({ length: 101 }, () => ({ sql: 'SELECT 1' })))).rejects.toThrow(/at most 100/);
await expect(s.tx([{ sql: '/* x */ COMMIT' }])).rejects.toThrow(/transaction-control/);
await expect(s.tx([{ sql: '/* x */ COMMIT' }])).rejects.toThrow(PLUGIN_DATA_ERRORS.txControl);
await expect(s.tx('nope' as never)).rejects.toThrow(/requires an array/);
});
@@ -281,7 +311,7 @@ describe('Postgres plugin data store', () => {
await expect(s.query(42 as never)).rejects.toThrow('sql must be a string');
await expect(s.query('x'.repeat(100_001))).rejects.toThrow('sql too long');
await expect(s.query('-- only a comment')).rejects.toThrow('contains no statements');
await expect(s.query('SELECT 1; SELECT 2')).rejects.toThrow(/exactly one statement/);
await expect(s.query('SELECT 1; SELECT 2')).rejects.toThrow(PLUGIN_DATA_ERRORS.moreThanOneStatement);
await expect(s.exec('DO $$ BEGIN END $$')).rejects.toThrow(/dollar-quoted/);
expect(log).toEqual([]);
expect(releases).toEqual([]);
@@ -342,9 +372,12 @@ describe('Postgres plugin data store', () => {
expect(configs.find((q) => q.text.startsWith('INSERT'))?.values).toEqual(['cd']);
});
it('PGSTORE-016: an argument or a migration id holding NUL is refused before a client is taken, never altered', async () => {
it('PGSTORE-016: SQL, an argument or a migration id holding NUL is refused before a client is taken, never altered', async () => {
const { store: s, log, releases } = store();
const nul = /U\+0000 \(NUL\), which Postgres text cannot store/;
const nul = PLUGIN_VALUE_NUL_REFUSAL;
// The same refusal as on SQLite, before the guard reads the SQL.
await expect(s.exec("INSERT INTO t VALUES ('a\u0000')")).rejects.toThrow(PLUGIN_SQL_NUL_REFUSAL);
await expect(s.query('SELECT 1 FROM t WHERE k = $1', [{ nested: ['\u0000'] }])).rejects.toThrow(nul);
await expect(s.query('SELECT 1 FROM t WHERE k = $1', ['a\u0000b'])).rejects.toThrow(nul);
await expect(s.exec('INSERT INTO t VALUES ($1)', [['x', 'c\u0000d']])).rejects.toThrow(nul);
await expect(s.tx([{ sql: 'SELECT 1' }, { sql: 'DELETE FROM t WHERE k = $1', args: ['\u0000'] }])).rejects.toThrow(
@@ -416,7 +449,7 @@ describe('Postgres plugin data store', () => {
it('PGSTORE-014: each transaction checks out a client of its own and gives it back clean, or closes it', async () => {
const ok = store({ changes: 1 });
await ok.store.exec('INSERT INTO a VALUES (1); INSERT INTO b VALUES (2)');
await expect(ok.store.query('SELECT 1; SELECT 2')).rejects.toThrow(/exactly one statement/);
await expect(ok.store.query('SELECT 1; SELECT 2')).rejects.toThrow(PLUGIN_DATA_ERRORS.moreThanOneStatement);
// One client per statement of the script, each after its session state was dropped; the refused read took none.
expect(ok.releases).toEqual([false, false]);
expect(ok.log.filter((sql) => sql === END_SESSION)).toHaveLength(2);
@@ -60,6 +60,12 @@ describe('functions a plugin may call on Postgres', () => {
"select has_largeobject_privilege(1, 'select')",
'select acldefault(1, 10)',
'select setseed(0.5)',
// A text search configuration is a regconfig, looked up by a name in a string.
"select to_tsvector('trek_plugin_other.cfg', 'a')",
"select to_tsvector('english', body) @@ plainto_tsquery('english', $1) from notes",
"select to_tsquery('a'), phraseto_tsquery('a'), websearch_to_tsquery('a')",
"select ts_headline('a', 'a'::tsquery)",
"select jsonb_to_tsvector('{}'::jsonb, '[\"all\"]')",
// Every spelling of the call.
'SELECT OBJ_DESCRIPTION(16386)',
'select "obj_description"(16386)',
@@ -92,6 +98,15 @@ describe('functions a plugin may call on Postgres', () => {
expect(() => parsePluginSql(sql)).toThrow(/a plugin may not (call|read)/);
});
it.each([
// xid is the transaction id type age() reads the server's counter with; after a dot it is a cast.
"select age('3'::xid)",
'select n.xid from notes n',
'select $1.xid',
])('refuses %s as a transaction id', (sql) => {
expect(() => parsePluginSql(sql)).toThrow(/stands for a transaction id type/);
});
it.each([
"select lower(body), substring(body from 2 for 3), regexp_replace(body, 'a', 'b') from notes",
"select now(), date_trunc('day', now()), extract(epoch from now()), to_char(now(), 'YYYY')",
@@ -100,7 +115,9 @@ describe('functions a plugin may call on Postgres', () => {
'select gen_random_uuid(), md5(body), sha256(body::bytea) from notes',
'select x from generate_series(1, 5) as g(x)',
'select unnest(array[1, 2]), cardinality(array[1])',
"select to_tsvector('english', body) @@ plainto_tsquery('english', $1) from notes",
// Text search on vectors a plugin builds itself, with no configuration to look up.
"select ts_rank(array_to_tsvector(tags), 'a & b'::tsquery), setweight(array_to_tsvector(tags), 'A') from notes",
'select body from notes where array_to_tsvector(tags) @@ $1::tsquery',
'select coalesce(a, b), nullif(a, 0), greatest(a, b), least(a, b) from notes',
"select cast(n as numeric(10, 2)), body::varchar(20), 'now'::timestamp(3) from notes",
'select current_date, current_timestamp, localtimestamp',
@@ -115,7 +132,7 @@ describe('functions a plugin may call on Postgres', () => {
'CREATE VIEW version (a) AS SELECT 1',
'select n.version, n.user_id, "user", "current_user" from notes n',
// The refused names a table may well have as a column, after a dot.
'select n.name, n.money, n.oid, n.xid, n.xml, n.version from notes n',
'select n.name, n.money, n.oid, n.xml, n.version from notes n',
'select (n).name, $1.name from notes n',
"insert into notes (id, name) values (1, 'a') on conflict (id) do update set name = excluded.name",
'select n.body from trek_plugin_notes.notes n join trek_plugin_notes.version v on v.id = n.id',
@@ -5,6 +5,7 @@
* the way Postgres does, and what it tells the store about a statement. The
* same rules against a real database are PGPLUG-003/004 in the Postgres lane.
*/
import { PLUGIN_SQL_NUL_REFUSAL } from '../../../../../src/db/engine/plugin-data-contract';
import {
checkPlaceholders,
checkQualifiers,
@@ -57,6 +58,31 @@ describe('plugin SQL guard', () => {
'SELECT 1 -- public.users\r',
'SELECT 1 -- public.users\r\nFROM notes',
'SELECT\t1\f',
// A value of the plugin's own may carry a system column's name where it is given.
'SELECT min(lat) AS ymin, min(lng) AS xmin, max(lng) AS xmax FROM places',
'SELECT min(lng) AS "xmin" FROM places',
'WITH b(xmin, ymin) AS (SELECT 1, 2) SELECT * FROM b',
'WITH a AS (SELECT 1), b(ctid) AS NOT MATERIALIZED (SELECT 1) SELECT * FROM b',
'SELECT * FROM (SELECT 1, 2) AS b(xmin, xmax)',
// A column of the plugin's own may be called xid, without its table.
'CREATE TABLE payments (id bigserial PRIMARY KEY, xid text NOT NULL UNIQUE)',
'ALTER TABLE payments ADD COLUMN xid text',
'SELECT xid, count(*) FROM payments WHERE xid = $1 AND NOT xid IS NULL GROUP BY xid ORDER BY xid',
'INSERT INTO payments (id, xid) VALUES (1, $1) ON CONFLICT (xid) DO NOTHING',
'UPDATE payments SET xid = $1 WHERE id = $2 RETURNING xid',
'SELECT id AS xid FROM payments',
"SELECT CASE WHEN xid = 'a' THEN xid ELSE NULL END, coalesce(xid, '') FROM payments",
// The collations and access methods every server has.
'SELECT body FROM notes ORDER BY body COLLATE "C", body COLLATE "POSIX", body COLLATE "default"',
'SELECT body COLLATE ucs_basic FROM notes',
'CREATE INDEX i ON notes USING gin (tags)',
'CREATE INDEX i ON notes USING brin (id)',
'CREATE TABLE t (x int) USING heap',
'ALTER TABLE notes ADD EXCLUDE USING gist (r WITH &&)',
'ALTER TABLE notes ALTER id TYPE int USING id::int',
'SELECT * FROM notes JOIN tags USING (id)',
'DELETE FROM notes USING trash WHERE notes.id = trash.note_id',
"SELECT collation FROM notes WHERE collation = 'x'",
// Characters JavaScript reads differently are fine inside strings, quoted names and comments.
"SELECT 'a b
c\u000bd'",
'SELECT 1 AS "a b"',
@@ -149,7 +175,7 @@ describe('plugin SQL guard', () => {
expect(() => check(sql)).toThrow(reason);
});
// The two bypasses of the final review, with their variants: each was let through, and Postgres ran it.
// Bypasses an earlier guard let through and Postgres ran, with their variants.
it.each([
// A `--` comment ended by a bare CR hid the rest from the guard, which Postgres then ran.
['select 1 --\rfrom public.users', /another schema/],
@@ -179,7 +205,7 @@ describe('plugin SQL guard', () => {
['CREATE TEMP VIEW v AS SELECT 1', /CREATE TEMP is not allowed/],
['CREATE OR REPLACE TEMP VIEW v AS SELECT 1', /CREATE TEMP is not allowed/],
['CREATE TEMPORARY SEQUENCE s', /CREATE TEMPORARY is not allowed/],
// The re-review's bypasses. A column alias named insert or merge in front of INTO made a table.
// A column alias named insert or merge in front of INTO made a table.
['select 1 insert into t1', /SELECT \.\.\. INTO/],
['select 1 merge into t9', /SELECT \.\.\. INTO/],
['select 1 insert into unlogged t10', /SELECT \.\.\. INTO/],
@@ -187,6 +213,53 @@ describe('plugin SQL guard', () => {
['WITH x AS (SELECT 1) SELECT 1 insert INTO t', /SELECT \.\.\. INTO/],
['insert into notes select 1 insert into t', /SELECT \.\.\. INTO/],
['select 1 insert into temp t', /SELECT \.\.\. INTO TEMP/],
// A read of a system column, quoted or not, wherever it stands.
['select xmin, xmax from notes', /"xmin" reads a Postgres system column/],
['select n.xmax from notes n', /"xmax" reads a Postgres system column/],
['select cmin, cmax from notes', /"cmin" reads a Postgres system column/],
['select ctid from notes order by 1', /"ctid" reads a Postgres system column/],
['select "tableoid" from notes', /"tableoid" reads a Postgres system column/],
['update notes set body = $1 where id = $2 and xmin = $3', /"xmin" reads a Postgres system column/],
['delete from notes returning ctid', /"ctid" reads a Postgres system column/],
['select min(id) xmin from notes', /"xmin" reads a Postgres system column/],
['WITH b(xmin) AS (SELECT 1) SELECT xmin FROM b', /"xmin" reads a Postgres system column/],
['select * from notes n, f(xmin) as (a int)', /"xmin" reads a Postgres system column/],
['select * from notes n, f(xmin, ctid) as (a int)', /"xmin" reads a Postgres system column/],
// A transaction id type where the word stands for the type.
["select age('3'::xid)", /"xid" stands for a transaction id type/],
["select cast('3' as xid8)", /"xid8" stands for a transaction id type/],
["select treat('3' as xid)", /"xid" stands for a transaction id type/],
["select age(xid '3')", /"xid" stands for a transaction id type/],
["select age(xid('3'))", /"xid" stands for a transaction id type/],
['select age($1.xid)', /"xid" stands for a transaction id type/],
["select age(u.xid) from unnest(array['3']) u", /"xid" stands for a transaction id type/],
["select age(('3').xid)", /"xid" stands for a transaction id type/],
['CREATE TABLE t (x _xid)', /"_xid" stands for a transaction id type/],
['CREATE TABLE t ("x" xid)', /"xid" stands for a transaction id type/],
["select '{}'::xid8[]", /"xid8" stands for a transaction id type/],
['select * from notes n, json_to_record(n.j) as x(a xid)', /"xid" stands for a transaction id type/],
['ALTER TABLE t ALTER COLUMN c TYPE xid', /"xid" stands for a transaction id type/],
['ALTER TABLE t ADD COLUMN c xid', /"xid" stands for a transaction id type/],
["select json_value('3', '$' returning xid)", /"xid" stands for a transaction id type/],
['CREATE TYPE r AS RANGE (subtype = xid8)', /"xid8" stands for a transaction id type/],
['CREATE TYPE c AS (a xid)', /"xid" stands for a transaction id type/],
[
'insert into pay (id, xid) values (1, $1) on conflict (id) do update set xid = excluded.xid',
/"xid" stands for a transaction id type.*excluded\.xid in an upsert/,
],
// A collation or an access method whose presence depends on the server.
[`select 'a' collate "de-x-icu"`, /a collation other than "C"/],
[`select body from notes order by body collate "de_DE.utf8"`, /a collation other than "C"/],
['select body from notes order by body collate C', /a collation other than "C"/],
[`select 'a' collate trek_plugin_notes."C"`, /a collation other than "C"/],
[`CREATE TABLE t (a text COLLATE "und-x-icu")`, /a collation other than "C"/],
[`CREATE TYPE r AS RANGE (subtype = text, collation = "de-x-icu")`, /a collation other than "C"/],
['CREATE INDEX i ON notes USING bloom (body)', /built-in access methods/],
['CREATE INDEX i ON notes USING "BTREE" (body)', /built-in access methods/],
['CREATE TABLE t (x int) USING columnar', /built-in access methods/],
['CREATE MATERIALIZED VIEW mv USING columnar AS SELECT 1', /built-in access methods/],
['ALTER TABLE notes SET ACCESS METHOD columnar', /built-in access methods/],
['ALTER TABLE notes ADD EXCLUDE USING bloom (body WITH =)', /built-in access methods/],
// The reg* types and functions that look an object up by a name in a string, in every spelling.
["select 'public.users'::regtype::oid", /"regtype" may not be named/],
["select cast('int4' as regtype)", /"regtype" may not be named/],
@@ -208,8 +281,6 @@ describe('plugin SQL guard', () => {
['CREATE TABLE grants (a aclitem)', /"aclitem" may not be named/],
// A base type is built from C functions, which only a superuser may do.
['CREATE TYPE fake (INPUT = int4in, OUTPUT = int4out, INTERNALLENGTH = 1000)', /composite, enum or range/],
// The protocol ends a statement's text at a NUL, in a string as anywhere else.
["select 'a\u0000' -- then\nfrom public.users", /U\+0000/],
['CREATE INDEX i (x)', /must name its table with ON/],
['ALTER TABLE', /could not be read/],
])('refuses the bypass %j', (sql, reason) => {
@@ -224,7 +295,6 @@ describe('plugin SQL guard', () => {
['PARAGRAPH SEPARATOR', '
', 'U+2029'],
['IDEOGRAPHIC SPACE', ' ', 'U+3000'],
['vertical tab', '\u000b', 'U+000B'],
['NUL', '\u0000', 'U+0000'],
['escape', '\u001b', 'U+001B'],
['DEL', '\u007f', 'U+007F'],
])('refuses a %s outside a string, which JavaScript and Postgres read differently', (_name, ch, code) => {
@@ -239,6 +309,19 @@ describe('plugin SQL guard', () => {
}
});
it('refuses a NUL anywhere, in a string too, with the words the stores of both engines use', () => {
// The protocol ends a statement's text at a NUL, so what Postgres would read is not what was checked.
for (const sql of [
"select 'a\u0000' -- then\nfrom public.users",
'SELECT 1\u0000FROM public.users',
'\u0000SELECT 1',
'SELECT "a\u0000b" FROM notes',
]) {
expect(() => tokenize(sql), JSON.stringify(sql)).toThrow(PLUGIN_SQL_NUL_REFUSAL);
expect(() => check(sql), JSON.stringify(sql)).toThrow(PLUGIN_SQL_NUL_REFUSAL);
}
});
it('reads nested block comments as Postgres does, so code after the inner close is still a comment', () => {
expect(() => check('SELECT 1 /* outer /* inner */ public.users */')).not.toThrow();
expect(() => check('SELECT 1 /* one */ FROM public.users')).toThrow(/another schema/);