@beechcms/core 0.8.0 → 0.9.0

package/dist/rbac/evaluate.js

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { GLOBAL_SCOPE } from './permissions.js';
+/**
+ * Folds a user's active assignments into their effective authority.
+ *
+ * The model is strictly additive: every assignment can only widen the result, and
+ * assignments referencing an unknown role are ignored rather than treated as an error.
+ *
+ * @param assignments - Active assignments, already decay-filtered by the repository.
+ * @param roles - The roles those assignments reference; extra roles are harmless.
+ */
+export function buildEffectivePermissions(assignments, roles) {
+    const rolesById = new Map(roles.map(role => [role.id, role]));
+    const global = new Set();
+    const byScope = new Map();
+    for (const assignment of assignments) {
+        const role = rolesById.get(assignment.roleId);
+        if (!role)
+            continue;
+        if (assignment.scope === GLOBAL_SCOPE) {
+            for (const permission of role.permissions)
+                global.add(permission);
+            continue;
+        }
+        let bucket = byScope.get(assignment.scope);
+        if (!bucket) {
+            bucket = new Set();
+            byScope.set(assignment.scope, bucket);
+        }
+        for (const permission of role.permissions)
+            bucket.add(permission);
+    }
+    return { global, byScope };
+}
+/**
+ * Returns everything the caller may do within one scope: the union of their global
+ * permissions and the permissions granted on that specific seed.
+ */
+export function permissionsForScope(effective, scope) {
+    if (scope === GLOBAL_SCOPE)
+        return effective.global;
+    const scoped = effective.byScope.get(scope);
+    if (!scoped)
+        return effective.global;
+    return new Set([...effective.global, ...scoped]);
+}
+/**
+ * The single authorization question: may this caller perform `permission` on `scope`?
+ *
+ * A global grant satisfies any scope. A scoped grant satisfies only its own seed and
+ * never {@link GLOBAL_SCOPE} — that asymmetry is what stops horizontal escalation.
+ */
+export function hasPermission(effective, permission, scope) {
+    if (effective.global.has(permission))
+        return true;
+    if (scope === GLOBAL_SCOPE)
+        return false;
+    return effective.byScope.get(scope)?.has(permission) === true;
+}
+/**
+ * The anti-escalation rule: an actor may only hand out authority they already hold.
+ *
+ * A grant is legal only when the actor holds every permission being granted, at the
+ * scope it is being granted on. Consequently an actor scoped to seed X can never mint
+ * a global assignment, and can never include a permission absent from their own set —
+ * regardless of what the role itself contains.
+ *
+ * @param actor - The granting user's effective authority.
+ * @param targetScope - The scope the new assignment would apply to.
+ * @param targetPermissions - The permissions carried by the role being assigned.
+ */
+export function canGrant(actor, targetScope, targetPermissions) {
+    if (targetScope === GLOBAL_SCOPE) {
+        return targetPermissions.every(permission => actor.global.has(permission));
+    }
+    const held = permissionsForScope(actor, targetScope);
+    return targetPermissions.every(permission => held.has(permission));
+}
+/**
+ * Every permission the actor holds at ANY scope — global or seed-scoped — folded into
+ * one set.
+ *
+ * This is deliberately NOT an authorization primitive: it answers "could this actor
+ * ever grant X somewhere", not "may this actor do X here". Only {@link hasPermission}
+ * and {@link canGrant} answer the latter, and every route-level decision must keep
+ * using them.
+ */
+export function permissionsHeldAnywhere(effective) {
+    const held = new Set(effective.global);
+    for (const bucket of effective.byScope.values()) {
+        for (const permission of bucket)
+            held.add(permission);
+    }
+    return held;
+}
+/**
+ * Whether the actor holds `permission` on at least one scope.
+ *
+ * Backs the coarse route gate for administration endpoints whose scope is not in the
+ * URL: the gate keeps out callers with no administrative authority at all, and the
+ * slice then makes the exact per-scope decision with {@link hasPermission} /
+ * {@link canGrant}. Never use it as the final authorization check.
+ */
+export function hasPermissionAnywhere(effective, permission) {
+    if (effective.global.has(permission))
+        return true;
+    for (const bucket of effective.byScope.values()) {
+        if (bucket.has(permission))
+            return true;
+    }
+    return false;
+}

package/dist/rbac/invitation.repository.d.ts

@@ -0,0 +1,84 @@
+import type { NewUserInput } from '../auth/user.repository.js';
+import type { PageRequest } from './types.js';
+import type { Scope } from './permissions.js';
+/** One invitation row. `tokenHash` is deliberately absent: nothing above the storage
+ *  boundary ever needs it, and an administration listing must not carry credential
+ *  material (same rule as AccountSummary omitting passwordHash). */
+export interface InvitationRecord {
+    id: string;
+    email: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+    expiresAt: number;
+    createdAt: number;
+    /** Non-null once redeemed. Single-use is enforced by {@link IInvitationRepository.redeem}. */
+    usedAt: number | null;
+}
+export interface NewInvitationInput {
+    email: string;
+    tokenHash: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+    expiresAt: number;
+}
+/** A live invitation resolved from a bearer token, with the pre-assignment it carries. */
+export interface ValidatedInvitation {
+    id: string;
+    email: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+}
+/** What {@link IInvitationRepository.redeem} writes in one transaction. */
+export interface InvitationRedemption {
+    invitationId: string;
+    user: NewUserInput;
+    assignmentId: string;
+    roleId: string;
+    scope: Scope;
+    usedAt: number;
+}
+/**
+ * Storage contract for onboarding invitations.
+ *
+ * Deliberately shaped after {@link IPasswordResetTokenRepository}: a single-use,
+ * expiring, hash-only bearer credential is the same lifecycle, and the codebase keeps
+ * exactly one shape for it.
+ */
+export interface IInvitationRepository {
+    /** Deletes every unredeemed invitation for an email before a new one is issued, so at
+     *  most one live token per address exists at any time. They are removed, not marked
+     *  used: `used_at` means "redeemed", and a superseded row must never be reported as
+     *  accepted. */
+    supersedePending(email: string): Promise<void>;
+    /** Stores a new invitation. Only the hash is persisted, never the plaintext.
+     *  Returns the new invitation id. */
+    create(input: NewInvitationInput): Promise<string>;
+    /** Resolves a live (unused, unexpired) invitation by token hash. Null otherwise —
+     *  expired, already used and unknown are deliberately indistinguishable. */
+    findValidByHash(tokenHash: string, nowTimestamp: number): Promise<ValidatedInvitation | null>;
+    /**
+     * Redeems an invitation: creates the account, writes its (role, scope) assignment and
+     * consumes the invitation in ONE atomic write. Either all three land or none does, so a
+     * failure can neither burn the invitation nor leave an account without its role.
+     *
+     * Returns TRUE only when THIS call performed the transition (`used_at IS NULL` at write
+     * time), which is what makes redemption single-use under concurrency; FALSE means the
+     * invitation was consumed or revoked meanwhile and nothing was written. Throws when the
+     * email is already registered (UNIQUE), writing nothing.
+     */
+    redeem(input: InvitationRedemption): Promise<boolean>;
+    /** One invitation by id, regardless of state. Null when absent. */
+    findById(invitationId: string): Promise<InvitationRecord | null>;
+    /** One page of invitations, newest first. */
+    list(page: PageRequest): Promise<InvitationRecord[]>;
+    /** Replaces the token and expiry of an existing PENDING-or-EXPIRED invitation,
+     *  preserving its (role, scope, email) pre-assignment. Returns false when the row is
+     *  absent or already used — a consumed invitation is never re-armed. */
+    regenerate(invitationId: string, tokenHash: string, expiresAt: number): Promise<boolean>;
+    /** Revokes (hard-deletes) an invitation. Returns false when it did not exist. */
+    delete(invitationId: string): Promise<boolean>;
+}
+//# sourceMappingURL=invitation.repository.d.ts.map

package/dist/rbac/invitation.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitation.repository.d.ts","sourceRoot":"","sources":["../../src/rbac/invitation.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;oEAEoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,8FAA8F;IAC9F,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,YAAY,CAAA;IAClB,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;oBAGgB;IAChB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE9C;yCACqC;IACrC,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAElD;gFAC4E;IAC5E,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAA;IAE7F;;;;;;;;;OASG;IACH,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAErD,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAEhE,6CAA6C;IAC7C,IAAI,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;IAEpD;;4EAEwE;IACxE,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAExF,iFAAiF;IACjF,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/C"}

package/dist/rbac/invitation.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/rbac/permissions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The closed atomic permission vocabulary.
+ *
+ * This tuple is the single source of truth for what a role may contain. It is
+ * CLOSED BY DESIGN: new permissions arrive only as a developer code change plus a
+ * migration widening the `role_permissions` CHECK constraint. Nothing at runtime —
+ * no API, no plugin, no dashboard screen — may extend it.
+ *
+ * `manage_seeds` (or any schema-mutation permission) is deliberately absent and must
+ * never be added. Seed schema mutation stays a developer capability exercised outside
+ * the dashboard, via CLI and migrations.
+ *
+ * Each non-CRUD dashboard surface owns one dedicated permission (`view_analytics` is
+ * the first). Absence of the permission hides the surface; there is no default-visible
+ * exception.
+ */
+export declare const PERMISSIONS: readonly ["content:read", "content:create", "content:update", "content:delete", "manage_users", "manage_roles", "view_analytics"];
+/** A single atomic permission drawn from the closed vocabulary. */
+export type Permission = (typeof PERMISSIONS)[number];
+/**
+ * The sentinel scope granting a permission across every seed, present and future.
+ * Reserved for cross-cutting coordination roles (e.g. SuperAdmin).
+ */
+export declare const GLOBAL_SCOPE = "*";
+/**
+ * A permission perimeter: either {@link GLOBAL_SCOPE} or a `seeds.slug`.
+ * Isolation is per-seed, never row-level.
+ */
+export type Scope = string;
+/** Narrows an arbitrary string to a known permission. */
+export declare function isPermission(value: string): value is Permission;
+/**
+ * Name of the system role seeded by `0000_v040_base.sql` with the full permission set.
+ *
+ * `roles.name` is UNIQUE, so the name is a stable handle; the id is minted by the
+ * migration and differs per database, which is why nothing may hardcode it.
+ */
+export declare const SUPER_ADMIN_ROLE_NAME = "SuperAdmin";
+//# sourceMappingURL=permissions.d.ts.map

package/dist/rbac/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/rbac/permissions.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,mIAQd,CAAA;AAEV,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;;GAGG;AACH,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAA;AAE1B,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA"}

package/dist/rbac/permissions.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * The closed atomic permission vocabulary.
+ *
+ * This tuple is the single source of truth for what a role may contain. It is
+ * CLOSED BY DESIGN: new permissions arrive only as a developer code change plus a
+ * migration widening the `role_permissions` CHECK constraint. Nothing at runtime —
+ * no API, no plugin, no dashboard screen — may extend it.
+ *
+ * `manage_seeds` (or any schema-mutation permission) is deliberately absent and must
+ * never be added. Seed schema mutation stays a developer capability exercised outside
+ * the dashboard, via CLI and migrations.
+ *
+ * Each non-CRUD dashboard surface owns one dedicated permission (`view_analytics` is
+ * the first). Absence of the permission hides the surface; there is no default-visible
+ * exception.
+ */
+export const PERMISSIONS = [
+    'content:read',
+    'content:create',
+    'content:update',
+    'content:delete',
+    'manage_users',
+    'manage_roles',
+    'view_analytics',
+];
+/**
+ * The sentinel scope granting a permission across every seed, present and future.
+ * Reserved for cross-cutting coordination roles (e.g. SuperAdmin).
+ */
+export const GLOBAL_SCOPE = '*';
+/** Narrows an arbitrary string to a known permission. */
+export function isPermission(value) {
+    return PERMISSIONS.includes(value);
+}
+/**
+ * Name of the system role seeded by `0000_v040_base.sql` with the full permission set.
+ *
+ * `roles.name` is UNIQUE, so the name is a stable handle; the id is minted by the
+ * migration and differs per database, which is why nothing may hardcode it.
+ */
+export const SUPER_ADMIN_ROLE_NAME = 'SuperAdmin';

package/dist/rbac/types.d.ts

@@ -0,0 +1,130 @@
+import type { Permission, Scope } from './permissions.js';
+/** A named, reusable bundle of atomic permissions. */
+export interface RoleRecord {
+    id: string;
+    name: string;
+    description: string | null;
+    icon?: string | null;
+    /** System roles (e.g. SuperAdmin) are seeded by migration and may not be deleted. */
+    isSystem: boolean;
+    /** Always a subset of `PERMISSIONS`; unknown values are dropped at the storage boundary. */
+    permissions: Permission[];
+    createdAt: number;
+    updatedAt: number;
+}
+/** One (user, role, scope) triple. A user may hold N independent assignments. */
+export interface PermissionAssignment {
+    id: string;
+    userId: string;
+    roleId: string;
+    scope: Scope;
+}
+export interface NewRoleInput {
+    name: string;
+    description: string | null;
+    icon?: string | null;
+    permissions: readonly Permission[];
+}
+export interface NewAssignmentInput {
+    userId: string;
+    roleId: string;
+    scope: Scope;
+}
+/**
+ * A caller's resolved authority, computed once per request from their active
+ * assignments. Purely additive: there is no negative permission and no conflict
+ * resolution between roles.
+ */
+export interface EffectivePermissions {
+    /** Permissions held at {@link GLOBAL_SCOPE}; they apply to every seed. */
+    global: ReadonlySet<Permission>;
+    /** Permissions held at a specific seed slug, keyed by that slug. */
+    byScope: ReadonlyMap<Scope, ReadonlySet<Permission>>;
+}
+/** One page of an administration listing. `limit` is at most {@link MAX_PAGE_SIZE}. */
+export interface PageRequest {
+    limit: number;
+    offset: number;
+}
+/** Largest page the administration listings serve. Keeps every `IN (...)` fan-out under D1's bound-parameter cap. */
+export declare const MAX_PAGE_SIZE = 100;
+/**
+ * Outcome of a write that must never remove the platform's last active global
+ * administrator. The repository enforces the invariant inside the write itself (one
+ * conditional statement), so two concurrent requests cannot both pass a stale count.
+ * - `applied`: the write happened.
+ * - `not-found`: the target does not exist (or is an immutable system role); nothing changed.
+ * - `last-global-admin`: refused because it would leave no other active global administrator.
+ */
+export type AdminGuardedResult = 'applied' | 'not-found' | 'last-global-admin';
+/** Storage contract for roles and their permission bundles. */
+export interface IRoleRepository {
+    /** Retrieves a role with its permissions, or null when it does not exist. */
+    findById(roleId: string): Promise<RoleRecord | null>;
+    /** Retrieves several roles in one round trip. Missing ids are simply absent. */
+    findByIds(roleIds: readonly string[]): Promise<RoleRecord[]>;
+    /** Lists every role, system roles included, ordered by name. */
+    listAll(): Promise<RoleRecord[]>;
+    /** Creates a role and its permission rows atomically. Returns the new role id. */
+    create(input: NewRoleInput): Promise<string>;
+    /**
+     * Replaces a role's name, description and full permission set atomically.
+     *
+     * `not-found` — changing NOTHING, permissions included — when the role does not exist or
+     * is a system role. System roles are seeded by migration and are immutable in both halves
+     * of the write, which is the guarantee callers rely on to keep `SuperAdmin` intact.
+     * `last-global-admin` when the new set drops `manage_users` from a role that carries the
+     * last active global administrator; nothing is written then either.
+     */
+    update(roleId: string, input: NewRoleInput): Promise<AdminGuardedResult>;
+    /**
+     * Deletes a non-system role and, by cascade, its permissions and assignments.
+     * `not-found` when the role does not exist or is a system role; `last-global-admin` when
+     * the role carries the last active global administrator.
+     */
+    delete(roleId: string): Promise<AdminGuardedResult>;
+}
+/** Storage contract for (user, role, scope) assignments. */
+export interface IRoleAssignmentRepository {
+    /**
+     * Lists a user's assignments that currently grant anything.
+     *
+     * An assignment is skipped when its scope names a seed that is absent or
+     * `status != 'active'`, so scopes decay with their seed and revive with it.
+     * {@link GLOBAL_SCOPE} assignments are always returned.
+     */
+    listActiveForUser(userId: string): Promise<PermissionAssignment[]>;
+    /** Lists every assignment referencing a role, decay filter NOT applied. */
+    listByRole(roleId: string): Promise<PermissionAssignment[]>;
+    /** Creates an assignment. Returns its id; an existing identical triple is a no-op. */
+    create(input: NewAssignmentInput): Promise<string>;
+    /**
+     * Removes one assignment. `not-found` when it did not exist; `last-global-admin` when it is
+     * the global `manage_users` assignment of the last active global administrator.
+     */
+    delete(assignmentId: string): Promise<AdminGuardedResult>;
+    /**
+     * Read-only twin of the {@link delete} guard: would removing this assignment leave no
+     * other active global administrator? ADVISORY — it only lets a caller that refuses for
+     * another reason (the Developer account) report the more fundamental one; it is never a
+     * substitute for the guard inside {@link delete}.
+     */
+    isLastGlobalAdminAssignment(assignmentId: string): Promise<boolean>;
+    /** One assignment by id, decay filter NOT applied. Null when absent. */
+    findById(assignmentId: string): Promise<PermissionAssignment | null>;
+    /**
+     * Every assignment of the given users, decay filter NOT applied, in ONE round trip.
+     *
+     * Exists so the account-list endpoint can resolve the scopes of one page of accounts
+     * without a query per account. Callers pass at most {@link MAX_PAGE_SIZE} ids (D1 caps
+     * bound parameters per statement); an empty list returns an empty list.
+     */
+    listForUsers(userIds: readonly string[]): Promise<PermissionAssignment[]>;
+    /**
+     * Every assignment of one user, decay filter NOT applied — administration screens must
+     * see (and be able to remove) a row whose seed is currently deleted, which
+     * {@link listActiveForUser} deliberately hides.
+     */
+    listAllForUser(userId: string): Promise<PermissionAssignment[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/rbac/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/rbac/types.ts"],"names":[],"mappings":"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"}

package/dist/rbac/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Largest page the administration listings serve. Keeps every `IN (...)` fan-out under D1's bound-parameter cap. */
+export const MAX_PAGE_SIZE = 100;

package/dist/relations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Back-reference helpers for the Beech CMS relation system.
+ *
+ * `buildBackrefMap` is a pure function that iterates the seed registry once
+ * and builds a lookup map: targetSlug → sources that point to it.
+ * Build this once at app factory time and cache it for the process lifetime.
+ */
+import type { Seed } from './types.js';
+export interface BackrefSource {
+    /** Slug of the seed that owns the relation branch */
+    sourceSlug: string;
+    /** `branch.alias` — the FK column name (single) or join-table name suffix (multi) */
+    branchAlias: string;
+    /** `branch.label` — human label for UI grouping */
+    branchLabel: string;
+    /** 'single' for direct FK, 'multi' for many-to-many join table */
+    relationship: 'single' | 'multi';
+    /** True when branch.onDelete === 'RESTRICT' — used to disable Delete button */
+    restricts: boolean;
+}
+/** Map: targetSlug → every source that points to it */
+export type BackrefMap = Map<string, BackrefSource[]>;
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export declare function buildBackrefMap(seeds: Seed[]): BackrefMap;
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAA;IAChC,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAoBzD"}

package/dist/relations.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export function buildBackrefMap(seeds) {
+    const map = new Map();
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            const existing = map.get(branch.targetSeed) ?? [];
+            existing.push({
+                sourceSlug: seed.slug,
+                branchAlias: branch.alias,
+                branchLabel: branch.label,
+                relationship: branch.multiple === true ? 'multi' : 'single',
+                restricts: branch.onDelete === 'RESTRICT',
+            });
+            map.set(branch.targetSeed, existing);
+        }
+    }
+    return map;
+}

package/dist/richtext-render.d.ts

@@ -0,0 +1,11 @@
+import type { JSONContent } from '@tiptap/core';
+/**
+ * Accetta JSON TipTap (`{ type: 'doc', ... }`), envelope v1, o stringa HTML legacy.
+ */
+export declare function normalizeRichtextForRender(value: unknown): JSONContent | string | null;
+/**
+ * Render deterministico JSON → HTML (per display, anteprime, API pubblica).
+ * Per stringhe HTML legacy restituisce la stringa sanificata come pass-through (nessun parse TipTap).
+ */
+export declare function renderRichText(value: unknown): string;
+//# sourceMappingURL=richtext-render.d.ts.map

package/dist/richtext-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"richtext-render.d.ts","sourceRoot":"","sources":["../src/richtext-render.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAuD/C;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,IAAI,CAatF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQrD"}

package/dist/richtext-render.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { generateHTML } from '@tiptap/html';
+import Highlight from '@tiptap/extension-highlight';
+import Image from '@tiptap/extension-image';
+import Link from '@tiptap/extension-link';
+import Subscript from '@tiptap/extension-subscript';
+import Superscript from '@tiptap/extension-superscript';
+import { Table, TableCell, TableHeader, TableRow } from '@tiptap/extension-table';
+import TextAlign from '@tiptap/extension-text-align';
+import { Mathematics } from '@tiptap/extension-mathematics';
+import StarterKit from '@tiptap/starter-kit';
+import { isRichtextEnvelopeV1 } from './richtext.js';
+/**
+ * Allinea l'output HTML allo schema TipTap usato dall'editor dashboard.
+ * Mantieni sincronizzato con `apps/dashboard/src/features/richtext-editor/extensions/build-editor-extensions.ts`.
+ */
+function createRichTextHtmlExtensions() {
+    return [
+        StarterKit.configure({
+            link: false,
+            codeBlock: {
+                HTMLAttributes: {
+                    class: 'richtext-code-block',
+                },
+            },
+        }),
+        Link.configure({
+            openOnClick: false,
+            autolink: true,
+            defaultProtocol: 'https',
+        }),
+        Mathematics.configure({
+            katexOptions: {
+                throwOnError: false,
+            },
+        }),
+        Highlight,
+        Superscript,
+        Subscript,
+        Image.configure({
+            allowBase64: false,
+        }),
+        TextAlign.configure({
+            types: ['heading', 'paragraph'],
+        }),
+        Table.configure({
+            resizable: false,
+        }),
+        TableRow,
+        TableHeader,
+        TableCell,
+    ];
+}
+/**
+ * Accetta JSON TipTap (`{ type: 'doc', ... }`), envelope v1, o stringa HTML legacy.
+ */
+export function normalizeRichtextForRender(value) {
+    if (value == null || value === '')
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        const o = value;
+        if (isRichtextEnvelopeV1(value)) {
+            return o.doc;
+        }
+        if (o.type === 'doc') {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Render deterministico JSON → HTML (per display, anteprime, API pubblica).
+ * Per stringhe HTML legacy restituisce la stringa sanificata come pass-through (nessun parse TipTap).
+ */
+export function renderRichText(value) {
+    const normalized = normalizeRichtextForRender(value);
+    if (normalized == null)
+        return '';
+    if (typeof normalized === 'string') {
+        return normalized;
+    }
+    const extensions = createRichTextHtmlExtensions();
+    return generateHTML(normalized, extensions);
+}

package/dist/richtext.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Convenzione storage richtext TipTap nel Content Engine.
+ * @see docs/Sprints/tiptap-elevation.md
+ */
+export declare const RICHTEXT_SCHEMA_VERSION: 1;
+export type RichtextEnvelopeV1 = {
+    schemaVersion: typeof RICHTEXT_SCHEMA_VERSION;
+    doc: Record<string, unknown>;
+};
+export declare function isRichtextEnvelopeV1(value: unknown): value is RichtextEnvelopeV1;
+//# sourceMappingURL=richtext.d.ts.map

package/dist/richtext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"richtext.d.ts","sourceRoot":"","sources":["../src/richtext.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAA;AAEjD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,aAAa,EAAE,OAAO,uBAAuB,CAAA;IAC7C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC7B,CAAA;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAIhF"}

package/dist/richtext.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Convenzione storage richtext TipTap nel Content Engine.
+ * @see docs/Sprints/tiptap-elevation.md
+ */
+export const RICHTEXT_SCHEMA_VERSION = 1;
+export function isRichtextEnvelopeV1(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const o = value;
+    return o.schemaVersion === RICHTEXT_SCHEMA_VERSION && typeof o.doc === 'object' && o.doc !== null;
+}

package/dist/scheduler.interface.d.ts

@@ -0,0 +1,4 @@
+export interface IScheduler {
+    waitUntil(promise: Promise<unknown>): void;
+}
+//# sourceMappingURL=scheduler.interface.d.ts.map

package/dist/scheduler.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.interface.d.ts","sourceRoot":"","sources":["../src/scheduler.interface.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C"}

package/dist/scheduler.interface.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/scheduler.stub.d.ts

@@ -0,0 +1,5 @@
+import type { IScheduler } from './scheduler.interface.js';
+export declare class NoOpScheduler implements IScheduler {
+    waitUntil(_promise: Promise<unknown>): void;
+}
+//# sourceMappingURL=scheduler.stub.d.ts.map

package/dist/scheduler.stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.stub.d.ts","sourceRoot":"","sources":["../src/scheduler.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,qBAAa,aAAc,YAAW,UAAU;IAC9C,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;CAG5C"}