@beechcms/core 0.8.0 → 0.9.0

package/dist/engine/localization.js

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { cleanString, isPlainObject } from './validation/primitives.js';
+/**
+ * Locale code grammar (v1): ISO 639 language (2–3 lowercase letters), optionally followed by an ISO 3166
+ * region (2 uppercase letters) or a UN M.49 area (3 digits) — `it`, `en`, `pt-BR`, `es-419`. Script
+ * subtags (`zh-Hant`) are outside v1. The grammar doubles as an injection guard: validated codes are
+ * later interpolated into SQLite JSON paths.
+ */
+export const LOCALE_CODE_RE = /^[a-z]{2,3}(?:-(?:[A-Z]{2}|[0-9]{3}))?$/;
+/** Branch types that may carry `localized: true`. */
+export const LOCALIZABLE_BRANCH_TYPES = new Set(['text', 'richtext', 'json']);
+/** True when `value` is a string matching {@link LOCALE_CODE_RE}. */
+export function isLocaleCode(value) {
+    return typeof value === 'string' && LOCALE_CODE_RE.test(value);
+}
+/**
+ * True when the branch is localized AND its type supports it. A malformed definition that slipped past
+ * seed validation (e.g. `localized: true` on a `number`) is treated as not localized, never as a dictionary.
+ */
+export function isLocalizedBranch(branch) {
+    return branch.localized === true && LOCALIZABLE_BRANCH_TYPES.has(branch.type);
+}
+/**
+ * Structural check used on READ paths (no config available): a non-empty plain object whose every key
+ * matches the locale-code grammar. A richtext envelope (`schemaVersion`, `doc`) and a TipTap doc
+ * (`type`, `content`) never match.
+ */
+export function isLocaleDictionary(value) {
+    if (!isPlainObject(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every(isLocaleCode);
+}
+/**
+ * Stricter check used on WRITE paths: a locale dictionary with at least one REGISTERED locale key.
+ * Without the registration requirement a legitimate json value such as `{"url": "…", "alt": "…"}` —
+ * whose keys happen to match the grammar — would be read as a dictionary of unregistered locales and
+ * silently emptied.
+ */
+export function isLocalizedWriteDictionary(value, config) {
+    return isLocaleDictionary(value) && Object.keys(value).some((key) => config.locales.includes(key));
+}
+function isBlankLocaleValue(value) {
+    return value === null || value === undefined || (typeof value === 'string' && cleanString(value) === '');
+}
+/**
+ * Normalises any accepted write value of a localized branch into a {@link LocalizedPatch}:
+ * - a write dictionary keeps its registered locales, in `config.locales` order; unregistered locale
+ *   keys are dropped;
+ * - any other value (string, richtext doc, non-dictionary json) is the default-locale value;
+ * - `null`, `undefined` and blank strings become `null` ("clear this locale").
+ * Idempotent: a patch passed back in yields the same patch.
+ */
+export function toLocalizedPatch(value, config) {
+    const source = isLocalizedWriteDictionary(value, config)
+        ? value
+        : { [config.defaultLocale]: value };
+    const patch = {};
+    for (const locale of config.locales) {
+        if (!Object.hasOwn(source, locale))
+            continue;
+        patch[locale] = isBlankLocaleValue(source[locale]) ? null : source[locale];
+    }
+    return patch;
+}
+/**
+ * Removes `null` / `undefined` / blank-string entries. Returns `null` when nothing remains, so an
+ * all-cleared dictionary is stored as SQL NULL rather than `{}`. Keys are otherwise preserved as-is —
+ * including locales no longer registered, which must never be dropped by a write (brief §2, no data loss).
+ */
+export function compactLocalizedDictionary(value) {
+    const compact = {};
+    for (const [locale, localeValue] of Object.entries(value)) {
+        if (isBlankLocaleValue(localeValue))
+            continue;
+        compact[locale] = localeValue;
+    }
+    return Object.keys(compact).length > 0 ? compact : null;
+}
+/** Content locale used when neither stored `locales` nor a valid `defaultLanguage` is available. */
+const FALLBACK_LOCALE = 'en';
+/**
+ * Builds the project's {@link LocaleConfig}, repairing whatever a hand-edited settings row could break so
+ * the LocaleConfig invariant always holds:
+ * - `locales`: the stored list minus invalid codes and duplicates; when nothing remains (never configured,
+ *   `[]`, corrupt), the implicit single-language config `[defaultLanguage]` (brief §2), which keeps the
+ *   feature invisible to a mono-lingual project;
+ * - `defaultLocale`: the stored value when it belongs to `locales`, else `locales[0]`.
+ */
+export function resolveLocaleConfig(settings) {
+    const stored = [...new Set((settings.locales ?? []).filter(isLocaleCode))];
+    const implicit = isLocaleCode(settings.defaultLanguage) ? settings.defaultLanguage : FALLBACK_LOCALE;
+    const locales = stored.length > 0 ? stored : [implicit];
+    const defaultLocale = settings.defaultLocale && locales.includes(settings.defaultLocale)
+        ? settings.defaultLocale
+        : locales[0];
+    return { locales, defaultLocale };
+}
+/**
+ * True when a STORED value of a localized branch is a locale dictionary. Text and richtext cannot hold an
+ * object keyed only by locale codes for any other reason; json can (`{"url": "…", "alt": "…"}`), so a json
+ * object counts only when at least one key is a registered locale — otherwise it is a legacy value written
+ * before the branch became localized.
+ */
+function isStoredLocaleDictionary(branch, value, config) {
+    if (!isLocalizedBranch(branch) || !isLocaleDictionary(value))
+        return false;
+    return branch.type !== 'json' || Object.keys(value).some((key) => config.locales.includes(key));
+}
+/**
+ * Merges a write into the value stored for a localized branch. The write path's only way to persist a
+ * localized value, so a translation the write does not mention is never dropped (brief §2):
+ * - `write === null` clears the whole field (an explicit null keeps its pre-localization meaning);
+ * - otherwise the write is normalised with {@link toLocalizedPatch}: every registered locale it names
+ *   overwrites that locale, a `null` entry clears that locale only, and every other stored locale —
+ *   including ones no longer registered — is kept as-is;
+ * - a stored legacy value (written before the branch became localized) is the default-locale value.
+ * @returns The compacted dictionary, or `null` when no locale keeps a value.
+ */
+export function applyLocalizedPatch(branch, stored, write, config) {
+    if (write === null)
+        return null;
+    const merged = isStoredLocaleDictionary(branch, stored, config)
+        ? { ...stored }
+        : isBlankLocaleValue(stored) ? {} : { [config.defaultLocale]: stored };
+    Object.assign(merged, toLocalizedPatch(write, config));
+    return compactLocalizedDictionary(merged);
+}
+/** Aliases of the localized branches a write carries — the fields it must merge rather than replace. */
+export function localizedAliasesIn(seed, data) {
+    return seed.branches
+        .filter((branch) => isLocalizedBranch(branch) && Object.hasOwn(data, branch.alias) && data[branch.alias] !== undefined)
+        .map((branch) => branch.alias);
+}
+/**
+ * Returns `data` with every localized branch it carries merged into `stored` via
+ * {@link applyLocalizedPatch}; other keys pass through untouched. `stored` is the entry's current values
+ * (`null` on create, which only compacts). Returns `data` itself when `config` is undefined or no localized
+ * branch is written.
+ */
+export function mergeLocalizedFields(seed, stored, data, config) {
+    if (!config)
+        return data;
+    const aliases = localizedAliasesIn(seed, data);
+    if (aliases.length === 0)
+        return data;
+    const merged = { ...data };
+    for (const branch of seed.branches) {
+        if (!aliases.includes(branch.alias))
+            continue;
+        merged[branch.alias] = applyLocalizedPatch(branch, stored?.[branch.alias], data[branch.alias], config);
+    }
+    return merged;
+}
+/**
+ * Resolves a stored localized value to one language: the requested locale, then the default locale, then the
+ * first stored translation (stored key order), then `null`. A legacy value that is not a dictionary is returned
+ * as-is. Non-localized branches return `value` unchanged. `buildSelectQuery` applies the same chain in SQL, so
+ * filters and ORDER BY compare exactly what a reader sees.
+ */
+export function resolveLocalizedValue(branch, value, locale, config) {
+    if (!isStoredLocaleDictionary(branch, value, config))
+        return value;
+    if (!isBlankLocaleValue(value[locale]))
+        return value[locale];
+    if (!isBlankLocaleValue(value[config.defaultLocale]))
+        return value[config.defaultLocale];
+    // An implicit config follows `defaultLanguage`; changing it before languages are configured leaves every
+    // dictionary without its default key. Returning null there would blank the public site (brief §2).
+    const firstStored = Object.values(value).find((translation) => !isBlankLocaleValue(translation));
+    return firstStored ?? null;
+}
+/**
+ * Returns a copy of `data` with every localized branch resolved to `locale` (default: the default locale)
+ * via {@link resolveLocalizedValue}. Returns `data` itself when `config` is undefined.
+ */
+export function resolveLocalizedFields(seed, data, config, locale) {
+    if (!config)
+        return data;
+    const target = locale ?? config.defaultLocale;
+    const resolved = { ...data };
+    for (const branch of seed.branches) {
+        if (isLocalizedBranch(branch) && Object.hasOwn(resolved, branch.alias)) {
+            resolved[branch.alias] = resolveLocalizedValue(branch, resolved[branch.alias], target, config);
+        }
+    }
+    return resolved;
+}
+/**
+ * The whole dictionary of a stored localized value, for readers asking every language (`?lang=all`):
+ * a stored dictionary as-is — unregistered locales included, nothing is hidden (brief §2) — a legacy
+ * value as `{ [defaultLocale]: value }` (the write path's reading of it), a blank value as `null`.
+ * Non-localized branches return `value` unchanged.
+ */
+export function asLocaleDictionary(branch, value, config) {
+    if (!isLocalizedBranch(branch))
+        return value;
+    if (isStoredLocaleDictionary(branch, value, config))
+        return value;
+    return isBlankLocaleValue(value) ? null : { [config.defaultLocale]: value };
+}
+/** Returns a copy of `data` with every localized branch it carries passed through {@link asLocaleDictionary}. */
+export function asLocaleDictionaries(seed, data, config) {
+    const expanded = { ...data };
+    for (const branch of seed.branches) {
+        if (isLocalizedBranch(branch) && Object.hasOwn(expanded, branch.alias)) {
+            expanded[branch.alias] = asLocaleDictionary(branch, expanded[branch.alias], config);
+        }
+    }
+    return expanded;
+}

package/dist/engine/privacy/policies.d.ts

@@ -0,0 +1,58 @@
+import type { ActorContext, Branch, DataClassification, Seed } from '../types.js';
+/**
+ * Computes an un-salted SHA-256 hex digest of a string value.
+ * Used for basic digest operations.
+ * @param value - The raw string value to hash.
+ * @returns A Promise resolving to a 64-character hex string.
+ */
+export declare function sha256hex(value: string): Promise<string>;
+/**
+ * Verifies if a candidate string matches a stored SHA-256 hash digest, comparing in constant time.
+ * @param stored - The expected 64-character SHA-256 hex digest.
+ * @param candidate - The raw candidate string to verify.
+ * @returns A Promise resolving to true if candidate matches stored digest, false otherwise.
+ */
+export declare function verifyHashField(stored: string, candidate: string): Promise<boolean>;
+/**
+ * Resolved classification rules for a branch, bundling storage strategy and API visibility defaults.
+ */
+export interface ResolvedClassification {
+    /** Canonical data classification tier. */
+    classification: DataClassification;
+    /** Storage mechanism at rest (`plain`, `encrypt` via AES-GCM, or `hash` via HMAC-SHA256). */
+    storage: 'plain' | 'encrypt' | 'hash';
+    /** Default visibility rule for unauthenticated public API endpoints (`full` or `hidden`). */
+    publicVisibility: 'full' | 'hidden';
+    /** Default visibility rule for authenticated API endpoints (`full` or `hidden`). */
+    authVisibility: 'full' | 'hidden';
+}
+/** Normalizes raw policy strings to canonical DataClassification enum. */
+export declare function normalizeClassification(raw?: string): DataClassification;
+/**
+ * Resolves the 4-tier DataClassification for a branch, bundling its storage
+ * strategy at rest and its API visibility rules (public vs auth context).
+ * @param branch - The seed branch definition to inspect.
+ * @returns The resolved classification details and visibility rules.
+ */
+export declare function resolveClassification(branch: Branch): ResolvedClassification;
+/**
+ * Resolves branch policies applying all defaults and classification rules.
+ * @param branch - The seed branch definition to inspect.
+ * @returns Complete required policies object for the branch.
+ */
+export declare function resolvePolicies(branch: Branch): Required<NonNullable<Branch['policies']>>;
+/**
+ * Filters entry payload fields based on the caller's {@link ActorContext} and branch classification tier.
+ *
+ * Rules:
+ * - Public actor: receives `public` fields; `internal`, `confidential`, and `restricted` fields are omitted.
+ * - Authenticated actor: receives `public`, `internal`, and `confidential` fields; `restricted` fields are ALWAYS omitted.
+ * - System actor: receives all fields including `restricted` (used for internal worker/automation orchestration).
+ *
+ * @param data - Raw record fields object.
+ * @param seed - Content type seed definition containing branch definitions.
+ * @param actor - Context of the caller requesting the entry payload (defaults to authenticated).
+ * @returns Filtered data record containing only authorized fields for the given actor context.
+ */
+export declare function filterEntryForActor(data: Record<string, unknown>, seed: Seed, actor?: ActorContext): Record<string, unknown>;
+//# sourceMappingURL=policies.d.ts.map

package/dist/engine/privacy/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../../src/engine/privacy/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAIjF;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,cAAc,EAAE,kBAAkB,CAAA;IAClC,6FAA6F;IAC7F,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACrC,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAA;IACnC,oFAAoF;IACpF,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAA;CAClC;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAQxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,CAmC5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CA+BzF;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,YAAwC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiDzB"}

package/dist/engine/privacy/policies.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { isLocaleDictionary, isLocalizedBranch } from '../localization/localization.js';
+import { timingSafeEqual } from '../../webhooks/webhook-crypto.js';
+/**
+ * Computes an un-salted SHA-256 hex digest of a string value.
+ * Used for basic digest operations.
+ * @param value - The raw string value to hash.
+ * @returns A Promise resolving to a 64-character hex string.
+ */
+export async function sha256hex(value) {
+    const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return Array.from(new Uint8Array(buf))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Verifies if a candidate string matches a stored SHA-256 hash digest, comparing in constant time.
+ * @param stored - The expected 64-character SHA-256 hex digest.
+ * @param candidate - The raw candidate string to verify.
+ * @returns A Promise resolving to true if candidate matches stored digest, false otherwise.
+ */
+export async function verifyHashField(stored, candidate) {
+    return timingSafeEqual(stored, await sha256hex(candidate));
+}
+/** Normalizes raw policy strings to canonical DataClassification enum. */
+export function normalizeClassification(raw) {
+    if (!raw)
+        return 'public';
+    const lower = raw.toLowerCase();
+    if (lower === 'confidential')
+        return 'confidential';
+    if (lower === 'restricted' || lower === 'hash')
+        return 'restricted';
+    if (lower === 'encrypt')
+        return 'confidential';
+    if (lower === 'internal')
+        return 'internal';
+    return 'public';
+}
+/**
+ * Resolves the 4-tier DataClassification for a branch, bundling its storage
+ * strategy at rest and its API visibility rules (public vs auth context).
+ * @param branch - The seed branch definition to inspect.
+ * @returns The resolved classification details and visibility rules.
+ */
+export function resolveClassification(branch) {
+    const rawClassification = branch.policies?.classification ?? branch.policies?.privacy;
+    const classification = normalizeClassification(rawClassification);
+    switch (classification) {
+        case 'confidential':
+            return {
+                classification: 'confidential',
+                storage: 'encrypt',
+                publicVisibility: 'hidden',
+                authVisibility: 'full',
+            };
+        case 'restricted':
+            return {
+                classification: 'restricted',
+                storage: 'hash',
+                publicVisibility: 'hidden',
+                authVisibility: 'hidden',
+            };
+        case 'internal':
+            return {
+                classification: 'internal',
+                storage: 'plain',
+                publicVisibility: 'hidden',
+                authVisibility: 'full',
+            };
+        case 'public':
+        default:
+            return {
+                classification: 'public',
+                storage: 'plain',
+                publicVisibility: 'full',
+                authVisibility: 'full',
+            };
+    }
+}
+/**
+ * Resolves branch policies applying all defaults and classification rules.
+ * @param branch - The seed branch definition to inspect.
+ * @returns Complete required policies object for the branch.
+ */
+export function resolvePolicies(branch) {
+    const resolved = resolveClassification(branch);
+    const isRepeater = branch.type === 'repeater';
+    const isEncryptedOrHashed = resolved.storage !== 'plain';
+    const defaultVisibility = resolved.authVisibility;
+    const isPublicAllowed = branch.policies?.public ?? (resolved.publicVisibility === 'full');
+    const visibility = branch.policies?.visibility ?? defaultVisibility;
+    // Concealed values must not be queryable: filter/sort/search leak them
+    const isConcealed = visibility === 'hidden' || visibility === 'masked';
+    const defaultFilter = branch.policies?.filter ?? (isRepeater || resolved.storage === 'hash' ? false : !isConcealed);
+    const defaultSort = branch.policies?.sort ?? (isRepeater || isEncryptedOrHashed ? false : !isConcealed);
+    const defaultSearch = branch.policies?.search ?? (isRepeater || isEncryptedOrHashed ? false : !isConcealed);
+    // publicEdit default: true for public fields (unless public: false), false for confidential/internal/restricted
+    const defaultPublicEdit = resolved.classification === 'public'
+        ? (branch.policies?.publicEdit ?? isPublicAllowed)
+        : (branch.policies?.publicEdit ?? false);
+    return {
+        classification: resolved.classification,
+        privacy: resolved.storage,
+        visibility,
+        search: defaultSearch,
+        filter: defaultFilter,
+        sort: defaultSort,
+        public: isPublicAllowed,
+        publicEdit: defaultPublicEdit,
+    };
+}
+const MASK = '••••••••';
+/**
+ * The masked form of a value. A localized dictionary (a `?lang=all` read) masks each translation, exactly as
+ * a single-language read masks the one translation it resolves to; before this, any object became `null`.
+ */
+function maskValue(branch, value) {
+    if (typeof value === 'string')
+        return value.length > 0 ? MASK : null;
+    if (isLocalizedBranch(branch) && isLocaleDictionary(value)) {
+        return Object.fromEntries(Object.entries(value).map(([locale, translation]) => [
+            locale,
+            typeof translation === 'string' && translation.length > 0 ? MASK : null,
+        ]));
+    }
+    return null;
+}
+const SYSTEM_FIELDS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at', 'version', 'has_pending_draft']);
+/**
+ * Filters entry payload fields based on the caller's {@link ActorContext} and branch classification tier.
+ *
+ * Rules:
+ * - Public actor: receives `public` fields; `internal`, `confidential`, and `restricted` fields are omitted.
+ * - Authenticated actor: receives `public`, `internal`, and `confidential` fields; `restricted` fields are ALWAYS omitted.
+ * - System actor: receives all fields including `restricted` (used for internal worker/automation orchestration).
+ *
+ * @param data - Raw record fields object.
+ * @param seed - Content type seed definition containing branch definitions.
+ * @param actor - Context of the caller requesting the entry payload (defaults to authenticated).
+ * @returns Filtered data record containing only authorized fields for the given actor context.
+ */
+export function filterEntryForActor(data, seed, actor = { type: 'authenticated' }) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (SYSTEM_FIELDS.has(key)) {
+            result[key] = value;
+            continue;
+        }
+        const branch = seed.branches.find((b) => b.alias === key);
+        if (!branch) {
+            // Pass through unknown/extra fields unless actor is public
+            if (actor.type !== 'public') {
+                result[key] = value;
+            }
+            continue;
+        }
+        const resolved = resolveClassification(branch);
+        const isPublicActor = actor.type === 'public';
+        const isSystemActor = actor.type === 'system';
+        // System actor sees all fields including restricted
+        if (isSystemActor) {
+            result[key] = value;
+            continue;
+        }
+        // Public actor check
+        if (isPublicActor) {
+            if (resolved.publicVisibility === 'hidden')
+                continue;
+            if (branch.policies?.public === false)
+                continue;
+        }
+        else {
+            // Authenticated actor check
+            if (resolved.authVisibility === 'hidden')
+                continue;
+        }
+        // Explicit visibility override check
+        if (branch.policies?.visibility === 'hidden')
+            continue;
+        // Masking rule check
+        if (branch.policies?.visibility === 'masked') {
+            result[key] = maskValue(branch, value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/engine/privacy/privacy.service.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Contract for the Application-Level Encryption (ALE) and hashing privacy service.
+ * Used by the Botanical Engine to secure fields classified as `confidential` or `restricted`.
+ */
+export interface IPrivacyService {
+    /**
+     * Symmetrically encrypts a plaintext string using AES-256-GCM.
+     * @param plaintext - The raw string value to encrypt.
+     * @returns A Promise resolving to formatted ciphertext (`v1:<iv_base64>:<ciphertext_base64>`).
+     */
+    encrypt(plaintext: string): Promise<string>;
+    /**
+     * Decrypts a formatted AES-256-GCM ciphertext payload.
+     * @param ciphertext - The formatted ciphertext string (`v1:<iv_base64>:<ciphertext_base64>`).
+     * @returns A Promise resolving to the original plaintext string.
+     * @throws Error if the ciphertext format is invalid or decryption fails (authentication tag mismatch).
+     */
+    decrypt(ciphertext: string): Promise<string>;
+    /**
+     * Computes a deterministic HMAC SHA-256 digest of a plaintext string.
+     * Used for blind-indexing and one-way field digests (`restricted` classification).
+     * @param plaintext - The raw string value to hash.
+     * @returns A Promise resolving to a 64-character hexadecimal digest string.
+     */
+    hash(plaintext: string): Promise<string>;
+}
+/**
+ * Concrete Edge-native implementation of {@link IPrivacyService}.
+ * Employs Web Crypto API (`crypto.subtle`) for zero-dependency execution in Cloudflare Workers.
+ */
+export declare class PrivacyService implements IPrivacyService {
+    private readonly masterKey;
+    private aesKeyPromise?;
+    private hmacKeyPromise?;
+    /**
+     * Initializes the PrivacyService with a Master Encryption Key.
+     * @param masterKey - Secret key used to derive cryptographic keys for AES-GCM and HMAC.
+     * @throws Error if `masterKey` is empty or undefined.
+     */
+    constructor(masterKey: string);
+    /**
+     * Lazy-loads and caches the derived AES-256-GCM {@link CryptoKey}.
+     * Derives a 256-bit key from `masterKey` via SHA-256 digest.
+     */
+    private getAesKey;
+    /**
+     * Lazy-loads and caches the derived HMAC SHA-256 {@link CryptoKey}.
+     */
+    private getHmacKey;
+    /**
+     * Encrypts a plaintext string with AES-256-GCM and a fresh 96-bit (12-byte) IV.
+     * Output is formatted as `v1:<iv_base64>:<ciphertext_base64>`.
+     */
+    encrypt(plaintext: string): Promise<string>;
+    /**
+     * Decrypts a `v1:<iv_base64>:<ciphertext_base64>` string back to its plaintext value.
+     * If the input string is not prefixed with `v1:`, returns the raw string as unencrypted legacy data.
+     */
+    decrypt(ciphertext: string): Promise<string>;
+    /**
+     * Computes a deterministic HMAC SHA-256 hex digest for blind index generation.
+     */
+    hash(plaintext: string): Promise<string>;
+}
+/** Thrown when a protected field is processed but no master key is configured. */
+export declare class PrivacyNotConfiguredError extends Error {
+    constructor();
+}
+/**
+ * Fail-closed {@link IPrivacyService} for installs without a master key.
+ * Never returns plaintext as protected output; legacy non-`v1:` values still read through.
+ */
+export declare class UnconfiguredPrivacyService implements IPrivacyService {
+    encrypt(_plaintext: string): Promise<string>;
+    decrypt(ciphertext: string): Promise<string>;
+    hash(_plaintext: string): Promise<string>;
+}
+//# sourceMappingURL=privacy.service.d.ts.map

package/dist/engine/privacy/privacy.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../../src/engine/privacy/privacy.service.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACzC;AA4BD;;;GAGG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,aAAa,CAAC,CAAoB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAoB;IAE3C;;;;OAIG;gBACS,SAAS,EAAE,MAAM;IAO7B;;;OAGG;YACW,SAAS;IAmBvB;;OAEG;YACW,UAAU;IAexB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcjD;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlD;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAa/C;AAED,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;;CAKnD;AAED;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,eAAe;IAC1D,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK5C,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGhD"}