@beechcms/core 0.8.0 → 0.9.0

package/dist/notifications/notification.repository.d.ts

@@ -16,6 +16,14 @@ export interface NotificationRecord {
     isRead: boolean;
     createdAt: number;
 }
+/** Input of {@link INotificationRepository.create}. */
+export type CreateNotificationRecord = Omit<NotificationRecord, 'id' | 'createdAt' | 'isRead'> & {
+    /**
+     * Stable identifier of the upstream event (e.g. a QStash message id). Creating twice with the
+     * same key stores one notification, so at-least-once delivery cannot inflate the inbox.
+     */
+    dedupeKey?: string;
+};
 export interface NotificationStats {
     totalCount: number;
     latestCreatedAt: number;
@@ -40,9 +48,10 @@ export interface INotificationRepository {
     /**
      * Insert a new notification and return its generated id so callers (e.g.
      * the public form submission flow) can correlate the notification with the
-     * triggering request.
+     * triggering request. With `dedupeKey`, a repeated key stores nothing and returns the id of the
+     * notification the first call created.
      */
-    create(record: Omit<NotificationRecord, 'id' | 'createdAt' | 'isRead'>): Promise<string>;
+    create(record: CreateNotificationRecord): Promise<string>;
     markRead(notificationId: string): Promise<void>;
     markUnread(notificationId: string): Promise<void>;
     markAllRead(): Promise<void>;

package/dist/notifications/notification.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notification.repository.d.ts","sourceRoot":"","sources":["../../src/notifications/notification.repository.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,gBAAgB,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAElD;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAEnC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,kBAAkB,EAAE,IAAI,GAAG,WAAW,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAExF,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C"}
+{"version":3,"file":"notification.repository.d.ts","sourceRoot":"","sources":["../../src/notifications/notification.repository.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAA;AAEvE,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,gBAAgB,CAAA;IACtB,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,uDAAuD;AACvD,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,kBAAkB,EAAE,IAAI,GAAG,WAAW,GAAG,QAAQ,CAAC,GAAG;IAC/F;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAElD;;;;;;OAMG;IACH,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAEnC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzD,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9C"}

package/dist/oauth/authorization-code.repository.d.ts

@@ -19,15 +19,20 @@ export interface IOAuthAuthorizationCodeRepository {
     /** Persists a new single-use authorization code. Hash only, never plaintext. */
     save(record: NewAuthorizationCode): Promise<void>;
     /**
-     * Returns the code regardless of its consumed state, provided it is unexpired.
-     * Callers MUST inspect `consumedAt`: a non-null value means replay, which
-     * requires cascade revocation via IOAuthTokenRepository.revokeByAuthorizationCode.
+     * Returns the code regardless of its consumed OR expired state — replay must be
+     * detectable even after the 60s TTL, since tokens derived from the code outlive it
+     * by 30 days. Callers MUST inspect `consumedAt` (replay signal, requires cascade
+     * revocation via IOAuthTokenRepository.revokeByAuthorizationCode) and `expiresAt`
+     * separately (an unconsumed-but-expired code is simply invalid, nothing to revoke).
      */
-    findByHash(codeHash: string, nowTimestamp: number): Promise<AuthorizationCodeRecord | null>;
+    findByHash(codeHash: string): Promise<AuthorizationCodeRecord | null>;
     /**
      * Atomically marks the code consumed. Returns true only for the first caller;
-     * every subsequent call returns false, which is the replay signal.
+     * every subsequent call returns false, which is the replay signal. Expiry is
+     * enforced here — redemption, unlike replay detection, must respect the TTL.
      */
     consumeByHash(codeHash: string, nowTimestamp: number): Promise<boolean>;
+    /** Invalidates every unconsumed code issued to a (client, user) pair, e.g. on consent revoke. */
+    invalidateByClientAndUser(clientId: string, userId: string): Promise<number>;
 }
 //# sourceMappingURL=authorization-code.repository.d.ts.map

package/dist/oauth/authorization-code.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization-code.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/authorization-code.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;IAE3F;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACxE"}
+{"version":3,"file":"authorization-code.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/authorization-code.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,oBAAoB;IACnC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,UAAU,EAAE,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,CAAA;IAC3B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,uBAAwB,SAAQ,oBAAoB;IACnE,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,gFAAgF;IAChF,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEjD;;;;;;OAMG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAA;IAErE;;;;OAIG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEvE,iGAAiG;IACjG,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC7E"}

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

@@ -1,32 +1,51 @@
 import type { OAuthScope } from './scopes.js';
+import type { EffectivePermissions } from '../rbac/types.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.
+ * Arbitrates which of the requested scopes a given caller 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.
+ * `/oauth/authorize` and `/oauth/token` must never branch on authority themselves.
+ *
+ * The parameter is the caller's RESOLVED authority, not a role string: the role
+ * string is the pre-RBAC vocabulary and is on its way out.
  */
 export interface IRoleGuard {
     /**
-     * @param role - The resource owner's role claim, or undefined when absent.
+     * @param effective - The resource owner's effective permissions, already folded.
      * @param requestedScopes - Scopes the client asked for, already validated.
      */
-    arbitrate(role: string | undefined, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
+    arbitrate(effective: EffectivePermissions, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
 }
 /**
- * Stub guard for the pre-roles world: grants every requested scope to every role.
+ * Stub guard: grants every requested scope to every caller.
  *
- * 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.
+ * Retained as the explicit, directly-tested permissive baseline and as the test
+ * double for suites that are not exercising arbitration. It is NO LONGER the
+ * production binding — `repositoryMiddleware` binds {@link PermissionRoleGuard}.
  */
 export declare class AllowAllRoleGuard implements IRoleGuard {
-    arbitrate(_role: string | undefined, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
+    arbitrate(_effective: EffectivePermissions, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
+}
+/**
+ * Production guard: only a platform-wide administrator may delegate authority to an
+ * OAuth/MCP client.
+ *
+ * Every OAuth scope in this system (`schema:read`, `schema:write`) drives seed-schema
+ * tooling, which brief §2 keeps OUT of the dashboard permission axis entirely — there is
+ * deliberately no `manage_seeds` permission to map onto. So the question this guard
+ * answers is not "which seed?" but "may this account hand platform authority to a
+ * client at all?", and the marker for that is holding `manage_users` at
+ * {@link GLOBAL_SCOPE} — the same SuperAdmin marker the last-global-admin guard uses.
+ *
+ * A seed-scoped collaborator therefore cannot mint an MCP token, no matter which
+ * scopes the client requests. Denial is all-or-nothing: there is no partial grant.
+ */
+export declare class PermissionRoleGuard implements IRoleGuard {
+    arbitrate(effective: EffectivePermissions, requestedScopes: readonly OAuthScope[]): Promise<ScopeGrantDecision>;
 }
 //# sourceMappingURL=role-guard.d.ts.map

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,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAE5D,iFAAiF;AACjF,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,YAAY,EAAE,UAAU,EAAE,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,SAAS,CACP,SAAS,EAAE,oBAAoB,EAC/B,eAAe,EAAE,SAAS,UAAU,EAAE,GACrC,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC/B;AAED;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAC5C,SAAS,CACb,UAAU,EAAE,oBAAoB,EAChC,eAAe,EAAE,SAAS,UAAU,EAAE,GACrC,OAAO,CAAC,kBAAkB,CAAC;CAG/B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,mBAAoB,YAAW,UAAU;IAC9C,SAAS,CACb,SAAS,EAAE,oBAAoB,EAC/B,eAAe,EAAE,SAAS,UAAU,EAAE,GACrC,OAAO,CAAC,kBAAkB,CAAC;CAM/B"}

package/dist/oauth/role-guard.js

@@ -1,14 +1,36 @@
 // 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.
+ * Stub guard: grants every requested scope to every caller.
  *
- * 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.
+ * Retained as the explicit, directly-tested permissive baseline and as the test
+ * double for suites that are not exercising arbitration. It is NO LONGER the
+ * production binding — `repositoryMiddleware` binds {@link PermissionRoleGuard}.
  */
 export class AllowAllRoleGuard {
-    async arbitrate(_role, requestedScopes) {
+    async arbitrate(_effective, requestedScopes) {
+        return { grantedScopes: [...requestedScopes], deniedScopes: [] };
+    }
+}
+/**
+ * Production guard: only a platform-wide administrator may delegate authority to an
+ * OAuth/MCP client.
+ *
+ * Every OAuth scope in this system (`schema:read`, `schema:write`) drives seed-schema
+ * tooling, which brief §2 keeps OUT of the dashboard permission axis entirely — there is
+ * deliberately no `manage_seeds` permission to map onto. So the question this guard
+ * answers is not "which seed?" but "may this account hand platform authority to a
+ * client at all?", and the marker for that is holding `manage_users` at
+ * {@link GLOBAL_SCOPE} — the same SuperAdmin marker the last-global-admin guard uses.
+ *
+ * A seed-scoped collaborator therefore cannot mint an MCP token, no matter which
+ * scopes the client requests. Denial is all-or-nothing: there is no partial grant.
+ */
+export class PermissionRoleGuard {
+    async arbitrate(effective, requestedScopes) {
+        if (!effective.global.has('manage_users')) {
+            return { grantedScopes: [], deniedScopes: [...requestedScopes] };
+        }
         return { grantedScopes: [...requestedScopes], deniedScopes: [] };
     }
 }

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

@@ -27,6 +27,8 @@ 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>;
+    /** Finds a token by hash and type in any state (expired or revoked included). */
+    findByHash(tokenHash: string, tokenType: OAuthTokenType): Promise<OAuthTokenRecord | null>;
     /** Revokes a single token. False when already revoked or absent. */
     revokeByHash(tokenHash: string, nowTimestamp: number): Promise<boolean>;
     /**

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

@@ -1 +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"}
+{"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,iFAAiF;IACjF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAE1F,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/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.interface.d.ts

@@ -12,7 +12,8 @@ export interface QueueMessage<T = unknown> {
 }
 /**
  * Execution context handed to every job. Botanical Invariant: jobs receive the
- * engine-mediated repository, NEVER a raw D1Database. `env` is a read-only,
+ * engine-mediated repository, NEVER a raw D1Database, and the engine-mediated
+ * queue port, NEVER a raw transport binding. `env` is a read-only,
  * stringly-typed view of bindings/secrets for things like fetch targets — it
  * deliberately does not expose `DB`.
  */
@@ -21,6 +22,13 @@ export interface JobContext {
     bucket: BeechBucket;
     clock: IClock;
     idGenerator: IIdGenerator;
+    /**
+     * Producer port, so a job can schedule its own successor. Required for cursor-style
+     * jobs that process a bounded slice per invocation, persist their offset and re-enqueue
+     * (bulk import): without it a handler would have to reach into `env` for the raw QUEUE
+     * binding, which is exactly the transport coupling `repository` exists to prevent for D1.
+     */
+    queue: IQueueService;
     env: Record<string, string | undefined>;
 }
 /** A single background worker. Receives the decoded payload + context. */

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

@@ -1 +1 @@
-{"version":3,"file":"queue.interface.d.ts","sourceRoot":"","sources":["../../src/queue/queue.interface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;;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;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvD"}
+{"version":3,"file":"queue.interface.d.ts","sourceRoot":"","sources":["../../src/queue/queue.interface.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAE7D;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,CAAC,CAAA;CACX;AAED;;;;;;GAMG;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;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAA;IACpB,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;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvD"}

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

@@ -1,5 +1,5 @@
 import type { IQueueService } from './queue.interface.js';
-/** Safe no-op producer (e.g. unit tests that don't assert on enqueue). */
+/** Drops messages without a transport. */
 export declare class NoOpQueueService implements IQueueService {
     enqueue<T>(_name: string, _payload: T): Promise<boolean>;
 }

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,0CAA0C;AAC1C,qBAAa,gBAAiB,YAAW,aAAa;IAC9C,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC;CAG/D"}

package/dist/queue/queue.stub.js

@@ -1,9 +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). */
+/** Drops messages without a transport. */
 export class NoOpQueueService {
     async enqueue(_name, _payload) {
-        // intentionally empty; reports success since there is nothing to fail
-        return true;
+        return false;
     }
 }

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

@@ -5,6 +5,8 @@ export interface TokenBucketOptions {
     refillRatePerSecond?: number;
     clock?: IClock;
     maxIdleTimeSeconds?: number;
+    maxBuckets?: number;
+    pruneIntervalSeconds?: number;
 }
 export declare class TokenBucketRateLimiter implements IRateLimiter {
     private readonly buckets;
@@ -12,8 +14,13 @@ export declare class TokenBucketRateLimiter implements IRateLimiter {
     private readonly refillRatePerSecond;
     private readonly clock;
     private readonly maxIdleTimeSeconds;
+    private readonly maxBuckets;
+    private readonly pruneIntervalSeconds;
+    private lastPruneTimestamp;
     constructor(options?: TokenBucketOptions);
+    private static readonly MAX_EVICTION_SCAN;
     private pruneExpiredBuckets;
+    private evictRefilledBucket;
     checkLimit(key: string): Promise<RateLimitResult>;
     reset(): void;
 }

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;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;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;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAQ;IAC7C,OAAO,CAAC,kBAAkB,CAAI;gBAElB,OAAO,CAAC,EAAE,kBAAkB;IAcxC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAK;IAE9C,OAAO,CAAC,mBAAmB;IA4B3B,OAAO,CAAC,mBAAmB;IAsBrB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAqDvD,KAAK,IAAI,IAAI;CAId"}

package/dist/rate-limit/token-bucket-rate-limiter.js

@@ -7,27 +7,90 @@ export class TokenBucketRateLimiter {
     refillRatePerSecond;
     clock;
     maxIdleTimeSeconds;
+    maxBuckets;
+    pruneIntervalSeconds;
+    lastPruneTimestamp = 0;
     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
+        this.maxBuckets = options?.maxBuckets ?? 5000; // Prevent unbounded memory growth
+        this.pruneIntervalSeconds = options?.pruneIntervalSeconds ?? 60; // Throttle O(n) scans
     }
+    // Bound the eviction scan so a flood of unique keys (each forcing an eviction attempt)
+    // cannot turn checkLimit into an O(maxBuckets) operation per request. Only the oldest
+    // slice of the map is examined; if nothing there qualifies, admission of the new key is
+    // denied instead of evicting something it shouldn't (see below).
+    static MAX_EVICTION_SCAN = 32;
     pruneExpiredBuckets(now) {
         if (this.buckets.size < 500)
             return;
+        if (now - this.lastPruneTimestamp < this.pruneIntervalSeconds)
+            return;
+        this.lastPruneTimestamp = now;
         for (const [key, state] of this.buckets.entries()) {
             if (now - state.lastRefillTimestamp > this.maxIdleTimeSeconds) {
                 this.buckets.delete(key);
             }
+            else {
+                // Since Map preserves insertion order and checkLimit re-inserts on every access,
+                // entries are monotonically ordered by lastRefillTimestamp. The first non-expired
+                // entry guarantees all subsequent entries are also active, allowing an immediate O(1) exit.
+                break;
+            }
         }
     }
+    // Evicts the oldest bucket ONLY if it has refilled to full capacity, in which case it is
+    // behaviourally equivalent to an absent bucket and dropping it loses no state. A bucket
+    // that hasn't refilled — including one sitting at 0 tokens and actively blocking its key —
+    // is never evicted: doing so would let an attacker flood distinct keys to silently reset a
+    // victim's exhausted bucket and bypass its limit (#458).
+    //
+    // When nothing in the scanned slice is eligible, the caller must not admit a new bucket
+    // anyway (#634) — that would make the map grow without bound under a distinct-key flood.
+    // Instead, report how long until the earliest-refilling scanned bucket would become a
+    // legitimate eviction candidate, so the caller can deny admission with a meaningful
+    // retryAfterSeconds rather than guessing.
+    evictRefilledBucket(now) {
+        let scanned = 0;
+        let minSecondsUntilRefilled = this.maxIdleTimeSeconds;
+        for (const [key, state] of this.buckets.entries()) {
+            if (scanned >= TokenBucketRateLimiter.MAX_EVICTION_SCAN)
+                break;
+            scanned++;
+            const elapsed = Math.max(0, now - state.lastRefillTimestamp);
+            const refilled = Math.min(this.capacity, state.tokens + elapsed * this.refillRatePerSecond);
+            if (refilled >= this.capacity) {
+                this.buckets.delete(key);
+                return { evicted: true, retryAfterSeconds: 0 };
+            }
+            if (this.refillRatePerSecond > 0) {
+                const secondsUntilRefilled = (this.capacity - refilled) / this.refillRatePerSecond;
+                minSecondsUntilRefilled = Math.min(minSecondsUntilRefilled, secondsUntilRefilled);
+            }
+        }
+        return { evicted: false, retryAfterSeconds: Math.max(1, Math.ceil(minSecondsUntilRefilled)) };
+    }
     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) {
+            if (this.buckets.size >= this.maxBuckets) {
+                const { evicted, retryAfterSeconds } = this.evictRefilledBucket(now);
+                if (!evicted) {
+                    // No safe eviction candidate: admitting a bucket for this never-seen key would
+                    // grow the map past maxBuckets. Deny it instead of allocating state (#634).
+                    return {
+                        isAllowed: false,
+                        retryAfterSeconds,
+                        limit: this.capacity,
+                        remaining: 0,
+                    };
+                }
+            }
             bucket = {
                 tokens: this.capacity,
                 lastRefillTimestamp: now,
@@ -37,6 +100,8 @@ export class TokenBucketRateLimiter {
             const elapsed = Math.max(0, now - bucket.lastRefillTimestamp);
             bucket.tokens = Math.min(this.capacity, bucket.tokens + elapsed * this.refillRatePerSecond);
             bucket.lastRefillTimestamp = now;
+            // Re-insert to maintain LRU access order
+            this.buckets.delete(key);
         }
         if (bucket.tokens >= 1) {
             bucket.tokens -= 1;
@@ -59,5 +124,6 @@ export class TokenBucketRateLimiter {
     }
     reset() {
         this.buckets.clear();
+        this.lastPruneTimestamp = 0;
     }
 }

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"}