@beechcms/core 0.9.4 → 0.9.6

package/dist/engine/introspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/engine/introspection.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CAClE;AAED,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,qDAAqD;IACrD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,sEAAsE;IACtE,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,wEAAwE;IACxE,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B,wBAAwB;IACxB,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AA6CD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,CAAC,CAgDpB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,EAAE,CAAC,CAoBjB"}

package/dist/engine/introspection.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Thrown when live state cannot be read or cannot be trusted. */
+export class IntrospectionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IntrospectionError';
+    }
+}
+/**
+ * SQLite identifiers cannot be bound as parameters, so every table name reaching a PRAGMA is
+ * interpolated — and therefore must be proven safe first. Table names in this system are always
+ * `content_{slug}` / `rel_{slug}_{alias}` / a structural table, all of which match this pattern.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Returns `name` unchanged when it is a safe SQL identifier; throws otherwise. */
+export function assertSafeIdentifier(name) {
+    if (!SAFE_IDENTIFIER.test(name)) {
+        throw new IntrospectionError(`Refusing to introspect '${name}': not a plain SQL identifier. Table names are never user input in BeechCMS.`);
+    }
+    return name;
+}
+/**
+ * Physical state of one table. A table SQLite does not know returns `{ exists: false }` with empty
+ * lists rather than throwing: "missing" is a legitimate diff outcome, not an error.
+ *
+ * `PRAGMA table_info` answers an unknown table with zero rows on the SQLite path and raises on some
+ * wrangler paths, so both outcomes collapse to the same result.
+ */
+export async function introspectTable(executor, table) {
+    const name = assertSafeIdentifier(table);
+    const empty = { name, exists: false, columns: [], foreignKeys: [], indexes: [] };
+    let info;
+    try {
+        info = await executor.all(`PRAGMA table_info(${name})`);
+    }
+    catch {
+        return empty;
+    }
+    if (info.length === 0)
+        return empty;
+    const columns = info.map(row => ({
+        name: row.name,
+        sqlType: String(row.type ?? '').toUpperCase(),
+        notNull: row.notnull === 1,
+        isPk: row.pk > 0,
+        defaultValue: row.dflt_value ?? null,
+    }));
+    let fkRows = [];
+    let indexRows = [];
+    try {
+        fkRows = await executor.all(`PRAGMA foreign_key_list(${name})`);
+        indexRows = await executor.all(`PRAGMA index_list(${name})`);
+    }
+    catch {
+        // A table with neither FKs nor indexes answers with zero rows on some drivers and raises on
+        // others; an unreadable constraint list must not hide the column list we already have.
+    }
+    const foreignKeys = fkRows
+        .map(row => ({
+        column: row.from,
+        targetTable: row.table,
+        targetColumn: row.to ?? 'id',
+        onDelete: String(row.on_delete ?? '').toUpperCase(),
+        onUpdate: String(row.on_update ?? '').toUpperCase(),
+    }))
+        .sort((a, b) => a.column.localeCompare(b.column) || a.targetTable.localeCompare(b.targetTable));
+    const indexes = indexRows
+        // Implicit indexes SQLite mints for UNIQUE/PK are not schema an author declared, and their
+        // names are not stable across environments.
+        .filter(row => !row.name.startsWith('sqlite_autoindex_'))
+        .map(row => ({ name: row.name, unique: row.unique === 1 }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { name, exists: true, columns, foreignKeys, indexes };
+}
+/**
+ * Names of the physical tables SQLite holds, optionally restricted to a `LIKE` prefix
+ * (e.g. `content_`). Sorted, `sqlite_*` internals excluded.
+ */
+export async function listTables(executor, prefix) {
+    if (prefix !== undefined)
+        assertSafeIdentifier(`${prefix}x`);
+    const filter = prefix ? ` AND name LIKE '${prefix}%'` : '';
+    const rows = await executor.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'${filter} ORDER BY name ASC`);
+    return rows.map(row => row.name);
+}
+/**
+ * Physical state of several tables at once. With no explicit list, every `content_*` table is
+ * introspected — the set a schema export or a drift check cares about.
+ */
+export async function introspectSchema(executor, tables) {
+    const names = tables ?? await listTables(executor, 'content_');
+    const sorted = [...names].sort((a, b) => a.localeCompare(b));
+    const result = [];
+    // Sequential on purpose: the CLI executor is a synchronous shell/SQLite call behind a Promise,
+    // and D1 rejects unbounded concurrent statements from one request.
+    for (const name of sorted) {
+        result.push(await introspectTable(executor, name));
+    }
+    return { tables: result };
+}
+/**
+ * The DECLARED schema: every active seed definition, read live from D1.
+ *
+ * This — not `beech.schema.ts` — is the source of truth for generated types and for the schema
+ * fingerprint (feature brief, business rule 1). The manifest file is a desired-state artifact and
+ * may legitimately be ahead of, or behind, what is deployed.
+ */
+export async function introspectSeedDefinitions(executor) {
+    let rows;
+    try {
+        rows = await executor.all(`SELECT slug, definition FROM seeds WHERE status = 'active' ORDER BY slug ASC`);
+    }
+    catch (error) {
+        throw new IntrospectionError('Failed to read the `seeds` table from D1.', error);
+    }
+    return rows.map(row => {
+        try {
+            return JSON.parse(row.definition);
+        }
+        catch (error) {
+            throw new IntrospectionError(`Seed '${row.slug}' holds a definition that is not valid JSON; D1 state is corrupt.`, error);
+        }
+    });
+}

package/dist/engine/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.
+ * @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/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../src/engine/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEhF;;;;;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,CA2BzF;AAID;;;;;;;;;;;;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,CAgDzB"}

package/dist/engine/policies.js

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * 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.
+ * @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 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 defaultFilter = isRepeater || resolved.storage === 'hash' ? false : branch.policies?.filter ?? true;
+    const defaultSort = isRepeater || isEncryptedOrHashed ? false : branch.policies?.sort ?? true;
+    const defaultSearch = isRepeater || isEncryptedOrHashed ? false : branch.policies?.search ?? true;
+    // 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: branch.policies?.visibility ?? defaultVisibility,
+        search: defaultSearch,
+        filter: defaultFilter,
+        sort: defaultSort,
+        public: isPublicAllowed,
+        publicEdit: defaultPublicEdit,
+    };
+}
+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;
+        }
+        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] = typeof value === 'string' && value.length > 0 ? '••••••••' : null;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=privacy.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../src/engine/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"}

package/dist/engine/privacy.service.js

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Converts a Uint8Array byte sequence to a Base64-encoded string.
+ * Native Edge-compatible implementation without Node.js Buffer dependencies.
+ */
+function bytesToBase64(bytes) {
+    let binary = '';
+    const len = bytes.byteLength;
+    for (let i = 0; i < len; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+/**
+ * Converts a Base64-encoded string back to a Uint8Array byte sequence.
+ * Native Edge-compatible implementation without Node.js Buffer dependencies.
+ */
+function base64ToBytes(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * Concrete Edge-native implementation of {@link IPrivacyService}.
+ * Employs Web Crypto API (`crypto.subtle`) for zero-dependency execution in Cloudflare Workers.
+ */
+export class PrivacyService {
+    masterKey;
+    aesKeyPromise;
+    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) {
+        if (!masterKey) {
+            throw new Error('PrivacyService requires a non-empty masterKey');
+        }
+        this.masterKey = masterKey;
+    }
+    /**
+     * Lazy-loads and caches the derived AES-256-GCM {@link CryptoKey}.
+     * Derives a 256-bit key from `masterKey` via SHA-256 digest.
+     */
+    async getAesKey() {
+        if (!this.aesKeyPromise) {
+            this.aesKeyPromise = (async () => {
+                const keyData = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(this.masterKey));
+                return crypto.subtle.importKey('raw', keyData, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+            })();
+        }
+        return this.aesKeyPromise;
+    }
+    /**
+     * Lazy-loads and caches the derived HMAC SHA-256 {@link CryptoKey}.
+     */
+    async getHmacKey() {
+        if (!this.hmacKeyPromise) {
+            this.hmacKeyPromise = (async () => {
+                return crypto.subtle.importKey('raw', new TextEncoder().encode(this.masterKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+            })();
+        }
+        return this.hmacKeyPromise;
+    }
+    /**
+     * 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>`.
+     */
+    async encrypt(plaintext) {
+        const key = await this.getAesKey();
+        const iv = crypto.getRandomValues(new Uint8Array(12));
+        const encodedText = new TextEncoder().encode(plaintext);
+        const encryptedBuffer = await crypto.subtle.encrypt({ name: 'AES-GCM', iv: iv }, key, encodedText);
+        const ivBase64 = bytesToBase64(iv);
+        const ciphertextBase64 = bytesToBase64(new Uint8Array(encryptedBuffer));
+        return `v1:${ivBase64}:${ciphertextBase64}`;
+    }
+    /**
+     * 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.
+     */
+    async decrypt(ciphertext) {
+        if (!ciphertext || !ciphertext.startsWith('v1:')) {
+            return ciphertext;
+        }
+        const parts = ciphertext.split(':');
+        if (parts.length !== 3) {
+            throw new Error('Invalid ciphertext format');
+        }
+        const [, ivBase64, cipherBase64] = parts;
+        const iv = base64ToBytes(ivBase64);
+        const cipherBytes = base64ToBytes(cipherBase64);
+        const key = await this.getAesKey();
+        const decryptedBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, cipherBytes);
+        return new TextDecoder().decode(decryptedBuffer);
+    }
+    /**
+     * Computes a deterministic HMAC SHA-256 hex digest for blind index generation.
+     */
+    async hash(plaintext) {
+        const key = await this.getHmacKey();
+        const encodedText = new TextEncoder().encode(plaintext);
+        const signatureBuffer = await crypto.subtle.sign('HMAC', key, encodedText);
+        const hashBytes = new Uint8Array(signatureBuffer);
+        return Array.from(hashBytes)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join('');
+    }
+}

package/dist/engine/query/active-clause.d.ts

@@ -1,7 +1,6 @@
 import type { Seed, TrashedMode } from '../types.js';
 /**
- * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
- * seed does not use soft delete or mode is 'any'.
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.
@@ -9,7 +8,7 @@ import type { Seed, TrashedMode } from '../types.js';
  */
 export declare function activeCondition(seed: Seed, mode?: TrashedMode, tableAlias?: string): string | null;
 /**
- * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ * Returns ` AND <activeCondition>`, or `''` when mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.

package/dist/engine/query/active-clause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"active-clause.d.ts","sourceRoot":"","sources":["../../../src/engine/query/active-clause.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAGR"}
+{"version":3,"file":"active-clause.d.ts","sourceRoot":"","sources":["../../../src/engine/query/active-clause.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAGR"}

package/dist/engine/query/active-clause.js

@@ -1,21 +1,20 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 /**
- * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
- * seed does not use soft delete or mode is 'any'.
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.
  * @param tableAlias - Optional table or alias qualifier prefix.
  */
 export function activeCondition(seed, mode = 'active', tableAlias) {
-    if (!seed.softDelete || mode === 'any')
+    if (mode === 'any')
         return null;
     const col = tableAlias ? `${tableAlias}.deleted_at` : 'deleted_at';
     return mode === 'trashed' ? `${col} IS NOT NULL` : `${col} IS NULL`;
 }
 /**
- * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ * Returns ` AND <activeCondition>`, or `''` when mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.

package/dist/engine/query/query.js

@@ -112,7 +112,7 @@ export function buildSelectQuery(seed, options = {}) {
         joinClause = `LEFT JOIN kanban_positions kp` +
             ` ON kp.seed_slug = ? AND kp.entry_id = ${table}.id AND kp.axis_branch_id = ?`;
         bindings.push(options.kanbanOrder.seedSlug, options.kanbanOrder.axisBranchId);
-        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC`;
+        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC, ${table}.id ASC`;
     }
     const rtBranches = indexableSearchBranches(seed);
     if (search && rtBranches.length > 0) {
@@ -128,12 +128,10 @@ export function buildSelectQuery(seed, options = {}) {
     // Soft delete: 'active' is the default, so a caller that forgets the option can never
     // observe a trashed row — including the Public API, relation expansion and subqueries,
     // which all reach SQL only through repository.findMany.
-    if (seed.softDelete) {
-        const trashed = options.trashed ?? 'active';
-        const cond = activeCondition(seed, trashed, table);
-        if (cond) {
-            whereClauses.push(cond);
-        }
+    const trashed = options.trashed ?? 'active';
+    const cond = activeCondition(seed, trashed, table);
+    if (cond) {
+        whereClauses.push(cond);
     }
     const groupClauses = [];
     for (const group of filters) {
@@ -202,9 +200,11 @@ export function buildSelectQuery(seed, options = {}) {
             sql += orderedBranch && isSingleChoiceTags(orderedBranch)
                 ? tagsOrderClause(col, orderedBranch, dir, bindings)
                 : ` ORDER BY ${col} ${dir}`;
+            // Unique final key: tied sort values would otherwise page in an undefined order.
+            sql += `, ${table}.id ${dir}`;
         }
         else {
-            sql += ` ORDER BY ${table}.created_at DESC`;
+            sql += ` ORDER BY ${table}.created_at DESC, ${table}.id DESC`;
         }
         if (pagination) {
             sql += ` LIMIT ? OFFSET ?`;

package/dist/engine/query/relations.d.ts

@@ -18,6 +18,21 @@ export interface BackrefSource {
     /** True when branch.onDelete === 'RESTRICT' — used to disable Delete button */
     restricts: boolean;
 }
+export interface BackrefItem {
+    id: string;
+    displayName: string | null;
+    status: string;
+    updated_at: number | null;
+}
+export interface QueryGroupResult {
+    items: BackrefItem[];
+    total: number;
+}
+/** Port for reading back-references (entries pointing at a target entry). */
+export interface IBackrefRepository {
+    entryExists(seedOrSlug: Seed | string, id: string): Promise<boolean>;
+    queryGroup(source: BackrefSource, sourceSeed: Seed, targetId: string, limit: number, offset: number): Promise<QueryGroupResult>;
+}
 /** Map: targetSlug → every source that points to it */
 export type BackrefMap = Map<string, BackrefSource[]>;
 /**