@beechcms/api 0.7.0 → 0.8.0

package/dist/shared/storage/s3-bucket.d.ts

@@ -1,33 +1,127 @@
 import { BeechBucket, PutBucketOptions, GetBucketResult, PresignOptions } from '@beechcms/core';
 /**
- * Implementation of BeechBucket using S3-compatible API (AWS SDK).
- * Used for production when connecting to R2 or any other S3 provider via HTTP.
+ * Configuration options for initializing an {@link S3Bucket} instance.
+ */
+export interface S3BucketConfig {
+    /** S3 API endpoint URL (e.g. Cloudflare R2 endpoint or MinIO endpoint). */
+    endpoint: string;
+    /** Access Key ID for S3 authentication. */
+    accessKeyId: string;
+    /** Secret Access Key for S3 authentication. */
+    secretAccessKey: string;
+    /** Target S3 bucket name. */
+    bucketName: string;
+    /** Base URL of the API server used for constructing fallback media access URLs. */
+    baseUrl: string;
+    /** Optional CDN base URL prepended to media assets when served via CDN. */
+    cdnUrl?: string;
+}
+/**
+ * Implementation of {@link BeechBucket} using an S3-compatible API via the AWS SDK.
+ *
+ * @remarks
+ * Used in production and staging when connecting to Cloudflare R2 or other S3-compatible providers (such as MinIO) over HTTP.
+ * Supports standard bucket operations: upload (`put`), retrieval (`get`), metadata inspection (`head`),
+ * deletion (`delete`), pagination (`list`), total size calculation (`getTotalSize`), and presigned URL generation (`presignPut`, `presignGet`).
  */
 export declare class S3Bucket implements BeechBucket {
+    /** AWS SDK S3 client configured with custom endpoint, credentials, and path-style addressing. */
     private client;
+    /** Name of the target S3/R2 bucket. */
     private bucketName;
+    /** Base URL of the API server used as the fallback origin for media asset URLs. */
     private baseUrl;
+    /** Optional custom CDN base URL used to serve media assets directly from a CDN. */
     private cdnUrl;
-    constructor(config: {
-        endpoint: string;
-        accessKeyId: string;
-        secretAccessKey: string;
-        bucketName: string;
-        baseUrl: string;
-        cdnUrl?: string;
-    });
+    /**
+     * Initializes a new instance of {@link S3Bucket}.
+     *
+     * @param config - The S3 client and bucket configuration options.
+     */
+    constructor(config: S3BucketConfig);
+    /**
+     * Uploads an object to the S3 bucket.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @param body - The object content as an `ArrayBuffer`, `Uint8Array`, or `ReadableStream`.
+     * @param options - Optional upload settings such as `contentType` and custom `metadata`.
+     * @throws {Error} If the S3 upload operation fails.
+     * @returns A promise that resolves when the upload completes.
+     */
     put(key: string, body: ArrayBuffer | Uint8Array | ReadableStream, options?: PutBucketOptions): Promise<void>;
+    /**
+     * Retrieves an object from the S3 bucket as a stream.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @returns A promise resolving to a {@link GetBucketResult} with the object body stream and metadata, or `null` if the object does not exist (`NoSuchKey` / `NotFound`).
+     * @throws {Error} If an S3 error other than `NoSuchKey` or `NotFound` occurs (e.g. `AccessDenied`, timeout).
+     */
     get(key: string): Promise<GetBucketResult | null>;
+    /**
+     * Deletes an object from the S3 bucket.
+     *
+     * @param key - The unique object key (path) to delete.
+     * @throws {Error} If the S3 delete operation fails.
+     * @returns A promise that resolves when the object has been deleted.
+     */
     delete(key: string): Promise<void>;
+    /**
+     * Retrieves metadata for an object without downloading its payload.
+     *
+     * @param key - The unique object key (path) within the bucket.
+     * @returns A promise resolving to the object's size, content type, and custom metadata, or `null` if the object does not exist.
+     * @throws {Error} If an S3 error other than `NoSuchKey` or `NotFound` occurs.
+     */
     head(key: string): Promise<{
         size: number;
         contentType?: string;
         metadata?: Record<string, string>;
     } | null>;
+    /**
+     * Constructs the public access URL for an object key.
+     *
+     * @remarks
+     * If a CDN URL is configured, returns the CDN-prefixed path (`${cdnUrl}/${encodedKey}`).
+     * Otherwise, returns the API fallback path (`${baseUrl}/api/media/${encodedKey}`).
+     *
+     * @param key - The storage object key.
+     * @returns The fully qualified URL to access the media object.
+     */
     getUrl(key: string): string;
+    /**
+     * Computes the cumulative size in bytes of all objects stored in the bucket.
+     *
+     * @remarks
+     * Iterates through all bucket objects using paginated S3 `ListObjectsV2` requests.
+     *
+     * @returns A promise resolving to the total storage size in bytes.
+     */
     getTotalSize(): Promise<number>;
+    /**
+     * Generates a presigned URL allowing clients to directly upload an object via HTTP PUT.
+     *
+     * @remarks
+     * Binds the expiration time, content type, and expected content length into the AWS SigV4 signature.
+     *
+     * @param key - The target object key (path) for upload.
+     * @param options - Presigning options including `expiresIn`, `contentType`, and `contentLength`.
+     * @returns A promise resolving to the presigned PUT URL.
+     */
     presignPut(key: string, options: PresignOptions): Promise<string>;
+    /**
+     * Generates a presigned URL allowing clients to directly download an object via HTTP GET.
+     *
+     * @param key - The target object key (path) to download.
+     * @param options - Presigning options including `expiresIn`.
+     * @returns A promise resolving to the presigned GET URL.
+     */
     presignGet(key: string, options: PresignOptions): Promise<string>;
+    /**
+     * Lists objects in the bucket matching an optional prefix, with pagination support.
+     *
+     * @param options - Optional listing parameters including `prefix`, `limit` (max keys), and `cursor` (continuation token).
+     * @returns A promise resolving to an array of object summaries (key and size) and an optional continuation cursor.
+     */
     list(options?: {
         prefix?: string;
         limit?: number;

package/dist/shared/storage/upload.d.ts

@@ -1,7 +1,35 @@
-export declare function deleteR2Objects(c: {
+import type { BeechBucket, MediaRepository, SystemStatsRepository } from '@beechcms/core';
+/**
+ * Context dependencies required to execute media deletion operations.
+ */
+export interface DeleteR2ObjectsContext {
+    /** Variables bound to the request context. */
     var: {
-        bucket: any;
-        mediaRepository: any;
-        systemStatsRepository: any;
+        /** Storage bucket instance used to delete the physical object. */
+        bucket: BeechBucket;
+        /** Media repository used to look up and untrack media database records. */
+        mediaRepository: MediaRepository;
+        /** System statistics repository used to decrement cumulative storage usage. */
+        systemStatsRepository: SystemStatsRepository;
     };
-}, objectKeys: string[]): Promise<void>;
+}
+/**
+ * Deletes one or more media objects from the storage bucket and synchronizes database tracking and statistics.
+ *
+ * @remarks
+ * For each provided object key, the following sequence is performed:
+ * 1. Looks up the media record in `mediaRepository` to obtain file size and ensure the key is tracked.
+ *    If the key is not found or the lookup fails, an error is thrown before bucket deletion.
+ * 2. Deletes the physical binary object from the storage `bucket`.
+ * 3. Untracks the media record from `mediaRepository` and decrements cumulative storage in `systemStatsRepository`.
+ * 4. If bucket deletion succeeds but untracking or statistics decrement fails, the key is recorded as out-of-sync
+ *    and a composite error is thrown after all operations complete to surface data drift.
+ *
+ * @param context - Context object holding `bucket`, `mediaRepository`, and `systemStatsRepository` dependencies in `context.var`.
+ * @param objectKeys - Array of media storage object keys to delete.
+ * @throws {Error} If media record lookup fails or key is untracked in the database.
+ * @throws {Error} If the storage bucket deletion fails.
+ * @throws {Error} If one or more media records fail to untrack after bucket deletion (data drift).
+ * @returns A promise that resolves when all objects have been successfully deleted and untracked.
+ */
+export declare function deleteR2Objects(context: DeleteR2ObjectsContext, objectKeys: string[]): Promise<void>;

package/dist/shared/utils/dual-key-rate-limiter.d.ts

@@ -0,0 +1,21 @@
+import type { IRateLimiter } from '@beechcms/core';
+export interface DualKeyRateLimitOptions {
+    ipLimiter: IRateLimiter;
+    accountLimiter: IRateLimiter;
+    clientIp: string;
+    accountKey: string;
+}
+export interface DualKeyRateLimitResult {
+    isAllowed: boolean;
+    retryAfterSeconds?: number;
+    blockedBy?: 'ip' | 'account' | 'both';
+}
+/**
+ * Normalizes account identifiers (e.g. emails) by trimming whitespace and converting to lowercase.
+ */
+export declare function normalizeAccountKey(rawKey: string): string;
+/**
+ * Coordinates atomic evaluation of IP and Account rate limiters.
+ * If either bucket violates its limit, access is rejected (HTTP 429).
+ */
+export declare function checkDualKeyRateLimit(options: DualKeyRateLimitOptions): Promise<DualKeyRateLimitResult>;

package/dist/shared/utils/media-utils.d.ts

@@ -16,11 +16,11 @@ import type { Seed } from '@beechcms/core';
 export declare function extractMediaKey(mediaUrl: string, cdnUrl?: string): string | null;
 /**
  * Estrae tutte le chiavi R2 dal data di un'entry.
- * Cerca nei campi `file` (stringa URL) e `json` (array/oggetto con URL).
- * Il data è in formato DB: chiavi = branch.id (es. art_03, prd_05).
+ * Cerca nei campi `file` (stringa URL), `json` (array/oggetto con URL) e `repeater` (array di record).
+ * Il data è in formato DB o deserializzato (chiavi = branch alias).
  *
  * @param seed - Schema del tipo di contenuto
- * @param entryData - Payload in formato DB (chiavi = branch ID)
+ * @param entryData - Payload (chiavi = branch alias)
  * @param cdnUrl - URL CDN opzionale configurato
  * @returns Array di chiavi R2 uniche da eliminare
  */

package/dist/shared/utils/opaque-token.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 256 bits of CSPRNG entropy, hex-encoded.
+ *
+ * The single entropy source for every bearer credential in the API: dashboard
+ * session refresh tokens, OAuth authorization codes, and OAuth access/refresh
+ * tokens. It lives in `shared/utils` — not inside `auth/` and not copied into a
+ * feature slice — so that changing the length or the encoding is a one-line
+ * change that cannot silently leave a second copy behind.
+ *
+ * Promoted from `auth/utils/refresh-token.ts` (`generateRefreshToken`) in the
+ * `oauth-authorization-server` sprint. Body is unchanged.
+ */
+export declare function generateOpaqueToken(): string;

package/dist/types.d.ts

@@ -4,7 +4,7 @@
  * per-request context values injected by middleware (`Variables`), and
  * the combined `AppEnv` used to type every Hono app/router in the API.
  */
-import type { Seed, ContentRepository, IdempotencyRepository, BeechBucket, MediaRepository, SystemStatsRepository, IHashProvider, ITokenService, IUserRepository, ISessionRepository, IPasswordResetTokenRepository, IActivityLogger, IActivityLogRepository, INotificationRepository, INotificationService, IWidgetRepository, ISearchRepository, IAnalyticsRepository, IContentScanRepository, ISeedRegistry, IClock, IIdGenerator, IAutomationRunner, IAutomationRepository, IScheduler, BackrefMap, ISiteSettingsRepository, IDemoDataRepository, JwtClaims, ISeedLayoutRepository, ISeedRepository, ISchemaMutator, IDashboardLayoutRepository, IQueueService, IKanbanPositionRepository, IPrivacyService, ActorContext } from '@beechcms/core';
+import type { Seed, ContentRepository, IdempotencyRepository, BeechBucket, MediaRepository, SystemStatsRepository, IHashProvider, ITokenService, IUserRepository, ISessionRepository, IPasswordResetTokenRepository, IActivityLogger, IActivityLogRepository, INotificationRepository, INotificationService, IWidgetRepository, ISearchRepository, IAnalyticsRepository, IContentScanRepository, ISeedRegistry, IClock, IIdGenerator, IAutomationRunner, IAutomationRepository, IScheduler, BackrefMap, ISiteSettingsRepository, IDemoDataRepository, JwtClaims, ISeedLayoutRepository, ISeedRepository, ISchemaMutator, IDashboardLayoutRepository, IQueueService, IKanbanPositionRepository, IPrivacyService, ActorContext, IAntivirusProvider, ITimeTrapTokenRepository, IOAuthClientRepository, IOAuthAuthorizationCodeRepository, IOAuthTokenRepository, IOAuthConsentRepository, IRoleGuard, OAuthScope } from '@beechcms/core';
 import type { IRateLimiterRegistry } from './middleware/rate-limit.middleware';
 import type { ISetupChecklistRepository } from './shared/db/repositories/d1-setup-checklist.repository';
 /**
@@ -14,12 +14,18 @@ import type { ISetupChecklistRepository } from './shared/db/repositories/d1-setu
 export interface Env {
     /** D1 database binding, the source of truth for all content and system tables. */
     DB: D1Database;
+    /** Cloudflare Workers AI binding for embeddings / LLMs. */
+    AI?: any;
+    /** Cloudflare R2 bucket binding for compiled search vectors and manifests. */
+    SEARCH_R2?: R2Bucket;
     /** Secret used to sign and verify JWTs. */
     JWT_SECRET: string;
     /** Expected `iss` claim on issued/verified JWTs. */
     JWT_ISSUER?: string;
     /** Expected `aud` claim on issued/verified JWTs. */
     JWT_AUDIENCE?: string;
+    /** Native Cloudflare R2 bucket binding for media storage. */
+    MEDIA_BUCKET?: R2Bucket;
     /** R2-compatible access key ID for media storage. */
     R2_ACCESS_KEY_ID?: string;
     /** R2-compatible secret access key for media storage. */
@@ -92,6 +98,29 @@ export interface Env {
     QSTASH_NEXT_SIGNING_KEY?: string;
     /** Master key used for Application-Level Encryption (ALE). */
     PRIVACY_MASTER_KEY?: string;
+    /** API key for VirusTotal file/hash scanning. */
+    VIRUSTOTAL_API_KEY?: string;
+    /** Secret used to sign and verify public form time-trap tokens. */
+    PUBLIC_TIME_TRAP_SECRET?: string;
+    /** Comma-separated list of allowed origins for public submissions. */
+    ALLOWED_ORIGINS?: string;
+}
+/**
+ * Authentication material carried by a request that authenticated with an OAuth 2.1
+ * access token instead of the dashboard admin JWT.
+ *
+ * `null` means the request authenticated with the admin JWT (or, on routers where
+ * `authMiddleware` is not registered, did not authenticate at all). The scope gate
+ * treats `null` as "not an OAuth request" and lets it through unchanged, so admin
+ * dashboard behaviour is never affected by scope enforcement.
+ */
+export interface OAuthGrantContext {
+    /** Client that presented the access token (`oauth_tokens.client_id`). */
+    clientId: string;
+    /** Resource owner the token acts for (`oauth_tokens.user_id`). */
+    userId: string;
+    /** Scopes frozen into the token record at issuance time. Never re-derived per request. */
+    scope: OAuthScope[];
 }
 /**
  * Per-request context values (`c.get(...)` / `c.set(...)`), injected by middleware
@@ -102,6 +131,11 @@ export interface Variables {
     actor?: ActorContext;
     /** Decoded JWT claims of the authenticated user. */
     jwtPayload: JwtClaims;
+    /**
+     * Set by `authMiddleware({ acceptOAuth: true })`. Non-null only when the request
+     * presented an OAuth access token. Read by `oauthScopeMiddleware()`.
+     */
+    oauthGrant: OAuthGrantContext | null;
     /** Application-level privacy and encryption service. */
     privacyService: IPrivacyService;
     /** Looks up a Seed definition by slug from the loaded schema. */
@@ -176,6 +210,20 @@ export interface Variables {
     dashboardLayoutRepository: IDashboardLayoutRepository;
     /** Repository for Kanban card position/ordering state. */
     kanbanPositionRepository: IKanbanPositionRepository;
+    /** Antivirus scanning provider. */
+    antivirusProvider: IAntivirusProvider;
+    /** Repository for single-use time-trap token deduplication. */
+    timeTrapTokenRepository: ITimeTrapTokenRepository;
+    /** Registry of OAuth clients authorized to use the authorization-code flow. */
+    oauthClientRepository: IOAuthClientRepository;
+    /** Repository for single-use OAuth authorization codes (hash-only). */
+    oauthAuthorizationCodeRepository: IOAuthAuthorizationCodeRepository;
+    /** Repository for OAuth access/refresh tokens (hash-only). */
+    oauthTokenRepository: IOAuthTokenRepository;
+    /** Repository for per-(client,user) OAuth scope consents. */
+    oauthConsentRepository: IOAuthConsentRepository;
+    /** Arbitrates which requested scopes a user's role may grant. Sole role-authorization seam in the OAuth flow. */
+    roleGuard: IRoleGuard;
 }
 /** Combined Hono generic type (`Bindings` + `Variables`) used to type every app/router in the API. */
 export type AppEnv = {

package/migrations/0000_v040_base.sql

@@ -276,3 +276,173 @@ CREATE TABLE IF NOT EXISTS setup_completed (
     id INTEGER NOT NULL PRIMARY KEY CHECK (id = 1)
 );
 
+
+-- =============================================================================
+-- 15. RUNTIME SEEDS
+--     `seeds`     : one row per content type. `definition` is the full Seed JSON.
+--     `seed_meta` : single-row table holding the registry version token used for
+--                   multi-isolate cache invalidation.
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS seeds (
+    slug        TEXT    NOT NULL PRIMARY KEY,
+    definition  TEXT    NOT NULL,
+    status      TEXT    NOT NULL DEFAULT 'active'
+                        CHECK (status IN ('active', 'deleted')),
+    source      TEXT    NOT NULL DEFAULT 'runtime'
+                        CHECK (source IN ('code', 'runtime')),
+    created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at  INTEGER NOT NULL DEFAULT (unixepoch())
+);
+
+CREATE INDEX IF NOT EXISTS idx_seeds_status ON seeds(status);
+
+CREATE TABLE IF NOT EXISTS seed_meta (
+    id      TEXT NOT NULL PRIMARY KEY,
+    value   TEXT NOT NULL
+);
+
+INSERT OR IGNORE INTO seed_meta (id, value) VALUES ('registry_version', '1');
+
+
+-- =============================================================================
+-- 16. DASHBOARD LAYOUTS
+--     One row per scope: 'default' | 'role:admin' | 'role:editor' ...
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS dashboard_layouts (
+    scope        TEXT NOT NULL PRIMARY KEY,
+    layout       TEXT NOT NULL,
+    updated_at   INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_by   TEXT NOT NULL
+);
+
+
+-- =============================================================================
+-- 17. KANBAN FOUNDATION
+--     kanban_positions : per-(seed, axis, entry) fractional-index ordering.
+--     seed_layouts.view_config : additive JSON blob for per-seed dashboard view
+--     preferences (kanban axis/sort/hidden columns).
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS kanban_positions (
+    seed_slug      TEXT    NOT NULL,
+    entry_id       TEXT    NOT NULL,
+    axis_branch_id TEXT    NOT NULL,
+    position       TEXT    NOT NULL,
+    updated_at     INTEGER NOT NULL DEFAULT (unixepoch()),
+    PRIMARY KEY (seed_slug, entry_id, axis_branch_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_kanban_positions_column
+    ON kanban_positions (seed_slug, axis_branch_id, position);
+
+ALTER TABLE seed_layouts ADD COLUMN view_config TEXT;
+
+
+-- =============================================================================
+-- 18. PUBLIC TIME-TRAP TOKENS
+--     Single-use tracking for HMAC time-trap tokens to prevent replay attacks.
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS public_time_trap_tokens (
+    token_hash  TEXT    NOT NULL PRIMARY KEY,
+    used_at     INTEGER NOT NULL,
+    expires_at  INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_time_trap_tokens_expires
+ON public_time_trap_tokens (expires_at);
+
+
+-- =============================================================================
+-- 19. OAUTH 2.1 AUTHORIZATION SERVER
+--     Authorization code + PKCE grant. Every credential (code, access token,
+--     refresh token) is persisted as a SHA-256 hex hash only — never plaintext.
+--     Expired rows are filtered at read time via expires_at; no pruning job.
+-- =============================================================================
+
+CREATE TABLE IF NOT EXISTS oauth_clients (
+    client_id       TEXT    NOT NULL PRIMARY KEY,
+    name            TEXT    NOT NULL,
+    redirect_uris   TEXT    NOT NULL,
+    allowed_scopes  TEXT    NOT NULL,
+    is_public       INTEGER NOT NULL DEFAULT 1
+                            CHECK (is_public IN (0, 1)),
+    created_at      INTEGER NOT NULL DEFAULT (unixepoch()),
+    disabled_at     INTEGER DEFAULT NULL
+);
+
+CREATE TABLE IF NOT EXISTS oauth_authorization_codes (
+    code_hash               TEXT    NOT NULL PRIMARY KEY,
+    client_id               TEXT    NOT NULL REFERENCES oauth_clients(client_id) ON DELETE CASCADE,
+    user_id                 TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    scope                   TEXT    NOT NULL,
+    redirect_uri            TEXT    NOT NULL,
+    code_challenge          TEXT    NOT NULL,
+    code_challenge_method   TEXT    NOT NULL DEFAULT 'S256'
+                                    CHECK (code_challenge_method = 'S256'),
+    expires_at              INTEGER NOT NULL,
+    created_at              INTEGER NOT NULL DEFAULT (unixepoch()),
+    consumed_at             INTEGER DEFAULT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_oauth_codes_user    ON oauth_authorization_codes(user_id);
+CREATE INDEX IF NOT EXISTS idx_oauth_codes_expires ON oauth_authorization_codes(expires_at);
+
+CREATE TABLE IF NOT EXISTS oauth_tokens (
+    id                      TEXT    NOT NULL PRIMARY KEY,
+    token_hash              TEXT    NOT NULL,
+    token_type              TEXT    NOT NULL
+                                    CHECK (token_type IN ('access', 'refresh')),
+    client_id               TEXT    NOT NULL REFERENCES oauth_clients(client_id) ON DELETE CASCADE,
+    user_id                 TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    scope                   TEXT    NOT NULL,
+    authorization_code_hash TEXT    NOT NULL,
+    expires_at              INTEGER NOT NULL,
+    created_at              INTEGER NOT NULL DEFAULT (unixepoch()),
+    revoked_at              INTEGER DEFAULT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_hash    ON oauth_tokens(token_hash);
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_code    ON oauth_tokens(authorization_code_hash);
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_client  ON oauth_tokens(client_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_user    ON oauth_tokens(user_id);
+CREATE INDEX IF NOT EXISTS idx_oauth_tokens_expires ON oauth_tokens(expires_at);
+
+CREATE TABLE IF NOT EXISTS oauth_consents (
+    id          TEXT    NOT NULL PRIMARY KEY,
+    client_id   TEXT    NOT NULL REFERENCES oauth_clients(client_id) ON DELETE CASCADE,
+    user_id     TEXT    NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    scopes      TEXT    NOT NULL,
+    created_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+    updated_at  INTEGER NOT NULL DEFAULT (unixepoch()),
+    revoked_at  INTEGER DEFAULT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_oauth_consents_pair ON oauth_consents(client_id, user_id);
+CREATE INDEX IF NOT EXISTS idx_oauth_consents_user ON oauth_consents(user_id);
+
+-- Static registry, no dynamic client registration (RFC 7591). Seeded client
+-- is @beechcms/mcp — public client (stdio CLI, no secret), PKCE S256 proof of
+-- possession. Redirect URI registered WITHOUT a port: matchesRegisteredRedirectUri()
+-- compares loopback URIs on protocol+hostname+pathname only (OAuth 2.1 §8.4.2),
+-- because the CLI binds an ephemeral port at runtime.
+INSERT OR IGNORE INTO oauth_clients (client_id, name, redirect_uris, allowed_scopes, is_public)
+VALUES (
+    'beech-mcp',
+    'BeechCMS MCP Server',
+    '["http://127.0.0.1/oauth/callback"]',
+    'schema:read schema:write',
+    1
+);
+
+INSERT OR IGNORE INTO oauth_clients (client_id, name, redirect_uris, allowed_scopes, is_public)
+VALUES (
+    'beech-mcp-cli',
+    'BeechCMS MCP Server',
+    '["http://127.0.0.1/callback"]',
+    'schema:read schema:write',
+    1
+);
+