diff --git a/plugin-sdk/src/cli/dev.ts b/plugin-sdk/src/cli/dev.ts index 8f057e437..0dea95ee5 100644 --- a/plugin-sdk/src/cli/dev.ts +++ b/plugin-sdk/src/cli/dev.ts @@ -23,6 +23,7 @@ import path from 'node:path'; import http from 'node:http'; import { createRequire } from 'node:module'; import * as sdk from '../index.js'; +import { PLUGIN_DATA_CAPS, PLUGIN_DATA_ERRORS, refuseNulSql, refuseNulValues, refuseTransactionControl } from '../plugin-data-contract.js'; import { injectTrekUi } from '../ui/kit.js'; import { readJsonFile } from './json.js'; import { @@ -79,26 +80,21 @@ function printGaps(gaps: GrantGap[]): void { } } -// The same SQL guards the real host's PluginDataDb applies (plugin-data.service.ts): -// forbidden statement types, an sql-length cap, a result-row cap, and — inside tx() — -// no transaction control plus a batch-size cap. Without them a statement production -// refuses would silently work in dev, and the author would debug a phantom. -const MAX_SQL_LENGTH = 100_000; +// The same SQL guards the real host's SQLite store applies (SqlitePluginDataStore): +// forbidden statement types, an sql-length cap, a result-row cap, NUL in the SQL, an +// argument or a migration id, transaction control in any statement of any call, and a +// tx batch-size cap. The caps and the refusal texts come from plugin-data-contract.ts, a byte-identical +// copy of the host's. Without them a statement production refuses would silently work +// in dev, and the author would debug a phantom. const FORBIDDEN_SQL = /\b(ATTACH|DETACH|VACUUM|PRAGMA|RECURSIVE|LOAD_EXTENSION)\b/i; -const TX_CONTROL = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|END)\b/i; -const MAX_TX_OPS = 100; -const MAX_ROWS = 100_000; -function guardSql(sql: string): void { - if (typeof sql !== 'string') throw new Error('sql must be a string'); - if (sql.length > MAX_SQL_LENGTH) throw new Error('sql too long'); - if (FORBIDDEN_SQL.test(sql)) throw new Error('statement type not allowed for plugin databases'); -} - -/** Strip LEADING comments/whitespace so a COMMIT hidden behind a comment can't slip - * past the start-anchored TX_CONTROL check (mirrors the host's tx() guard). */ -function stripLeadingComments(sql: string): string { - return String(sql ?? '').replace(/^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)*/, ''); +/** The host's checks on one SQL text, in the order the host runs them. */ +function guardSql(sql: unknown): void { + if (typeof sql !== 'string') throw new Error(PLUGIN_DATA_ERRORS.sqlNotString); + if (sql.length > PLUGIN_DATA_CAPS.maxSqlLength) throw new Error(PLUGIN_DATA_ERRORS.sqlTooLong); + refuseNulSql(sql); + if (FORBIDDEN_SQL.test(sql)) throw new Error(PLUGIN_DATA_ERRORS.statementNotAllowed); + refuseTransactionControl(sql); } // The credential-free inbound-header allowlist TREK's proxy forwards to auth:false @@ -149,11 +145,11 @@ export function createDevDb(dbFile: string): { db: PluginContextDb; note: string return { note: `db:own → in-memory STUB (writes are discarded — upgrade to Node 22.5+; you are on ${process.version})`, close: () => {}, - db: { - async query(sql: string) { guardSql(sql); return []; }, - async exec(sql: string) { guardSql(sql); return { changes: 0 }; }, - async migrate(_id: string, sql: string) { guardSql(sql); return { applied: true }; }, - }, + db: withTx({ + async query(sql: string, ...args: unknown[]) { guardSql(sql); refuseNulValues(flatBind(args)); return []; }, + async exec(sql: string, ...args: unknown[]) { guardSql(sql); refuseNulValues(flatBind(args)); return { changes: 0 }; }, + async migrate(id: string, sql: string) { guardSql(sql); refuseNulValues([id]); return { applied: true }; }, + }), }; } @@ -164,26 +160,59 @@ export function createDevDb(dbFile: string): { db: PluginContextDb; note: string return { note: `db:own → real SQLite at ${dbFile}`, close: () => { try { sq.close(); } catch { /* ignore */ } }, - db: { + db: withTx({ async query(sql: string, ...args: unknown[]) { guardSql(sql); + refuseNulValues(flatBind(args)); const rows = sq.prepare(sql).all(...flatBind(args)) as unknown[]; - if (rows.length > MAX_ROWS) throw new Error(`query returned more than ${MAX_ROWS} rows`); + if (rows.length > PLUGIN_DATA_CAPS.maxRows) throw new Error(PLUGIN_DATA_ERRORS.queryTooManyRows(PLUGIN_DATA_CAPS.maxRows)); return rows; }, async exec(sql: string, ...args: unknown[]) { guardSql(sql); + refuseNulValues(flatBind(args)); if (args.length) { const r = sq.prepare(sql).run(...flatBind(args)); return { changes: Number(r.changes ?? 0) }; } sq.exec(sql); return { changes: 0 }; }, - async migrate(id: string, sql: string) { guardSql(sql); if (applied.has(id)) return { applied: false }; sq.exec(sql); applied.add(id); return { applied: true }; }, - }, + async migrate(id: string, sql: string) { guardSql(sql); refuseNulValues([id]); if (applied.has(id)) return { applied: false }; sq.exec(sql); applied.add(id); return { applied: true }; }, + }), }; } } +type DevTxOp = { sql: string; args?: unknown[] }; +type DevTxResult = { results: Array<{ changes?: number; rows?: unknown[] }> }; + +const isRead = (sql: string) => /^\s*(SELECT|WITH|VALUES)\b/i.test(sql) || /\bRETURNING\b/i.test(sql); + +/** + * Adds a functional (not strictly atomic) tx over `db`, so read-modify-write batches + * work in dev; production runs it in one transaction. The whole batch is checked up + * front, like the host's SqlitePluginDataStore.tx, so a bad op fails before anything ran + * instead of leaving earlier writes behind. + */ +function withTx(db: Omit): PluginContextDb { + return { + ...db, + async tx(ops: DevTxOp[]): Promise { + if (!Array.isArray(ops)) throw new Error(PLUGIN_DATA_ERRORS.txNotArray); + if (ops.length > PLUGIN_DATA_CAPS.maxTxOps) throw new Error(PLUGIN_DATA_ERRORS.txTooManyOps(PLUGIN_DATA_CAPS.maxTxOps)); + for (const op of ops) { + guardSql(op?.sql); + refuseNulValues(op.args ?? []); + } + const results: DevTxResult['results'] = []; + for (const op of ops) { + if (isRead(op.sql)) results.push({ rows: await db.query(op.sql, ...(op.args ?? [])) }); + else { const r = await db.exec(op.sql, ...(op.args ?? [])); results.push({ changes: r.changes }); } + } + return { results }; + }, + }; +} + interface SqliteDb { prepare(sql: string): { all(...a: unknown[]): unknown[]; run(...a: unknown[]): { changes?: number | bigint } }; exec(sql: string): void; close(): void; } -interface PluginContextDb { query(sql: string, ...a: unknown[]): Promise; exec(sql: string, ...a: unknown[]): Promise<{ changes: number }>; migrate(id: string, sql: string): Promise<{ applied: boolean }>; } +interface PluginContextDb { query(sql: string, ...a: unknown[]): Promise; exec(sql: string, ...a: unknown[]): Promise<{ changes: number }>; migrate(id: string, sql: string): Promise<{ applied: boolean }>; tx(ops: DevTxOp[]): Promise; } function createDevContext(id: string, grants: Set, fx: Fixtures, db: PluginContextDb, broadcasts: unknown[]) { const need = (perm: string, method: string) => { if (!grants.has(perm)) throw new PermissionDenied(`PERMISSION_DENIED: ${method} requires ${perm}`); }; @@ -198,32 +227,13 @@ function createDevContext(id: string, grants: Set, fx: Fixtures, db: Plu // one-arg calls work on a fresh scaffold — without this, a fixtures file that omits // actingUserId leaves the mock userless and every user-bound capability throws. const mock = sdk.createMockHost({ ...fx, actingUserId: fx.actingUserId ?? 1, grants: [...grants] }); - const isRead = (sql: string) => /^\s*(SELECT|WITH|VALUES)\b/i.test(sql) || /\bRETURNING\b/i.test(sql); const devDb = { query: (sql: string, ...a: unknown[]) => { need('db:own', 'db.query'); return db.query(sql, ...a); }, exec: (sql: string, ...a: unknown[]) => { need('db:own', 'db.exec'); return db.exec(sql, ...a); }, migrate: (mid: string, sql: string) => { need('db:own', 'db.migrate'); return db.migrate(mid, sql); }, // `dev` always runs your plugin on SQLite; test the Postgres dialect against a TREK on Postgres. engine: async () => { need('db:own', 'db.engine'); return 'sqlite' as const; }, - // A functional (not strictly atomic) tx over the real dev db so read-modify-write - // batches work in dev; production runs it in one better-sqlite3 transaction. - tx: async (ops: Array<{ sql: string; args?: unknown[] }>) => { - need('db:own', 'db.tx'); - // Validate the WHOLE batch up front, like the host's PluginDataDb.tx — a bad - // op must fail before anything ran, not leave earlier writes behind. - if (!Array.isArray(ops)) throw new Error('tx requires an array of { sql, args }'); - if (ops.length > MAX_TX_OPS) throw new Error(`tx allows at most ${MAX_TX_OPS} statements`); - for (const op of ops) { - guardSql(op?.sql as string); - if (TX_CONTROL.test(stripLeadingComments(op?.sql as string))) throw new Error('transaction-control statements are not allowed inside tx()'); - } - const results: Array<{ changes?: number; rows?: unknown[] }> = []; - for (const op of ops) { - if (isRead(op.sql)) results.push({ rows: await db.query(op.sql, ...(op.args ?? [])) as unknown[] }); - else { const r = await db.exec(op.sql, ...(op.args ?? [])) as { changes?: number }; results.push({ changes: r?.changes ?? 0 }); } - } - return { results }; - }, + tx: (ops: DevTxOp[]) => { need('db:own', 'db.tx'); return db.tx(ops); }, }; const wrap = (base: typeof mock.ctx, actingUserId: number | undefined) => ({ ...base, diff --git a/plugin-sdk/src/mock-host.ts b/plugin-sdk/src/mock-host.ts index 35d24eb43..4888fba53 100644 --- a/plugin-sdk/src/mock-host.ts +++ b/plugin-sdk/src/mock-host.ts @@ -2,6 +2,14 @@ import { PLUGIN_SESSION_MAX_KEYS, PLUGIN_SESSION_MAX_KEY_LENGTH, PLUGIN_SESSION_ import type { PluginContext, PluginDefinition, PluginRequest, PluginResponse, Trip, Place, Day, Reservation, PackingItem, TripFile, BudgetItem, User, NotificationMessage, PluginActionResult, PluginSessionStorage } from './index.js'; import { CHANNEL_EVENTS } from './manifest.js'; import { PermissionDenied, HOOK_PERMISSION, USER_DATA_PERMISSION, EVENTS_PERMISSION, JOBS_PERMISSION } from './permissions.js'; +import { + PLUGIN_DATA_CAPS, + PLUGIN_DATA_ERRORS, + refuseNulSql, + refuseNulValues, + refuseTransactionControl, + type PluginSqlDialect, +} from './plugin-data-contract.js'; /** * A mock PluginContext for unit-testing a plugin without a running TREK @@ -194,25 +202,24 @@ export interface MockHost { } -// --- Statement guards copied from the host's PluginDataDb (plugin-data.service.ts), -// so SQL production refuses fails in a unit test too instead of silently passing. --- -const MAX_SQL_LENGTH = 100_000; +// --- Statement guards copied from the host's SQLite store (SqlitePluginDataStore), +// so SQL production refuses fails in a unit test too instead of silently passing. +// The caps, the refusal texts and the NUL refusal come from plugin-data-contract.ts, +// a byte-identical copy of the host's. --- const FORBIDDEN_SQL = /\b(ATTACH|DETACH|VACUUM|PRAGMA|RECURSIVE|LOAD_EXTENSION)\b/i; -// Transaction-control keywords, matched only at statement start (CASE…END and -// identifiers are unaffected). A raw COMMIT inside tx() would break atomicity. -const TX_CONTROL = /^\s*(BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|END)\b/i; -const MAX_TX_OPS = 100; -function guardSql(sql: string): void { - if (typeof sql !== 'string') throw new Error('sql must be a string'); - if (sql.length > MAX_SQL_LENGTH) throw new Error('sql too long'); - if (FORBIDDEN_SQL.test(sql)) throw new Error('statement type not allowed for plugin databases'); -} - -/** Strip LEADING comments/whitespace so a COMMIT hidden behind a line or block - * comment can't slip past the start-anchored TX_CONTROL check. */ -function stripLeadingComments(sql: string): string { - return String(sql ?? '').replace(/^(?:\s|--[^\n]*\n?|\/\*[\s\S]*?\*\/)*/, ''); +/** + * The host's checks on one SQL text, in the order the host runs them. The + * transaction-control scan reads `sql` in the dialect of the engine the mock + * host emulates, so Postgres spellings (`$1::numeric(10, 2)`, `$$...$$`) pass + * where TREK on Postgres runs them. + */ +function guardSql(sql: unknown, dialect: PluginSqlDialect): void { + if (typeof sql !== 'string') throw new Error(PLUGIN_DATA_ERRORS.sqlNotString); + if (sql.length > PLUGIN_DATA_CAPS.maxSqlLength) throw new Error(PLUGIN_DATA_ERRORS.sqlTooLong); + refuseNulSql(sql); + if (FORBIDDEN_SQL.test(sql)) throw new Error(PLUGIN_DATA_ERRORS.statementNotAllowed); + refuseTransactionControl(sql, dialect); } // The host's stripEmoji (text-sanitize.ts), copied so notify.send cleans/rejects the @@ -261,6 +268,7 @@ const META_KEY_MAX = 256; const META_KEYS_MAX = 100; export function createMockHost(opts: MockHostOptions = {}): MockHost { + const dialect: PluginSqlDialect = opts.dbEngine ?? 'sqlite'; const grants = new Set(opts.grants ?? []); const calls: MockHost['calls'] = []; const logs: MockHost['logs'] = []; @@ -438,33 +446,39 @@ export function createMockHost(opts: MockHostOptions = {}): MockHost { }, }, db: { - async query(sql) { + async query(sql, ...args) { need('db:own', 'db.query'); - guardSql(sql); - return (opts.queryResults?.[sql] ?? []) as never[]; + guardSql(sql, dialect); + refuseNulValues(args); + const rows = opts.queryResults?.[sql] ?? []; + if (rows.length > PLUGIN_DATA_CAPS.maxRows) throw new Error(PLUGIN_DATA_ERRORS.queryTooManyRows(PLUGIN_DATA_CAPS.maxRows)); + return rows as never[]; }, - async exec(sql) { + async exec(sql, ...args) { need('db:own', 'db.exec'); - guardSql(sql); + guardSql(sql, dialect); + refuseNulValues(args); return { changes: 0 }; }, - async migrate(_id, sql) { + async migrate(id, sql) { need('db:own', 'db.migrate'); - guardSql(sql); + guardSql(sql, dialect); + refuseNulValues([id]); return { applied: true }; }, async engine() { need('db:own', 'db.engine'); - return opts.dbEngine ?? 'sqlite'; + return dialect; }, async tx(ops) { need('db:own', 'db.tx'); - // Same batch guards as the host's PluginDataDb: an op cap, the forbidden - // statement types, and no transaction control inside the batch. - if (ops.length > MAX_TX_OPS) throw new Error(`tx allows at most ${MAX_TX_OPS} statements`); + // Same batch guards as the host's SQLite store: an op cap, then each op's + // SQL through the guard every call takes (transaction control included). + if (!Array.isArray(ops)) throw new Error(PLUGIN_DATA_ERRORS.txNotArray); + if (ops.length > PLUGIN_DATA_CAPS.maxTxOps) throw new Error(PLUGIN_DATA_ERRORS.txTooManyOps(PLUGIN_DATA_CAPS.maxTxOps)); for (const op of ops) { - guardSql(op.sql); - if (TX_CONTROL.test(stripLeadingComments(op.sql))) throw new Error('transaction-control statements are not allowed inside tx()'); + guardSql(op?.sql, dialect); + refuseNulValues(op.args ?? []); } // Mirror the host: reads resolve from queryResults, writes report 0 changes. return { diff --git a/plugin-sdk/src/plugin-data-contract.ts b/plugin-sdk/src/plugin-data-contract.ts new file mode 100644 index 000000000..c6b19be7a --- /dev/null +++ b/plugin-sdk/src/plugin-data-contract.ts @@ -0,0 +1,355 @@ +/** + * The contract of a plugin's own database (`db:own`) that holds on every + * engine: the caps, the words a call that breaks it is refused with, and the + * refusals of U+0000 (NUL) and of transaction control, so a plugin answers the + * same whichever engine TREK runs on. + * + * TREK's two stores (`server/src/db/engine/sqlite/plugin-data-store.ts` and + * `server/src/db/engine/postgres/plugin-data-store.ts`) throw these texts; + * `server/tests/unit/db/engine/plugin-data-contract.test.ts` runs every case + * on both and fails on a store that answers one differently. + * + * The plugin SDK keeps a byte-identical copy (`plugin-sdk/src/plugin-data-contract.ts`) + * so `trek-plugin dev` and the mock host refuse what TREK refuses, with the + * same words; its `test/permissions-parity.test.ts` compares the two files. + * Change both together. No imports: the SDK ships standalone. + */ + +/** + * The limits every plugin database is held to, whatever the engine. The + * plugin-sdk README's "Runtime limits" table documents them. + */ +export const PLUGIN_DATA_CAPS = { + /** The longest SQL text one call may carry. */ + maxSqlLength: 100_000, + /** The most rows a query, or a whole tx batch, returns. */ + maxRows: 100_000, + /** The most statements one tx batch holds. */ + maxTxOps: 100, + /** Wall-clock time for one query, one tx batch or one exec script. */ + timeBudgetMs: 2_000, + /** The most a plugin's data may take on disk. */ + quotaBytes: 256 * 1024 * 1024, +} as const; + +/** The calls a time budget holds. */ +export type PluginDataBudgetedCall = 'query' | 'exec' | 'tx'; + +/** The start of every refusal of a statement a plugin may not run. */ +const STATEMENT_NOT_ALLOWED = 'statement type not allowed for plugin databases'; + +/** + * What a plugin is told when a call breaks the contract. Both stores throw + * these and nothing else for these cases. + * + * `noStatement`, `moreThanOneStatement` and `closed` are better-sqlite3's own + * messages: the SQLite store passes them on as the driver throws them, and + * the Postgres store says the same. `statementNotAllowed` starts every + * refusal of a statement the store does not run for a plugin; the Postgres + * guard adds the reason after a colon. `txControl` is such a refusal with its + * reason, in the same words on both engines ({@link refuseTransactionControl}). + * `parameterBeforeParenthesis` is the refusal of a spelling no engine TREK + * runs accepts, which the scanner behind `refuseTransactionControl` cannot + * read the way every SQLite build does. + */ +export const PLUGIN_DATA_ERRORS = { + sqlNotString: 'sql must be a string', + sqlTooLong: 'sql too long', + statementNotAllowed: STATEMENT_NOT_ALLOWED, + txControl: + `${STATEMENT_NOT_ALLOWED}: transaction-control statements are not allowed: ` + + 'each call runs in its own transaction, and tx() makes a batch atomic', + parameterBeforeParenthesis: + `${STATEMENT_NOT_ALLOWED}: a parameter name ($name, :name, @name) directly followed by "(" is not allowed: ` + + 'no engine TREK runs accepts it, and the SQLite of trek-plugin dev would read the parentheses as part of the name', + noStatement: 'The supplied SQL string contains no statements', + moreThanOneStatement: 'The supplied SQL string contains more than one statement', + closed: 'The database connection is not open', + txNotArray: 'tx requires an array of { sql, args }', + txTooManyOps: (max: number): string => `tx allows at most ${max} statements`, + queryTooManyRows: (max: number): string => `query returned more than ${max} rows`, + txTooManyRows: (max: number): string => `tx returned more than ${max} rows in total`, + overBudget: (call: PluginDataBudgetedCall, ms: number): string => `${call} exceeded its ${ms} ms time budget`, +} as const; + +/** + * Why a plugin's SQL holding NUL is refused: Postgres ends a statement's text + * at a NUL and its text cannot hold one. On SQLite a NUL in a string literal + * would store a value the same plugin could never store on Postgres. + */ +export const PLUGIN_SQL_NUL_REFUSAL = + 'the SQL holds the character U+0000 (NUL), which plugin databases refuse on every engine: ' + + 'Postgres cannot read it in a statement or store it in text. Remove it from the SQL'; + +/** + * Why a plugin's bound value or migration id holding NUL is refused: TREK + * will not change what a plugin asked to store or compare (`'a\0b'` and + * `'ab'` are different keys). SQLite could store it, but then the plugin + * would answer differently on Postgres and its data could not move there. + */ +export const PLUGIN_VALUE_NUL_REFUSAL = + 'a plugin argument holds the character U+0000 (NUL), which plugin databases refuse on every engine: ' + + 'Postgres text cannot store it, and TREK refuses it instead of changing the value. ' + + 'Remove it, or bind binary data as a Buffer (a BLOB on SQLite, bytea on Postgres)'; + +/** Refuses plugin SQL holding NUL ({@link PLUGIN_SQL_NUL_REFUSAL}). */ +export function refuseNulSql(sql: string): void { + if (sql.includes('\u0000')) throw new Error(PLUGIN_SQL_NUL_REFUSAL); +} + +/** + * Refuses plugin values holding NUL ({@link PLUGIN_VALUE_NUL_REFUSAL}): a + * string, or a string anywhere in an array or a plain object (SQLite binds an + * object's fields as named parameters, `pg` sends one as JSON). A Buffer is + * binary data and holds any byte. + */ +export function refuseNulValues(values: readonly unknown[]): void { + if (holdsNul(values, new Set())) throw new Error(PLUGIN_VALUE_NUL_REFUSAL); +} + +function holdsNul(value: unknown, seen: Set): boolean { + if (typeof value === 'string') return value.includes('\u0000'); + if (typeof value !== 'object' || value === null || seen.has(value)) return false; + seen.add(value); + if (Array.isArray(value)) return value.some((item) => holdsNul(item, seen)); + const proto: unknown = Object.getPrototypeOf(value); + if (proto !== Object.prototype && proto !== null) return false; + return Object.values(value).some((item) => holdsNul(item, seen)); +} + +/** + * The verbs of transaction control, in lower case. TREK runs every call in a + * transaction of its own and `tx()` makes a batch atomic, so a plugin never + * opens, ends or nests one: a COMMIT in the middle would keep writes the call + * then reports as failed. SQLite knows no START or ABORT, but they are refused + * there too, so a plugin is told the same on both engines. + */ +export const PLUGIN_TRANSACTION_CONTROL: ReadonlySet = new Set([ + 'begin', + 'start', + 'commit', + 'end', + 'rollback', + 'abort', + 'savepoint', + 'release', +]); + +/** + * Refuses SQL in which any statement starts with transaction control + * ({@link PLUGIN_DATA_ERRORS.txControl}), in a query, a tx op, a migration or + * any statement of an exec script, before anything runs. The SQLite store and + * the SDK harnesses call it; the Postgres guard finds the same verbs with its + * own lexer. + * + * A named parameter directly followed by `(` is refused as well + * ({@link PLUGIN_DATA_ERRORS.parameterBeforeParenthesis}). A SQLite built with + * Tcl variables, as node:sqlite is under `trek-plugin dev`, reads `$a(...)` + * up to the closing parenthesis as one token, quotes and semicolons + * included, so `$a(')); COMMIT; --')` would hide a COMMIT from this scan. + * better-sqlite3 and Postgres refuse the spelling anyway. + * + * `dialect` says whose spelling `sql` is. The stores and `trek-plugin dev` + * run SQLite and pass nothing. The SDK's mock host emulating Postgres passes + * `'postgres'`, so `$1`, dollar quotes (`$$...$$`, `$tag$...$tag$`) and + * escape strings (`E'...'`) are read as Postgres reads them, `:`, `@` and `#` + * are operators there, and a trigger has no body of statements. + */ +export function refuseTransactionControl(sql: string, dialect: PluginSqlDialect = 'sqlite'): void { + if (statementVerbs(sql, dialect).some((verb) => PLUGIN_TRANSACTION_CONTROL.has(verb))) { + throw new Error(PLUGIN_DATA_ERRORS.txControl); + } +} + +/** Whose spelling a plugin's SQL is in. */ +export type PluginSqlDialect = 'sqlite' | 'postgres'; + +/** A name or keyword as SQLite reads one, unquoted. */ +const WORD = /[A-Za-z_\u0080-￿][A-Za-z0-9_$\u0080-￿]*/y; + +/** A character SQLite reads as part of a name. */ +const NAME_CHAR = /[A-Za-z0-9_$\u0080-￿]/; + +/** The characters a named parameter starts with in SQLite. */ +const PARAMETER_PREFIXES = new Set(['$', ':', '@', '#']); + +/** + * How many leading words of a statement are kept: enough for + * EXPLAIN QUERY PLAN CREATE TEMP TRIGGER. + */ +const LEADING_WORDS = 6; + +/** + * The first word of every statement in `sql`, in lower case, read the way + * SQLite splits a script: quoted text ('...', "...", `...`, [...]) and + * comments are skipped, and a semicolon ends a statement, except inside + * the body of a CREATE TRIGGER, which only `; END ;` ends (as in SQLite's + * sqlite3_complete). The statements of a trigger body are not counted, so + * its closing END is not taken for transaction control. A statement that + * starts with a quoted name or a parenthesis has no verb here. A named + * parameter is read as SQLite reads it ({@link afterParameter}). + */ +function statementVerbs(sql: string, dialect: PluginSqlDialect): string[] { + const verbs: string[] = []; + let words: string[] = []; + let tokens = 0; + let inTrigger = false; + // In a trigger body: whether the last tokens were `;`, or `;` and END. + let afterSemicolon = false; + let afterEnd = false; + let i = 0; + while (i < sql.length) { + const c = sql[i]; + const next = sql[i + 1]; + if (/\s/.test(c)) { + i++; + continue; + } + if (c === '-' && next === '-') { + i = indexAfter(sql, '\n', i + 2); + continue; + } + if (c === '/' && next === '*') { + i = indexAfter(sql, '*/', i + 2); + continue; + } + if (c === ';') { + if (!inTrigger || afterEnd) { + words = []; + tokens = 0; + inTrigger = false; + } + afterSemicolon = inTrigger; + afterEnd = false; + i++; + continue; + } + WORD.lastIndex = i; + const word = WORD.exec(sql)?.[0]; + tokens++; + if (word === undefined) { + i = afterOtherToken(sql, i, dialect); + afterSemicolon = false; + afterEnd = false; + continue; + } + i += word.length; + const lower = word.toLowerCase(); + if (tokens === 1) verbs.push(lower); + if (tokens === words.length + 1 && words.length < LEADING_WORDS) words.push(lower); + if (!inTrigger && dialect === 'sqlite') inTrigger = opensTrigger(words); + afterEnd = afterSemicolon && lower === 'end'; + afterSemicolon = false; + } + return verbs; +} + +/** + * Whether a statement starting with `words` is + * [EXPLAIN [QUERY PLAN]] CREATE [TEMP | TEMPORARY] TRIGGER. + */ +function opensTrigger(words: readonly string[]): boolean { + let at = 0; + if (words[0] === 'explain') at = words[1] === 'query' && words[2] === 'plan' ? 3 : 1; + if (words[at] !== 'create') return false; + at += words[at + 1] === 'temp' || words[at + 1] === 'temporary' ? 2 : 1; + return words[at] === 'trigger'; +} + +/** The index after the token at `start` that is no word: quoted text, a parameter, or one character. */ +function afterOtherToken(sql: string, start: number, dialect: PluginSqlDialect): number { + if (dialect === 'postgres') return afterPostgresToken(sql, start); + const c = sql[start]; + if (c === '[') return indexAfter(sql, ']', start + 1); + if (c === "'" || c === '"' || c === '`') return afterQuoted(sql, start); + if (PARAMETER_PREFIXES.has(c)) return afterParameter(sql, start); + return start + 1; +} + +/** A dollar quote's opening tag, `$$` or `$tag$`, as Postgres reads one. */ +const DOLLAR_TAG = /\$(?:[A-Za-z_\u0080-￿][A-Za-z0-9_\u0080-￿]*)?\$/y; + +/** + * The index after the token at `start` that is no word, read as Postgres reads + * it: quoted text and quoted names, a dollar-quoted string up to its closing + * tag, an escape string (`E'...'`, where a backslash escapes the next + * character), or one character (`$1` is `$` and a number, `::` two colons). + */ +function afterPostgresToken(sql: string, start: number): number { + const c = sql[start]; + if (c === '$') { + DOLLAR_TAG.lastIndex = start; + const tag = DOLLAR_TAG.exec(sql)?.[0]; + if (tag !== undefined) return indexAfter(sql, tag, start + tag.length); + return start + 1; + } + if (c === "'" && isEscapeStringPrefix(sql, start - 1)) return afterEscapeString(sql, start); + if (c === "'" || c === '"') return afterQuoted(sql, start); + return start + 1; +} + +/** Whether the character at `at` is a lone `E`/`e` that makes the string after it an escape string. */ +function isEscapeStringPrefix(sql: string, at: number): boolean { + return (sql[at] === 'E' || sql[at] === 'e') && (at === 0 || !NAME_CHAR.test(sql[at - 1])); +} + +/** The index after the escape string whose quote is at `start`. */ +function afterEscapeString(sql: string, start: number): number { + let i = start + 1; + while (i < sql.length) { + if (sql[i] === '\\') i += 2; + else if (sql[i] !== "'") i++; + else if (sql[i + 1] === "'") i += 2; + else return i + 1; + } + return sql.length; +} + +/** + * The index after the named parameter starting at `start`, read as SQLite's + * tokenizer reads one: name characters, with `::` allowed inside. Refuses a + * name directly followed by `(` ({@link PLUGIN_DATA_ERRORS.parameterBeforeParenthesis}). + * + * A prefix without a name is no parameter, and SQLite refuses the statement + * holding it. Its colons are skipped together, so the scan does not read a + * Postgres cast (`x::numeric(10)`, which the mock host may be handed) as a + * parameter. + */ +function afterParameter(sql: string, start: number): number { + let i = start + 1; + let named = false; + while (i < sql.length) { + if (NAME_CHAR.test(sql[i])) { + named = true; + i++; + } else if (sql[i] === ':' && sql[i + 1] === ':') { + i += 2; + } else { + break; + } + } + if (!named) { + while (sql[i] === ':') i++; + return i; + } + if (sql[i] === '(') throw new Error(PLUGIN_DATA_ERRORS.parameterBeforeParenthesis); + return i; +} + +/** The index after the first `token` from `from`, or the end of `sql`. */ +function indexAfter(sql: string, token: string, from: number): number { + const at = sql.indexOf(token, from); + return at < 0 ? sql.length : at + token.length; +} + +/** The index after the quoted text starting at `start`; a doubled quote stands for itself. */ +function afterQuoted(sql: string, start: number): number { + const quote = sql[start]; + let i = start + 1; + while (i < sql.length) { + if (sql[i] !== quote) i++; + else if (sql[i + 1] === quote) i += 2; + else return i + 1; + } + return sql.length; +} diff --git a/plugin-sdk/test/permissions-parity.test.ts b/plugin-sdk/test/permissions-parity.test.ts index 619cdbca8..71c3ffc29 100644 --- a/plugin-sdk/test/permissions-parity.test.ts +++ b/plugin-sdk/test/permissions-parity.test.ts @@ -63,6 +63,17 @@ describe.skipIf(!inMonorepo)('parity with the host', () => { }); }); +const serverDataContract = path.resolve(here, '../../server/src/db/engine/plugin-data-contract.ts'); + +describe.skipIf(!fs.existsSync(serverDataContract))('parity with the host plugin database', () => { + it("the vendored ctx.db contract is byte-identical to the server's", () => { + // dev and the mock host hold ctx.db to the host's caps and refuse a call with the host's + // own words, NUL included; a drift would let a plugin pass here and fail in TREK. + const ours = fs.readFileSync(path.resolve(here, '../src/plugin-data-contract.ts'), 'utf8'); + expect(ours.replace(/\r\n/g, '\n')).toBe(fs.readFileSync(serverDataContract, 'utf8').replace(/\r\n/g, '\n')); + }); +}); + describe.skipIf(!fs.existsSync(hostFrame))('parity with the host frame', () => { it('the session storage contract is one contract in all three copies', () => { // Nothing generates these: the limits are written out by hand in the SDK export diff --git a/plugin-sdk/test/sdk.test.ts b/plugin-sdk/test/sdk.test.ts index f22a8bbf5..fda25523e 100644 --- a/plugin-sdk/test/sdk.test.ts +++ b/plugin-sdk/test/sdk.test.ts @@ -5,6 +5,7 @@ import path from 'node:path'; import zlib from 'node:zlib'; import { createRequire } from 'node:module'; import { definePlugin, PLUGIN_API_VERSION, validateManifest, createMockHost, PermissionDenied } from '../src/index.js'; +import { PLUGIN_DATA_CAPS, PLUGIN_DATA_ERRORS, PLUGIN_SQL_NUL_REFUSAL, PLUGIN_VALUE_NUL_REFUSAL } from '../src/plugin-data-contract.js'; import { isUnboundedRange } from '../src/manifest.js'; import { scaffold } from '../src/cli/create.js'; import { validatePluginDir } from '../src/cli/validate.js'; @@ -506,11 +507,69 @@ describe('createMockHost', () => { it('db guards match the host: forbidden statements, tx control, op cap', async () => { const { ctx } = createMockHost({ grants: ['db:own'] }); await expect(ctx.db.query('PRAGMA user_version')).rejects.toThrow(/not allowed/); - await expect(ctx.db.tx([{ sql: ' COMMIT' }])).rejects.toThrow(/transaction-control/); - await expect(ctx.db.tx([{ sql: '/* x */ROLLBACK' }])).rejects.toThrow(/transaction-control/); + await expect(ctx.db.tx([{ sql: ' COMMIT' }])).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txControl)); + await expect(ctx.db.tx([{ sql: '/* x */ROLLBACK' }])).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txControl)); await expect(ctx.db.tx(Array.from({ length: 101 }, () => ({ sql: 'SELECT 1' })))).rejects.toThrow(/at most 100/); }); + it('db refuses transaction control in every call and statement position, as TREK does on both engines', async () => { + const { ctx } = createMockHost({ grants: ['db:own'] }); + const txControl = new Error(PLUGIN_DATA_ERRORS.txControl); + for (const sql of ['BEGIN', 'start transaction', 'End', 'ABORT', 'SAVEPOINT a', 'RELEASE a', '-- c\nCOMMIT']) { + await expect(ctx.db.query(sql)).rejects.toThrow(txControl); + } + await expect(ctx.db.exec('BEGIN; INSERT INTO kv VALUES (1); COMMIT;')).rejects.toThrow(txControl); + await expect(ctx.db.exec('INSERT INTO kv VALUES (1); /* x */ commit')).rejects.toThrow(txControl); + await expect(ctx.db.migrate('001', 'CREATE TABLE kv (k TEXT); COMMIT;')).rejects.toThrow(txControl); + await expect(ctx.db.tx([{ sql: 'SELECT 1' }, { sql: 'ROLLBACK' }])).rejects.toThrow(txControl); + // The words where they are no statement's verb run. + await expect(ctx.db.exec("SELECT CASE WHEN 1 THEN 'BEGIN; COMMIT' END; -- END")).resolves.toEqual({ changes: 0 }); + }); + + it('db reads SQL in the dialect of the engine it emulates', async () => { + const txControl = new Error(PLUGIN_DATA_ERRORS.txControl); + const pg = createMockHost({ grants: ['db:own'], dbEngine: 'postgres' }).ctx; + // Postgres spellings TREK on Postgres runs: a cast with a precision, dollar quotes, escape strings. + await expect(pg.db.query('SELECT $1::numeric(10, 2) AS v', 1)).resolves.toEqual([]); + await expect(pg.db.exec("SELECT $$it's; COMMIT$$; SELECT $f$ROLLBACK$f$")).resolves.toEqual({ changes: 0 }); + await expect(pg.db.exec("SELECT E'it\\'s; COMMIT'")).resolves.toEqual({ changes: 0 }); + await expect(pg.db.exec('CREATE TRIGGER t AFTER INSERT ON kv FOR EACH ROW EXECUTE FUNCTION f(); END')).rejects.toThrow(txControl); + await expect(pg.db.exec("SELECT $$x$$; COMMIT")).rejects.toThrow(txControl); + await expect(pg.db.exec("SELECT E'a\\''; ROLLBACK")).rejects.toThrow(txControl); + // The SQLite mock keeps SQLite's reading: a named parameter before a parenthesis is refused. + const sqlite = createMockHost({ grants: ['db:own'] }).ctx; + await expect(sqlite.db.query('SELECT $a(1)')).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.parameterBeforeParenthesis)); + }); + + it("db refuses NUL in the SQL, an argument or a migration id with the host's errors", async () => { + const { ctx } = createMockHost({ grants: ['db:own'] }); + await expect(ctx.db.query("SELECT 'a\u0000'")).rejects.toThrow(PLUGIN_SQL_NUL_REFUSAL); + await expect(ctx.db.exec('INSERT INTO kv VALUES (?)', 'a\u0000b')).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(ctx.db.query('SELECT 1 WHERE ? = 1', [{ k: '\u0000' }])).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(ctx.db.tx([{ sql: 'INSERT INTO kv VALUES (?)', args: ['\u0000'] }])).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(ctx.db.migrate('001\u0000', 'CREATE TABLE t (x)')).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + // Binary data with a zero byte is a Buffer, which holds any byte. + await expect(ctx.db.exec('INSERT INTO raw VALUES (?)', Buffer.from([1, 0, 2]))).resolves.toEqual({ changes: 0 }); + }); + + it("db refuses a call that breaks the contract with the host's exact words", async () => { + const tooLong = 'x'.repeat(PLUGIN_DATA_CAPS.maxSqlLength + 1); + const { ctx } = createMockHost({ + grants: ['db:own'], + queryResults: { 'SELECT n FROM big': Array.from({ length: PLUGIN_DATA_CAPS.maxRows + 1 }, (_, n) => ({ n })) }, + }); + await expect(ctx.db.query(42 as never)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlNotString)); + await expect(ctx.db.exec(tooLong)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlTooLong)); + await expect(ctx.db.migrate('m', 'PRAGMA user_version')).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.statementNotAllowed)); + await expect(ctx.db.query('SELECT n FROM big')).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.queryTooManyRows(PLUGIN_DATA_CAPS.maxRows))); + await expect(ctx.db.tx('nope' as never)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txNotArray)); + await expect(ctx.db.tx([null as never])).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlNotString)); + const ops = Array.from({ length: PLUGIN_DATA_CAPS.maxTxOps + 1 }, () => ({ sql: 'SELECT 1' })); + await expect(ctx.db.tx(ops)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txTooManyOps(PLUGIN_DATA_CAPS.maxTxOps))); + // The host checks NUL before the statement type, so SQL breaking both is told about the NUL. + await expect(ctx.db.query("PRAGMA x = 'a\u0000'")).rejects.toThrow(new Error(PLUGIN_SQL_NUL_REFUSAL)); + }); + it('db.engine says SQLite unless the mock is told the host runs Postgres, and needs db:own', async () => { await expect(createMockHost({ grants: ['db:own'] }).ctx.db.engine()).resolves.toBe('sqlite'); await expect(createMockHost({ grants: ['db:own'], dbEngine: 'postgres' }).ctx.db.engine()).resolves.toBe('postgres'); @@ -790,6 +849,104 @@ describe('dev db bind shapes', () => { close(); } }); + + it.runIf(hasNodeSqlite)('refuses transaction control in every call before anything runs, as TREK does on both engines', async () => { + const { createDevDb } = await import('../src/cli/dev.js'); + const { db, close } = createDevDb(path.join(tmp, 'db.sqlite')); + const txControl = new Error(PLUGIN_DATA_ERRORS.txControl); + try { + await db.migrate('001', 'CREATE TABLE kv (k TEXT)'); + await expect(db.query('/* x */ BEGIN')).rejects.toThrow(txControl); + await expect(db.query('START TRANSACTION')).rejects.toThrow(txControl); + await expect(db.exec("INSERT INTO kv VALUES ('a'); BEGIN; INSERT INTO kv VALUES ('b'); COMMIT;")).rejects.toThrow(txControl); + await expect(db.exec('COMMIT', 'x')).rejects.toThrow(txControl); + await expect(db.migrate('002', "INSERT INTO kv VALUES ('c');\n-- done\nEND")).rejects.toThrow(txControl); + await expect(db.tx([{ sql: "INSERT INTO kv VALUES ('d')" }, { sql: 'SAVEPOINT s' }])).rejects.toThrow(txControl); + expect(await db.query('SELECT count(*) AS n FROM kv')).toEqual([{ n: 0 }]); + // A trigger body's closing END and a CASE ... END run. + await db.exec("CREATE TRIGGER t AFTER INSERT ON kv BEGIN SELECT CASE WHEN 1 THEN 'x' END; END; INSERT INTO kv VALUES ('e');"); + expect(await db.query('SELECT k FROM kv')).toEqual([{ k: 'e' }]); + } finally { + close(); + } + }); + + it.runIf(hasNodeSqlite)('refuses a parameter name followed by "(", which node:sqlite reads past quotes and semicolons', async () => { + const { createDevDb } = await import('../src/cli/dev.js'); + const { db, close } = createDevDb(path.join(tmp, 'db.sqlite')); + const refusal = new Error(PLUGIN_DATA_ERRORS.parameterBeforeParenthesis); + try { + await db.migrate('001', 'CREATE TABLE kv (k TEXT)'); + // node:sqlite reads $a(')) as one parameter, so the COMMIT after it would run. + await expect(db.exec("INSERT INTO kv VALUES ($a(')); COMMIT; --')")).rejects.toThrow(refusal); + await expect(db.query("SELECT :a(')")).rejects.toThrow(refusal); + await expect(db.tx([{ sql: "SELECT @a::b(';')" }])).rejects.toThrow(refusal); + expect(await db.query('SELECT count(*) AS n FROM kv')).toEqual([{ n: 0 }]); + // A parameter with a space before the parenthesis, or none at all, is read as before. + await db.exec('INSERT INTO kv VALUES ($a)', { a: 'x' }); + expect(await db.query('SELECT k FROM kv')).toEqual([{ k: 'x' }]); + } finally { + close(); + } + }); + + it.runIf(hasNodeSqlite)('reads the body of an EXPLAIN CREATE TRIGGER as a trigger body', async () => { + const { createDevDb } = await import('../src/cli/dev.js'); + const { db, close } = createDevDb(path.join(tmp, 'db.sqlite')); + try { + await db.migrate('001', 'CREATE TABLE kv (k TEXT)'); + expect((await db.query('EXPLAIN CREATE TRIGGER t AFTER INSERT ON kv BEGIN SELECT 1; END')).length).toBeGreaterThan(0); + await db.query('EXPLAIN QUERY PLAN CREATE TEMP TRIGGER t AFTER INSERT ON kv BEGIN SELECT 1; END'); + await expect(db.exec('EXPLAIN CREATE TRIGGER t AFTER INSERT ON kv BEGIN SELECT 1; END; COMMIT')).rejects.toThrow( + new Error(PLUGIN_DATA_ERRORS.txControl), + ); + } finally { + close(); + } + }); + + it.runIf(hasNodeSqlite)('refuses NUL in the SQL, an argument or a migration id, as TREK does on every engine', async () => { + const { createDevDb } = await import('../src/cli/dev.js'); + const { db, close } = createDevDb(path.join(tmp, 'db.sqlite')); + try { + await db.migrate('001', 'CREATE TABLE kv (k TEXT PRIMARY KEY, v BLOB)'); + await expect(db.exec("INSERT INTO kv VALUES ('a\u0000b', 'x')")).rejects.toThrow(PLUGIN_SQL_NUL_REFUSAL); + await expect(db.exec('INSERT INTO kv VALUES (?, ?)', ['a\u0000b', 'x'])).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(db.exec('INSERT INTO kv VALUES (?, ?)', 'c', ['\u0000'])).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(db.query('SELECT v FROM kv WHERE k = :k', { k: 'x\u0000' })).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + await expect(db.migrate('002\u0000', 'CREATE TABLE more (x INTEGER)')).rejects.toThrow(PLUGIN_VALUE_NUL_REFUSAL); + expect(await db.query('SELECT count(*) AS n FROM kv')).toEqual([{ n: 0 }]); + // Binary data with a zero byte goes in as a Buffer. + await db.exec('INSERT INTO kv VALUES (?, ?)', 'b', Buffer.from([1, 0, 2])); + expect(await db.query('SELECT length(v) AS n FROM kv')).toEqual([{ n: 3 }]); + } finally { + close(); + } + }); + + it.runIf(hasNodeSqlite)("refuses a call that breaks the contract with the host's exact words", async () => { + const { createDevDb } = await import('../src/cli/dev.js'); + const { db, close } = createDevDb(path.join(tmp, 'db.sqlite')); + try { + await expect(db.query(42 as never)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlNotString)); + await expect(db.exec('x'.repeat(PLUGIN_DATA_CAPS.maxSqlLength + 1))).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlTooLong)); + await expect(db.migrate('m', "ATTACH DATABASE 'x' AS y")).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.statementNotAllowed)); + await expect(db.tx('nope' as never)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txNotArray)); + await expect(db.tx([{ sql: 7 as never }])).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.sqlNotString)); + const ops = Array.from({ length: PLUGIN_DATA_CAPS.maxTxOps + 1 }, () => ({ sql: 'SELECT 1' })); + await expect(db.tx(ops)).rejects.toThrow(new Error(PLUGIN_DATA_ERRORS.txTooManyOps(PLUGIN_DATA_CAPS.maxTxOps))); + // A batch is checked whole before anything runs: the insert ahead of the bad op never lands. + await db.migrate('001', 'CREATE TABLE kv (k TEXT)'); + await expect(db.tx([{ sql: "INSERT INTO kv VALUES ('a')" }, { sql: 'PRAGMA user_version' }])).rejects.toThrow( + new Error(PLUGIN_DATA_ERRORS.statementNotAllowed), + ); + await expect(db.tx([{ sql: 'INSERT INTO kv VALUES (?)', args: ['b'] }, { sql: 'SELECT k FROM kv' }])).resolves.toEqual({ + results: [{ changes: 1 }, { rows: [{ k: 'b' }] }], + }); + } finally { + close(); + } + }); }); describe('reference plugin (examples/koffi)', () => {