@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.11

package/{scripts/lib/rehearsal → src/baseline}/sanitization_policy.mjs

@@ -3,6 +3,9 @@
  * 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",
@@ -31,6 +34,11 @@ const assertIdentifier = (value, label) => {
   }
   return value;
 };
+const tableSchema = (table) => table.schema ?? "public";
+const tableKey = (table) =>
+  tableSchema(table) === "public"
+    ? table.name
+    : `${tableSchema(table)}.${table.name}`;
 
 export const normalizeSanitizationAction = (action) => {
   const normalized = actionAliases.get(
@@ -44,12 +52,134 @@ export const normalizeSanitizationAction = (action) => {
   return normalized;
 };
 
+export const validateRuntimeSanitizationPolicy = (policy) => {
+  if (!policy || typeof policy !== "object" || Array.isArray(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 (!/^\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 table of policy.tables) {
+    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 (!["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 column of table.columns) {
+      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 (!["ALWAYS", "NEVER"].includes(column.generated)) {
+        throw new Error(
+          `Sanitization policy column ${tableName}.${columnName} must classify generated as ALWAYS or NEVER.`,
+        );
+      }
+      if (!["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.`,
+          );
+        }
+        assertIdentifier(
+          column.foreignKey.schema,
+          `Foreign-key schema for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.foreignKey.table,
+          `Foreign-key table for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.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 table of tables) {
+    const schema = assertIdentifier(
+      tableSchema(table),
+      `${label} table schema`,
+    );
     const name = assertIdentifier(table?.name, `${label} table name`);
-    if (index.has(name)) throw new Error(`${label} duplicates 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.`);
     }
@@ -64,7 +194,7 @@ const indexTables = (tables, label) => {
       }
       columns.set(columnName, column);
     }
-    index.set(name, { table, columns });
+    index.set(key, { table: { ...table, schema }, columns });
   }
   return index;
 };
@@ -107,7 +237,7 @@ export const validateSanitizationCoverage = ({ policy, schemaTables }) => {
     }
     normalizedTables.push({
       ...policyEntry.table,
-      name: tableName,
+      schema: tableSchema(policyEntry.table),
       columns: normalizedColumns,
     });
   }

package/{scripts/lib/rehearsal → src/baseline}/schema_snapshot.mjs

@@ -7,7 +7,7 @@ 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 "./process_environment.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 
 const maximumSchemaBytes = 64 * 1024 * 1024;
 

package/src/cli/arguments.mjs

@@ -0,0 +1,123 @@
+/** Parse and classify the stable Rehearsal command-line contract. */
+
+export const parseArguments = (arguments_) => {
+  const flags = {
+    json: false,
+    help: 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,
+  };
+  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 === "--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);
+};