@rehearsal-db/core 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/src/baseline/sanitization_policy.mjs

@@ -0,0 +1,227 @@
+/**
+ * Generic, fail-closed sanitization policy validation and value operations.
+ * Projects own the policy, schema inventory, pseudonym keys, and derivation logic.
+ */
+import { createHash } from "node:crypto";
+import { validateExecutablePrivacyPolicy, } from "./privacy_engine.mjs";
+export const SANITIZATION_ACTIONS = Object.freeze({
+    KEEP: "KEEP",
+    PSEUDONYMIZE: "PSEUDONYMIZE",
+    REPLACE: "REPLACE",
+    EXCLUDE: "EXCLUDE",
+    DERIVE: "DERIVE",
+});
+export const EXCLUDED_VALUE = Symbol("REHEARSAL_EXCLUDED_VALUE");
+const isPolicyObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const assertPolicyObject = (value, label) => {
+    if (!isPolicyObject(value))
+        throw new Error(`${label} must be an object.`);
+    return value;
+};
+const actionAliases = new Map([
+    ["KEEP", SANITIZATION_ACTIONS.KEEP],
+    ["KEEP EXACTLY", SANITIZATION_ACTIONS.KEEP],
+    ["PSEUDONYMIZE", SANITIZATION_ACTIONS.PSEUDONYMIZE],
+    ["REPLACE", SANITIZATION_ACTIONS.REPLACE],
+    ["REPLACE WITH SYNTHETIC", SANITIZATION_ACTIONS.REPLACE],
+    ["EXCLUDE", SANITIZATION_ACTIONS.EXCLUDE],
+    ["DERIVE", SANITIZATION_ACTIONS.DERIVE],
+]);
+const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
+const assertIdentifier = (value, label) => {
+    if (typeof value !== "string" || !identifierPattern.test(value)) {
+        throw new Error(`${label} must be a lowercase PostgreSQL identifier.`);
+    }
+    return value;
+};
+const tableSchema = (table) => assertIdentifier(table.schema ?? "public", "Sanitization policy table schema");
+export const normalizeSanitizationAction = (action) => {
+    const normalized = actionAliases.get(String(action ?? "")
+        .trim()
+        .toUpperCase());
+    if (!normalized) {
+        throw new Error(`Unknown Rehearsal sanitization action: ${action}.`);
+    }
+    return normalized;
+};
+export const validateRuntimeSanitizationPolicy = (policy) => {
+    if (!isPolicyObject(policy)) {
+        throw new Error("A Rehearsal sanitization policy object is required.");
+    }
+    if (policy.draft === true) {
+        throw new Error("The sanitization policy is still a REVIEW REQUIRED draft.");
+    }
+    if (policy.policyVersion === 2) {
+        return validateExecutablePrivacyPolicy(policy);
+    }
+    if (policy.policyVersion !== 1) {
+        throw new Error("The sanitization policy must use policyVersion 1 or 2.");
+    }
+    if (typeof policy.migrationCutoff !== "string" ||
+        !/^\d{14}$/u.test(policy.migrationCutoff)) {
+        throw new Error("The sanitization policy must declare a timestamp migrationCutoff.");
+    }
+    if (!Array.isArray(policy.tables) || policy.tables.length === 0) {
+        throw new Error("The sanitization policy does not list tables.");
+    }
+    const tables = new Set();
+    for (const tableValue of policy.tables) {
+        const table = assertPolicyObject(tableValue, "Sanitization policy table");
+        const schemaName = assertIdentifier(tableSchema(table), "Sanitization policy table schema");
+        const tableName = assertIdentifier(table?.name, "Sanitization policy table name");
+        const key = schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
+        if (tables.has(key)) {
+            throw new Error(`Sanitization policy duplicates table ${key}.`);
+        }
+        tables.add(key);
+        if (typeof table.sourceRows !== "string" ||
+            !["STREAM AND SANITIZE", "EXCLUDE"].includes(table.sourceRows)) {
+            throw new Error(`Sanitization policy table ${tableName} has an invalid sourceRows decision.`);
+        }
+        if (!Array.isArray(table.columns) || table.columns.length === 0) {
+            throw new Error(`Sanitization policy table ${tableName} must list its columns.`);
+        }
+        const columns = new Set();
+        for (const columnValue of table.columns) {
+            const column = assertPolicyObject(columnValue, `Sanitization policy column in ${tableName}`);
+            const columnName = assertIdentifier(column?.name, `Sanitization policy column in ${tableName}`);
+            if (columns.has(columnName)) {
+                throw new Error(`Sanitization policy duplicates column ${tableName}.${columnName}.`);
+            }
+            columns.add(columnName);
+            normalizeSanitizationAction(column.action);
+            if (typeof column.generated !== "string" ||
+                !["ALWAYS", "NEVER"].includes(column.generated)) {
+                throw new Error(`Sanitization policy column ${tableName}.${columnName} must classify generated as ALWAYS or NEVER.`);
+            }
+            if (typeof column.identity !== "string" ||
+                !["YES", "NO"].includes(column.identity)) {
+                throw new Error(`Sanitization policy column ${tableName}.${columnName} must classify identity as YES or NO.`);
+            }
+            if (column.foreignKey !== null) {
+                if (!column.foreignKey ||
+                    typeof column.foreignKey !== "object" ||
+                    Array.isArray(column.foreignKey)) {
+                    throw new Error(`Sanitization policy column ${tableName}.${columnName} has an invalid foreignKey decision.`);
+                }
+                const foreignKey = column.foreignKey;
+                assertIdentifier(foreignKey.schema, `Foreign-key schema for ${tableName}.${columnName}`);
+                assertIdentifier(foreignKey.table, `Foreign-key table for ${tableName}.${columnName}`);
+                assertIdentifier(foreignKey.column, `Foreign-key column for ${tableName}.${columnName}`);
+            }
+        }
+    }
+    return policy;
+};
+export const readBoundRuntimeSanitizationPolicy = ({ bytes, expectedSha256, }) => {
+    const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+    const policy = validateRuntimeSanitizationPolicy(JSON.parse(source.toString("utf8")));
+    const actualSha256 = createHash("sha256").update(source).digest("hex");
+    if (actualSha256 !== expectedSha256) {
+        throw new Error("The active sanitization policy does not match the reviewed baseline policy checksum.");
+    }
+    return policy;
+};
+const indexTables = (tables, label) => {
+    if (!Array.isArray(tables))
+        throw new Error(`${label} must be an array.`);
+    const index = new Map();
+    for (const tableValue of tables) {
+        const table = assertPolicyObject(tableValue, `${label} table`);
+        const schema = assertIdentifier(tableSchema(table), `${label} table schema`);
+        const name = assertIdentifier(table?.name, `${label} table name`);
+        const key = schema === "public" ? name : `${schema}.${name}`;
+        if (index.has(key))
+            throw new Error(`${label} duplicates table ${key}.`);
+        if (!Array.isArray(table.columns)) {
+            throw new Error(`${label} table ${name} must list its columns.`);
+        }
+        const columns = new Map();
+        for (const column of table.columns) {
+            const columnName = assertIdentifier(typeof column === "string"
+                ? column
+                : isPolicyObject(column)
+                    ? column.name
+                    : undefined, `${label} column name`);
+            if (columns.has(columnName)) {
+                throw new Error(`${label} duplicates column ${name}.${columnName}.`);
+            }
+            columns.set(columnName, column);
+        }
+        index.set(key, { table: { ...table, schema }, columns });
+    }
+    return index;
+};
+export const validateSanitizationCoverage = ({ policy, schemaTables, }) => {
+    if (!isPolicyObject(policy)) {
+        throw new Error("A Rehearsal sanitization policy object is required.");
+    }
+    const schema = indexTables(schemaTables, "Schema inventory");
+    const classified = indexTables(policy.tables, "Sanitization policy");
+    const normalizedTables = [];
+    for (const [tableName, schemaEntry] of schema) {
+        const policyEntry = classified.get(tableName);
+        if (!policyEntry) {
+            throw new Error(`Sanitization policy does not classify table ${tableName}.`);
+        }
+        const normalizedColumns = [];
+        for (const columnName of schemaEntry.columns.keys()) {
+            const column = policyEntry.columns.get(columnName);
+            if (!column) {
+                throw new Error(`Sanitization policy does not classify column ${tableName}.${columnName}.`);
+            }
+            const policyColumn = assertPolicyObject(column, `Sanitization policy column ${tableName}.${columnName}`);
+            normalizedColumns.push({
+                ...policyColumn,
+                name: columnName,
+                action: normalizeSanitizationAction(policyColumn.action),
+            });
+        }
+        for (const columnName of policyEntry.columns.keys()) {
+            if (!schemaEntry.columns.has(columnName)) {
+                throw new Error(`Sanitization policy references unknown column ${tableName}.${columnName}.`);
+            }
+        }
+        normalizedTables.push({
+            ...policyEntry.table,
+            schema: tableSchema(policyEntry.table),
+            columns: normalizedColumns,
+        });
+    }
+    for (const tableName of classified.keys()) {
+        if (!schema.has(tableName)) {
+            throw new Error(`Sanitization policy references unknown table ${tableName}.`);
+        }
+    }
+    return Object.freeze({
+        policyVersion: policy.policyVersion,
+        tableCount: normalizedTables.length,
+        columnCount: normalizedTables.reduce((total, table) => total + table.columns.length, 0),
+        tables: Object.freeze(normalizedTables),
+    });
+};
+export const applySanitizationAction = ({ action, value, replace, pseudonymize, derive, context = {}, }) => {
+    switch (normalizeSanitizationAction(action)) {
+        case SANITIZATION_ACTIONS.KEEP:
+            return value;
+        case SANITIZATION_ACTIONS.EXCLUDE:
+            return EXCLUDED_VALUE;
+        case SANITIZATION_ACTIONS.REPLACE:
+            if (typeof replace !== "function") {
+                throw new Error("REPLACE requires a project-owned replacement function.");
+            }
+            return replace(value, context);
+        case SANITIZATION_ACTIONS.PSEUDONYMIZE:
+            if (typeof pseudonymize !== "function") {
+                throw new Error("PSEUDONYMIZE requires a project-owned pseudonymization function.");
+            }
+            return pseudonymize(value, context);
+        case SANITIZATION_ACTIONS.DERIVE:
+            if (typeof derive !== "function") {
+                throw new Error("DERIVE requires a project-owned derivation function.");
+            }
+            return derive(value, context);
+        default:
+            throw new Error("Unreachable Rehearsal sanitization action.");
+    }
+};

package/dist/src/baseline/schema_snapshot.d.mts

@@ -0,0 +1,19 @@
+/**
+ * Purpose: Capture and compare bounded, data-free PostgreSQL public-schema
+ * snapshots for a local Rehearsal runtime. Do not run directly.
+ */
+export declare const assertProductionSchemaDump: (schemaSql: string) => string;
+export declare const compareProductionSchemaDumps: ({ expected, actual, }: {
+    expected: string;
+    actual: string;
+}) => string;
+export declare const captureSupabasePublicSchema: ({ repositoryRoot, artifactRoot, arguments_, }: {
+    repositoryRoot: string;
+    artifactRoot: string;
+    arguments_: readonly string[];
+}) => Promise<string>;
+export declare const captureLocalPublicSchema: ({ repositoryRoot, artifactRoot, workdir, }: {
+    repositoryRoot: string;
+    artifactRoot: string;
+    workdir: string;
+}) => Promise<string>;

package/dist/src/baseline/schema_snapshot.mjs

@@ -0,0 +1,79 @@
+/**
+ * Purpose: Capture and compare bounded, data-free PostgreSQL public-schema
+ * snapshots for a local Rehearsal runtime. Do not run directly.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmod, mkdir, mkdtemp, readFile, rm } from "node:fs/promises";
+import { basename, join, resolve, sep } from "node:path";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
+const maximumSchemaBytes = 64 * 1024 * 1024;
+const assertArtifactRoot = (artifactRoot) => {
+    const resolved = resolve(artifactRoot);
+    if (basename(resolved) !== ".rehearsal" || resolved === sep) {
+        throw new Error(`Refusing an unsafe Rehearsal artifact root: ${artifactRoot}`);
+    }
+    return resolved;
+};
+export const assertProductionSchemaDump = (schemaSql) => {
+    if (typeof schemaSql !== "string" || schemaSql.length === 0) {
+        throw new Error("The Rehearsal production schema snapshot is empty.");
+    }
+    if (Buffer.byteLength(schemaSql) > maximumSchemaBytes) {
+        throw new Error("The Rehearsal production schema snapshot is too large.");
+    }
+    if (!schemaSql.includes('CREATE SCHEMA IF NOT EXISTS "public";')) {
+        throw new Error("The Rehearsal production schema snapshot does not define public.");
+    }
+    if (/^COPY\s|^\\connect\s|^CREATE DATABASE\s/mu.test(schemaSql)) {
+        throw new Error("The Rehearsal production schema snapshot contains data or database switching commands.");
+    }
+    return schemaSql;
+};
+const comparableSchemaDump = (schemaSql) => assertProductionSchemaDump(schemaSql)
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter(Boolean)
+    .map((line) => {
+    const checkConstraint = line.match(/^(\s*CONSTRAINT "[^"]+" CHECK ).*(,?)$/u);
+    return checkConstraint
+        ? `${checkConstraint[1]}<database-normalized-expression>${checkConstraint[2]}`
+        : line;
+})
+    .join("\n");
+export const compareProductionSchemaDumps = ({ expected, actual, }) => {
+    const expectedComparable = comparableSchemaDump(expected);
+    const actualComparable = comparableSchemaDump(actual);
+    if (expectedComparable !== actualComparable) {
+        throw new Error("The local Rehearsal public schema does not structurally match the production snapshot.");
+    }
+    return createHash("sha256").update(actualComparable).digest("hex");
+};
+export const captureSupabasePublicSchema = async ({ repositoryRoot, artifactRoot, arguments_, }) => {
+    const root = assertArtifactRoot(artifactRoot);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const temporaryDirectory = await mkdtemp(join(root, ".schema-capture-"));
+    const destination = join(temporaryDirectory, "production-schema.sql");
+    try {
+        const result = spawnSync("supabase", [...arguments_, "--schema", "public", "--file", destination], {
+            cwd: repositoryRoot,
+            env: createCleanProcessEnvironment(),
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 4 * 1024 * 1024,
+        });
+        if (result.error || result.status !== 0) {
+            throw new Error("The exact Rehearsal schema snapshot could not be captured.", { cause: result.error });
+        }
+        await chmod(destination, 0o600);
+        return assertProductionSchemaDump(await readFile(destination, "utf8"));
+    }
+    finally {
+        await rm(temporaryDirectory, { recursive: true, force: true });
+    }
+};
+export const captureLocalPublicSchema = ({ repositoryRoot, artifactRoot, workdir, }) => captureSupabasePublicSchema({
+    repositoryRoot,
+    artifactRoot,
+    arguments_: ["db", "dump", "--local", "--workdir", workdir],
+});

package/dist/src/cli/arguments.d.mts

@@ -0,0 +1,43 @@
+/** Parse and classify the stable Rehearsal command-line contract. */
+export type RehearsalVerbosity = "normal" | "verbose" | "debug";
+export interface RehearsalCliFlags {
+    json: boolean;
+    help: boolean;
+    version: boolean;
+    verbosity: RehearsalVerbosity;
+    dryRun: boolean;
+    write: boolean;
+    plain: boolean;
+    configPath: string | undefined;
+    confirmation: string | undefined;
+    recordsPath: string | undefined;
+    ledgerPath: string | undefined;
+    assetsPath: string | undefined;
+    target: string | undefined;
+    includeRuntime: boolean;
+    includeImages: boolean;
+    cleanupConfirmation: string | undefined;
+    sourceAccessConfirmation: string | undefined;
+    sourceRetirementConfirmation: string | undefined;
+    refreshConfirmation: string | undefined;
+    identityConfirmation: string | undefined;
+    identityName: string | undefined;
+    runtimeTopology: unknown | undefined;
+    targetConfirmations: unknown | undefined;
+    exitGuidedSession: boolean;
+    guided: boolean;
+    setupPlan?: unknown;
+    preparationPlan?: unknown;
+    cleanupPlan?: unknown;
+}
+export interface ParsedArguments {
+    flags: RehearsalCliFlags;
+    positionals: string[];
+}
+export declare const parseArguments: (arguments_: readonly string[]) => ParsedArguments;
+export declare const resetGuidedFlags: (flags: RehearsalCliFlags) => void;
+export declare const commandMutatesProject: ({ command, flags, guided, }: {
+    command: string;
+    flags: RehearsalCliFlags;
+    guided: boolean;
+}) => boolean;

package/dist/src/cli/arguments.mjs

@@ -0,0 +1,135 @@
+/** Parse and classify the stable Rehearsal command-line contract. */
+export const parseArguments = (arguments_) => {
+    const flags = {
+        json: false,
+        help: false,
+        version: false,
+        verbosity: "normal",
+        dryRun: false,
+        write: false,
+        plain: false,
+        configPath: undefined,
+        confirmation: undefined,
+        recordsPath: undefined,
+        ledgerPath: undefined,
+        assetsPath: undefined,
+        target: undefined,
+        includeRuntime: false,
+        includeImages: false,
+        cleanupConfirmation: undefined,
+        sourceAccessConfirmation: undefined,
+        sourceRetirementConfirmation: undefined,
+        refreshConfirmation: undefined,
+        identityConfirmation: undefined,
+        identityName: undefined,
+        runtimeTopology: undefined,
+        targetConfirmations: undefined,
+        exitGuidedSession: false,
+        guided: false,
+    };
+    const positionals = [];
+    for (const argument of arguments_) {
+        if (argument === "--json")
+            flags.json = true;
+        else if (argument === "--help" || argument === "-h")
+            flags.help = true;
+        else if (argument === "--version" || argument === "-V")
+            flags.version = true;
+        else if (argument === "--verbose")
+            flags.verbosity = "verbose";
+        else if (argument === "--debug")
+            flags.verbosity = "debug";
+        else if (argument === "--dry-run")
+            flags.dryRun = true;
+        else if (argument === "--write")
+            flags.write = true;
+        else if (argument === "--plain")
+            flags.plain = true;
+        else if (argument.startsWith("--config="))
+            flags.configPath = argument.slice("--config=".length);
+        else if (argument.startsWith("--confirm-candidates="))
+            flags.confirmation = argument.slice("--confirm-candidates=".length);
+        else if (argument.startsWith("--confirm-cleanup="))
+            flags.cleanupConfirmation = argument.slice("--confirm-cleanup=".length);
+        else if (argument.startsWith("--confirm-source-access="))
+            flags.sourceAccessConfirmation = argument.slice("--confirm-source-access=".length);
+        else if (argument.startsWith("--confirm-source-retirement="))
+            flags.sourceRetirementConfirmation = argument.slice("--confirm-source-retirement=".length);
+        else if (argument.startsWith("--confirm-refresh="))
+            flags.refreshConfirmation = argument.slice("--confirm-refresh=".length);
+        else if (argument.startsWith("--confirm-identity="))
+            flags.identityConfirmation = argument.slice("--confirm-identity=".length);
+        else if (argument.startsWith("--identity="))
+            flags.identityName = argument.slice("--identity=".length);
+        else if (argument.startsWith("--records="))
+            flags.recordsPath = argument.slice("--records=".length);
+        else if (argument.startsWith("--ledger="))
+            flags.ledgerPath = argument.slice("--ledger=".length);
+        else if (argument.startsWith("--assets="))
+            flags.assetsPath = argument.slice("--assets=".length);
+        else if (argument.startsWith("--target="))
+            flags.target = argument.slice("--target=".length);
+        else if (argument === "--include-runtime")
+            flags.includeRuntime = true;
+        else if (argument === "--include-images")
+            flags.includeImages = true;
+        else if (argument.startsWith("--"))
+            throw new Error(`Unknown Rehearsal option: ${argument}.`);
+        else
+            positionals.push(argument);
+    }
+    return { flags, positionals };
+};
+export const resetGuidedFlags = (flags) => {
+    Object.assign(flags, {
+        dryRun: false,
+        write: false,
+        confirmation: undefined,
+        recordsPath: undefined,
+        ledgerPath: undefined,
+        assetsPath: undefined,
+        target: undefined,
+        includeRuntime: false,
+        includeImages: false,
+        cleanupConfirmation: undefined,
+        sourceAccessConfirmation: undefined,
+        sourceRetirementConfirmation: undefined,
+        refreshConfirmation: undefined,
+        identityConfirmation: undefined,
+        identityName: undefined,
+        runtimeTopology: undefined,
+        targetConfirmations: undefined,
+        exitGuidedSession: false,
+        setupPlan: undefined,
+        preparationPlan: undefined,
+        cleanupPlan: undefined,
+    });
+};
+export const commandMutatesProject = ({ command, flags, guided, }) => {
+    if (guided)
+        return true;
+    if (["setup", "init", "baseline prepare", "privacy key"].includes(command))
+        return flags.write;
+    if (command === "cleanup")
+        return flags.write;
+    if (command === "source apply")
+        return Boolean(flags.sourceAccessConfirmation);
+    if (command === "source retire")
+        return Boolean(flags.sourceRetirementConfirmation);
+    if (command === "refresh")
+        return Boolean(flags.refreshConfirmation);
+    if (command === "identity claim")
+        return Boolean(flags.identityConfirmation);
+    if (command === "run")
+        return !flags.dryRun;
+    return [
+        "baseline create",
+        "baseline refresh",
+        "open",
+        "start",
+        "migrate",
+        "reset",
+        "stop",
+        "discard",
+    ].includes(command);
+};

package/dist/src/cli/guided.d.mts

@@ -0,0 +1,51 @@
+/**
+ * State-aware interactive home screen and first-run flows.
+ */
+import type { RehearsalConfigPathOptions } from "../project/configuration.mjs";
+import type { RehearsalCliFlags } from "./arguments.mjs";
+import type { RuntimeTopologyTarget } from "../runtime/topology.mjs";
+import type { RehearsalCleanupPlan } from "../runtime/cleanup.mjs";
+interface TopologySummary {
+    readonly topology: {
+        readonly dependents: readonly unknown[];
+        readonly targets: readonly RuntimeTopologyTarget[];
+    };
+}
+type GuidedCleanupPlan = RehearsalCleanupPlan | Readonly<{
+    digest: string;
+    targets: readonly Readonly<{
+        name: string;
+        plan: RehearsalCleanupPlan;
+    }>[];
+}>;
+interface GuidedRefreshPlan {
+    readonly digest: string;
+    readonly review: {
+        readonly currentBaseline: string;
+        readonly source: {
+            readonly readerExpiresAt: string;
+        };
+        readonly runtimeTargets: readonly string[];
+        readonly retention: {
+            readonly generations: number;
+            readonly removeAfterReplacement: readonly string[];
+        };
+        readonly steps: readonly string[];
+    };
+}
+export declare const createGuidedHome: ({ projectRoot, topologyCandidateSummary, buildRefreshWorkflowPlan, planRuntimeStackCleanup, getLastGuidedDetails, }: {
+    projectRoot: string;
+    topologyCandidateSummary: (options: RehearsalConfigPathOptions) => Promise<TopologySummary>;
+    buildRefreshWorkflowPlan: (options: RehearsalConfigPathOptions) => Promise<{
+        plan: GuidedRefreshPlan;
+    }>;
+    planRuntimeStackCleanup: (input: {
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+    }) => Promise<GuidedCleanupPlan>;
+    getLastGuidedDetails: () => string | undefined;
+}) => ({ flags, planOptions, }: {
+    flags: RehearsalCliFlags;
+    planOptions: RehearsalConfigPathOptions;
+}) => Promise<string | null>;
+export {};