@beechcms/core 0.7.0 → 0.8.1

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

@@ -0,0 +1,32 @@
+import type { OAuthScope } from './scopes.js';
+/** Outcome of a role arbitration. `deniedScopes` is empty when fully granted. */
+export interface ScopeGrantDecision {
+    grantedScopes: OAuthScope[];
+    deniedScopes: OAuthScope[];
+}
+/**
+ * Arbitrates which of the requested scopes a given user role may grant.
+ *
+ * This is the ONLY place role-based authorization may live in the OAuth flow.
+ * `/oauth/authorize` and `/oauth/token` must never branch on `role` themselves,
+ * so introducing a real role system later requires swapping the implementation
+ * bound in repositoryMiddleware and nothing else.
+ */
+export interface IRoleGuard {
+    /**
+     * @param role - The resource owner's role claim, or undefined when absent.
+     * @param requestedScopes - Scopes the client asked for, already validated.
+     */
+    arbitrate(role: string | undefined, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
+}
+/**
+ * Stub guard for the pre-roles world: grants every requested scope to every role.
+ *
+ * This permissiveness is EXPLICIT and directly tested, not an accidental default.
+ * When the roles feature lands, replace this binding with a real adapter; the
+ * behaviour change will then be visible as a failing test here, by design.
+ */
+export declare class AllowAllRoleGuard implements IRoleGuard {
+    arbitrate(_role: string | undefined, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
+}
+//# sourceMappingURL=role-guard.d.ts.map

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

@@ -0,0 +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,CAE7B;CACF"}

package/dist/oauth/role-guard.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Stub guard for the pre-roles world: grants every requested scope to every role.
+ *
+ * This permissiveness is EXPLICIT and directly tested, not an accidental default.
+ * When the roles feature lands, replace this binding with a real adapter; the
+ * behaviour change will then be visible as a failing test here, by design.
+ */
+export class AllowAllRoleGuard {
+    async arbitrate(_role, requestedScopes) {
+        return { grantedScopes: [...requestedScopes], deniedScopes: [] };
+    }
+}

package/dist/oauth/scopes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * OAuth scope vocabulary. Scopes map 1:1 onto the MCP tools exposed today; no
+ * speculative scopes are defined.
+ *
+ * - `schema:read`  -> beech_list_seeds, beech_get_seed, beech_schema_export,
+ *                     beech_schema_validate, beech_schema_plan
+ * - `schema:write` -> beech_schema_apply
+ *
+ * `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 type OAuthScope = (typeof OAUTH_SCOPES)[number];
+/** Narrows an arbitrary string to a known scope. */
+export declare function isOAuthScope(value: string): value is OAuthScope;
+/**
+ * Parses an RFC 6749 §3.3 space-delimited scope string.
+ * Returns null if the string is empty or contains any unknown scope — callers
+ * must reject the request with `invalid_scope` rather than silently dropping it.
+ * Duplicates are collapsed; order is not significant.
+ */
+export declare function parseScopeString(raw: string): OAuthScope[] | null;
+/** Serializes scopes back to the space-delimited wire/storage format. */
+export declare function formatScopes(scopes: readonly OAuthScope[]): string;
+/** True when every scope in `requested` is present in `granted`. */
+export declare function isScopeSubset(requested: readonly OAuthScope[], granted: readonly OAuthScope[]): boolean;
+//# sourceMappingURL=scopes.d.ts.map

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

@@ -0,0 +1 @@
+{"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/oauth/scopes.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * OAuth scope vocabulary. Scopes map 1:1 onto the MCP tools exposed today; no
+ * speculative scopes are defined.
+ *
+ * - `schema:read`  -> beech_list_seeds, beech_get_seed, beech_schema_export,
+ *                     beech_schema_validate, beech_schema_plan
+ * - `schema:write` -> beech_schema_apply
+ *
+ * `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 const OAUTH_SCOPES = ['schema:read', 'schema:write'];
+/** Narrows an arbitrary string to a known scope. */
+export function isOAuthScope(value) {
+    return OAUTH_SCOPES.includes(value);
+}
+/**
+ * Parses an RFC 6749 §3.3 space-delimited scope string.
+ * Returns null if the string is empty or contains any unknown scope — callers
+ * must reject the request with `invalid_scope` rather than silently dropping it.
+ * Duplicates are collapsed; order is not significant.
+ */
+export function parseScopeString(raw) {
+    const parts = raw.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return null;
+    const unique = [...new Set(parts)];
+    if (!unique.every(isOAuthScope))
+        return null;
+    return unique;
+}
+/** Serializes scopes back to the space-delimited wire/storage format. */
+export function formatScopes(scopes) {
+    return [...new Set(scopes)].join(' ');
+}
+/** True when every scope in `requested` is present in `granted`. */
+export function isScopeSubset(requested, granted) {
+    return requested.every(scope => granted.includes(scope));
+}

package/dist/oauth/token.repository.d.ts

@@ -0,0 +1,46 @@
+import type { OAuthScope } from './scopes.js';
+export type OAuthTokenType = 'access' | 'refresh';
+export interface NewOAuthToken {
+    id: string;
+    /** SHA-256 hex hash of the token. The plaintext token is never persisted. */
+    tokenHash: string;
+    tokenType: OAuthTokenType;
+    clientId: string;
+    userId: string;
+    scope: OAuthScope[];
+    /** Hash of the authorization code this token descends from, for cascade revocation. */
+    authorizationCodeHash: string;
+    expiresAt: number;
+}
+export interface OAuthTokenRecord extends NewOAuthToken {
+    createdAt: number;
+    revokedAt: number | null;
+}
+export interface AuthorizedClientSummary {
+    clientId: string;
+    clientName: string;
+    scope: OAuthScope[];
+    /** Creation timestamp of the most recent live token for this client. */
+    lastIssuedAt: number;
+}
+export interface IOAuthTokenRepository {
+    save(record: NewOAuthToken): Promise<void>;
+    /** Finds an unexpired, unrevoked token by hash and type. */
+    findActiveByHash(tokenHash: string, tokenType: OAuthTokenType, nowTimestamp: number): Promise<OAuthTokenRecord | null>;
+    /** Revokes a single token. False when already revoked or absent. */
+    revokeByHash(tokenHash: string, nowTimestamp: number): Promise<boolean>;
+    /**
+     * Revokes EVERY token descending from one authorization code, both access and
+     * refresh. Called on authorization-code replay (OAuth 2.1 §4.1.3).
+     * Returns the number of tokens revoked.
+     */
+    revokeByAuthorizationCode(authorizationCodeHash: string, nowTimestamp: number): Promise<number>;
+    /**
+     * Revokes every live token for one (client, user) pair — access AND refresh,
+     * never one without the other. Backs "revoke this app" in the dashboard.
+     */
+    revokeAllForClientAndUser(clientId: string, userId: string, nowTimestamp: number): Promise<number>;
+    /** Lists the clients holding at least one live token for this user, newest first. */
+    listAuthorizedClientsForUser(userId: string, nowTimestamp: number): Promise<AuthorizedClientSummary[]>;
+}
+//# sourceMappingURL=token.repository.d.ts.map

package/dist/oauth/token.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/token.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEjD,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,cAAc,CAAA;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,uFAAuF;IACvF,qBAAqB,EAAE,MAAM,CAAA;IAC7B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1C,4DAA4D;IAC5D,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,cAAc,EACzB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAEnC,oEAAoE;IACpE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE;;;;OAIG;IACH,yBAAyB,CAAC,qBAAqB,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE/F;;;OAGG;IACH,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAElG,qFAAqF;IACrF,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAA;CACvG"}

package/dist/oauth/token.repository.js

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

package/dist/observability/activity-logger.d.ts

@@ -9,7 +9,7 @@
  *
  * @module @beechcms/core/observability/activity-logger
  */
-export type ActivityAction = 'create' | 'update' | 'delete' | 'upload' | 'bulk_update';
+export type ActivityAction = 'create' | 'update' | 'delete' | 'upload' | 'bulk_update' | 'security_alert';
 export type EntityType = 'content' | 'media' | 'seed';
 /**
  * Identifies the human (or machine) actor that triggered the event.

package/dist/observability/activity-logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-logger.d.ts","sourceRoot":"","sources":["../../src/observability/activity-logger.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,CAAA;AACtF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,KAAK,EAAE,aAAa,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,GAAG,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACnD"}
+{"version":3,"file":"activity-logger.d.ts","sourceRoot":"","sources":["../../src/observability/activity-logger.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,aAAa,GAAG,gBAAgB,CAAA;AACzG,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAErD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,KAAK,EAAE,aAAa,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;OASG;IACH,GAAG,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CACnD"}

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/rate-limiter.d.ts

@@ -1,18 +1,26 @@
 export interface RateLimitResult {
     isAllowed: boolean;
     /**
-     * The number of seconds after which the client may retry the request.
-     * Note: This field is optional and may not be supported by all implementations
-     * (e.g. Cloudflare Rate Limit binding does not return retry-after information).
+     * The number of whole seconds after which the client may retry the request.
      */
     retryAfterSeconds?: number;
+    /**
+     * The maximum token capacity configured for this limiter.
+     */
+    limit?: number;
+    /**
+     * The number of whole tokens remaining in the bucket.
+     */
+    remaining?: number;
 }
 export interface IRateLimiter {
     /**
      * Checks whether the given key is within the rate limit.
-     * The key should combine the client IP address and an endpoint-specific prefix
-     * to prevent one endpoint's limit from being shared with another.
      */
     checkLimit(key: string): Promise<RateLimitResult>;
+    /**
+     * Clears cached bucket state (for testing and isolation).
+     */
+    reset?(): void;
 }
 //# sourceMappingURL=rate-limiter.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/rate-limiter.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAClD"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/rate-limiter.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,OAAO,CAAA;IAClB;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IACjD;;OAEG;IACH,KAAK,CAAC,IAAI,IAAI,CAAA;CACf"}

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

@@ -0,0 +1,20 @@
+import type { IRateLimiter, RateLimitResult } from './rate-limiter.js';
+import type { IClock } from '../common/clock.js';
+export interface TokenBucketOptions {
+    capacity?: number;
+    refillRatePerSecond?: number;
+    clock?: IClock;
+    maxIdleTimeSeconds?: number;
+}
+export declare class TokenBucketRateLimiter implements IRateLimiter {
+    private readonly buckets;
+    private readonly capacity;
+    private readonly refillRatePerSecond;
+    private readonly clock;
+    private readonly maxIdleTimeSeconds;
+    constructor(options?: TokenBucketOptions);
+    private pruneExpiredBuckets;
+    checkLimit(key: string): Promise<RateLimitResult>;
+    reset(): void;
+}
+//# sourceMappingURL=token-bucket-rate-limiter.d.ts.map

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

@@ -0,0 +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;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/rate-limit/token-bucket-rate-limiter.js

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { SystemClock } from '../common/clock.js';
+export class TokenBucketRateLimiter {
+    buckets = new Map();
+    capacity;
+    refillRatePerSecond;
+    clock;
+    maxIdleTimeSeconds;
+    constructor(options) {
+        this.capacity = options?.capacity ?? 17;
+        // Default: 1 token every 3.53 seconds (~0.283286 tokens/sec)
+        this.refillRatePerSecond = options?.refillRatePerSecond ?? (1 / 3.53);
+        this.clock = options?.clock ?? SystemClock;
+        this.maxIdleTimeSeconds = options?.maxIdleTimeSeconds ?? 3600; // 1 hour idle TTL
+    }
+    pruneExpiredBuckets(now) {
+        if (this.buckets.size < 500)
+            return;
+        for (const [key, state] of this.buckets.entries()) {
+            if (now - state.lastRefillTimestamp > this.maxIdleTimeSeconds) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+    async checkLimit(key) {
+        const now = this.clock.now() / 1000; // fractional seconds for continuous refill
+        this.pruneExpiredBuckets(now);
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = {
+                tokens: this.capacity,
+                lastRefillTimestamp: now,
+            };
+        }
+        else {
+            const elapsed = Math.max(0, now - bucket.lastRefillTimestamp);
+            bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsed * this.refillRatePerSecond);
+            bucket.lastRefillTimestamp = now;
+        }
+        if (bucket.tokens >= 1) {
+            bucket.tokens -= 1;
+            this.buckets.set(key, bucket);
+            return {
+                isAllowed: true,
+                limit: this.capacity,
+                remaining: Math.floor(bucket.tokens),
+            };
+        }
+        this.buckets.set(key, bucket);
+        const tokensNeeded = 1 - bucket.tokens;
+        const retryAfterSeconds = Math.max(1, Math.ceil(tokensNeeded / this.refillRatePerSecond));
+        return {
+            isAllowed: false,
+            retryAfterSeconds,
+            limit: this.capacity,
+            remaining: Math.max(0, Math.floor(bucket.tokens)),
+        };
+    }
+    reset() {
+        this.buckets.clear();
+    }
+}

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