@rehearsal-db/core 0.1.0-beta.14 → 0.1.0-beta.16

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

@@ -0,0 +1,147 @@
+/** Typed, normalized contract shared by privacy validation and execution stages. */
+export type PrivacyAction = "KEEP" | "PSEUDONYMIZE" | "REPLACE" | "EXCLUDE" | "DERIVE";
+export type PrivacyObject = Record<string, unknown>;
+export interface PseudonymRecipe {
+    format: "uuid" | "email" | "text" | "integer" | "hex" | "gtin" | "url";
+    namespace: string;
+    maxLength?: number;
+    length?: number;
+    allowedLengths?: readonly number[];
+    origin?: string;
+}
+export interface ConstantRecipe {
+    kind: "constant";
+    value: unknown;
+}
+export interface DateShiftRecipe {
+    kind: "date-shift";
+    days: number;
+    representation: "iso-string" | "epoch-milliseconds";
+    group?: string;
+}
+export interface EnumRecipe {
+    kind: "enum";
+    allowNull: boolean;
+    values: readonly (string | number | boolean)[];
+}
+export interface ValidatedStringRecipe {
+    kind: "validated-string";
+    format: "portable-code";
+    maximumBytes: number;
+    allowNull: boolean;
+}
+export interface DigestRecipe {
+    kind: "digest";
+    format: "hex";
+    length: number;
+    namespace: string;
+    inputs: readonly string[];
+}
+export interface BindingSubstituteRecipe {
+    kind: "binding-substitute";
+    binding: string;
+    format: "uuid";
+    namespace: string;
+    maximumBytes: number;
+}
+export interface PathMapRecipe {
+    kind: "path-map";
+    mapping: string;
+}
+export interface ApprovedOwnerRecipe {
+    kind: "approved-owner";
+    approved: NormalizedDeclaration;
+    otherwise: NormalizedDeclaration;
+}
+export interface JsonArrayRecipe {
+    kind: "json-array";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    items: NormalizedDeclaration;
+}
+export interface JsonObjectRecipe {
+    kind: "json-object";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    fields: Readonly<Record<string, NormalizedDeclaration>>;
+}
+export interface JsonUnionRecipe {
+    kind: "json-union";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    variants: Readonly<Record<string, NormalizedDeclaration>>;
+}
+export interface JsonDictionaryRecipe {
+    kind: "json-dictionary";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    keys: Readonly<Record<string, unknown>>;
+    values: NormalizedDeclaration;
+}
+export type DerivationRecipe = DateShiftRecipe | EnumRecipe | ValidatedStringRecipe | DigestRecipe | BindingSubstituteRecipe | PathMapRecipe | ApprovedOwnerRecipe | JsonArrayRecipe | JsonObjectRecipe | JsonUnionRecipe | JsonDictionaryRecipe;
+export type NormalizedRecipe = PseudonymRecipe | ConstantRecipe | DerivationRecipe | null;
+export interface NormalizedDeclaration {
+    action: PrivacyAction;
+    recipe: NormalizedRecipe;
+    required?: boolean;
+}
+export interface PrivacyBinding {
+    environmentVariable: string;
+    approvedValueSha256: string;
+}
+export interface PrivacyPathMapping extends PseudonymRecipe {
+    binding: string;
+    format: "uuid" | "text";
+    maximumBytes: number;
+    maximumSegments: number;
+}
+export interface PrivacyForeignKey {
+    readonly schema: string;
+    readonly table: string;
+    readonly column: string;
+}
+export interface PrivacyColumn extends NormalizedDeclaration {
+    name: string;
+    generated: "ALWAYS" | "NEVER";
+    identity: "YES" | "NO";
+    foreignKey: PrivacyForeignKey | null;
+}
+export interface PrivacyTable {
+    schema: string;
+    name: string;
+    sourceRows: "STREAM AND SANITIZE" | "EXCLUDE";
+    ownerBinding: Readonly<{
+        binding: string;
+        columns: readonly string[];
+        match: "any";
+        nullBehavior?: "otherwise";
+    }> | null;
+    columns: readonly PrivacyColumn[];
+}
+export interface ExecutablePrivacyPolicy {
+    readonly policyVersion: 2;
+    readonly migrationCutoff: string;
+    readonly bindings: Readonly<Record<string, PrivacyBinding>>;
+    readonly pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
+    readonly tables: readonly PrivacyTable[];
+}
+export interface PrivacySourceRecord {
+    schema?: string;
+    table: string;
+    row: Record<string, unknown>;
+}
+export interface PrivacyEngine {
+    readonly keyFingerprint: string;
+    remapPath(input: {
+        mapping: string;
+        value: string;
+    }): string;
+    sanitize(record: unknown): PrivacySourceRecord | null;
+}

package/dist/src/baseline/privacy_contract.mjs

@@ -0,0 +1,2 @@
+/** Typed, normalized contract shared by privacy validation and execution stages. */
+export {};

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

@@ -0,0 +1,7 @@
+/** Validate cross-rule bindings, dependencies, and shared deterministic groups. */
+import type { PrivacyBinding, PrivacyPathMapping, PrivacyTable } from "./privacy_contract.mjs";
+export declare const validatePrivacyDependencyGraph: ({ tables, bindings, pathMappings, }: {
+    tables: readonly PrivacyTable[];
+    bindings: Readonly<Record<string, PrivacyBinding>>;
+    pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
+}) => void;

package/dist/src/baseline/privacy_dependency_graph.mjs

@@ -0,0 +1,110 @@
+/** Validate cross-rule bindings, dependencies, and shared deterministic groups. */
+import { structuredJsonDeclarations } from "./privacy_structured_json.mjs";
+const usesApprovedOwner = (declaration) => (declaration.recipe !== null &&
+    "kind" in declaration.recipe &&
+    declaration.recipe.kind === "approved-owner") ||
+    structuredJsonDeclarations(declaration.recipe).some(usesApprovedOwner);
+const visitRecipes = (declaration, visit) => {
+    visit(declaration.recipe);
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "approved-owner") {
+        visitRecipes(declaration.recipe.approved, visit);
+        visitRecipes(declaration.recipe.otherwise, visit);
+    }
+    else {
+        structuredJsonDeclarations(declaration.recipe).forEach((nested) => visitRecipes(nested, visit));
+    }
+};
+const digestInputs = (declaration) => {
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "digest") {
+        return [...declaration.recipe.inputs];
+    }
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "approved-owner") {
+        return [
+            ...digestInputs(declaration.recipe.approved),
+            ...digestInputs(declaration.recipe.otherwise),
+        ];
+    }
+    return structuredJsonDeclarations(declaration.recipe).flatMap(digestInputs);
+};
+const validateTableDependencies = ({ table, index, bindings, pathMappings, }) => {
+    const label = `policy.tables[${index}]`;
+    if (table.columns.some(usesApprovedOwner) && !table.ownerBinding) {
+        throw new Error(`${label} uses approved-owner without ownerBinding.`);
+    }
+    for (const column of table.columns) {
+        visitRecipes(column, (recipe) => {
+            if (recipe &&
+                "kind" in recipe &&
+                recipe.kind === "path-map" &&
+                !Object.hasOwn(pathMappings, recipe.mapping)) {
+                throw new Error(`${label} references unknown path mapping ${recipe.mapping}.`);
+            }
+            if (recipe !== null &&
+                "kind" in recipe &&
+                recipe.kind === "binding-substitute" &&
+                !Object.hasOwn(bindings, recipe.binding)) {
+                throw new Error(`${label} references unknown privacy binding ${recipe.binding}.`);
+            }
+        });
+    }
+    const dependencies = new Map(table.columns.map((column) => [column.name, []]));
+    for (const column of table.columns) {
+        const inputs = [...new Set(digestInputs(column))];
+        for (const input of inputs) {
+            const inputColumn = table.columns.find((entry) => entry.name === input);
+            if (!inputColumn) {
+                throw new Error(`${label}.${column.name} digest references unknown column ${input}.`);
+            }
+            if (inputColumn.action === "EXCLUDE") {
+                throw new Error(`${label}.${column.name} digest input ${input} is excluded instead of sanitized.`);
+            }
+        }
+        dependencies.set(column.name, inputs);
+    }
+    const resolved = new Set();
+    const resolving = new Set();
+    const visitDependency = (columnName) => {
+        if (resolved.has(columnName))
+            return;
+        if (resolving.has(columnName)) {
+            throw new Error(`${label} contains a cyclic digest dependency.`);
+        }
+        resolving.add(columnName);
+        for (const input of dependencies.get(columnName) ?? []) {
+            visitDependency(input);
+        }
+        resolving.delete(columnName);
+        resolved.add(columnName);
+    };
+    table.columns.forEach((column) => visitDependency(column.name));
+};
+export const validatePrivacyDependencyGraph = ({ tables, bindings, pathMappings, }) => {
+    tables.forEach((table, index) => validateTableDependencies({ table, index, bindings, pathMappings }));
+    const dateShiftGroups = new Map();
+    const validateDateShiftGroup = (declaration) => {
+        const recipe = declaration.recipe;
+        if (!recipe || !("kind" in recipe))
+            return;
+        if (recipe.kind === "date-shift" && recipe.group) {
+            const existing = dateShiftGroups.get(recipe.group);
+            if (existing !== undefined && existing !== recipe.days) {
+                throw new Error(`Privacy date-shift group ${recipe.group} must use one days value.`);
+            }
+            dateShiftGroups.set(recipe.group, recipe.days);
+        }
+        if (recipe.kind === "approved-owner") {
+            validateDateShiftGroup(recipe.approved);
+            validateDateShiftGroup(recipe.otherwise);
+        }
+        else {
+            structuredJsonDeclarations(recipe).forEach(validateDateShiftGroup);
+        }
+    };
+    tables.forEach((table) => table.columns.forEach(validateDateShiftGroup));
+};

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

@@ -0,0 +1,5 @@
+/** Stable public facade for the versioned, fail-closed privacy pipeline. */
+export { validateExecutablePrivacyPolicy } from "./privacy_policy.mjs";
+export { createPrivacyEngine } from "./privacy_pipeline.mjs";
+export { assertPrivacyKeyFingerprint, createPrivacyKey, readPrivacyKey, } from "./privacy_key.mjs";
+export type { ExecutablePrivacyPolicy, PrivacyColumn, PrivacyEngine, PrivacyForeignKey, PrivacySourceRecord, PrivacyTable, } from "./privacy_policy.mjs";

package/dist/src/baseline/privacy_engine.mjs

@@ -0,0 +1,4 @@
+/** Stable public facade for the versioned, fail-closed privacy pipeline. */
+export { validateExecutablePrivacyPolicy } from "./privacy_policy.mjs";
+export { createPrivacyEngine } from "./privacy_pipeline.mjs";
+export { assertPrivacyKeyFingerprint, createPrivacyKey, readPrivacyKey, } from "./privacy_key.mjs";

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

@@ -0,0 +1,7 @@
+/** Create and verify the owner-only secret used by deterministic privacy rules. */
+export declare const PRIVACY_KEY_BYTES = 32;
+export declare const createPrivacyKey: (path: string) => Promise<{
+    fingerprint: string;
+}>;
+export declare const readPrivacyKey: (path: string) => Promise<Buffer>;
+export declare const assertPrivacyKeyFingerprint: (key: Uint8Array, expected: unknown) => void;

package/dist/src/baseline/privacy_key.mjs

@@ -0,0 +1,42 @@
+/** Create and verify the owner-only secret used by deterministic privacy rules. */
+import { createHash, randomBytes } from "node:crypto";
+import { chmod, mkdir, open, readFile, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+export const PRIVACY_KEY_BYTES = 32;
+const HEX_64 = /^[a-f0-9]{64}$/u;
+export const createPrivacyKey = async (path) => {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const key = randomBytes(PRIVACY_KEY_BYTES);
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(`${key.toString("base64")}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await chmod(path, 0o600);
+    return { fingerprint: createHash("sha256").update(key).digest("hex") };
+};
+export const readPrivacyKey = async (path) => {
+    const details = await stat(path);
+    if (!details.isFile() || (details.mode & 0o077) !== 0) {
+        throw new Error("Privacy key must be an owner-only regular file.");
+    }
+    const encoded = (await readFile(path, "utf8")).trim();
+    const key = Buffer.from(encoded, "base64");
+    if (key.length !== PRIVACY_KEY_BYTES ||
+        !/^[A-Za-z0-9+/]+={0,2}$/u.test(encoded)) {
+        throw new Error("Privacy key file is invalid.");
+    }
+    return key;
+};
+export const assertPrivacyKeyFingerprint = (key, expected) => {
+    if (typeof expected !== "string" || !HEX_64.test(expected)) {
+        throw new Error("Privacy key fingerprint is invalid.");
+    }
+    const actual = createHash("sha256").update(key).digest("hex");
+    if (actual !== expected) {
+        throw new Error("Privacy key does not match the reviewed baseline receipt.");
+    }
+};

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

@@ -0,0 +1,7 @@
+/** Resolve reviewed bindings and execute the dependency-aware row privacy pipeline. */
+import type { PrivacyEngine } from "./privacy_contract.mjs";
+export declare const createPrivacyEngine: ({ policy, key, environment, }: {
+    policy: unknown;
+    key: Uint8Array | string;
+    environment?: NodeJS.ProcessEnv;
+}) => Readonly<PrivacyEngine>;

package/dist/src/baseline/privacy_pipeline.mjs

@@ -0,0 +1,127 @@
+/** Resolve reviewed bindings and execute the dependency-aware row privacy pipeline. */
+import { createHash } from "node:crypto";
+import { PRIVACY_KEY_BYTES } from "./privacy_key.mjs";
+import { validateExecutablePrivacyPolicy } from "./privacy_policy.mjs";
+import { executePrivacyDeclaration } from "./privacy_rule_registry.mjs";
+import { remapPrivacyPath } from "./privacy_transforms.mjs";
+import { IDENTIFIER, isPrivacyObject } from "./privacy_validation_shared.mjs";
+export const createPrivacyEngine = ({ policy, key, environment = process.env, }) => {
+    const normalized = validateExecutablePrivacyPolicy(policy);
+    const secret = Buffer.isBuffer(key) ? key : Buffer.from(key ?? "");
+    if (secret.length < PRIVACY_KEY_BYTES) {
+        throw new Error(`Privacy key must contain at least ${PRIVACY_KEY_BYTES} bytes.`);
+    }
+    const bindingValues = new Map(Object.entries(normalized.bindings).map(([name, binding]) => {
+        const value = environment[binding.environmentVariable];
+        if (typeof value !== "string" || !value) {
+            throw new Error(`Privacy binding ${name} requires ${binding.environmentVariable}.`);
+        }
+        const receipt = createHash("sha256").update(value).digest("hex");
+        if (receipt !== binding.approvedValueSha256) {
+            throw new Error(`Privacy binding ${name} does not match its review receipt.`);
+        }
+        return [name, value];
+    }));
+    const tables = new Map(normalized.tables.map((table) => [
+        table.schema === "public" ? table.name : `${table.schema}.${table.name}`,
+        table,
+    ]));
+    return Object.freeze({
+        keyFingerprint: createHash("sha256").update(secret).digest("hex"),
+        remapPath({ mapping: mappingName, value, }) {
+            const mapping = normalized.pathMappings[mappingName];
+            if (!mapping) {
+                throw new Error(`Privacy path mapping ${mappingName} is not declared.`);
+            }
+            return remapPrivacyPath({
+                key: secret,
+                mapping,
+                bindingValue: bindingValues.get(mapping.binding),
+                value,
+                label: `Privacy path mapping ${mappingName}`,
+            });
+        },
+        sanitize(record) {
+            if (!isPrivacyObject(record) ||
+                typeof (record.schema ?? "public") !== "string" ||
+                !IDENTIFIER.test(String(record.schema ?? "public")) ||
+                typeof record.table !== "string" ||
+                !IDENTIFIER.test(record.table) ||
+                !isPrivacyObject(record.row)) {
+                throw new Error("Source record has an invalid privacy-engine shape.");
+            }
+            const schema = String(record.schema ?? "public");
+            const rowSource = record.row;
+            const relation = schema === "public" ? record.table : `${schema}.${record.table}`;
+            const table = tables.get(relation);
+            if (!table) {
+                throw new Error(`Privacy policy does not classify table ${relation}.`);
+            }
+            if (table.sourceRows === "EXCLUDE")
+                return null;
+            const actual = Object.keys(rowSource).sort();
+            const expected = table.columns.map((column) => column.name).sort();
+            if (actual.join("\0") !== expected.join("\0")) {
+                throw new Error(`Source table ${relation} contains an unclassified or missing column.`);
+            }
+            let ownerApproved;
+            if (table.ownerBinding) {
+                const approvedValue = bindingValues.get(table.ownerBinding.binding);
+                const owners = table.ownerBinding.columns.map((column) => rowSource[column]);
+                for (const owner of owners) {
+                    if (owner === null) {
+                        if (table.ownerBinding.nullBehavior !== "otherwise") {
+                            throw new Error(`${relation} has an invalid owner binding value.`);
+                        }
+                        continue;
+                    }
+                    if (!["string", "number"].includes(typeof owner) ||
+                        owner === "" ||
+                        (typeof owner === "number" && !Number.isFinite(owner))) {
+                        throw new Error(`${relation} has an invalid owner binding value.`);
+                    }
+                }
+                ownerApproved = owners.some((owner) => owner !== null && String(owner) === approvedValue);
+            }
+            const sanitizedColumns = new Map();
+            const resolvingColumns = new Set();
+            const sanitizeColumn = (columnName) => {
+                if (sanitizedColumns.has(columnName)) {
+                    return sanitizedColumns.get(columnName);
+                }
+                if (resolvingColumns.has(columnName)) {
+                    throw new Error(`${relation} contains a cyclic digest dependency.`);
+                }
+                const column = table.columns.find((entry) => entry.name === columnName);
+                if (!column) {
+                    throw new Error(`${relation} digest references unknown column ${columnName}.`);
+                }
+                resolvingColumns.add(columnName);
+                try {
+                    const transformed = executePrivacyDeclaration({
+                        declaration: column,
+                        value: rowSource[column.name],
+                        key: secret,
+                        path: `${relation}.${column.name}`,
+                        ownerApproved,
+                        pathMappings: normalized.pathMappings,
+                        bindingValues,
+                        resolveInput: sanitizeColumn,
+                    });
+                    sanitizedColumns.set(columnName, transformed);
+                    return transformed;
+                }
+                finally {
+                    resolvingColumns.delete(columnName);
+                }
+            };
+            const row = Object.fromEntries(table.columns.flatMap((column) => {
+                const transformed = sanitizeColumn(column.name);
+                return transformed === undefined ? [] : [[column.name, transformed]];
+            }));
+            return schema === "public"
+                ? { table: record.table, row }
+                : { schema, table: record.table, row };
+        },
+    });
+};

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

@@ -0,0 +1,6 @@
+/**
+ * Validate and normalize the complete reviewed privacy policy version 2.
+ */
+import type { ExecutablePrivacyPolicy } from "./privacy_contract.mjs";
+export type { ExecutablePrivacyPolicy, PrivacyColumn, PrivacyEngine, PrivacyForeignKey, PrivacySourceRecord, PrivacyTable, } from "./privacy_contract.mjs";
+export declare const validateExecutablePrivacyPolicy: (policy: unknown) => ExecutablePrivacyPolicy;