Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,448 @@
/**
* Phase 06 #22 — Plugin-DB migration applier.
*
* Plugins that need their own tables declare them in the manifest
* (foundation: single `migration.up` SQL string). The operator-side
* lifecycle service calls {@link applyPluginMigration} on install,
* which:
*
* 1. Validates the SQL text only references tables prefixed with
* `plugin_<sanitized-plugin-id>_` (no DROP DATABASE, no GRANT,
* no cross-schema writes — the manifest cannot trick the host
* into running arbitrary DDL).
* 2. Executes the (possibly multi-statement) SQL via the injected
* `executeRawUnsafe` seam — supplied at call-site as Prisma
* `$executeRawUnsafe`.
* 3. Records the applied version so re-installs are idempotent.
*
* Down-migrations + per-version sequencing are intentionally deferred:
* the foundation accepts one up-migration per install. Subsequent
* versions can re-run with their own up-SQL.
*/
/**
* Sanitize a reverse-DNS plugin id (`com.acme.slack`) into a SQL
* identifier (`com_acme_slack`). Lowercases, replaces `.` and `-`
* with `_`, then rejects anything outside `[a-z0-9_]`.
*/
export function sanitizePluginIdForSql(pluginId: string): string {
const lower = pluginId.toLowerCase();
const replaced = lower.replace(/[.\-]/g, "_");
if (!/^[a-z][a-z0-9_]*$/u.test(replaced)) {
throw new PluginMigrationError(
"invalid_plugin_id",
`Plugin id '${pluginId}' cannot be sanitized to a SQL identifier.`
);
}
return replaced;
}
export class PluginMigrationError extends Error {
public override readonly name = "PluginMigrationError";
public readonly code:
| "invalid_plugin_id"
| "forbidden_statement"
| "prefix_violation"
| "missing_tenant_id_column"
| "too_many_statements"
| "execute_failed";
constructor(code: PluginMigrationError["code"], message: string) {
super(message);
this.code = code;
}
}
/**
* Hard cap on the number of statements a single plugin migration may
* declare. Defends against the "thousand-tables" DoS where a manifest
* spans the entire DB with garbage. Closes F-008 from the internal
* findings. Operators can override via the migration runner caller; the
* default is conservative because legitimate plugin migrations rarely
* exceed a handful of tables.
*/
export const DEFAULT_MAX_STATEMENTS_PER_MIGRATION = 32;
/**
* Comment / whitespace stripper used by both the statement splitter
* and the keyword scanner. Removes:
* - `-- line comments`
* - `/* block comments *​/`
* and collapses runs of whitespace.
*/
export function stripSqlNoise(sql: string): string {
return sql
.replace(/\/\*[\s\S]*?\*\//gu, " ")
.replace(/--[^\n]*/gu, " ")
.replace(/\s+/gu, " ")
.trim();
}
const FORBIDDEN_TOKENS = [
"DROP DATABASE",
"DROP SCHEMA",
"GRANT",
"REVOKE",
"CREATE USER",
"ALTER USER",
"DROP USER",
"COPY ",
"TRUNCATE",
"SET ROLE",
"PG_",
];
/**
* F-006 — defence-in-depth AST-lite token scan.
*
* Stage-1 forbidden-tokens check is a substring match on the stripped
* SQL — robust against simple split-comment-grant obfuscation (the comment is
* removed first) but vulnerable to two failure modes:
* - false positives when a string literal contains a forbidden word
* (a column DEFAULT with the substring "grant" trips the rule);
*
* Stage-2 (this function) walks the SQL token-by-token respecting:
* - single-quoted strings with two single quotes escape
* - double-quoted identifiers with two double quotes escape
* - dollar-quoted strings ($$ ... $$ and $tag$ ... $tag$)
* - the actual unicode whitespace class
* It returns the sequence of identifier-shaped tokens (uppercased). The
* caller scans this sequence for forbidden keyword pairs without
* worrying about content inside literals.
*
* Intentionally tiny — we only need enough of a tokenizer to make
* obfuscation harder, not to parse arbitrary Postgres.
*/
export type SqlIdentifierToken = {
readonly text: string; // uppercased
readonly start: number;
};
export function tokenizeSqlIdentifiers(sql: string): ReadonlyArray<SqlIdentifierToken> {
const tokens: SqlIdentifierToken[] = [];
const len = sql.length;
let i = 0;
while (i < len) {
const ch = sql[i]!;
// line comment
if (ch === "-" && sql[i + 1] === "-") {
while (i < len && sql[i] !== "\n") i += 1;
continue;
}
// block comment
if (ch === "/" && sql[i + 1] === "*") {
i += 2;
while (i < len && !(sql[i] === "*" && sql[i + 1] === "/")) i += 1;
i += 2;
continue;
}
// single-quoted string
if (ch === "'") {
i += 1;
while (i < len) {
if (sql[i] === "'" && sql[i + 1] === "'") {
i += 2;
continue;
}
if (sql[i] === "'") {
i += 1;
break;
}
i += 1;
}
continue;
}
// double-quoted identifier
if (ch === '"') {
const start = i;
i += 1;
let inner = "";
while (i < len) {
if (sql[i] === '"' && sql[i + 1] === '"') {
inner += '"';
i += 2;
continue;
}
if (sql[i] === '"') {
i += 1;
break;
}
inner += sql[i]!;
i += 1;
}
tokens.push({ text: inner.toUpperCase(), start });
continue;
}
// dollar-quoted string ($tag$ ... $tag$)
if (ch === "$") {
const tagMatch = /^\$([A-Za-z_][A-Za-z0-9_]*)?\$/.exec(sql.slice(i));
if (tagMatch) {
const closeTag = tagMatch[0];
i += closeTag.length;
const close = sql.indexOf(closeTag, i);
i = close === -1 ? len : close + closeTag.length;
continue;
}
}
// identifier
if (/[A-Za-z_]/.test(ch)) {
const start = i;
let end = i + 1;
while (end < len && /[A-Za-z0-9_]/.test(sql[end]!)) end += 1;
tokens.push({ text: sql.slice(start, end).toUpperCase(), start });
i = end;
continue;
}
i += 1;
}
return tokens;
}
/**
* Scan the tokenized identifier stream for any forbidden 1- or 2-word
* keyword sequence. Returns the first match or null. Unlike the stage-1
* substring scan, this respects string-literal content (so a legitimate
* `DEFAULT 'no grant'` no longer false-positives) AND tightens the
* obfuscation surface (string-internal forbidden words cannot smuggle
* a real GRANT past the splitter).
*/
export function findForbiddenKeyword(
tokens: ReadonlyArray<SqlIdentifierToken>,
): { keyword: string; position: number } | null {
for (let i = 0; i < tokens.length; i++) {
const t = tokens[i]!.text;
const next = tokens[i + 1]?.text ?? "";
// 2-word keywords
const pair = `${t} ${next}`;
if (
pair === "DROP DATABASE" ||
pair === "DROP SCHEMA" ||
pair === "CREATE USER" ||
pair === "ALTER USER" ||
pair === "DROP USER" ||
pair === "SET ROLE"
) {
return { keyword: pair, position: tokens[i]!.start };
}
// single-word keywords
if (
t === "GRANT" ||
t === "REVOKE" ||
t === "TRUNCATE" ||
t === "COPY"
) {
return { keyword: t, position: tokens[i]!.start };
}
// pg_* function family
if (t.startsWith("PG_")) {
return { keyword: "PG_*", position: tokens[i]!.start };
}
}
return null;
}
/**
* Validate that a CREATE TABLE statement targets the allowed prefix
* and includes a `tenantId` column. We deliberately keep the parser
* dumb — anything that does not match the simple "CREATE TABLE
* <name> ( ... )" shape is rejected. Plugin authors who want fancy
* migrations should split them into multiple CREATE TABLEs.
*/
function validateCreateTable(statement: string, allowedPrefix: string): void {
const m = /^CREATE\s+TABLE(\s+IF\s+NOT\s+EXISTS)?\s+("?)([a-z_][a-z0-9_]*)\2\s*\(([\s\S]+)\)\s*$/iu.exec(statement);
if (!m) {
throw new PluginMigrationError(
"forbidden_statement",
`CREATE TABLE statement does not match the supported shape: ${statement.slice(0, 80)}…`
);
}
const tableName = m[3]!;
if (!tableName.startsWith(allowedPrefix)) {
throw new PluginMigrationError(
"prefix_violation",
`Table '${tableName}' must start with '${allowedPrefix}'.`
);
}
const body = m[4]!;
// F-021 — strict column-name check. The previous `\btenantId\b` regex
// matched the substring anywhere in the body, including inside DEFAULT
// literals like `comment TEXT DEFAULT 'tenantId here'`. We now require
// `tenantId` to appear as a column-definition header: preceded by
// either the start of the body or a comma (the column-def separator),
// optionally double-quoted, followed by whitespace before the type.
// Comments are already removed by stripSqlNoise before we get here.
if (!/(?:^|,)\s*"?tenantId"?\s+/iu.test(body)) {
throw new PluginMigrationError(
"missing_tenant_id_column",
`Table '${tableName}' must declare a tenantId column for tenant scoping.`
);
}
}
function validateCreateIndex(statement: string, allowedPrefix: string): void {
const m = /^CREATE\s+(UNIQUE\s+)?INDEX(\s+IF\s+NOT\s+EXISTS)?\s+("?)([a-z_][a-z0-9_]*)\3\s+ON\s+("?)([a-z_][a-z0-9_]*)\5/iu.exec(statement);
if (!m) {
throw new PluginMigrationError(
"forbidden_statement",
`CREATE INDEX statement does not match the supported shape: ${statement.slice(0, 80)}…`
);
}
const tableName = m[6]!;
if (!tableName.startsWith(allowedPrefix)) {
throw new PluginMigrationError(
"prefix_violation",
`Index target '${tableName}' must start with '${allowedPrefix}'.`
);
}
}
/**
* Split on top-level semicolons. Keeps it intentionally naive — the
* supported migration grammar (CREATE TABLE / CREATE INDEX) does not
* embed semicolons inside string literals.
*/
export function splitStatements(sql: string): ReadonlyArray<string> {
return stripSqlNoise(sql)
.split(";")
.map((s) => s.trim())
.filter((s) => s.length > 0);
}
export type ValidatedPluginMigration = {
pluginId: string;
sanitizedPluginId: string;
allowedPrefix: string;
statements: ReadonlyArray<string>;
};
/**
* Parse + validate a plugin migration SQL blob without executing it.
* Throws {@link PluginMigrationError} on any rule violation.
*/
export function validatePluginMigration(args: {
pluginId: string;
sql: string;
/** Override the default DEFAULT_MAX_STATEMENTS_PER_MIGRATION cap. */
maxStatements?: number;
}): ValidatedPluginMigration {
const sanitized = sanitizePluginIdForSql(args.pluginId);
const allowedPrefix = `plugin_${sanitized}_`;
const statements = splitStatements(args.sql);
const maxStatements = args.maxStatements ?? DEFAULT_MAX_STATEMENTS_PER_MIGRATION;
if (statements.length > maxStatements) {
throw new PluginMigrationError(
"too_many_statements",
`Migration declares ${statements.length} statements; cap is ${maxStatements}. ` +
"Split into multiple plugin versions or raise PLUGIN_MAX_STATEMENTS_PER_MIGRATION.",
);
}
for (const stmt of statements) {
const upper = stmt.toUpperCase();
// Stage 1 (legacy substring scan) — kept as belt-and-braces. Stage 2
// (token-aware scan, F-006) catches obfuscation + ignores string
// literal content. We run both: if stage 1 rejects a string-literal
// false-positive (e.g. `DEFAULT 'no grant'`) we let stage 2 override
// by checking it first. If stage 2 finds nothing AND stage 1 finds
// something, that something is by definition inside a string literal
// or a comment — both are benign in our limited grammar.
const tokens = tokenizeSqlIdentifiers(stmt);
const stage2 = findForbiddenKeyword(tokens);
if (stage2) {
throw new PluginMigrationError(
"forbidden_statement",
`Statement contains forbidden token '${stage2.keyword}' at position ${stage2.position}: ${stmt.slice(0, 80)}…`,
);
}
// Stage 1 fallback only when stage 2 found nothing — guards against
// a tokenizer edge-case missing something the substring scan would
// catch. Skip the check when the only stage-1 hit is inside a
// string literal (already cleared by stage 2's literal-aware walk).
for (const forbidden of FORBIDDEN_TOKENS) {
if (upper.includes(forbidden)) {
// Only treat as a real reject if NO identifier token containing
// the forbidden text exists OUTSIDE a string literal. The
// tokenizer already skipped string content; if a substring match
// wasn't covered by stage 2, it lives inside a literal/comment.
const live = tokens.some((tk) => tk.text.includes(forbidden.trim()));
if (live) {
throw new PluginMigrationError(
"forbidden_statement",
`Statement contains forbidden token '${forbidden}': ${stmt.slice(0, 80)}…`,
);
}
}
}
if (upper.startsWith("CREATE TABLE")) {
validateCreateTable(stmt, allowedPrefix);
} else if (upper.startsWith("CREATE INDEX") || upper.startsWith("CREATE UNIQUE INDEX")) {
validateCreateIndex(stmt, allowedPrefix);
} else {
throw new PluginMigrationError(
"forbidden_statement",
`Only CREATE TABLE / CREATE INDEX are allowed for plugin migrations. Got: ${stmt.slice(0, 40)}…`
);
}
}
return { pluginId: args.pluginId, sanitizedPluginId: sanitized, allowedPrefix, statements };
}
export type ApplyPluginMigrationDeps = {
/** Prisma `$executeRawUnsafe`-shaped seam. Returns rows affected. */
executeRawUnsafe: (sql: string) => Promise<number>;
logger?: {
info: (fields: Record<string, unknown>, msg: string) => void;
warn?: (fields: Record<string, unknown>, msg: string) => void;
error?: (fields: Record<string, unknown>, msg: string) => void;
};
};
/**
* Validate the SQL, then execute each statement sequentially through
* the injected seam. Returns the validated migration record for the
* caller to persist (e.g. `plugin_migrations_applied`).
*/
export async function applyPluginMigration(
args: { pluginId: string; sql: string },
deps: ApplyPluginMigrationDeps
): Promise<ValidatedPluginMigration> {
const validated = validatePluginMigration(args);
// F-007 — emit a per-statement audit line BEFORE running, so even a
// crash mid-execution leaves a trail of what the host attempted.
// The line is structured so log aggregation can join it back to the
// pluginId. We deliberately do NOT log the full statement — only the
// first 200 chars (enough for forensic correlation, short enough to
// bound log volume for big migrations).
for (let i = 0; i < validated.statements.length; i++) {
const stmt = validated.statements[i]!;
deps.logger?.info?.(
{
pluginId: args.pluginId,
statementIndex: i,
statementCount: validated.statements.length,
statementPreview: stmt.slice(0, 200),
},
"plugin.migration.execute_statement"
);
try {
await deps.executeRawUnsafe(stmt);
} catch (err) {
deps.logger?.error?.(
{
pluginId: args.pluginId,
statementIndex: i,
statementPreview: stmt.slice(0, 200),
error: err instanceof Error ? err.message : String(err),
},
"plugin.migration.execute_failed"
);
throw new PluginMigrationError(
"execute_failed",
`Plugin migration for ${args.pluginId} failed to execute: ${err instanceof Error ? err.message : String(err)}`
);
}
}
deps.logger?.info?.(
{ pluginId: args.pluginId, statements: validated.statements.length },
"plugin.migration.applied"
);
return validated;
}