fix(db): hold plugin SQL on Postgres in layers the database enforces

The token guard kept leaking: on a superuser connection an unqualified
`alter type int4 rename to int4x` renamed pg_catalog's type for the whole
server, sequences and catalog-only objects grew the database past the quota,
regtype/regconfig/regdictionary looked TREK's objects up by name, and a
column alias named insert or merge in front of INTO made a table. Instead
of a longer word list, the store now asks the database:

- No plugin SQL while TREK's role is privileged in the sense of the restore
  check (PRIVILEGED_ROLE_SQL, imported from server-checks.ts): every db:own
  call fails with PRIVILEGED_ROLE_PLUGIN_REFUSAL, read once per pool
  connection, and the boot log says why.
- The objects an ALTER, DROP, REFRESH, TRUNCATE or CREATE INDEX ... ON
  changes, and the tables a CREATE or ALTER TABLE ties to its own, are
  resolved with to_regclass/to_regtype in the transaction right before the
  statement, and it is refused unless each one found lies in the plugin's
  schema. An unqualified int4, text or box is pg_catalog's and refused even
  with the role check off.
- The quota counts every relation of the schema with its TOAST table, and a
  schema holds at most PLUGIN_SCHEMA_MAX_OBJECTS catalog objects (relations,
  types, constraints, enum labels).
- The guard refuses every reg* type and its array in every spelling, the
  has_*_privilege functions, currtid2 and the BRIN/GIN maintenance
  functions; INTO only after the INSERT or MERGE that is the statement's
  verb or a WITH body's; TEMP only where it makes a temporary object
  (CREATE TEMP/TEMPORARY, SELECT ... INTO TEMP), so a column named temp
  works again; a base type; and a NUL anywhere in the SQL text.
- A bound value or a migration id holding NUL is refused with the reason
  instead of being stripped, so the plugin's keys never change meaning.

Every bypass from the re-review is a test on the real database, on the
role the plugin data is meant to run as and on a superuser connection with
the role check off.
This commit is contained in:
Maurice
2026-11-17 22:28:38 +01:00
parent da1a02e7a8
commit f1ea716305
10 changed files with 1097 additions and 151 deletions
@@ -0,0 +1,161 @@
import type { PluginSqlClient } from './plugin-data-store';
import { PluginSqlRefused, type PluginStatement } from './plugin-sql-guard';
import { PRIVILEGED_ROLE_DESCRIPTION, PRIVILEGED_ROLE_SQL } from './server-checks';
/**
* The checks the Postgres plugin store (`plugin-data-store.ts`) asks the
* database itself, behind the token guard (`plugin-sql-guard.ts`): whether
* TREK's role may run plugin SQL at all, which schema the objects a statement
* changes really live in, and how much the plugin's schema holds.
*/
/**
* Why plugin databases are refused while TREK connects as a privileged role:
* every statement a plugin sends runs as that role, and such a role may
* change the system catalogs or reach the database host, which no check on
* the SQL can rule out.
*/
export const PRIVILEGED_ROLE_PLUGIN_REFUSAL =
`Plugin databases (db:own) are refused on Postgres while TREK_DB_URL connects as ${PRIVILEGED_ROLE_DESCRIPTION}: ` +
"a plugin's SQL runs as TREK's role. Connect TREK as a role that owns its database and is not a superuser " +
'(see the wiki page "Database: Postgres").';
/** Asks whether TREK's role is privileged before a plugin call runs on a connection. */
export interface PluginRoleGate {
/** Throws {@link PRIVILEGED_ROLE_PLUGIN_REFUSAL} when the role `client` is connected as is privileged. */
refuseIfPrivileged(client: PluginSqlClient): Promise<void>;
}
/**
* The role check of {@link PRIVILEGED_ROLE_SQL}, read once per pool
* connection and kept for as long as that connection lives. A new connection,
* after a restart, a reconnect or the pool replacing one, reads it again, so a
* role that gained or lost a privilege is seen without a restart once the pool
* has turned over; the check costs one query per connection, not per call.
*/
export class PrivilegedRoleGate implements PluginRoleGate {
private readonly answers = new WeakMap<PluginSqlClient, Promise<boolean>>();
async refuseIfPrivileged(client: PluginSqlClient): Promise<void> {
if (await this.privileged(client)) throw new Error(PRIVILEGED_ROLE_PLUGIN_REFUSAL);
}
/** Whether the role `client` is connected as is privileged; a failed read is not kept. */
privileged(client: PluginSqlClient): Promise<boolean> {
let answer = this.answers.get(client);
if (answer === undefined) {
answer = client
.query(`select (${PRIVILEGED_ROLE_SQL}) as privileged`)
.then((result) => (result.rows as Array<{ privileged?: boolean }>)[0]?.privileged === true);
void answer.catch(() => this.answers.delete(client));
this.answers.set(client, answer);
}
return answer;
}
}
/**
* Refuses `statement` unless every object it changes ({@link PluginStatement.targets})
* that exists lies in `schema`. Run inside the call's transaction right
* before the statement, so it sees what the statements before it made,
* renamed or dropped. Postgres resolves each name itself with `to_regclass`
* or `to_regtype` on the plugin's `search_path`, where `pg_catalog` is
* searched first: an unqualified `int4`, `text` or `box` is the catalog's
* type and refused here, whatever the role may do. A name that resolves to
* nothing is left to the statement.
*/
export async function refuseForeignTargets(
client: PluginSqlClient,
statement: PluginStatement,
schema: string,
): Promise<void> {
if (statement.targets.length === 0) return;
const result = await client.query({
text:
'select t.name, n.nspname from unnest($1::text[], $2::text[]) as t(name, kind) ' +
'join pg_namespace n on n.oid = case t.kind ' +
"when 'type' then (select typnamespace from pg_type where oid = to_regtype(t.name)) " +
'else (select relnamespace from pg_class where oid = to_regclass(t.name)) end ' +
'where n.nspname <> $3',
values: [
statement.targets.map((t) => t.name.map(quoteName).join('.')),
statement.targets.map((t) => t.kind),
schema,
],
});
const [foreign] = result.rows as Array<{ name: string; nspname: string }>;
if (foreign !== undefined) {
throw new PluginSqlRefused(
`${foreign.name} is an object of the schema "${foreign.nspname}"; a plugin changes its own objects only`,
);
}
}
/** `part` as a quoted identifier, as `to_regclass` and `to_regtype` read it. */
function quoteName(part: string): string {
return `"${part.replaceAll('"', '""')}"`;
}
/**
* The most catalog objects one plugin schema may hold: its relations (tables,
* indexes, sequences, views, materialized views), types (each table brings its
* row type and that type's array), constraints and enum labels. An empty
* table, a view or an enum label takes no disk space the quota sees but adds
* rows to the system catalogs, so their number is held on its own.
*/
export const PLUGIN_SCHEMA_MAX_OBJECTS = 5_000;
/** What a plugin schema holds, as the quota measures it. */
export interface SchemaUsage {
/** Bytes on disk of every relation of the schema and of each one's TOAST table. */
bytes: number;
/** Catalog objects, as {@link PLUGIN_SCHEMA_MAX_OBJECTS} counts them. */
objects: number;
}
/**
* The disk space and the catalog objects of `schema`. Every relation is
* counted once, whatever its kind (tables, partitions, indexes, sequences,
* materialized views; a view has no storage), each with all its forks, and
* a table's TOAST table, which lives in `pg_toast`, through its
* `reltoastrelid` with the TOAST table's own index.
*/
export async function schemaUsage(client: PluginSqlClient, schema: string): Promise<SchemaUsage> {
const result = await client.query({
text:
'select coalesce((select sum(' +
"pg_relation_size(c.oid, 'main') + pg_relation_size(c.oid, 'fsm') + pg_relation_size(c.oid, 'vm') + " +
"pg_relation_size(c.oid, 'init') + " +
'case when c.reltoastrelid <> 0 then pg_total_relation_size(c.reltoastrelid) else 0 end) ' +
'from pg_class c where c.relnamespace = n.oid), 0) as bytes, ' +
'(select count(*) from pg_class c where c.relnamespace = n.oid) + ' +
'(select count(*) from pg_type t where t.typnamespace = n.oid) + ' +
'(select count(*) from pg_constraint k where k.connamespace = n.oid) + ' +
'(select count(*) from pg_enum e join pg_type t on t.oid = e.enumtypid where t.typnamespace = n.oid) as objects ' +
'from pg_namespace n where n.nspname = $1',
values: [schema],
});
const [row] = result.rows as Array<{ bytes?: number | string; objects?: number | string }>;
return { bytes: Number(row?.bytes ?? 0), objects: Number(row?.objects ?? 0) };
}
/**
* Refuses a plugin's bound value that holds U+0000 (NUL): Postgres text
* cannot store the character, and TREK will not change what a plugin asked
* to store or compare (`'a\0b'` and `'ab'` are different keys on SQLite).
* A string, or a string anywhere in an array, is checked; a Buffer goes to
* `bytea`, which holds any byte.
*/
export function refuseNulValues(values: readonly unknown[]): void {
if (values.some(holdsNul)) {
throw new Error(
'a plugin argument holds the character U+0000 (NUL), which Postgres text cannot store; ' +
'TREK refuses it instead of changing the value. Remove it, or bind binary data as a Buffer (bytea)',
);
}
}
function holdsNul(value: unknown): boolean {
if (typeof value === 'string') return value.includes('\u0000');
return Array.isArray(value) && value.some(holdsNul);
}
@@ -1,5 +1,13 @@
import { nulFreeParameter } from '../../nul-free';
import { PLUGIN_DATA_CAPS, type PluginDataStore, type PluginTxOp, type PluginTxResult } from '../plugin-data';
import {
PLUGIN_SCHEMA_MAX_OBJECTS,
PrivilegedRoleGate,
refuseForeignTargets,
refuseNulValues,
schemaUsage,
type PluginRoleGate,
type SchemaUsage,
} from './plugin-data-checks';
import { isPluginId, pluginSchemaName, quotePluginSchema } from './plugin-schema';
import { checkPlaceholders, checkQualifiers, parsePluginSql, type PluginStatement } from './plugin-sql-guard';
@@ -12,19 +20,27 @@ import Cursor from 'pg-cursor';
*
* Every call checks a `pg` client out of the pool for itself
* ({@link poolClients}) and runs one transaction on it directly, not through
* Kysely. The transaction first makes sure the schema and its migration table
* exist, then puts only that schema on the `search_path`, with `pg_temp`
* explicitly last so a temporary table is never found before the plugin's
* own, and sets `statement_timeout` to the call's time budget; every setting
* is `local` and ends with the transaction. The plugin's SQL is checked by
* `plugin-sql-guard.ts` before it runs, so it cannot name another schema, and
* each statement goes to Postgres on its own over the extended query
* protocol, which runs one statement and no more: a write as a query with
* `queryMode: 'extended'`, which `pg` honours even without values, and a read
* through a `pg-cursor`, which always uses that protocol. Reads stop at the
* row cap. A call that may write measures the schema's size before and
* after, and rolls back one that leaves it past the quota and larger than it
* found it, so a plugin at its quota can still delete. Before the client goes
* Kysely. Before the transaction it refuses the call outright while TREK's
* role is privileged (`PrivilegedRoleGate` in `plugin-data-checks.ts`, read
* once per connection). The transaction first makes sure the schema and its
* migration table exist, then puts only that schema on the `search_path`,
* with `pg_temp` explicitly last so a temporary table is never found before
* the plugin's own, and sets `statement_timeout` to the call's time budget;
* every setting is `local` and ends with the transaction. The plugin's SQL is
* checked by `plugin-sql-guard.ts` before it runs, so it cannot name another
* schema; right before each statement, the existing objects it changes are
* resolved by Postgres and must lie in the plugin's schema
* (`refuseForeignTargets`); and each statement goes to Postgres on its own
* over the extended query protocol, which runs one statement and no more: a
* write as a query with `queryMode: 'extended'`, which `pg` honours even
* without values, and a read through a `pg-cursor`, which always uses that
* protocol. A bound value or a migration id holding U+0000 is refused before
* anything runs, since Postgres text cannot hold it and changing it would
* change the plugin's data. Reads stop at the row cap. A call that may write
* measures the schema before and after (`schemaUsage`: the bytes of every
* relation with its TOAST table, and the catalog objects), and rolls back one
* that leaves it past the quota or the object cap and larger than it found
* it, so a plugin at either limit can still delete. Before the client goes
* back to the pool, whatever session state a statement could have left on it
* is dropped ({@link END_SESSION}); a client that cannot be brought back to a
* clean state is closed instead of reused.
@@ -47,6 +63,8 @@ interface PostgresPluginDataLimits {
maxRows: number;
timeBudgetMs: number;
quotaBytes: number;
/** The most catalog objects the schema may hold (`PLUGIN_SCHEMA_MAX_OBJECTS`). */
maxObjects: number;
/** The clock the time budget reads. */
now: () => number;
}
@@ -55,6 +73,7 @@ const DEFAULT_LIMITS: PostgresPluginDataLimits = {
maxRows: PLUGIN_DATA_CAPS.maxRows,
timeBudgetMs: PLUGIN_DATA_CAPS.timeBudgetMs,
quotaBytes: PLUGIN_DATA_CAPS.quotaBytes,
maxObjects: PLUGIN_SCHEMA_MAX_OBJECTS,
now: () => Date.now(),
};
@@ -166,6 +185,7 @@ export class PostgresPluginDataStore implements PluginDataStore {
private readonly connect: ConnectPluginClient,
private readonly slots: PluginDataSlots,
limits: Partial<PostgresPluginDataLimits> = {},
private readonly roleGate: PluginRoleGate = new PrivilegedRoleGate(),
) {
this.schema = pluginSchemaName(pluginId);
this.quoted = quotePluginSchema(this.schema);
@@ -242,6 +262,7 @@ export class PostgresPluginDataStore implements PluginDataStore {
/** No time budget, as on SQLite: a migration stopped part of the way would fail the same way on every start. */
async migrate(id: string, sql: string): Promise<{ applied: boolean }> {
const statements = this.parse(sql);
refuseNulValues([id]);
return this.enqueue(() =>
this.transaction(null, statements, async (client) => {
const seen = await client.query({
@@ -264,6 +285,7 @@ export class PostgresPluginDataStore implements PluginDataStore {
const statements = this.parse(sql);
if (statements.length !== 1) throw new Error('sql must hold exactly one statement here; use exec() for a script');
checkPlaceholders(statements[0], args);
refuseNulValues(args);
return statements[0];
}
@@ -327,6 +349,7 @@ export class PostgresPluginDataStore implements PluginDataStore {
const client = await this.connect();
let reusable = true;
try {
await this.roleGate.refuseIfPrivileged(client);
await client.query('begin');
try {
const result = await this.inTransaction(client, timeoutMs, statements, work);
@@ -368,17 +391,29 @@ export class PostgresPluginDataStore implements PluginDataStore {
for (const statement of statements) checkQualifiers(statement, this.schema, schemas);
}
const writes = statements.some((s) => s.mayWrite);
const before = writes ? await this.sizeBytes(client) : 0;
const before = writes ? await schemaUsage(client, this.schema) : null;
const result = await work(client);
if (writes) {
const after = await this.sizeBytes(client);
if (after > this.limits.quotaBytes && after > before) {
throw new Error(`the plugin database is past its ${this.limits.quotaBytes / 1024 / 1024} MB quota`);
}
}
if (before !== null) this.checkQuota(before, await schemaUsage(client, this.schema));
return result;
}
/**
* Refuses a call that left the schema past its quota or its object cap and
* grew it there, so a plugin at either limit can still delete.
*/
private checkQuota(before: SchemaUsage, after: SchemaUsage): void {
const { quotaBytes, maxObjects } = this.limits;
if (after.bytes > quotaBytes && after.bytes > before.bytes) {
throw new Error(`the plugin database is past its ${quotaBytes / 1024 / 1024} MB quota`);
}
if (after.objects > maxObjects && after.objects > before.objects) {
throw new Error(
`the plugin database holds more than ${maxObjects} catalog objects (tables, indexes, sequences, views, ` +
'types, constraints, enum labels)',
);
}
}
private async setTimeout(client: PluginSqlClient, ms: number): Promise<void> {
await client.query({
text: "select set_config('statement_timeout', $1, true)",
@@ -392,30 +427,19 @@ export class PostgresPluginDataStore implements PluginDataStore {
return new Set((result.rows as Array<{ nspname: string }>).map((row) => row.nspname));
}
/** What this plugin's tables, indexes and materialized views take on disk. */
private async sizeBytes(client: PluginSqlClient): Promise<number> {
const result = await client.query({
text:
'select coalesce(sum(pg_total_relation_size(c.oid)), 0) as bytes from pg_class c ' +
"join pg_namespace n on n.oid = c.relnamespace where n.nspname = $1 and c.relkind in ('r', 'm')",
values: [this.schema],
});
const [row] = result.rows as Array<{ bytes: number | string }>;
return Number(row?.bytes ?? 0);
}
/**
* Runs a statement for its effect: the rows it changed, or 0 for a read,
* whose rows are read past and dropped. Both go over the extended protocol:
* a write as an extended query, a read through a cursor.
*/
private async run(client: PluginSqlClient, statement: PluginStatement, args: readonly unknown[]): Promise<number> {
await refuseForeignTargets(client, statement, this.schema);
if (!statement.mayWrite) {
// Read to the end so the statement runs whole; its rows are not wanted.
await readCursor(client.query(new Cursor(statement.text, boundValues(args))), () => undefined);
await readCursor(client.query(new Cursor(statement.text, [...args])), () => undefined);
return 0;
}
const result = await client.query({ text: statement.text, values: boundValues(args), queryMode: 'extended' });
const result = await client.query({ text: statement.text, values: [...args], queryMode: 'extended' });
return result.rowCount ?? 0;
}
@@ -430,8 +454,9 @@ export class PostgresPluginDataStore implements PluginDataStore {
budget: RowBudget,
checkTime: () => void,
): Promise<unknown[]> {
await refuseForeignTargets(client, statement, this.schema);
const rows: unknown[] = [];
await readCursor(client.query(new Cursor(statement.text, boundValues(args))), (chunk) => {
await readCursor(client.query(new Cursor(statement.text, [...args])), (chunk) => {
if (rows.length > 0) checkTime();
for (const row of chunk) {
rows.push(row);
@@ -443,11 +468,6 @@ export class PostgresPluginDataStore implements PluginDataStore {
}
}
/** A plugin's args as they are bound: without NUL, which Postgres text cannot hold (`nul-free.ts`). */
function boundValues(args: readonly unknown[]): unknown[] {
return args.map(nulFreeParameter);
}
/**
* Reads `cursor` to its end a chunk at a time, handing each chunk to `take`
* (which may throw to stop the read), and closes it however the read ends.
+273 -39
View File
@@ -7,19 +7,40 @@ import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema';
* TREK's tables at all. On Postgres its schema sits in TREK's database and
* its statements run as TREK's role, which may read every table TREK has: a
* role per plugin would need CREATEROLE, which TREK's role is not given. So
* three layers keep it in, each enough on its own for what it covers:
* the store (`plugin-data-store.ts`) keeps it in with layers that each hold
* on their own for what they cover, the ones after this guard enforced by
* the database itself:
*
* 1. This guard holds the statement to what cannot leave the schema, before
* it runs.
* 2. The store sends every statement on its own over the extended query
* protocol, on a pool client it checked out for the call
* (`plugin-data-store.ts`): Postgres parses exactly one statement there,
* so a second statement the guard missed is an error, never run.
* 3. The transaction puts the plugin's schema on the `search_path` with
* 1. No plugin SQL at all while TREK's role is privileged in the sense of the
* restore check (`PRIVILEGED_ROLE_SQL` in `server-checks.ts`: a superuser
* or a member of one, a role that may reach the server's files or
* programs, ...): every `db:own` call fails with
* `PRIVILEGED_ROLE_PLUGIN_REFUSAL`, and the boot log says why
* (`plugin-data-checks.ts`). Such a role may change the system catalogs,
* which no check on the SQL text can rule out.
* 2. This guard holds each statement to what cannot leave the schema, before
* it runs (below).
* 3. Every existing object a statement changes ({@link PluginTarget}: the
* target of an ALTER, DROP, REFRESH, TRUNCATE or CREATE INDEX ... ON, and
* the tables a CREATE or ALTER TABLE ties to its own) is resolved by
* Postgres in the transaction, right before the statement, with
* `to_regclass` or `to_regtype` on the plugin's `search_path`, and the
* statement is refused unless each one found lies in the plugin's schema.
* `pg_catalog` is searched first, so an unqualified `int4`, `text` or
* `box` is the catalog's type and refused, on a superuser connection too.
* 4. The store sends every statement on its own over the extended query
* protocol, on a pool client it checked out for the call: Postgres parses
* exactly one statement there, so a second statement the guard missed is
* an error, never run.
* 5. The transaction puts the plugin's schema on the `search_path` with
* `pg_temp` explicitly last, TREK's own pool connections put `pg_temp`
* last too (`session-search-path.ts`), and the store drops every
* temporary table on its client before giving it back, so a temporary
* table never stands in for a table of TREK's or of the plugin's.
* 6. A call that may write is held to the disk quota, counted over every
* relation of the schema with its TOAST table, and to
* `PLUGIN_SCHEMA_MAX_OBJECTS` catalog objects, so views, types and enum
* labels, which take no disk space of their own, are bounded too.
*
* The SQL is split into tokens the way Postgres's own lexer splits it (string
* and identifier quoting, comments, dollar signs). Where JavaScript and the
@@ -27,12 +48,14 @@ import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema';
* instead of guessing: whitespace is exactly what Postgres skips (space, tab,
* CR, LF, form feed), a `--` comment ends at CR or LF as it does there, and
* any other control character, or whitespace past ASCII (U+00A0, U+FEFF,
* U+2028, ...), outside a string, a quoted name or a comment is refused. The
* SQL is refused when it holds:
* U+2028, ...), outside a string, a quoted name or a comment is refused. A
* NUL is refused anywhere, strings included: the protocol ends a statement's
* text there. The SQL is refused when it holds:
*
* - a statement other than SELECT, INSERT, UPDATE, DELETE, MERGE, WITH,
* VALUES, TABLE, TRUNCATE, REFRESH, or a CREATE, ALTER or DROP of a table,
* index, view, materialized view, sequence or type. No function, schema,
* index, view, materialized view, sequence or type (a composite, enum or
* range type; a base type is built from C functions). No function, schema,
* role, setting, transaction control, COPY, LOCK, prepared statement or
* notification. Several statements are split at their semicolons and each
* is checked;
@@ -43,11 +66,21 @@ import { PLUGIN_SCHEMA_PREFIX } from './plugin-schema';
* - a function that runs SQL handed to it as text (`query_to_xml`, `ts_stat`,
* `ts_rewrite`), reads or changes settings (`set_config`,
* `current_setting`), reaches objects by a name in a string (`nextval`,
* `setval`, the `reg*` casts), large objects (`lo_*`) or `dblink`;
* - the words TEMP and TEMPORARY anywhere outside a string or a quoted name,
* and INTO anywhere but right after INSERT or MERGE, at any depth of
* parentheses: a temporary table outlives the call on a pooled connection,
* and `SELECT ... INTO` creates a table outside what CREATE is held to;
* `setval`, `has_table_privilege` and its siblings, `currtid2`, the BRIN
* and GIN maintenance functions, `to_reg*`), large objects (`lo_*`) or
* `dblink`;
* - the object identifier types that look an object up by name
* (`regclass`, `regtype`, `regproc`, `regprocedure`, `regoper`,
* `regoperator`, `regconfig`, `regdictionary`, `regnamespace`, `regrole`,
* `regcollation`, and their array types `_regclass`, ...), in every
* spelling: `'x'::regtype`, `CAST('x' AS regtype)`, `regtype 'x'`, quoted;
* - a temporary object: CREATE TEMP or TEMPORARY (also after OR REPLACE,
* LOCAL or GLOBAL), and SELECT ... INTO TEMP; a temporary table outlives
* the call on a pooled connection. Elsewhere `temp` is an ordinary name;
* - INTO anywhere but right after the verb INSERT or MERGE of the statement
* itself or of a WITH query's body, at any depth of parentheses: `SELECT
* ... INTO` creates a table outside what CREATE is held to, and in `SELECT
* 1 insert INTO t` the word `insert` is only a column alias;
* - `WITH RECURSIVE`, refused on SQLite too;
* - in an ALTER, a change of a table's schema, owner or tablespace;
* - escape strings (`E'...'`), Unicode escapes (`U&'...'`), dollar-quoted
@@ -92,6 +125,27 @@ export interface PluginStatement {
readonly qualifies: boolean;
/** How many `$n` placeholders it holds. */
readonly params: number;
/**
* The existing objects it changes, which the store resolves in the
* transaction right before the statement runs and refuses unless each one
* found lies in the plugin's own schema ({@link PluginTarget}).
*/
readonly targets: readonly PluginTarget[];
}
/**
* An existing object a statement changes: the table, index, view,
* materialized view or sequence (`relation`) or the type an ALTER, DROP,
* REFRESH or TRUNCATE names, the table a CREATE INDEX is ON, and the tables a
* CREATE or ALTER TABLE ties to its own (REFERENCES, INHERITS, PARTITION OF,
* ATTACH, DETACH and INHERIT). `name` holds the name's parts as Postgres
* keeps them (folded unless quoted, cut to 63 bytes), qualifier first. A
* name that resolves to nothing is left to Postgres, which reports it missing
* or, with IF EXISTS, skips it.
*/
export interface PluginTarget {
readonly kind: 'relation' | 'type';
readonly name: readonly string[];
}
/** Postgres keeps the first 63 bytes of a name (NAMEDATALEN - 1) and drops the rest. */
@@ -126,6 +180,26 @@ const VERBS = new Set(['select', 'insert', 'update', 'delete', 'merge', 'values'
/** The verbs of a statement that only reads. */
const READ_VERBS = new Set(['select', 'values', 'table']);
/**
* The object identifier types whose input looks an object up by a name in a
* string (`'public.users'::regclass`, `CAST('int4' AS regtype)`,
* `regtype 'text'`), refused in every spelling, their array types
* (`_regclass`) too.
*/
const NAME_LOOKUP_TYPES = [
'regclass',
'regtype',
'regproc',
'regprocedure',
'regoper',
'regoperator',
'regconfig',
'regdictionary',
'regnamespace',
'regrole',
'regcollation',
];
/** Functions and types refused under any spelling, quoted or not. */
const REFUSED_NAMES = new Set([
'set_config',
@@ -138,14 +212,29 @@ const REFUSED_NAMES = new Set([
'lastval',
'loread',
'lowrite',
'regclass',
'regproc',
'regprocedure',
'regoper',
'regoperator',
'regnamespace',
'regrole',
'regcollation',
...NAME_LOOKUP_TYPES,
...NAME_LOOKUP_TYPES.map((type) => `_${type}`),
// Functions that take a relation, a type or another object by a name in a
// string, or reach an index by one to maintain it.
'has_any_column_privilege',
'has_column_privilege',
'has_database_privilege',
'has_foreign_data_wrapper_privilege',
'has_function_privilege',
'has_language_privilege',
'has_parameter_privilege',
'has_schema_privilege',
'has_sequence_privilege',
'has_server_privilege',
'has_table_privilege',
'has_tablespace_privilege',
'has_type_privilege',
'row_security_active',
'currtid2',
'brin_summarize_new_values',
'brin_summarize_range',
'brin_desummarize_range',
'gin_clean_pending_list',
'information_schema',
]);
@@ -166,8 +255,10 @@ const PUNCT = new Set([...'.,()[];+-*/<>=~!@#%^&|?']);
* tab is whitespace only from Postgres 16 on, so it is refused instead.
*/
const WHITESPACE = new Set([' ', '\t', '\n', '\r', '\f']);
/** The keywords INTO may follow. Anywhere else it makes a table (`SELECT ... INTO`). */
/** The verbs INTO may follow. Anywhere else it makes a table (`SELECT ... INTO`). */
const INTO_AFTER = new Set(['insert', 'merge']);
/** The words that make an object temporary right after CREATE (`CREATE LOCAL TEMP TABLE`). */
const TEMPORARY = new Set(['temp', 'temporary']);
/**
* Whether JavaScript and the Postgres lexer read `ch` differently: a control
@@ -208,6 +299,12 @@ function truncateName(name: string): string {
/** Splits `sql` into tokens, or refuses what this guard does not read the way Postgres would. */
export function tokenize(sql: string): Token[] {
if (sql.includes('\u0000')) {
// The protocol ends a statement's text at a NUL, so what Postgres would read is not what was checked.
throw new PluginSqlRefused(
'the SQL holds the character U+0000 (NUL), which Postgres cannot read in a statement or store in text',
);
}
const tokens: Token[] = [];
let i = 0;
const n = sql.length;
@@ -341,6 +438,11 @@ function keyword(token: Token | undefined): string | null {
return token?.kind === 'word' && !token.quoted ? token.value : null;
}
/** Whether `token` is the punctuation `value`. */
function isPunct(token: Token | undefined, value: string): boolean {
return token?.kind === 'punct' && token.value === value;
}
/** Reads what a statement's caller needs to know about it, and refuses one this guard does not allow. */
function describe(text: string, tokens: Token[]): PluginStatement {
const first = tokens[0];
@@ -355,9 +457,12 @@ function describe(text: string, tokens: Token[]): PluginStatement {
throw new PluginSqlRefused(`a statement may not start with ${describeToken(first)}`);
}
if (verb === 'create' || verb === 'alter' || verb === 'drop' || verb === 'refresh') checkObject(verb, tokens);
const targets = targetsOf(verb, tokens);
let depth = 0;
let main: string | null = verb === 'with' ? null : verb;
// Where the statement's own verb stands: its first token, or after a WITH clause the verb at depth 0.
let mainAt = verb === 'with' ? -1 : 0;
let returning = false;
let params = 0;
let qualifies = false;
@@ -370,12 +475,16 @@ function describe(text: string, tokens: Token[]): PluginStatement {
const after = tokens[index + 1];
if (after?.kind === 'punct' && after.value === '.') qualifies = true;
if (token.quoted) continue;
checkKeyword(token.value, keyword(tokens[index - 1]));
checkKeyword(token.value);
if (token.value === 'into') checkInto(tokens, index, mainAt);
if (verb === 'alter' && (token.value === 'schema' || token.value === 'owner')) {
throw new PluginSqlRefused(`an ALTER may not change the ${token.value}`);
}
if (depth !== 0) continue;
if (main === null && VERBS.has(token.value)) main = token.value;
if (main === null && VERBS.has(token.value)) {
main = token.value;
mainAt = index;
}
if (token.value === 'returning') returning = true;
}
@@ -391,6 +500,7 @@ function describe(text: string, tokens: Token[]): PluginStatement {
mayWrite: !reads || writesInside,
qualifies,
params,
targets,
};
}
@@ -399,6 +509,15 @@ function checkObject(verb: string, tokens: readonly Token[]): void {
let at = 1;
if (verb === 'create') {
if (keyword(tokens[at]) === 'or' && keyword(tokens[at + 1]) === 'replace') at += 2;
const scope = keyword(tokens[at]);
if (
TEMPORARY.has(scope ?? '') ||
((scope === 'local' || scope === 'global') && TEMPORARY.has(keyword(tokens[at + 1]) ?? ''))
) {
throw new PluginSqlRefused(
`CREATE ${describeToken(tokens[at])} is not allowed: a temporary object outlives the call on a pooled connection`,
);
}
while (keyword(tokens[at]) === 'unique' || keyword(tokens[at]) === 'unlogged') at++;
}
const object = keyword(tokens[at]);
@@ -406,29 +525,144 @@ function checkObject(verb: string, tokens: readonly Token[]): void {
if (!allowed) {
throw new PluginSqlRefused(`${verb.toUpperCase()} ${describeToken(tokens[at])} is not allowed`);
}
// A base type is made of C functions and needs a superuser; a composite, enum or range type says AS.
if (verb === 'create' && object === 'type' && isPunct(tokens[at + 2], '(')) {
throw new PluginSqlRefused('CREATE TYPE may make a composite, enum or range type (CREATE TYPE x AS ...) only');
}
}
/**
* Refuses an unquoted keyword that is never safe, at whatever depth of
* parentheses it sits: `previous` is the unquoted keyword before it, if any.
* TEMP and TEMPORARY make an object that outlives the call on a pooled
* connection. INTO anywhere but after INSERT or MERGE is `SELECT ... INTO`,
* which makes a table (a temporary one with TEMP) past what CREATE is held to;
* `(SELECT ... INTO t)` and `WITH x AS (...) SELECT ... INTO t` included.
* parentheses it sits.
*/
function checkKeyword(word: string, previous: string | null): void {
function checkKeyword(word: string): void {
if (word === 'recursive') throw new PluginSqlRefused('WITH RECURSIVE is not allowed');
if (word === 'tablespace') throw new PluginSqlRefused('a tablespace may not be named');
if (word === 'temp' || word === 'temporary') {
throw new PluginSqlRefused(
`temporary objects are not allowed (${word.toUpperCase()}); quote a name spelled "${word}"`,
);
}
/**
* Refuses the INTO at `index` unless it follows the verb INSERT or MERGE of
* the statement itself (`mainAt`) or of a WITH query's body (`AS (INSERT
* INTO ...`). Anywhere else it is `SELECT ... INTO`, which makes a table (a
* temporary one with TEMP) past what CREATE is held to, at any depth of
* parentheses: `(SELECT ... INTO t)`, `WITH x AS (...) SELECT ... INTO t`,
* and `SELECT 1 insert INTO t`, where `insert` is only a column alias.
*/
function checkInto(tokens: readonly Token[], index: number, mainAt: number): void {
const verbAt = index - 1;
const verb = keyword(tokens[verbAt]);
if (verb !== null && INTO_AFTER.has(verb) && (verbAt === mainAt || opensQueryBody(tokens, verbAt))) return;
const next = keyword(tokens[index + 1]);
if (next !== null && TEMPORARY.has(next)) {
throw new PluginSqlRefused(`SELECT ... INTO ${next.toUpperCase()} is not allowed: no temporary tables`);
}
if (word === 'into' && (previous === null || !INTO_AFTER.has(previous))) {
throw new PluginSqlRefused('SELECT ... INTO is not allowed; use CREATE TABLE ... AS');
throw new PluginSqlRefused('SELECT ... INTO is not allowed; use CREATE TABLE ... AS');
}
/** Whether the token at `index` is the first of a WITH query's body: `AS (`, `AS [NOT] MATERIALIZED (`. */
function opensQueryBody(tokens: readonly Token[], index: number): boolean {
if (!isPunct(tokens[index - 1], '(')) return false;
const before = keyword(tokens[index - 2]);
return before === 'as' || (before === 'materialized' && keyword(tokens[index - 3]) !== null);
}
/** A name of up to three parts (`t`, `s.t`, `db.s.t`) at `at` and the index past it; null when none starts there. */
function readName(tokens: readonly Token[], at: number): { name: string[]; next: number } | null {
const name: string[] = [];
let i = at;
for (;;) {
const token = tokens[i];
if (token?.kind !== 'word') return name.length === 0 ? null : { name, next: i };
name.push(token.value);
if (!isPunct(tokens[i + 1], '.')) return { name, next: i + 1 };
if (name.length === 3) throw new PluginSqlRefused('a name may have at most three parts');
i += 2;
}
}
/** The index past the unquoted keywords `words` at `at`, or `at` when they are not there. */
function skip(tokens: readonly Token[], at: number, ...words: string[]): number {
return words.every((word, i) => keyword(tokens[at + i]) === word) ? at + words.length : at;
}
/** The comma-separated names starting at `at`, each optionally led by ONLY or followed by `*` (TRUNCATE). */
function readNames(tokens: readonly Token[], at: number, what: string): string[][] {
const names: string[][] = [];
let i = at;
for (;;) {
const read = readName(tokens, skip(tokens, i, 'only'));
if (read === null) throw new PluginSqlRefused(`the object ${what} acts on could not be read`);
names.push(read.name);
i = read.next;
if (isPunct(tokens[i], '*')) i++;
if (!isPunct(tokens[i], ',')) return names;
i++;
}
}
/**
* The existing objects a statement changes ({@link PluginTarget}). The one an
* ALTER, DROP, REFRESH, TRUNCATE or CREATE INDEX acts on must be readable, or
* the statement is refused; the tables a CREATE or ALTER ties to its own are
* every name after REFERENCES, INHERITS (, PARTITION OF, ATTACH PARTITION,
* DETACH PARTITION and INHERIT, read generously: a word there that is no
* table resolves to nothing and changes nothing.
*/
function targetsOf(verb: string, tokens: readonly Token[]): PluginTarget[] {
const targets: PluginTarget[] = [];
const add = (kind: PluginTarget['kind'], names: string[][]) => {
for (const name of names) targets.push({ kind, name });
};
const object = keyword(tokens[1]);
const kind = object === 'type' ? 'type' : 'relation';
if (verb === 'alter') {
const at = skip(tokens, object === 'materialized' ? 3 : 2, 'if', 'exists');
add(kind, readNames(tokens, at, 'an ALTER').slice(0, 1));
} else if (verb === 'drop') {
const at = skip(tokens, skip(tokens, object === 'materialized' ? 3 : 2, 'concurrently'), 'if', 'exists');
add(kind, readNames(tokens, at, 'a DROP'));
} else if (verb === 'refresh') {
add('relation', readNames(tokens, skip(tokens, 3, 'concurrently'), 'a REFRESH').slice(0, 1));
} else if (verb === 'truncate') {
add('relation', readNames(tokens, skip(tokens, 1, 'table'), 'a TRUNCATE'));
} else if (verb === 'create' && keyword(tokens[skip(tokens, 1, 'unique')]) === 'index') {
const on = tokens.findIndex((t, i) => keyword(t) === 'on' && depthAt(tokens, i) === 0);
if (on < 0) throw new PluginSqlRefused('a CREATE INDEX must name its table with ON');
add('relation', readNames(tokens, on + 1, 'a CREATE INDEX').slice(0, 1));
}
if (verb === 'create' || verb === 'alter') add('relation', tiedTables(tokens));
return targets;
}
/** The names after REFERENCES, INHERITS (, PARTITION OF, ATTACH/DETACH PARTITION and INHERIT. */
function tiedTables(tokens: readonly Token[]): string[][] {
const names: string[][] = [];
for (const [index, token] of tokens.entries()) {
const word = keyword(token);
let at = -1;
if (word === 'references' || word === 'inherit') at = index + 1;
else if (word === 'partition' && keyword(tokens[index + 1]) === 'of') at = index + 2;
else if (word === 'partition' && ['attach', 'detach'].includes(keyword(tokens[index - 1]) ?? '')) at = index + 1;
else if (word === 'inherits' && isPunct(tokens[index + 1], '(')) {
names.push(...readNames(tokens, index + 2, 'INHERITS'));
continue;
}
const read = at < 0 ? null : readName(tokens, at);
if (read !== null) names.push(read.name);
}
return names;
}
/** How deep in parentheses the token at `index` sits. */
function depthAt(tokens: readonly Token[], index: number): number {
let depth = 0;
for (const token of tokens.slice(0, index)) {
if (token.kind === 'punct' && token.value === '(') depth++;
if (token.kind === 'punct' && token.value === ')') depth--;
}
return depth;
}
/** Refuses a name that reaches past the plugin's schema whatever qualifies it. */
function checkName(name: string): void {
if (REFUSED_NAMES.has(name) || REFUSED_PREFIXES.some((p) => name.startsWith(p)) || XML_EXPORT.test(name)) {
+5 -4
View File
@@ -21,13 +21,14 @@ import type { AbortableOperationOptions, CompiledQuery, DatabaseConnection, Dial
* `engine/postgres/postgres-driver.ts`) send every query's parameters
* through {@link withNulFreeParameters}, which covers the Kysely
* statements of the repositories;
* - a plugin's own SQLite file (`nest/plugins/host/plugin-data.service.ts`)
* and its schema on Postgres (`engine/postgres/plugin-data-store.ts`,
* which sends on a `pg` client of its own) bind its arguments through
* {@link nulFreeParameter};
* - the move from SQLite to Postgres (`engine/postgres/sqlite-move/values.ts`)
* copies text the same way.
*
* A plugin's own data (`db:own`) is not TREK's to change: its SQLite file
* (`nest/plugins/host/plugin-data.service.ts`) binds a NUL exactly, so keys
* it stored with one stay findable, and its schema on Postgres refuses an
* argument holding one with an error (`engine/postgres/plugin-data-checks.ts`).
*
* A filter is stripped as well as a write, so a lookup finds what the write
* stored. Text that spells the character as the six characters `\u0000`
* (JSON already encoded to a string) is left alone: it holds no NUL.
@@ -2,6 +2,7 @@ import type { DbSettings } from '../../../app-config';
import type { EngineId } from '../../../app-config/db-settings';
import { postgresTarget, type DatabaseEngine } from '../../../db/engine';
import type { PluginDataStore } from '../../../db/engine/plugin-data';
import { PRIVILEGED_ROLE_PLUGIN_REFUSAL, PrivilegedRoleGate } from '../../../db/engine/postgres/plugin-data-checks';
import {
dropPluginSchema,
PluginDataSlots,
@@ -9,12 +10,13 @@ import {
poolClients,
PostgresPluginDataStore,
} from '../../../db/engine/postgres/plugin-data-store';
import { logWarn } from '../../audit/audit-log.logger';
import { DATABASE_ENGINE, DATABASE_SETTINGS } from '../../database/database-engine.module';
import { pluginDataDir } from '../paths';
import { PluginDataDb, removePluginData } from './plugin-data.service';
import { MikroORM } from '@mikro-orm/core';
import type { AbstractSqlConnection } from '@mikro-orm/sql';
import { Inject, Injectable, type Provider } from '@nestjs/common';
import { Inject, Injectable, type OnApplicationBootstrap, type Provider } from '@nestjs/common';
import type { Kysely } from 'kysely';
import fs from 'node:fs';
@@ -58,21 +60,44 @@ export class SqlitePluginDataBackend implements PluginDataBackend {
* client. The plugin's data directory is still created, for the files a plugin
* keeps beside its database, and it is what marks a plugin uninstalled with
* its data kept (the erasure queue reads it).
*
* While TREK's role is privileged (`PRIVILEGED_ROLE_SQL`), every store refuses
* its calls (`plugin-data-checks.ts`), and the boot log says so once.
*/
@Injectable()
export class PostgresPluginDataBackend implements PluginDataBackend {
export class PostgresPluginDataBackend implements PluginDataBackend, OnApplicationBootstrap {
readonly engine = 'postgres' as const;
/** Shared by every plugin's store; made on first use, since on SQLite this provider is built but never used. */
private slots: PluginDataSlots | null = null;
/** Shared by every plugin's store, so the role is read once per pool connection. */
private readonly roleGate = new PrivilegedRoleGate();
constructor(
private readonly orm: MikroORM,
@Inject(DATABASE_SETTINGS) private readonly settings: DbSettings,
) {}
/** On Postgres, says in the boot log when plugin databases are refused because of TREK's role. */
async onApplicationBootstrap(): Promise<void> {
if (!postgresTarget(this.settings)) return;
try {
const client = await poolClients(this.orm.em.getConnection())();
try {
if (await this.roleGate.privileged(client)) logWarn(PRIVILEGED_ROLE_PLUGIN_REFUSAL);
} finally {
client.release();
}
} catch (err) {
logWarn(
`Could not check whether TREK's role may run plugin SQL: ${err instanceof Error ? err.message : String(err)}`,
);
}
}
open(pluginId: string): PluginDataStore {
fs.mkdirSync(pluginDataDir(pluginId), { recursive: true });
return new PostgresPluginDataStore(pluginId, poolClients(this.orm.em.getConnection()), this.sharedSlots());
const connect = poolClients(this.orm.em.getConnection());
return new PostgresPluginDataStore(pluginId, connect, this.sharedSlots(), {}, this.roleGate);
}
async erase(pluginId: string): Promise<void> {