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

package/dist/src/baseline/privacy_recipe_validation.mjs

@@ -0,0 +1,289 @@
+/**
+ * Validate and normalize reviewed privacy recipes for policy version 2.
+ */
+import { validateStructuredJsonRecipe } from "./privacy_structured_json.mjs";
+import { ACTIONS, BINDING_NAME, DATE_REPRESENTATIONS, DERIVATION_KINDS, GTIN_LENGTHS, HEX_LENGTHS, MAXIMUM_ENUM_VALUES, MAXIMUM_POLICY_DEPTH, MAXIMUM_TEXT_SUBSTITUTION_BYTES, MAXIMUM_URL_LENGTH, PSEUDONYM_FORMATS, URL_PATH_PREFIX, URL_TOKEN_LENGTH, assertKnownKeys as knownKeys, isPrivacyObject as isObject, validateHttpsLoopbackOrigin as httpsLoopbackOrigin, validateIdentifier as identifier, validateNonEmpty as nonEmpty, validatePositiveInteger as positiveInteger, validateReviewedScalar as reviewedScalar, } from "./privacy_validation_shared.mjs";
+const validateNestedDeclaration = (declaration, label, { allowRequired = false, depth = 0, } = {}) => {
+    if (!isObject(declaration))
+        throw new Error(`${label} must be an object.`);
+    knownKeys(declaration, allowRequired ? ["action", "recipe", "required"] : ["action", "recipe"], label);
+    if (allowRequired &&
+        declaration.required !== undefined &&
+        typeof declaration.required !== "boolean") {
+        throw new Error(`${label}.required must be true or false.`);
+    }
+    const action = String(declaration.action ?? "").toUpperCase();
+    if (!ACTIONS.has(action))
+        throw new Error(`${label}.action is unsupported.`);
+    return Object.freeze({
+        action: action,
+        recipe: validatePrivacyRecipe(action, declaration.recipe, label, depth + 1),
+        ...(allowRequired ? { required: declaration.required !== false } : {}),
+    });
+};
+export const validatePrivacyRecipe = (action, recipe, label, depth = 0) => {
+    if (depth > MAXIMUM_POLICY_DEPTH) {
+        throw new Error(`${label}.recipe exceeds the supported nesting depth.`);
+    }
+    if (action === "KEEP" || action === "EXCLUDE") {
+        if (recipe !== undefined && recipe !== null) {
+            throw new Error(`${label}.recipe is not allowed for ${action}.`);
+        }
+        return null;
+    }
+    if (!isObject(recipe)) {
+        throw new Error(`${label}.recipe is required for ${action}.`);
+    }
+    if (action === "PSEUDONYMIZE") {
+        knownKeys(recipe, [
+            "format",
+            "namespace",
+            "maxLength",
+            "length",
+            "allowedLengths",
+            "origin",
+        ], `${label}.recipe`);
+        if (typeof recipe.format !== "string" ||
+            !PSEUDONYM_FORMATS.has(recipe.format)) {
+            throw new Error(`${label}.recipe.format is unsupported.`);
+        }
+        const normalized = {
+            format: recipe.format,
+            namespace: nonEmpty(recipe.namespace, `${label}.recipe.namespace`),
+        };
+        if (recipe.format === "text") {
+            normalized.maxLength = positiveInteger(recipe.maxLength, `${label}.recipe.maxLength`, 1_024);
+        }
+        else if (recipe.format === "url") {
+            normalized.origin = httpsLoopbackOrigin(recipe.origin, `${label}.recipe.origin`);
+            normalized.maxLength = positiveInteger(recipe.maxLength, `${label}.recipe.maxLength`, MAXIMUM_URL_LENGTH);
+            const outputLength = normalized.origin.length + URL_PATH_PREFIX.length + URL_TOKEN_LENGTH;
+            if (normalized.maxLength < outputLength) {
+                throw new Error(`${label}.recipe.maxLength must allow the complete pseudonymous URL (${outputLength} characters).`);
+            }
+        }
+        else if (recipe.maxLength !== undefined) {
+            throw new Error(`${label}.recipe.maxLength is supported only for text and url pseudonyms.`);
+        }
+        if (recipe.format === "hex") {
+            if (typeof recipe.length !== "number" ||
+                !HEX_LENGTHS.has(recipe.length)) {
+                throw new Error(`${label}.recipe.length must be 32 or 64 for hex.`);
+            }
+            normalized.length = recipe.length;
+        }
+        else if (recipe.format === "gtin") {
+            const hasLength = Object.hasOwn(recipe, "length");
+            const hasAllowedLengths = Object.hasOwn(recipe, "allowedLengths");
+            if (hasLength === hasAllowedLengths) {
+                throw new Error(`${label}.recipe must declare exactly one of length or allowedLengths for gtin.`);
+            }
+            if (hasLength) {
+                if (typeof recipe.length !== "number" ||
+                    !GTIN_LENGTHS.has(recipe.length)) {
+                    throw new Error(`${label}.recipe.length must be 8, 12, 13, or 14 for gtin.`);
+                }
+                normalized.length = recipe.length;
+            }
+            else {
+                if (!Array.isArray(recipe.allowedLengths) ||
+                    recipe.allowedLengths.length === 0) {
+                    throw new Error(`${label}.recipe.allowedLengths must contain reviewed GTIN lengths 8, 12, 13, or 14.`);
+                }
+                const allowedLengths = recipe.allowedLengths.map((length) => {
+                    if (typeof length !== "number" || !GTIN_LENGTHS.has(length)) {
+                        throw new Error(`${label}.recipe.allowedLengths must contain reviewed GTIN lengths 8, 12, 13, or 14.`);
+                    }
+                    return length;
+                });
+                if (new Set(allowedLengths).size !== allowedLengths.length) {
+                    throw new Error(`${label}.recipe.allowedLengths must not contain duplicates.`);
+                }
+                normalized.allowedLengths = Object.freeze(allowedLengths);
+            }
+        }
+        else if (recipe.length !== undefined ||
+            recipe.allowedLengths !== undefined ||
+            (recipe.origin !== undefined && recipe.format !== "url")) {
+            throw new Error(`${label}.recipe shape controls do not match its pseudonym format.`);
+        }
+        return Object.freeze(normalized);
+    }
+    if (action === "REPLACE") {
+        knownKeys(recipe, ["kind", "value"], `${label}.recipe`);
+        if (recipe.kind !== "constant" || !Object.hasOwn(recipe, "value")) {
+            throw new Error(`${label}.recipe must be an explicit constant.`);
+        }
+        if (typeof recipe.value === "function" || recipe.value === undefined) {
+            throw new Error(`${label}.recipe.value must be JSON-compatible.`);
+        }
+        JSON.stringify(recipe.value);
+        return Object.freeze({ kind: "constant", value: recipe.value });
+    }
+    knownKeys(recipe, [
+        "kind",
+        "days",
+        "group",
+        "representation",
+        "format",
+        "length",
+        "namespace",
+        "inputs",
+        "mapping",
+        "binding",
+        "fields",
+        "items",
+        "variants",
+        "keys",
+        "values",
+        "approved",
+        "otherwise",
+        "allowNull",
+        "maximumBytes",
+        "maximumDepth",
+        "maximumItems",
+    ], `${label}.recipe`);
+    if (typeof recipe.kind !== "string" || !DERIVATION_KINDS.has(recipe.kind)) {
+        throw new Error(`${label}.recipe.kind is unsupported.`);
+    }
+    if (recipe.kind === "enum") {
+        if (Object.keys(recipe).some((key) => !["kind", "values", "allowNull"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by enum.`);
+        }
+        if (!Array.isArray(recipe.values) ||
+            recipe.values.length === 0 ||
+            recipe.values.length > MAXIMUM_ENUM_VALUES) {
+            throw new Error(`${label}.recipe.values must contain 1 through ${MAXIMUM_ENUM_VALUES} reviewed scalars.`);
+        }
+        if (recipe.allowNull !== undefined &&
+            typeof recipe.allowNull !== "boolean") {
+            throw new Error(`${label}.recipe.allowNull must be true or false.`);
+        }
+        const values = Array.from(recipe.values, (value, index) => reviewedScalar(value, `${label}.recipe.values[${index}]`));
+        const identities = values.map((value) => JSON.stringify([typeof value, value]));
+        if (new Set(identities).size !== identities.length) {
+            throw new Error(`${label}.recipe.values must not contain duplicates.`);
+        }
+        return Object.freeze({
+            kind: "enum",
+            allowNull: recipe.allowNull === true,
+            values: Object.freeze(values),
+        });
+    }
+    if (recipe.kind === "validated-string") {
+        if (Object.keys(recipe).some((key) => !["kind", "format", "maximumBytes", "allowNull"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by validated-string.`);
+        }
+        if (recipe.format !== "portable-code") {
+            throw new Error(`${label}.recipe.format must be portable-code for validated-string.`);
+        }
+        const maximumBytes = positiveInteger(recipe.maximumBytes, `${label}.recipe.maximumBytes`, 1_024);
+        if (recipe.allowNull !== undefined &&
+            typeof recipe.allowNull !== "boolean") {
+            throw new Error(`${label}.recipe.allowNull must be true or false.`);
+        }
+        return Object.freeze({
+            kind: "validated-string",
+            format: "portable-code",
+            maximumBytes,
+            allowNull: recipe.allowNull === true,
+        });
+    }
+    if (recipe.kind === "digest") {
+        if (Object.keys(recipe).some((key) => !["kind", "format", "length", "namespace", "inputs"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by digest.`);
+        }
+        if (recipe.format !== "hex") {
+            throw new Error(`${label}.recipe.format must be hex for digest.`);
+        }
+        if (typeof recipe.length !== "number" || !HEX_LENGTHS.has(recipe.length)) {
+            throw new Error(`${label}.recipe.length must be 32 or 64 for digest.`);
+        }
+        if (!Array.isArray(recipe.inputs) ||
+            recipe.inputs.length === 0 ||
+            recipe.inputs.length > 32) {
+            throw new Error(`${label}.recipe.inputs must contain 1 through 32 columns.`);
+        }
+        const inputs = recipe.inputs.map((input, index) => identifier(input, `${label}.recipe.inputs[${index}]`));
+        if (new Set(inputs).size !== inputs.length) {
+            throw new Error(`${label}.recipe.inputs must not contain duplicates.`);
+        }
+        return Object.freeze({
+            kind: "digest",
+            format: "hex",
+            length: recipe.length,
+            namespace: nonEmpty(recipe.namespace, `${label}.recipe.namespace`),
+            inputs: Object.freeze(inputs),
+        });
+    }
+    if (recipe.kind === "date-shift") {
+        const days = positiveInteger(recipe.days, `${label}.recipe.days`, 3_650);
+        if (Object.keys(recipe).some((key) => !["kind", "days", "group", "representation"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by date-shift.`);
+        }
+        if (recipe.group !== undefined &&
+            (typeof recipe.group !== "string" || !BINDING_NAME.test(recipe.group))) {
+            throw new Error(`${label}.recipe.group is invalid.`);
+        }
+        const representation = recipe.representation === undefined
+            ? "iso-string"
+            : recipe.representation;
+        if (typeof representation !== "string" ||
+            !DATE_REPRESENTATIONS.has(representation)) {
+            throw new Error(`${label}.recipe.representation must be iso-string or epoch-milliseconds.`);
+        }
+        return Object.freeze({
+            kind: "date-shift",
+            days,
+            representation: representation,
+            ...(recipe.group === undefined ? {} : { group: recipe.group }),
+        });
+    }
+    if (recipe.kind === "path-map") {
+        if (Object.keys(recipe).some((key) => !["kind", "mapping"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by path-map.`);
+        }
+        if (typeof recipe.mapping !== "string" ||
+            !BINDING_NAME.test(recipe.mapping)) {
+            throw new Error(`${label}.recipe.mapping is invalid.`);
+        }
+        return Object.freeze({ kind: "path-map", mapping: recipe.mapping });
+    }
+    if (recipe.kind === "binding-substitute") {
+        if (Object.keys(recipe).some((key) => !["kind", "binding", "format", "namespace", "maximumBytes"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by binding-substitute.`);
+        }
+        if (typeof recipe.binding !== "string" ||
+            !BINDING_NAME.test(recipe.binding)) {
+            throw new Error(`${label}.recipe.binding is invalid.`);
+        }
+        if (recipe.format !== "uuid") {
+            throw new Error(`${label}.recipe.format must be uuid.`);
+        }
+        return Object.freeze({
+            kind: "binding-substitute",
+            binding: recipe.binding,
+            format: "uuid",
+            namespace: nonEmpty(recipe.namespace, `${label}.recipe.namespace`),
+            maximumBytes: positiveInteger(recipe.maximumBytes, `${label}.recipe.maximumBytes`, MAXIMUM_TEXT_SUBSTITUTION_BYTES),
+        });
+    }
+    if (recipe.kind === "approved-owner") {
+        if (Object.keys(recipe).some((key) => !["kind", "approved", "otherwise"].includes(key))) {
+            throw new Error(`${label}.recipe contains fields not used by approved-owner.`);
+        }
+        return Object.freeze({
+            kind: "approved-owner",
+            approved: validateNestedDeclaration(recipe.approved, `${label}.recipe.approved`, { depth }),
+            otherwise: validateNestedDeclaration(recipe.otherwise, `${label}.recipe.otherwise`, { depth }),
+        });
+    }
+    return validateStructuredJsonRecipe({
+        recipe,
+        label,
+        depth,
+        maximumPolicyDepth: MAXIMUM_POLICY_DEPTH,
+        validateDeclaration: validateNestedDeclaration,
+        validatePseudonymRecipe: (nestedRecipe, nestedLabel, nestedDepth) => validatePrivacyRecipe("PSEUDONYMIZE", nestedRecipe, nestedLabel, nestedDepth),
+    });
+};

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

@@ -0,0 +1,18 @@
+/** Explicit typed registry for every normalized privacy action and derivation rule. */
+import type { DerivationRecipe, NormalizedDeclaration, PrivacyAction, PrivacyPathMapping } from "./privacy_contract.mjs";
+interface PrivacyExecutionContext {
+    readonly declaration: NormalizedDeclaration;
+    readonly value: unknown;
+    readonly key: Uint8Array;
+    readonly path: string;
+    readonly ownerApproved: boolean | undefined;
+    readonly pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
+    readonly bindingValues: ReadonlyMap<string, string>;
+    readonly resolveInput: (name: string) => unknown;
+}
+type ActionHandler = (context: PrivacyExecutionContext) => unknown;
+type DerivationHandler = (recipe: DerivationRecipe, context: PrivacyExecutionContext) => unknown;
+export declare const PRIVACY_DERIVATION_RULES: Readonly<Record<DerivationRecipe["kind"], DerivationHandler>>;
+export declare const PRIVACY_ACTION_RULES: Readonly<Record<PrivacyAction, ActionHandler>>;
+export declare const executePrivacyDeclaration: (context: PrivacyExecutionContext) => unknown;
+export {};

package/dist/src/baseline/privacy_rule_registry.mjs

@@ -0,0 +1,143 @@
+/** Explicit typed registry for every normalized privacy action and derivation rule. */
+import { executeStructuredJsonDeclaration } from "./privacy_structured_json.mjs";
+import { privacyDigest, pseudonymize, remapPrivacyPath, substitutePrivacyBinding, } from "./privacy_transforms.mjs";
+import { PORTABLE_CODE } from "./privacy_validation_shared.mjs";
+const dateShift = (normalized, context) => {
+    const recipe = normalized;
+    if (context.value === null)
+        return null;
+    if (recipe.representation === "epoch-milliseconds" &&
+        (typeof context.value !== "number" || !Number.isSafeInteger(context.value))) {
+        throw new Error(`${context.path} must be a safe epoch-millisecond integer.`);
+    }
+    const date = new Date(context.value);
+    if (!Number.isFinite(date.valueOf())) {
+        throw new Error(`${context.path} is not a valid date.`);
+    }
+    const direction = recipe.group
+        ? privacyDigest(context.key, "date-shift-group", recipe.group)[0] % 2 === 0
+            ? -1
+            : 1
+        : privacyDigest(context.key, context.path, context.value)[0] % 2 === 0
+            ? -1
+            : 1;
+    date.setUTCDate(date.getUTCDate() + direction * recipe.days);
+    if (!Number.isFinite(date.valueOf())) {
+        throw new Error(`${context.path} shifts outside the supported date range.`);
+    }
+    return recipe.representation === "epoch-milliseconds"
+        ? date.valueOf()
+        : date.toISOString();
+};
+const retainEnum = (normalized, context) => {
+    const recipe = normalized;
+    if (context.value === null && recipe.allowNull)
+        return null;
+    if (!recipe.values.some((candidate) => Object.is(candidate, context.value))) {
+        throw new Error(`${context.path} is outside its reviewed scalar domain.`);
+    }
+    return context.value;
+};
+const retainValidatedString = (normalized, context) => {
+    const recipe = normalized;
+    if (context.value === null && recipe.allowNull)
+        return null;
+    if (typeof context.value !== "string" ||
+        Buffer.byteLength(context.value) > recipe.maximumBytes ||
+        !PORTABLE_CODE.test(context.value)) {
+        throw new Error(`${context.path} is not a valid reviewed portable code.`);
+    }
+    return context.value;
+};
+const deriveDigest = (normalized, context) => {
+    const recipe = normalized;
+    const inputs = recipe.inputs.map((name) => {
+        const sanitized = context.resolveInput(name);
+        if (sanitized === undefined) {
+            throw new Error(`${context.path} digest input ${name} was not sanitized.`);
+        }
+        return { name, value: sanitized };
+    });
+    return privacyDigest(context.key, recipe.namespace, inputs)
+        .toString("hex")
+        .slice(0, recipe.length);
+};
+const mapPath = (normalized, context) => {
+    const recipe = normalized;
+    const mapping = context.pathMappings[recipe.mapping];
+    if (!mapping) {
+        throw new Error(`${context.path} references an unknown privacy path mapping.`);
+    }
+    return remapPrivacyPath({
+        key: context.key,
+        mapping,
+        bindingValue: context.bindingValues.get(mapping.binding),
+        value: context.value,
+        label: context.path,
+    });
+};
+const substituteBinding = (normalized, context) => {
+    const recipe = normalized;
+    return substitutePrivacyBinding({
+        key: context.key,
+        recipe,
+        bindingValue: context.bindingValues.get(recipe.binding),
+        value: context.value,
+        label: context.path,
+    });
+};
+const chooseApprovedOwner = (normalized, context) => {
+    const recipe = normalized;
+    if (context.ownerApproved === undefined) {
+        throw new Error(`${context.path} has no reviewed owner condition.`);
+    }
+    return executePrivacyDeclaration({
+        ...context,
+        declaration: context.ownerApproved ? recipe.approved : recipe.otherwise,
+    });
+};
+const structuredJson = (_recipe, context) => executeStructuredJsonDeclaration({
+    declaration: context.declaration,
+    value: context.value,
+    key: context.key,
+    path: context.path,
+    pseudonymize: (nestedKey, nestedRecipe, nestedValue) => pseudonymize(nestedKey, nestedRecipe, nestedValue),
+    execute: (nestedDeclaration, nestedValue, nestedPath) => executePrivacyDeclaration({
+        ...context,
+        declaration: nestedDeclaration,
+        value: nestedValue,
+        path: nestedPath,
+    }),
+});
+export const PRIVACY_DERIVATION_RULES = Object.freeze({
+    "date-shift": dateShift,
+    enum: retainEnum,
+    "validated-string": retainValidatedString,
+    digest: deriveDigest,
+    "path-map": mapPath,
+    "binding-substitute": substituteBinding,
+    "approved-owner": chooseApprovedOwner,
+    "json-object": structuredJson,
+    "json-array": structuredJson,
+    "json-union": structuredJson,
+    "json-dictionary": structuredJson,
+});
+const derive = (context) => {
+    const recipe = context.declaration.recipe;
+    if (!recipe || !("kind" in recipe) || recipe.kind === "constant") {
+        throw new Error(`${context.path} has an invalid derivation recipe.`);
+    }
+    const handler = PRIVACY_DERIVATION_RULES[recipe.kind];
+    if (!handler) {
+        throw new Error(`${context.path} uses an unsupported privacy recipe.`);
+    }
+    return handler(recipe, context);
+};
+export const PRIVACY_ACTION_RULES = Object.freeze({
+    KEEP: ({ value }) => value,
+    EXCLUDE: () => undefined,
+    REPLACE: ({ declaration }) => structuredClone(declaration.recipe.value),
+    PSEUDONYMIZE: ({ declaration, key, value }) => pseudonymize(key, declaration.recipe, value),
+    DERIVE: derive,
+});
+export const executePrivacyDeclaration = (context) => PRIVACY_ACTION_RULES[context.declaration.action](context);

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

@@ -0,0 +1,18 @@
+/** Deterministic primitive, identifier-shape, URL, and path transformations. */
+import type { BindingSubstituteRecipe, PrivacyPathMapping, PseudonymRecipe } from "./privacy_contract.mjs";
+export declare const privacyDigest: (key: Uint8Array, namespace: string, value: unknown) => Buffer;
+export declare const pseudonymize: (key: Uint8Array, recipe: PseudonymRecipe, value: unknown) => unknown;
+export declare const remapPrivacyPath: ({ key, mapping, bindingValue, value, label, }: {
+    key: Uint8Array;
+    mapping: PrivacyPathMapping;
+    bindingValue: string | undefined;
+    value: unknown;
+    label: string;
+}) => string;
+export declare const substitutePrivacyBinding: ({ key, recipe, bindingValue, value, label, }: {
+    key: Uint8Array;
+    recipe: BindingSubstituteRecipe;
+    bindingValue: string | undefined;
+    value: unknown;
+    label: string;
+}) => string | null;

package/dist/src/baseline/privacy_transforms.mjs

@@ -0,0 +1,142 @@
+/** Deterministic primitive, identifier-shape, URL, and path transformations. */
+import { createHmac } from "node:crypto";
+import { URL_PATH_PREFIX, URL_TOKEN_LENGTH, UUID, } from "./privacy_validation_shared.mjs";
+export const privacyDigest = (key, namespace, value) => {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined) {
+        throw new Error("Privacy input must be JSON-compatible.");
+    }
+    return createHmac("sha256", key)
+        .update(namespace)
+        .update("\0")
+        .update(serialized)
+        .digest();
+};
+const gtinCheckDigit = (payload) => {
+    const sum = [...payload]
+        .reverse()
+        .reduce((total, digit, index) => total + Number(digit) * (index % 2 === 0 ? 3 : 1), 0);
+    return String((10 - (sum % 10)) % 10);
+};
+const isValidGtin = (value, length) => typeof value === "string" &&
+    value.length === length &&
+    /^\d+$/u.test(value) &&
+    value.at(-1) === gtinCheckDigit(value.slice(0, -1));
+export const pseudonymize = (key, recipe, value) => {
+    if (value === null)
+        return null;
+    const bytes = privacyDigest(key, recipe.namespace, value);
+    if (recipe.format === "uuid") {
+        const copy = Buffer.from(bytes.subarray(0, 16));
+        copy[6] = (copy[6] & 0x0f) | 0x40;
+        copy[8] = (copy[8] & 0x3f) | 0x80;
+        const hex = copy.toString("hex");
+        return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+    }
+    if (recipe.format === "email") {
+        return `rehearsal+${bytes.toString("hex").slice(0, 24)}@example.invalid`;
+    }
+    if (recipe.format === "integer") {
+        return Number(bytes.readBigUInt64BE(0) % 9007199254740991n) + 1;
+    }
+    if (recipe.format === "hex") {
+        return bytes.toString("hex").slice(0, recipe.length);
+    }
+    if (recipe.format === "gtin") {
+        const allowedLengths = recipe.allowedLengths ??
+            (recipe.length === undefined ? [] : [recipe.length]);
+        const sourceLength = typeof value === "string" ? value.length : null;
+        if (sourceLength === null ||
+            !allowedLengths.includes(sourceLength) ||
+            !isValidGtin(value, sourceLength)) {
+            if (recipe.length !== undefined) {
+                throw new Error(`A gtin pseudonym source must be a valid normalized GTIN-${recipe.length} string.`);
+            }
+            throw new Error(`A gtin pseudonym source must be a valid normalized GTIN string with an allowed length (${allowedLengths.join(", ")}).`);
+        }
+        const modulus = 10n ** BigInt(sourceLength - 1);
+        const payload = (BigInt(`0x${bytes.toString("hex")}`) % modulus)
+            .toString()
+            .padStart(sourceLength - 1, "0");
+        return `${payload}${gtinCheckDigit(payload)}`;
+    }
+    if (recipe.format === "url") {
+        if (typeof value !== "string" ||
+            value.trim() !== value ||
+            /\s/u.test(value)) {
+            throw new Error("A url pseudonym source must be a valid HTTPS URL.");
+        }
+        let source;
+        try {
+            source = new URL(value);
+        }
+        catch {
+            throw new Error("A url pseudonym source must be a valid HTTPS URL.");
+        }
+        if (source.protocol !== "https:") {
+            throw new Error("A url pseudonym source must be a valid HTTPS URL.");
+        }
+        const output = `${recipe.origin}${URL_PATH_PREFIX}${bytes
+            .toString("hex")
+            .slice(0, URL_TOKEN_LENGTH)}`;
+        if (output.length > recipe.maxLength) {
+            throw new Error("A url pseudonym exceeded its reviewed maximum length.");
+        }
+        return output;
+    }
+    const token = `rehearsal_${bytes.toString("hex")}`;
+    return token.slice(0, recipe.maxLength);
+};
+export const remapPrivacyPath = ({ key, mapping, bindingValue, value, label, }) => {
+    if (typeof value !== "string") {
+        throw new Error(`${label} must be a Storage-style path string.`);
+    }
+    if (Buffer.byteLength(value) > mapping.maximumBytes) {
+        throw new Error(`${label} exceeds its reviewed byte limit.`);
+    }
+    const segments = value.split("/");
+    if (!value ||
+        value.startsWith("/") ||
+        value.endsWith("/") ||
+        segments.length > mapping.maximumSegments ||
+        segments.some((segment) => !segment || segment === "." || segment === "..")) {
+        throw new Error(`${label} is not a safe bounded Storage path.`);
+    }
+    if (typeof bindingValue !== "string" ||
+        !bindingValue ||
+        bindingValue.includes("/") ||
+        bindingValue === "." ||
+        bindingValue === "..") {
+        throw new Error(`${label} has an invalid reviewed identity binding.`);
+    }
+    if (segments[0] !== bindingValue) {
+        throw new Error(`${label} does not begin with its exact reviewed identity.`);
+    }
+    const destination = [
+        String(pseudonymize(key, mapping, bindingValue)),
+        ...segments.slice(1),
+    ].join("/");
+    if (Buffer.byteLength(destination) > mapping.maximumBytes) {
+        throw new Error(`${label} destination exceeds its reviewed byte limit.`);
+    }
+    return destination;
+};
+export const substitutePrivacyBinding = ({ key, recipe, bindingValue, value, label, }) => {
+    if (typeof bindingValue !== "string" || !UUID.test(bindingValue)) {
+        throw new Error(`${label} has an invalid reviewed UUID binding.`);
+    }
+    if (value === null)
+        return null;
+    if (typeof value !== "string") {
+        throw new Error(`${label} must be text or null for binding substitution.`);
+    }
+    if (Buffer.byteLength(value) > recipe.maximumBytes) {
+        throw new Error(`${label} exceeds its reviewed byte limit.`);
+    }
+    const replacement = String(pseudonymize(key, recipe, bindingValue));
+    const destination = value.replaceAll(bindingValue, replacement);
+    if (Buffer.byteLength(destination) > recipe.maximumBytes) {
+        throw new Error(`${label} destination exceeds its reviewed byte limit.`);
+    }
+    return destination;
+};

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

@@ -0,0 +1,31 @@
+/** Redacted primitive validators and closed vocabulary for privacy policy v2. */
+import type { PrivacyObject } from "./privacy_contract.mjs";
+export declare const IDENTIFIER: RegExp;
+export declare const BINDING_NAME: RegExp;
+export declare const ENVIRONMENT_KEY: RegExp;
+export declare const HEX_64: RegExp;
+export declare const UUID: RegExp;
+export declare const PORTABLE_CODE: RegExp;
+export declare const ACTIONS: Set<string>;
+export declare const PSEUDONYM_FORMATS: Set<string>;
+export declare const HEX_LENGTHS: Set<number>;
+export declare const GTIN_LENGTHS: Set<number>;
+export declare const DATE_REPRESENTATIONS: Set<string>;
+export declare const DERIVATION_KINDS: Set<string>;
+export declare const URL_PATH_PREFIX = "/rehearsal/";
+export declare const URL_TOKEN_LENGTH = 32;
+export declare const MAXIMUM_URL_LENGTH = 2048;
+export declare const MAXIMUM_TEXT_SUBSTITUTION_BYTES = 65536;
+export declare const LOOPBACK_HOSTNAMES: Set<string>;
+export declare const DEFAULT_PATH_MAXIMUM_BYTES = 2048;
+export declare const DEFAULT_PATH_MAXIMUM_SEGMENTS = 32;
+export declare const MAXIMUM_POLICY_DEPTH = 16;
+export declare const MAXIMUM_ENUM_VALUES = 128;
+export declare const MAXIMUM_ENUM_STRING_BYTES = 256;
+export declare const isPrivacyObject: (value: unknown) => value is PrivacyObject;
+export declare const assertKnownKeys: (value: PrivacyObject, allowed: readonly string[], label: string) => void;
+export declare const validateIdentifier: (value: unknown, label: string) => string;
+export declare const validateNonEmpty: (value: unknown, label: string) => string;
+export declare const validatePositiveInteger: (value: unknown, label: string, maximum?: number) => number;
+export declare const validateReviewedScalar: (value: unknown, label: string) => string | number | boolean;
+export declare const validateHttpsLoopbackOrigin: (value: unknown, label: string) => string;