Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/plugin-runtime/src/migrations.ts
T

449 lines
15 KiB
TypeScript
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 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;
}