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

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;

package/dist/src/baseline/privacy_policy.mjs

@@ -0,0 +1,237 @@
+/**
+ * Validate and normalize the complete reviewed privacy policy version 2.
+ */
+import { validatePrivacyDependencyGraph } from "./privacy_dependency_graph.mjs";
+import { validatePrivacyRecipe } from "./privacy_recipe_validation.mjs";
+import { ACTIONS, BINDING_NAME, DEFAULT_PATH_MAXIMUM_BYTES, DEFAULT_PATH_MAXIMUM_SEGMENTS, ENVIRONMENT_KEY, HEX_64, assertKnownKeys as knownKeys, isPrivacyObject as isObject, validateIdentifier as identifier, validateNonEmpty as nonEmpty, validatePositiveInteger as positiveInteger, } from "./privacy_validation_shared.mjs";
+export const validateExecutablePrivacyPolicy = (policy) => {
+    if (!isObject(policy))
+        throw new Error("Privacy policy must be an object.");
+    knownKeys(policy, [
+        "policyVersion",
+        "draft",
+        "migrationCutoff",
+        "bindings",
+        "pathMappings",
+        "tables",
+    ], "policy");
+    if (policy.policyVersion !== 2) {
+        throw new Error("Executable privacy policies must use policyVersion 2.");
+    }
+    if (policy.draft === true) {
+        throw new Error("The privacy policy is still a REVIEW REQUIRED draft.");
+    }
+    if (typeof policy.migrationCutoff !== "string" ||
+        !/^\d{14}$/u.test(policy.migrationCutoff)) {
+        throw new Error("Privacy policy migrationCutoff must be a timestamp version.");
+    }
+    if (!Array.isArray(policy.tables) || policy.tables.length === 0) {
+        throw new Error("Privacy policy must classify at least one table.");
+    }
+    if (policy.bindings !== undefined && !isObject(policy.bindings)) {
+        throw new Error("policy.bindings must be an object.");
+    }
+    const bindings = Object.fromEntries(Object.entries(policy.bindings ?? {}).map(([name, binding]) => {
+        if (!BINDING_NAME.test(name) || !isObject(binding)) {
+            throw new Error("policy.bindings contains an invalid binding.");
+        }
+        knownKeys(binding, ["environmentVariable", "approvedValueSha256"], `policy.bindings.${name}`);
+        if (typeof binding.environmentVariable !== "string" ||
+            !ENVIRONMENT_KEY.test(binding.environmentVariable)) {
+            throw new Error(`policy.bindings.${name}.environmentVariable is invalid.`);
+        }
+        if (typeof binding.approvedValueSha256 !== "string" ||
+            !HEX_64.test(binding.approvedValueSha256)) {
+            throw new Error(`policy.bindings.${name}.approvedValueSha256 must be a lowercase SHA-256 receipt.`);
+        }
+        return [
+            name,
+            Object.freeze({
+                environmentVariable: binding.environmentVariable,
+                approvedValueSha256: binding.approvedValueSha256,
+            }),
+        ];
+    }));
+    if (policy.pathMappings !== undefined && !isObject(policy.pathMappings)) {
+        throw new Error("policy.pathMappings must be an object.");
+    }
+    const pathMappings = Object.fromEntries(Object.entries(policy.pathMappings ?? {}).map(([name, mapping]) => {
+        const label = `policy.pathMappings.${name}`;
+        if (!BINDING_NAME.test(name) || !isObject(mapping)) {
+            throw new Error("policy.pathMappings contains an invalid mapping.");
+        }
+        knownKeys(mapping, [
+            "binding",
+            "format",
+            "namespace",
+            "maxLength",
+            "maximumBytes",
+            "maximumSegments",
+        ], label);
+        if (typeof mapping.binding !== "string" ||
+            !Object.hasOwn(bindings, mapping.binding)) {
+            throw new Error(`${label}.binding references an unknown binding.`);
+        }
+        if (typeof mapping.format !== "string" ||
+            !["uuid", "text"].includes(mapping.format)) {
+            throw new Error(`${label}.format must be uuid or text.`);
+        }
+        const normalized = {
+            binding: mapping.binding,
+            format: mapping.format,
+            namespace: nonEmpty(mapping.namespace, `${label}.namespace`),
+            maximumBytes: positiveInteger(mapping.maximumBytes ?? DEFAULT_PATH_MAXIMUM_BYTES, `${label}.maximumBytes`, 16_384),
+            maximumSegments: positiveInteger(mapping.maximumSegments ?? DEFAULT_PATH_MAXIMUM_SEGMENTS, `${label}.maximumSegments`, 256),
+        };
+        if (mapping.format === "text") {
+            return [
+                name,
+                Object.freeze({
+                    ...normalized,
+                    maxLength: positiveInteger(mapping.maxLength, `${label}.maxLength`, 1_024),
+                }),
+            ];
+        }
+        else if (mapping.maxLength !== undefined) {
+            throw new Error(`${label}.maxLength is supported only for text.`);
+        }
+        return [name, Object.freeze(normalized)];
+    }));
+    const names = new Set();
+    const tables = policy.tables.map((table, tableIndex) => {
+        const label = `policy.tables[${tableIndex}]`;
+        if (!isObject(table))
+            throw new Error(`${label} must be an object.`);
+        knownKeys(table, ["schema", "name", "sourceRows", "ownerBinding", "columns"], label);
+        const schema = identifier(table.schema ?? "public", `${label}.schema`);
+        const name = identifier(table.name, `${label}.name`);
+        const key = schema === "public" ? name : `${schema}.${name}`;
+        if (names.has(key))
+            throw new Error(`Privacy policy duplicates table ${key}.`);
+        names.add(key);
+        if (typeof table.sourceRows !== "string" ||
+            !["STREAM AND SANITIZE", "EXCLUDE"].includes(table.sourceRows)) {
+            throw new Error(`${label}.sourceRows is unsupported.`);
+        }
+        if (!Array.isArray(table.columns) || table.columns.length === 0) {
+            throw new Error(`${label}.columns must not be empty.`);
+        }
+        const sourceRows = table.sourceRows;
+        const columnNames = new Set();
+        const columns = table.columns.map((column, columnIndex) => {
+            const columnLabel = `${label}.columns[${columnIndex}]`;
+            if (!isObject(column))
+                throw new Error(`${columnLabel} must be an object.`);
+            knownKeys(column, ["name", "action", "recipe", "generated", "identity", "foreignKey"], columnLabel);
+            const columnName = identifier(column.name, `${columnLabel}.name`);
+            if (columnNames.has(columnName)) {
+                throw new Error(`Privacy policy duplicates column ${name}.${columnName}.`);
+            }
+            columnNames.add(columnName);
+            const action = String(column.action ?? "").toUpperCase();
+            if (!ACTIONS.has(action))
+                throw new Error(`${columnLabel}.action is unsupported.`);
+            if (typeof column.generated !== "string" ||
+                !["ALWAYS", "NEVER"].includes(column.generated)) {
+                throw new Error(`${columnLabel}.generated must be ALWAYS or NEVER.`);
+            }
+            if (typeof column.identity !== "string" ||
+                !["YES", "NO"].includes(column.identity)) {
+                throw new Error(`${columnLabel}.identity must be YES or NO.`);
+            }
+            if (column.foreignKey !== null) {
+                if (!isObject(column.foreignKey)) {
+                    throw new Error(`${columnLabel}.foreignKey must be null or an object.`);
+                }
+                knownKeys(column.foreignKey, ["schema", "table", "column"], `${columnLabel}.foreignKey`);
+                identifier(column.foreignKey.schema, `${columnLabel}.foreignKey.schema`);
+                identifier(column.foreignKey.table, `${columnLabel}.foreignKey.table`);
+                identifier(column.foreignKey.column, `${columnLabel}.foreignKey.column`);
+            }
+            return Object.freeze({
+                ...column,
+                name: columnName,
+                action: action,
+                recipe: validatePrivacyRecipe(action, column.recipe, columnLabel),
+                generated: column.generated,
+                identity: column.identity,
+                foreignKey: column.foreignKey,
+            });
+        });
+        let ownerBinding = null;
+        if (table.ownerBinding !== undefined && table.ownerBinding !== null) {
+            if (!isObject(table.ownerBinding)) {
+                throw new Error(`${label}.ownerBinding must be an object.`);
+            }
+            knownKeys(table.ownerBinding, ["binding", "column", "columns", "match", "nullBehavior"], `${label}.ownerBinding`);
+            const binding = nonEmpty(table.ownerBinding.binding, `${label}.ownerBinding.binding`);
+            const hasColumn = table.ownerBinding.column !== undefined;
+            const hasColumns = table.ownerBinding.columns !== undefined;
+            if (hasColumn === hasColumns) {
+                throw new Error(`${label}.ownerBinding must declare exactly one of column or columns.`);
+            }
+            let ownerColumns;
+            if (hasColumn) {
+                if (table.ownerBinding.match !== undefined) {
+                    throw new Error(`${label}.ownerBinding.match is supported only with columns.`);
+                }
+                ownerColumns = [
+                    identifier(table.ownerBinding.column, `${label}.ownerBinding.column`),
+                ];
+            }
+            else {
+                if (!Array.isArray(table.ownerBinding.columns) ||
+                    table.ownerBinding.columns.length === 0 ||
+                    table.ownerBinding.columns.length > 16) {
+                    throw new Error(`${label}.ownerBinding.columns must contain 1 through 16 columns.`);
+                }
+                if (table.ownerBinding.match !== "any") {
+                    throw new Error(`${label}.ownerBinding.match must be any when columns are used.`);
+                }
+                ownerColumns = table.ownerBinding.columns.map((column, index) => identifier(column, `${label}.ownerBinding.columns[${index}]`));
+                if (new Set(ownerColumns).size !== ownerColumns.length) {
+                    throw new Error(`${label}.ownerBinding.columns must not contain duplicates.`);
+                }
+            }
+            if (table.ownerBinding.nullBehavior !== undefined &&
+                table.ownerBinding.nullBehavior !== "otherwise") {
+                throw new Error(`${label}.ownerBinding.nullBehavior must be otherwise when declared.`);
+            }
+            if (!Object.hasOwn(bindings, binding)) {
+                throw new Error(`${label}.ownerBinding references an unknown binding.`);
+            }
+            for (const column of ownerColumns) {
+                if (!columnNames.has(column)) {
+                    throw new Error(`${label}.ownerBinding references an unknown column.`);
+                }
+                const ownerColumn = columns.find((entry) => entry.name === column);
+                if (!ownerColumn || ownerColumn.action !== "PSEUDONYMIZE") {
+                    throw new Error(`${label}.ownerBinding columns must be explicitly pseudonymized.`);
+                }
+            }
+            ownerBinding = Object.freeze({
+                binding,
+                columns: Object.freeze(ownerColumns),
+                match: "any",
+                ...(table.ownerBinding.nullBehavior === undefined
+                    ? {}
+                    : { nullBehavior: table.ownerBinding.nullBehavior }),
+            });
+        }
+        return Object.freeze({
+            schema,
+            name,
+            sourceRows,
+            ownerBinding,
+            columns: Object.freeze(columns),
+        });
+    });
+    validatePrivacyDependencyGraph({ tables, bindings, pathMappings });
+    return Object.freeze({
+        policyVersion: 2,
+        migrationCutoff: policy.migrationCutoff,
+        bindings: Object.freeze(bindings),
+        pathMappings: Object.freeze(pathMappings),
+        tables: Object.freeze(tables),
+    });
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Validate and normalize reviewed privacy recipes for policy version 2.
+ */
+import type { NormalizedRecipe, PrivacyAction } from "./privacy_contract.mjs";
+export declare const validatePrivacyRecipe: (action: PrivacyAction, recipe: unknown, label: string, depth?: number) => NormalizedRecipe;