@beechcms/core 0.8.0 → 0.8.1

package/dist/media/media-transform.js

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { sha256hex } from '../engine/privacy/policies.js';
+import { canonicalizeMime } from './file-types.js';
+/** Default ceiling, in pixels, on either side of a derived variant. Covers native 32:9 ultrawide panels. */
+export const DEFAULT_MEDIA_MAX_DIMENSION = 5120;
+/** MEDIA_MAX_DIMENSION may lower the ceiling freely but raise it only this far. */
+export const ABSOLUTE_MAX_MEDIA_DIMENSION = 8192;
+export const MEDIA_OUTPUT_FORMATS = ['original', 'webp', 'jpeg'];
+export const MEDIA_QUALITIES = ['low', 'medium', 'high'];
+export const DEFAULT_MEDIA_FORMAT = 'original';
+export const DEFAULT_MEDIA_QUALITY = 'medium';
+/** Encoder quality per enum value. `medium` ≈ 82 per the brief. */
+export const MEDIA_QUALITY_VALUES = Object.freeze({ low: 60, medium: 82, high: 92 });
+export const DEFAULT_MEDIA_SCALE_WIDTHS = [320, 480, 640, 768, 1024, 1280, 1536, 1920, 2560, 3840, 5120];
+export const DEFAULT_MEDIA_PRESETS = Object.freeze({
+    thumbnail: { kind: 'crop', width: 200, height: 200 },
+    avatar: { kind: 'crop', width: 128, height: 128 },
+    card: { kind: 'crop', width: 400, height: 300 },
+    'og-image': { kind: 'crop', width: 1200, height: 630 },
+    hero: { kind: 'crop', width: 1920, height: 800 },
+    ...Object.fromEntries(DEFAULT_MEDIA_SCALE_WIDTHS.map((width) => [`w-${width}`, { kind: 'scale', width }])),
+});
+/** Raster sources the transform path accepts. Everything else — SVG, PDF, video, AVIF, BMP, ICO — is refused. */
+export const TRANSFORMABLE_MEDIA_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp'];
+/** Parameters of the discarded free-form contract. Their presence is an error, never ignored. */
+export const FORBIDDEN_MEDIA_TRANSFORM_PARAMS = ['w', 'h', 'width', 'height', 'fit', 'q'];
+/** Thrown by buildMediaPresetCatalog on any malformed MEDIA_PRESETS entry. Fail closed, never fall back. */
+export class MediaPresetCatalogError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid media preset catalog: ${reason}`);
+        this.reason = reason;
+        this.name = 'MediaPresetCatalogError';
+    }
+}
+const PRESET_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const SCALE_NAME_PATTERN = /^w-([1-9]\d*)$/;
+const invalid = (code) => ({ kind: 'invalid', code });
+/**
+ * Classifies a media query string. Pure: does not consult the catalog (that is env-dependent and
+ * resolved by the caller), so an unknown-but-well-formed preset name returns `transform`.
+ */
+export function parseMediaTransformQuery(params) {
+    if (FORBIDDEN_MEDIA_TRANSFORM_PARAMS.some((name) => params.has(name)))
+        return invalid('media_param_forbidden');
+    const presets = params.getAll('preset');
+    const formats = params.getAll('format');
+    const qualities = params.getAll('quality');
+    if (presets.length > 1 || formats.length > 1 || qualities.length > 1)
+        return invalid('media_param_duplicated');
+    if (presets.length === 0 && formats.length === 0 && qualities.length === 0)
+        return { kind: 'none' };
+    const preset = presets[0];
+    if (!preset)
+        return invalid('media_preset_required');
+    const format = formats[0] ?? DEFAULT_MEDIA_FORMAT;
+    if (!MEDIA_OUTPUT_FORMATS.includes(format))
+        return invalid('media_format_invalid');
+    const quality = qualities[0] ?? DEFAULT_MEDIA_QUALITY;
+    if (!MEDIA_QUALITIES.includes(quality))
+        return invalid('media_quality_invalid');
+    if (!PRESET_NAME_PATTERN.test(preset))
+        return invalid('media_preset_unknown');
+    return { kind: 'transform', request: { preset, format: format, quality: quality } };
+}
+/**
+ * Canonical query for a request: fixed order preset → format → quality, defaults omitted.
+ * `@beechcms/client` emits exactly this string; the server recomputes it and never trusts the client's.
+ */
+export function canonicalMediaTransformQuery(request) {
+    let query = `preset=${encodeURIComponent(request.preset)}`;
+    if (request.format !== DEFAULT_MEDIA_FORMAT)
+        query += `&format=${request.format}`;
+    if (request.quality !== DEFAULT_MEDIA_QUALITY)
+        query += `&quality=${request.quality}`;
+    return query;
+}
+function isPositiveIntegerAtMost(value, max) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0 && value <= max;
+}
+function parsePresetEntry(name, value, maxDimension) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new MediaPresetCatalogError(`preset "${name}" must be an object or null`);
+    }
+    const entry = value;
+    const scaleMatch = SCALE_NAME_PATTERN.exec(name);
+    if (entry.kind === 'crop') {
+        if (Object.keys(entry).some((field) => !['kind', 'width', 'height'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields`);
+        }
+        if (scaleMatch)
+            throw new MediaPresetCatalogError(`"${name}" is reserved for scale presets`);
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension) || !isPositiveIntegerAtMost(entry.height, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs integer width/height in 1..${maxDimension}`);
+        }
+        return { kind: 'crop', width: entry.width, height: entry.height };
+    }
+    if (entry.kind === 'scale') {
+        if (Object.keys(entry).some((field) => !['kind', 'width'].includes(field))) {
+            throw new MediaPresetCatalogError(`preset "${name}" has unknown fields (scale presets never take a height)`);
+        }
+        if (!isPositiveIntegerAtMost(entry.width, maxDimension)) {
+            throw new MediaPresetCatalogError(`preset "${name}" needs an integer width in 1..${maxDimension}`);
+        }
+        if (name !== `w-${entry.width}`)
+            throw new MediaPresetCatalogError(`scale preset "${name}" must be named "w-${entry.width}"`);
+        return { kind: 'scale', width: entry.width };
+    }
+    throw new MediaPresetCatalogError(`preset "${name}" has kind other than "crop" | "scale"`);
+}
+/**
+ * Builds the active catalog: DEFAULT_MEDIA_PRESETS merged by name with `overrides`
+ * (the parsed MEDIA_PRESETS JSON). An override value of `null` removes a preset.
+ * Defaults larger than `maxDimension` are dropped (they could only ever 400); an operator-supplied
+ * preset larger than `maxDimension` is an error.
+ *
+ * @throws {MediaPresetCatalogError} on any malformed override.
+ */
+export function buildMediaPresetCatalog(overrides, maxDimension) {
+    const catalog = new Map();
+    for (const [name, preset] of Object.entries(DEFAULT_MEDIA_PRESETS)) {
+        const largest = preset.kind === 'crop' ? Math.max(preset.width, preset.height) : preset.width;
+        if (largest <= maxDimension)
+            catalog.set(name, preset);
+    }
+    if (overrides === undefined)
+        return catalog;
+    if (typeof overrides !== 'object' || overrides === null || Array.isArray(overrides)) {
+        throw new MediaPresetCatalogError('MEDIA_PRESETS must be a JSON object keyed by preset name');
+    }
+    for (const [name, value] of Object.entries(overrides)) {
+        if (!PRESET_NAME_PATTERN.test(name))
+            throw new MediaPresetCatalogError(`"${name}" is not a valid preset name`);
+        if (value === null) {
+            catalog.delete(name);
+            continue;
+        }
+        catalog.set(name, parsePresetEntry(name, value, maxDimension));
+    }
+    return catalog;
+}
+export function isTransformableMime(mime) {
+    if (!mime)
+        return false;
+    return TRANSFORMABLE_MEDIA_MIME_TYPES.includes(canonicalizeMime(mime));
+}
+/**
+ * Output dimensions of a scale preset (`fit=scale-down`: never upscales). Returns `null` when either
+ * side would exceed `maxDimension` — the pathological-aspect-ratio guard of brief §4. Never truncates.
+ */
+export function deriveScaleOutput(presetWidth, source, maxDimension) {
+    if (source.width <= 0 || source.height <= 0)
+        return null;
+    const output = source.width <= presetWidth
+        ? { width: source.width, height: source.height }
+        : { width: presetWidth, height: Math.max(1, Math.round((source.height * presetWidth) / source.width)) };
+    return output.width > maxDimension || output.height > maxDimension ? null : output;
+}
+/** Identity of a preset's *definition*, so redefining a name never reuses an old variant. */
+export function mediaPresetSignature(preset) {
+    return preset.kind === 'crop' ? `crop:${preset.width}x${preset.height}` : `scale:${preset.width}`;
+}
+/** Precondition: `isTransformableMime(sourceMime)` is true. */
+export function buildImageTransformSpec(preset, request, sourceMime) {
+    const outputMime = request.format === 'webp'
+        ? 'image/webp'
+        : request.format === 'jpeg'
+            ? 'image/jpeg'
+            : canonicalizeMime(sourceMime);
+    const quality = MEDIA_QUALITY_VALUES[request.quality];
+    return preset.kind === 'crop'
+        ? { width: preset.width, height: preset.height, fit: 'cover', outputMime, quality }
+        : { width: preset.width, fit: 'scale-down', outputMime, quality };
+}
+/**
+ * Strong ETag of a variant: source identity (key + size — keys are never overwritten) plus the
+ * canonical request plus the preset definition. Format: `"mv1-<32 hex>"`.
+ */
+export async function computeMediaVariantEtag(source, request, preset) {
+    const digest = await sha256hex(`${source.key}\n${source.size}\n${canonicalMediaTransformQuery(request)}\n${mediaPresetSignature(preset)}`);
+    return `"mv1-${digest.slice(0, 32)}"`;
+}
+/** RFC 9110 §13.1.2: `*` matches; otherwise weak comparison against a comma-separated list. */
+export function ifNoneMatchMatches(header, etag) {
+    if (!header || !etag)
+        return false;
+    const target = etag.replace(/^W\//, '');
+    return header.split(',').some((candidate) => {
+        const trimmed = candidate.trim();
+        return trimmed === '*' || trimmed.replace(/^W\//, '') === target;
+    });
+}

package/dist/media.repository.d.ts

@@ -0,0 +1,61 @@
+/**
+ * MediaRepository - Interface for tracking media assets in the database.
+ */
+export interface MediaObject {
+    key: string;
+    filename: string;
+    mime_type: string;
+    size_bytes: number;
+    uploaded_by: string;
+    created_at: number;
+}
+export interface MediaRepository {
+    /**
+     * Tracks a new file upload in the database.
+     */
+    trackUpload(media: Omit<MediaObject, 'created_at'>): Promise<void>;
+    /**
+     * Retrieves tracking info for a file by its key.
+     */
+    getByKey(key: string): Promise<MediaObject | null>;
+    /**
+     * Removes tracking info for a file.
+     */
+    untrack(key: string): Promise<void>;
+    /**
+     * Lists all tracked media with pagination.
+     */
+    list(options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        items: MediaObject[];
+        total: number;
+    }>;
+    /**
+     * Gets the total number of tracked media objects.
+     */
+    count(): Promise<number>;
+}
+/**
+ * SystemStatsRepository - Interface for managing global system metrics.
+ */
+export interface SystemStatsRepository {
+    /**
+     * Increments the total storage counter.
+     */
+    incrementStorage(bytes: number): Promise<void>;
+    /**
+     * Decrements the total storage counter.
+     */
+    decrementStorage(bytes: number): Promise<void>;
+    /**
+     * Sets a specific value for a storage stat (e.g. after a full sync).
+     */
+    setStorage(bytes: number): Promise<void>;
+    /**
+     * Gets the current total storage usage in bytes.
+     */
+    getStorageUsage(): Promise<number>;
+}
+//# sourceMappingURL=media.repository.d.ts.map

package/dist/media.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.repository.d.ts","sourceRoot":"","sources":["../src/media.repository.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAEnD;;OAEG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEnG;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC"}

package/dist/media.repository.js

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

package/dist/notifications/notification-service.d.ts

@@ -13,9 +13,9 @@ export declare const createNotificationSchema: z.ZodObject<{
     title: z.ZodString;
     message: z.ZodString;
     type: z.ZodOptional<z.ZodEnum<{
-        success: "success";
         error: "error";
         info: "info";
+        success: "success";
         warning: "warning";
     }>>;
 }, z.core.$strip>;

package/dist/oauth/pkce.d.ts

@@ -3,7 +3,7 @@
  * per OAuth 2.1, so no weak fallback configuration can ever exist.
  */
 /** The only accepted code challenge method. */
-export declare const PKCE_CHALLENGE_METHOD: "S256";
+export declare const PKCE_CHALLENGE_METHOD: 'S256';
 export type PkceChallengeMethod = typeof PKCE_CHALLENGE_METHOD;
 /** Minimum / maximum code_verifier length, RFC 7636 §4.1. */
 export declare const PKCE_VERIFIER_MIN_LENGTH = 43;

package/dist/oauth/role-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"role-guard.d.ts","sourceRoot":"","sources":["../../src/oauth/role-guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,YAAY,EAAE,UAAU,EAAE,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACzG;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAC5C,SAAS,CACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,eAAe,EAAE,SAAS,UAAU,EAAE,GACrC,OAAO,CAAC,kBAAkB,CAAC;CAG/B"}
+{"version":3,"file":"role-guard.d.ts","sourceRoot":"","sources":["../../src/oauth/role-guard.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,YAAY,EAAE,UAAU,EAAE,CAAA;CAC3B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,eAAe,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACzG;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAC5C,SAAS,CACb,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,eAAe,EAAE,SAAS,UAAU,EAAE,GACrC,OAAO,CAAC,kBAAkB,CAAC,CAE7B;CACF"}

package/dist/oauth/scopes.d.ts

@@ -9,7 +9,7 @@
  * `beech_schema_plan` is deliberately classified as READ: despite the imperative
  * name it is a dry-run that computes a migration plan and mutates nothing.
  */
-export declare const OAUTH_SCOPES: readonly ["schema:read", "schema:write"];
+export declare const OAUTH_SCOPES: readonly ['schema:read', 'schema:write'];
 export type OAuthScope = (typeof OAUTH_SCOPES)[number];
 /** Narrows an arbitrary string to a known scope. */
 export declare function isOAuthScope(value: string): value is OAuthScope;

package/dist/oauth/scopes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/oauth/scopes.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,0CAA2C,CAAA;AAEpE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtD,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAMjE;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAElE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,OAAO,EAAE,SAAS,UAAU,EAAE,GAC7B,OAAO,CAET"}
+{"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/oauth/scopes.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,YAAI,aAAa,EAAE,cAAc,CAAU,CAAA;AAEpE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAA;AAEtD,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAMjE;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAElE;AAED,oEAAoE;AACpE,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,OAAO,EAAE,SAAS,UAAU,EAAE,GAC7B,OAAO,CAET"}

package/dist/policies.d.ts

@@ -0,0 +1,10 @@
+import type { Branch } from './types.js';
+export declare function sha256hex(value: string): Promise<string>;
+export declare function verifyHashField(stored: string, candidate: string): Promise<boolean>;
+/**
+ * Risolve le policy di un branch applicando i valori di default.
+ * Tutta la logica di accesso ai campi deve passare per questa funzione,
+ * mai con inline `branch.policies?.x ?? default`.
+ */
+export declare function resolvePolicies(branch: Branch): Required<NonNullable<Branch['policies']>>;
+//# sourceMappingURL=policies.d.ts.map

package/dist/policies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAgBzF"}

package/dist/policies.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+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('');
+}
+export async function verifyHashField(stored, candidate) {
+    return stored === (await sha256hex(candidate));
+}
+/**
+ * Risolve le policy di un branch applicando i valori di default.
+ * Tutta la logica di accesso ai campi deve passare per questa funzione,
+ * mai con inline `branch.policies?.x ?? default`.
+ */
+export function resolvePolicies(branch) {
+    const privacy = branch.policies?.privacy ?? 'plain';
+    // Non-plain privacy implies hidden by default: the CMS hashes/encrypts on write,
+    // so returning the stored value would leak the digest to readers.
+    const defaultVisibility = privacy !== 'plain' ? 'hidden' : 'full';
+    // Repeaters live in a single JSON column — never filterable, sortable, or
+    // searchable/facetable in v1, regardless of what's set on the branch.
+    const isRepeater = branch.type === 'repeater';
+    return {
+        privacy,
+        visibility: branch.policies?.visibility ?? defaultVisibility,
+        search: isRepeater ? false : branch.policies?.search ?? true,
+        filter: isRepeater ? false : branch.policies?.filter ?? true,
+        sort: isRepeater ? false : branch.policies?.sort ?? true,
+        public: branch.policies?.public ?? true,
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"queue.stub.d.ts","sourceRoot":"","sources":["../../src/queue/queue.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,0EAA0E;AAC1E,qBAAa,gBAAiB,YAAW,aAAa;IAC9C,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;CAI/D"}
+{"version":3,"file":"queue.stub.d.ts","sourceRoot":"","sources":["../../src/queue/queue.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,0EAA0E;AAC1E,qBAAa,gBAAiB,YAAW,aAAa;IAC9C,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAG7D;CACF"}

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

@@ -1 +1 @@
-{"version":3,"file":"scheduler.stub.d.ts","sourceRoot":"","sources":["../../src/queue/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"}
+{"version":3,"file":"scheduler.stub.d.ts","sourceRoot":"","sources":["../../src/queue/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,CAE1C;CACF"}

package/dist/queue.interface.d.ts

@@ -0,0 +1,39 @@
+import type { ContentRepository } from './content.repository.js';
+import type { BeechBucket } from './storage.js';
+import type { IClock } from './clock.js';
+import type { IIdGenerator } from './id-generator.js';
+/**
+ * The envelope put on the wire / queue. `name` selects the handler from the
+ * JobRegistry; `payload` is the developer-supplied, JSON-serializable body.
+ */
+export interface QueueMessage<T = unknown> {
+    name: string;
+    payload: T;
+}
+/**
+ * Execution context handed to every job. Botanical Invariant: jobs receive the
+ * engine-mediated repository, NEVER a raw D1Database. `env` is a read-only,
+ * stringly-typed view of bindings/secrets for things like fetch targets — it
+ * deliberately does not expose `DB`.
+ */
+export interface JobContext {
+    repository: ContentRepository;
+    bucket: BeechBucket;
+    clock: IClock;
+    idGenerator: IIdGenerator;
+    env: Record<string, string | undefined>;
+}
+/** A single background worker. Receives the decoded payload + context. */
+export type JobHandler<T = unknown> = (payload: T, context: JobContext) => Promise<void>;
+/** Name -> handler map, supplied via BeechConfig.jobs. */
+export type JobRegistry = Record<string, JobHandler<any>>;
+/**
+ * Producer port. `enqueue` schedules deferred work and returns once the message
+ * is accepted by the transport. Like INotificationService, implementations MUST
+ * decide their own fire-and-forget vs inline semantics and MUST NOT let a
+ * transport failure crash the request that called enqueue.
+ */
+export interface IQueueService {
+    enqueue<T>(name: string, payload: T): Promise<void>;
+}
+//# sourceMappingURL=queue.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.interface.d.ts","sourceRoot":"","sources":["../src/queue.interface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,CAAC,CAAA;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,iBAAiB,CAAA;IAC7B,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,YAAY,CAAA;IACzB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACxC;AAED,0EAA0E;AAC1E,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAAI,CACpC,OAAO,EAAE,CAAC,EACV,OAAO,EAAE,UAAU,KAChB,OAAO,CAAC,IAAI,CAAC,CAAA;AAElB,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACpD"}

package/dist/queue.interface.js

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

package/dist/queue.stub.d.ts

@@ -0,0 +1,6 @@
+import type { IQueueService } from './queue.interface.js';
+/** Safe no-op producer (e.g. unit tests that don't assert on enqueue). */
+export declare class NoOpQueueService implements IQueueService {
+    enqueue<T>(_name: string, _payload: T): Promise<void>;
+}
+//# sourceMappingURL=queue.stub.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue.stub.d.ts","sourceRoot":"","sources":["../src/queue.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEzD,0EAA0E;AAC1E,qBAAa,gBAAiB,YAAW,aAAa;IAC9C,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAG5D"}

package/dist/queue.stub.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Safe no-op producer (e.g. unit tests that don't assert on enqueue). */
+export class NoOpQueueService {
+    async enqueue(_name, _payload) {
+        // intentionally empty
+    }
+}

package/dist/rate-limit/token-bucket-rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-bucket-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/token-bucket-rate-limiter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAQhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,qBAAa,sBAAuB,YAAW,YAAY;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;gBAE/B,OAAO,CAAC,EAAE,kBAAkB;IAQxC,OAAO,CAAC,mBAAmB;IASrB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAsCvD,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"token-bucket-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/token-bucket-rate-limiter.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAQhD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kBAAkB,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,qBAAa,sBAAuB,YAAW,YAAY;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAQ;IAE3C,YAAY,OAAO,CAAC,EAAE,kBAAkB,EAMvC;IAED,OAAO,CAAC,mBAAmB;IASrB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAoCtD;IAED,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/rbac/evaluate.d.ts

@@ -0,0 +1,57 @@
+import { type Permission, type Scope } from './permissions.js';
+import type { EffectivePermissions, PermissionAssignment, RoleRecord } from './types.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 declare function buildEffectivePermissions(assignments: readonly PermissionAssignment[], roles: readonly RoleRecord[]): EffectivePermissions;
+/**
+ * Returns everything the caller may do within one scope: the union of their global
+ * permissions and the permissions granted on that specific seed.
+ */
+export declare function permissionsForScope(effective: EffectivePermissions, scope: Scope): ReadonlySet<Permission>;
+/**
+ * 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 declare function hasPermission(effective: EffectivePermissions, permission: Permission, scope: Scope): boolean;
+/**
+ * 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 declare function canGrant(actor: EffectivePermissions, targetScope: Scope, targetPermissions: readonly Permission[]): boolean;
+/**
+ * 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 declare function permissionsHeldAnywhere(effective: EffectivePermissions): ReadonlySet<Permission>;
+/**
+ * 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 declare function hasPermissionAnywhere(effective: EffectivePermissions, permission: Permission): boolean;
+//# sourceMappingURL=evaluate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/rbac/evaluate.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,UAAU,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAExF;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,KAAK,EAAE,SAAS,UAAU,EAAE,GAC3B,oBAAoB,CAuBtB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,oBAAoB,EAC/B,KAAK,EAAE,KAAK,GACX,WAAW,CAAC,UAAU,CAAC,CAKzB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,KAAK,GACX,OAAO,CAIT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,oBAAoB,EAC3B,WAAW,EAAE,KAAK,EAClB,iBAAiB,EAAE,SAAS,UAAU,EAAE,GACvC,OAAO,CAMT;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,oBAAoB,GAAG,WAAW,CAAC,UAAU,CAAC,CAMhG;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,UAAU,GACrB,OAAO,CAMT"}

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;
+}