@beechcms/core 0.7.0 → 0.8.0

package/dist/media/magic-bytes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Result of a file magic bytes signature validation.
+ */
+export interface MagicBytesValidationResult {
+    /** Whether the byte buffer matches the declared format signature. */
+    valid: boolean;
+    /** Detected canonical primary MIME type if valid or identified. */
+    detectedMime?: string;
+    /** Human-readable error description when validation fails. */
+    error?: string;
+}
+/**
+ * Validates that an uploaded file's binary content matches its declared MIME type,
+ * protecting against MIME-spoofing, disguised executables, and blocked formats (e.g. SVG).
+ *
+ * @param buffer - The raw binary buffer (ArrayBuffer or Uint8Array).
+ * @param declaredMime - The client-declared MIME type string.
+ * @returns A MagicBytesValidationResult indicating validity and details.
+ */
+export declare function verifyMagicBytes(buffer: ArrayBuffer | Uint8Array, declaredMime: string): MagicBytesValidationResult;
+//# sourceMappingURL=magic-bytes.d.ts.map

package/dist/media/magic-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"magic-bytes.d.ts","sourceRoot":"","sources":["../../src/media/magic-bytes.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,qEAAqE;IACrE,KAAK,EAAE,OAAO,CAAA;IACd,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAiBD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,GAAG,UAAU,EAChC,YAAY,EAAE,MAAM,GACnB,0BAA0B,CAgD5B"}

package/dist/media/magic-bytes.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { SUPPORTED_FILE_TYPES, getFileTypeByMime, BLOCKED_IMAGE_MIME_TYPES, matchesFileSignature, } from './file-types.js';
+/**
+ * Iterates across supported binary definitions to find any matching file signature.
+ *
+ * @param bytes - The raw byte buffer to analyze.
+ * @returns The matching FileTypeDefinition if recognized, or undefined.
+ */
+function detectBinaryType(bytes) {
+    for (const def of Object.values(SUPPORTED_FILE_TYPES)) {
+        if (def.isBinary && matchesFileSignature(def, bytes)) {
+            return def;
+        }
+    }
+    return undefined;
+}
+/**
+ * Validates that an uploaded file's binary content matches its declared MIME type,
+ * protecting against MIME-spoofing, disguised executables, and blocked formats (e.g. SVG).
+ *
+ * @param buffer - The raw binary buffer (ArrayBuffer or Uint8Array).
+ * @param declaredMime - The client-declared MIME type string.
+ * @returns A MagicBytesValidationResult indicating validity and details.
+ */
+export function verifyMagicBytes(buffer, declaredMime) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    if (bytes.length < 2) {
+        return { valid: false, error: 'File buffer too small for signature inspection' };
+    }
+    const normalizedDeclared = declaredMime.split(';')[0].trim().toLowerCase();
+    // Unconditionally reject blocked MIME types (e.g. SVG)
+    if (BLOCKED_IMAGE_MIME_TYPES.includes(normalizedDeclared)) {
+        return {
+            valid: false,
+            error: `File type '${declaredMime}' is blocked for security reasons`,
+        };
+    }
+    const declaredDef = getFileTypeByMime(normalizedDeclared);
+    if (!declaredDef) {
+        return { valid: false, error: `Unrecognized file signature for declared MIME ${declaredMime}` };
+    }
+    // Non-binary types (e.g. text/plain, text/csv, text/markdown, application/json)
+    if (!declaredDef.isBinary) {
+        return { valid: true, detectedMime: declaredDef.primaryMime };
+    }
+    // If buffer is smaller than the minimum bytes needed for initial signature inspection (typically 4, or 2-3 for short signatures)
+    const minInspectionLength = Math.min(4, declaredDef.magicBytes?.length ?? 4);
+    if (bytes.length < minInspectionLength) {
+        return { valid: false, error: 'File buffer too small for signature inspection' };
+    }
+    // Binary types: verify signature against declared definition
+    if (matchesFileSignature(declaredDef, bytes)) {
+        return { valid: true, detectedMime: declaredDef.primaryMime };
+    }
+    // Signature mismatch: check if it matches another known binary signature
+    const detectedDef = detectBinaryType(bytes);
+    if (detectedDef) {
+        return {
+            valid: false,
+            detectedMime: detectedDef.primaryMime,
+            error: `Signature mismatch: file is ${detectedDef.extension.toUpperCase()} but declared as ${declaredMime}`,
+        };
+    }
+    return { valid: false, error: `Unrecognized file signature for declared MIME ${declaredMime}` };
+}

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

@@ -0,0 +1,33 @@
+import type { OAuthScope } from './scopes.js';
+export interface NewAuthorizationCode {
+    /** SHA-256 hex hash of the code. The plaintext code is never persisted. */
+    codeHash: string;
+    clientId: string;
+    userId: string;
+    scope: OAuthScope[];
+    redirectUri: string;
+    codeChallenge: string;
+    /** Always 'S256'; the column CHECK constraint rejects anything else. */
+    codeChallengeMethod: 'S256';
+    expiresAt: number;
+}
+export interface AuthorizationCodeRecord extends NewAuthorizationCode {
+    createdAt: number;
+    consumedAt: number | null;
+}
+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.
+     */
+    findByHash(codeHash: string, nowTimestamp: number): 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.
+     */
+    consumeByHash(codeHash: string, nowTimestamp: number): Promise<boolean>;
+}
+//# sourceMappingURL=authorization-code.repository.d.ts.map

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

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

package/dist/oauth/authorization-code.repository.js

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

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

@@ -0,0 +1,17 @@
+import type { OAuthScope } from './scopes.js';
+export interface OAuthClientRecord {
+    clientId: string;
+    name: string;
+    /** Registered redirect URIs. Loopback entries are matched ignoring the port. */
+    redirectUris: string[];
+    allowedScopes: OAuthScope[];
+    /** True for clients that cannot hold a secret (native/CLI). PKCE is required regardless. */
+    isPublic: boolean;
+    createdAt: number;
+    disabledAt: number | null;
+}
+export interface IOAuthClientRepository {
+    /** Returns the client, or null when unknown or disabled. */
+    findActiveById(clientId: string): Promise<OAuthClientRecord | null>;
+}
+//# sourceMappingURL=client.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/client.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,aAAa,EAAE,UAAU,EAAE,CAAA;IAC3B,4FAA4F;IAC5F,QAAQ,EAAE,OAAO,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAA;CACpE"}

package/dist/oauth/client.repository.js

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

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

@@ -0,0 +1,25 @@
+import type { OAuthScope } from './scopes.js';
+export interface ConsentRecord {
+    id: string;
+    clientId: string;
+    userId: string;
+    /** Cumulative set of scopes the user has approved for this client. */
+    scopes: OAuthScope[];
+    createdAt: number;
+    updatedAt: number;
+    revokedAt: number | null;
+}
+export interface IOAuthConsentRepository {
+    /** Returns the live consent for the pair, or null when absent or revoked. */
+    findActive(clientId: string, userId: string): Promise<ConsentRecord | null>;
+    /**
+     * Records consent for the pair, unioning `scopes` into any existing live grant
+     * and reviving a previously revoked row. Idempotent for an unchanged scope set.
+     */
+    grant(id: string, clientId: string, userId: string, scopes: readonly OAuthScope[], nowTimestamp: number): Promise<void>;
+    /** Revokes the consent. False when there was nothing live to revoke. */
+    revoke(clientId: string, userId: string, nowTimestamp: number): Promise<boolean>;
+    /** Lists all live consents for a user, newest first. */
+    listForUser(userId: string): Promise<ConsentRecord[]>;
+}
+//# sourceMappingURL=consent.repository.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"consent.repository.d.ts","sourceRoot":"","sources":["../../src/oauth/consent.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,sEAAsE;IACtE,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,uBAAuB;IACtC,6EAA6E;IAC7E,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IAE3E;;;OAGG;IACH,KAAK,CACH,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhB,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEhF,wDAAwD;IACxD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAAA;CACtD"}

package/dist/oauth/consent.repository.js

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

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PKCE (RFC 7636) verification. `S256` only — `plain` is rejected unconditionally,
+ * 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 type PkceChallengeMethod = typeof PKCE_CHALLENGE_METHOD;
+/** Minimum / maximum code_verifier length, RFC 7636 §4.1. */
+export declare const PKCE_VERIFIER_MIN_LENGTH = 43;
+export declare const PKCE_VERIFIER_MAX_LENGTH = 128;
+/** Validates the code_verifier character set and length. */
+export declare function isValidCodeVerifier(verifier: string): boolean;
+/** Computes BASE64URL(SHA256(ASCII(verifier))). */
+export declare function deriveCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Verifies a code_verifier against a stored code_challenge.
+ * Returns false — never throws — on any malformed input, unsupported method, or
+ * mismatch, so callers cannot distinguish failure modes from the return value.
+ */
+export declare function verifyPkceChallenge(verifier: string, challenge: string, method: string): Promise<boolean>;
+//# sourceMappingURL=pkce.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,+CAA+C;AAC/C,eAAO,MAAM,qBAAqB,EAAG,MAAe,CAAA;AAEpD,MAAM,MAAM,mBAAmB,GAAG,OAAO,qBAAqB,CAAA;AAE9D,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAC1C,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAI3C,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAM7D;AAQD,mDAAmD;AACnD,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAG3E;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC,CAUlB"}

package/dist/oauth/pkce.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * PKCE (RFC 7636) verification. `S256` only — `plain` is rejected unconditionally,
+ * per OAuth 2.1, so no weak fallback configuration can ever exist.
+ */
+/** The only accepted code challenge method. */
+export const PKCE_CHALLENGE_METHOD = 'S256';
+/** Minimum / maximum code_verifier length, RFC 7636 §4.1. */
+export const PKCE_VERIFIER_MIN_LENGTH = 43;
+export const PKCE_VERIFIER_MAX_LENGTH = 128;
+const VERIFIER_PATTERN = /^[A-Za-z0-9\-._~]+$/;
+/** Validates the code_verifier character set and length. */
+export function isValidCodeVerifier(verifier) {
+    return (verifier.length >= PKCE_VERIFIER_MIN_LENGTH &&
+        verifier.length <= PKCE_VERIFIER_MAX_LENGTH &&
+        VERIFIER_PATTERN.test(verifier));
+}
+/** Base64url-encodes bytes without padding, per RFC 7636 §A. */
+function base64UrlEncode(bytes) {
+    const binary = String.fromCharCode(...new Uint8Array(bytes));
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/** Computes BASE64URL(SHA256(ASCII(verifier))). */
+export async function deriveCodeChallenge(verifier) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64UrlEncode(digest);
+}
+/**
+ * Verifies a code_verifier against a stored code_challenge.
+ * Returns false — never throws — on any malformed input, unsupported method, or
+ * mismatch, so callers cannot distinguish failure modes from the return value.
+ */
+export async function verifyPkceChallenge(verifier, challenge, method) {
+    if (method !== PKCE_CHALLENGE_METHOD)
+        return false;
+    if (!isValidCodeVerifier(verifier))
+        return false;
+    const derived = await deriveCodeChallenge(verifier);
+    if (derived.length !== challenge.length)
+        return false;
+    let mismatch = 0;
+    for (let index = 0; index < derived.length; index += 1) {
+        mismatch |= derived.charCodeAt(index) ^ challenge.charCodeAt(index);
+    }
+    return mismatch === 0;
+}

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;CAG/B"}

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

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

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/search/vector-extractor.d.ts

@@ -0,0 +1,11 @@
+import type { Seed } from '../engine/types.js';
+/**
+ * Extracts and concatenates text from all public indexable text/richtext branches of a seed.
+ * Enforces privacy policies by utilizing indexableSearchBranches.
+ *
+ * @param seed The seed definition.
+ * @param entry The content entry record.
+ * @returns The combined text, or null if no indexable text exists.
+ */
+export declare function extractIndexableText(seed: Seed, entry: Record<string, any>): string | null;
+//# sourceMappingURL=vector-extractor.d.ts.map

package/dist/search/vector-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-extractor.d.ts","sourceRoot":"","sources":["../../src/search/vector-extractor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AAG9C;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,GAAG,IAAI,CAc1F"}