@rebasepro/server-core 0.7.0 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@ pnpm add @rebasepro/server-core
 
 ## What This Package Does
 
-This is the central orchestrator for any Rebase backend. It provides the framework-level plumbing — HTTP routing (Hono), authentication middleware, storage, email, cron jobs, custom functions, and the REST/GraphQL API generator — without being coupled to any specific database. Database implementations are plugged in via driver packages like `@rebasepro/server-postgresql` or `@rebasepro/server-mongodb`.
+This is the central orchestrator for any Rebase backend. It provides the framework-level plumbing — HTTP routing (Hono), authentication middleware, storage, email, cron jobs, custom functions, and the REST API generator — without being coupled to any specific database. Database implementations are plugged in via driver packages like `@rebasepro/server-postgresql` or `@rebasepro/server-mongodb`.
 
 ## Key Exports
 
@@ -72,6 +72,6 @@ serveSPA(app, { frontendPath: "./frontend/dist" });
 |---------|------|
 | `@rebasepro/server-postgresql` | PostgreSQL database driver (Drizzle ORM) |
 | `@rebasepro/server-mongodb` | MongoDB database driver |
-| `@rebasepro/types` | Shared type definitions (`DataDriver`, `EntityCollection`, etc.) |
+| `@rebasepro/types` | Shared type definitions (`DataDriver`, `CollectionConfig`, etc.) |
 | `@rebasepro/client` | Client SDK used internally by the `rebase` singleton |
 | `@rebasepro/common` | Shared utilities and default collections |

package/dist/api/ast-schema-editor.d.ts

@@ -0,0 +1,21 @@
+export declare class AstSchemaEditor {
+    private project;
+    private collectionsDir;
+    constructor(collectionsDir: string);
+    /**
+     * Sanitize collectionId to prevent path traversal attacks.
+     * Only allows alphanumeric characters, underscores, and hyphens.
+     */
+    private sanitizeCollectionId;
+    /**
+     * Resolve a file path and ensure it falls within the collectionsDir.
+     */
+    private safePath;
+    private getCollectionFile;
+    private getCollectionObject;
+    private convertJsonToAstString;
+    saveProperty(collectionId: string, propertyKey: string, propertyConfig: Record<string, unknown>): Promise<void>;
+    deleteProperty(collectionId: string, propertyKey: string): Promise<void>;
+    saveCollection(collectionId: string, collectionData: Record<string, unknown>): Promise<void>;
+    deleteCollection(collectionId: string): Promise<void>;
+}

package/dist/api/collections_for_test/callbacks_test_collection.d.ts

@@ -0,0 +1,2 @@
+import { PostgresCollectionConfig } from "@rebasepro/types";
+export declare const callbacksTestCollection: PostgresCollectionConfig;

package/dist/api/errors.d.ts

@@ -0,0 +1,53 @@
+import type { ErrorHandler } from "hono";
+import type { HonoEnv } from "./types";
+/**
+ * Standardized API error class.
+ * Throw this from any route handler — the errorHandler middleware
+ * will format it into `{ error: { message, code, details? } }`.
+ */
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(statusCode: number, code: string, message: string, details?: unknown);
+    static badRequest(message: string, code?: string, details?: unknown): ApiError;
+    static unauthorized(message: string, code?: string): ApiError;
+    static forbidden(message: string, code?: string): ApiError;
+    static notFound(message: string, code?: string): ApiError;
+    static conflict(message: string, code?: string): ApiError;
+    static internal(message: string, code?: string): ApiError;
+    static serviceUnavailable(message: string, code?: string): ApiError;
+}
+/**
+ * Canonical error response shape:
+ * `{ error: { message: string, code: string, details?: unknown } }`
+ */
+export interface ErrorResponse {
+    error: {
+        message: string;
+        code: string;
+        details?: unknown;
+        /** Request correlation ID for tracing (echoes X-Request-ID). */
+        requestId?: string;
+    };
+}
+/**
+ * General shape of errors that flow through the API error handler.
+ * Extends Error with optional HTTP status, error code, and details.
+ */
+export interface RebaseApiError extends Error {
+    statusCode?: number;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * Type guard for errors that carry optional API metadata (statusCode, code, details).
+ * Returns true for any Error instance — the optional properties are then
+ * checked via normal property access.
+ */
+export declare function isRebaseApiError(error: unknown): error is RebaseApiError;
+/**
+ * Hono error-handling middleware (`app.onError`).
+ * Converts any error into the canonical `{ error: { message, code } }` shape.
+ */
+export declare const errorHandler: ErrorHandler<HonoEnv>;

package/dist/api/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * API generation infrastructure for Rebase
+ * Automatically generates REST APIs from CollectionConfig definitions
+ */
+export * from "./rest";
+export * from "./types";
+export * from "./errors";

package/dist/api/logs-routes.d.ts

@@ -0,0 +1,37 @@
+import { Hono } from "hono";
+import type { MiddlewareHandler } from "hono";
+import type { HonoEnv } from "./types";
+export interface LogEntry {
+    id: string;
+    timestamp: string;
+    level: "debug" | "info" | "warn" | "error";
+    source: "api" | "auth" | "storage" | "realtime" | "system";
+    message: string;
+    metadata?: Record<string, unknown>;
+}
+declare class LogRingBuffer {
+    private buffer;
+    private maxSize;
+    private idCounter;
+    constructor(maxSize?: number);
+    push(entry: Omit<LogEntry, "id">): void;
+    query(options: {
+        level?: string;
+        source?: string;
+        search?: string;
+        limit?: number;
+        offset?: number;
+        since?: string;
+    }): {
+        entries: LogEntry[];
+        total: number;
+    };
+    getLatest(count?: number): LogEntry[];
+}
+export declare const logBuffer: LogRingBuffer;
+/** Add a log entry */
+export declare function addLog(level: LogEntry["level"], source: LogEntry["source"], message: string, metadata?: Record<string, unknown>): void;
+/** Hono middleware to log API requests */
+export declare function logMiddleware(): MiddlewareHandler<HonoEnv>;
+declare const app: Hono<HonoEnv, import("hono/types").BlankSchema, "/">;
+export default app;

package/dist/api/openapi-generator.d.ts

@@ -0,0 +1,16 @@
+import { CollectionConfig } from "@rebasepro/types";
+/**
+ * OpenAPI 3.0.3 specification generator.
+ *
+ * Produces a spec that exactly mirrors the REST API consumed by the
+ * Rebase SDK client (`@rebasepro/client`).
+ *
+ * Routes are mounted at `{basePath}/data/{slug}` by `initializeRebaseBackend`.
+ */
+export interface OpenApiGeneratorOptions {
+    /** Base path for the API (e.g. "/api"). Defaults to "/api". */
+    basePath?: string;
+    /** Whether auth is enabled on data routes. Defaults to true. */
+    requireAuth?: boolean;
+}
+export declare function generateOpenApiSpec(collections: CollectionConfig[], options?: OpenApiGeneratorOptions): Record<string, unknown>;

package/dist/api/rest/api-generator.d.ts

@@ -0,0 +1,68 @@
+import { Hono } from "hono";
+import { AuthAdapter, DataDriver, CollectionConfig } from "@rebasepro/types";
+import { HonoEnv } from "../types";
+/**
+ * Lightweight REST API generator that leverages existing Rebase DataDriver.
+ * Supports `include` query parameter for eager-loading relations via Drizzle.
+ */
+export declare class RestApiGenerator {
+    private collections;
+    private router;
+    private driver;
+    private authAdapter?;
+    constructor(collections: CollectionConfig[], driver: DataDriver, authAdapter?: AuthAdapter);
+    /**
+     * Generate REST routes using existing DataDriver
+     */
+    generateRoutes(): Hono<HonoEnv>;
+    /**
+     * Check API key permissions for a collection operation.
+     * Throws 403 if the key doesn't have the required permission.
+     * No-ops if the request is not authenticated via an API key.
+     */
+    private enforceApiKeyPermission;
+    /**
+     * Get the request-scoped driver. Throws if none is set — never falls
+     * back to the unscoped `this.driver` to avoid bypassing RLS/auth.
+     */
+    private getScopedDriver;
+    /**
+     * Create REST routes for a collection using existing Rebase patterns
+     */
+    private createCollectionRoutes;
+    /**
+     * Catch-all routes for subcollection paths.
+     *
+     * Matches URL patterns like:
+     *   GET    /authors/111094/posts          → list child collection
+     *   GET    /authors/111094/posts/43       → get child entity
+     *   POST   /authors/111094/posts          → create child entity
+     *   PUT    /authors/111094/posts/43       → update child entity
+     *   DELETE /authors/111094/posts/43       → delete child entity
+     *
+     * The `:rest{.+}` regex param captures the full remainder of the URL
+     * path (Hono v4 `*` wildcard does not populate `c.req.param("*")`).
+     * We split it into segments and reconstruct the `collectionPath`
+     * (e.g. "authors/111094/posts") and optional `id` (e.g. "43").
+     *
+     * The DataDriver.save / fetchCollection / etc. already know how to
+     * resolve multi-segment relation paths, so we just forward to them.
+     */
+    private createSubcollectionRoutes;
+    /**
+     * Format successful API response
+     */
+    private formatResponse;
+    /**
+     * Fetch raw collection data without Entity wrapper (fallback for non-Postgres)
+     */
+    private fetchRawCollection;
+    /**
+     * Count raw entities for a collection
+     */
+    private countRawEntities;
+    /**
+     * Fetch single entity raw data without Entity wrapper (fallback)
+     */
+    private fetchRawEntity;
+}

package/{src/api/rest/index.ts → dist/api/rest/index.d.ts}

@@ -1,2 +1 @@
 export * from "./api-generator";
-

package/dist/api/rest/query-parser.d.ts

@@ -0,0 +1,6 @@
+import { QueryOptions } from "../types";
+export declare const mapOperator: (op: string) => import("@rebasepro/types").WhereFilterOp | null;
+/**
+ * Parse query parameters into QueryOptions
+ */
+export declare function parseQueryOptions(query: Record<string, unknown>): QueryOptions;

package/dist/api/schema-editor-routes.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from "hono";
+import { HonoEnv } from "./types";
+export declare function createSchemaEditorRoutes(collectionsDir: string): Hono<HonoEnv>;

package/dist/api/types.d.ts

@@ -0,0 +1,56 @@
+import { VectorSearchParams, LogicalCondition, FilterValues } from "@rebasepro/types";
+import { AuthResult } from "../auth/middleware";
+import { DataDriver } from "@rebasepro/types";
+import type { ApiKeyMasked } from "../auth/api-keys/api-key-types";
+/**
+ * Hono Environment Variables
+ * Passed to generic Hono<HonoEnv> to type `c.get()`
+ */
+export type HonoEnv = {
+    Variables: {
+        user?: AuthResult | {
+            userId?: string;
+            roles?: string[];
+        };
+        driver?: DataDriver;
+        /** Set when the request is authenticated via a Service API Key. */
+        apiKey?: ApiKeyMasked;
+        /** Unique request correlation ID (generated or propagated from X-Request-ID header). */
+        requestId?: string;
+    };
+};
+/**
+ * Standard API response format
+ */
+export interface ApiResponse<T = unknown> {
+    data?: T;
+    error?: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+    meta?: {
+        total?: number;
+        page?: number;
+        limit?: number;
+        hasMore?: boolean;
+    };
+}
+/**
+ * Query options for API endpoints
+ */
+export interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    where?: FilterValues<string>;
+    logical?: LogicalCondition;
+    orderBy?: Array<{
+        field: string;
+        direction: "asc" | "desc";
+    }>;
+    include?: string[];
+    /** Columns to return in the response (field-level selection) */
+    fields?: string[];
+    /** Vector similarity search configuration */
+    vectorSearch?: VectorSearchParams;
+}

package/dist/auth/adapter-middleware.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Adapter Auth Middleware
+ *
+ * Creates a Hono middleware that delegates authentication to an `AuthAdapter`
+ * instead of hardcoded JWT verification. This is used when the user passes
+ * an `AuthAdapter` to `initializeRebaseBackend()`.
+ *
+ * The middleware:
+ * 1. Checks for API key tokens (`rk_` prefix) first — these are Rebase-level
+ * 2. Falls back to `adapter.verifyRequest(request)` to resolve the user
+ * 3. Scopes the DataDriver via `withAuth()` for RLS
+ * 4. Enforces auth (401) when `requireAuth` is true and no user is found
+ *
+ * The behavior is identical to `createAuthMiddleware()` — only the
+ * token verification strategy is pluggable.
+ */
+import type { MiddlewareHandler, Context } from "hono";
+import type { DataDriver, AuthAdapter } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types";
+import type { ApiKeyStore } from "./api-keys/api-key-store";
+export interface AdapterAuthMiddlewareOptions {
+    /** The auth adapter to delegate verification to. */
+    adapter: AuthAdapter;
+    /** The DataDriver to scope via withAuth() for RLS. */
+    driver: DataDriver;
+    /**
+     * Optional per-request driver resolver for multi-data-source backends.
+     * Returns the unscoped delegate to use for this request (e.g. Postgres vs
+     * Mongo). When omitted, `driver` is used for every request.
+     */
+    resolveDriver?: (c: Context<HonoEnv>) => DataDriver;
+    /**
+     * If true, return 401 when no valid user is resolved.
+     * Defaults to `true` (secure by default).
+     */
+    requireAuth?: boolean;
+    /** Optional API key store — when provided, `rk_` bearer tokens are accepted. */
+    apiKeyStore?: ApiKeyStore;
+}
+/**
+ * Create a Hono middleware that uses an `AuthAdapter` for request verification.
+ */
+export declare function createAdapterAuthMiddleware(options: AdapterAuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;

package/dist/auth/admin-roles-route.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Admin endpoint for listing all roles.
+ *
+ * Mounts: GET /roles
+ */
+import { Hono } from "hono";
+import type { AuthRepository } from "./interfaces";
+import type { HonoEnv } from "../api/types";
+export interface AdminRolesRouteConfig {
+    authRepo: AuthRepository;
+    serviceKey?: string;
+}
+/**
+ * Create a standalone admin route for listing roles.
+ *
+ * Mounts: GET /roles
+ */
+export declare function createAdminRolesRoute(config: AdminRolesRouteConfig): Hono<HonoEnv>;

package/dist/auth/admin-user-ops.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Admin User Operations
+ *
+ * Shared utilities and orchestration for admin-initiated user management
+ * (user creation via REST API, password reset via admin panel).
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onCreateUser` on the collection) — closest to the data
+ * 2. Backend-level hook (`AuthHooks.onAdminCreateUser`) — global override
+ * 3. Built-in default — framework fallback
+ */
+import type { AuthRepository } from "./interfaces";
+import type { EmailService, EmailConfig } from "../email";
+import type { ResolvedAuthHooks } from "./auth-hooks";
+import type { AuthCollectionConfig } from "@rebasepro/types";
+/**
+ * Generate a cryptographically secure random password that meets strength requirements.
+ *
+ * 16 characters, guaranteed at least one uppercase, one lowercase, one digit.
+ * Ambiguous characters (0, O, 1, l, I) are excluded.
+ */
+export declare function generateSecurePassword(): string;
+/**
+ * Generate a cryptographically secure random token (80 hex characters).
+ */
+export declare function generateSecureToken(): string;
+/**
+ * Hash a token for database storage using SHA-256.
+ */
+export declare function hashToken(token: string): string;
+/**
+ * Context needed by admin user creation / password reset operations.
+ */
+export interface AdminUserContext {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    resolvedHooks: ResolvedAuthHooks;
+    /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+/**
+ * Result of preparing user values for admin-initiated creation.
+ */
+export interface AdminUserPrepareResult {
+    /** Values ready for `driver.save()`. */
+    values: Record<string, unknown>;
+    /** The cleartext password (for returning to admin or sending via email). */
+    clearPassword?: string;
+    /** Whether the hook already handled the invitation email. */
+    hookHandledEmail: boolean;
+    /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
+    invitationSent: boolean;
+}
+/**
+ * Prepare user values for an admin-initiated user creation.
+ *
+ * Resolution order:
+ * 1. Collection-level `auth.onCreateUser` — closest to the data
+ * 2. Backend-level `AuthHooks.onAdminCreateUser` — global override
+ * 3. Built-in default — generate password → hash → normalize email
+ *
+ * The caller is responsible for persisting (via `driver.save()`).
+ */
+export declare function prepareAdminUserValues(body: Record<string, unknown>, ctx: AdminUserContext): Promise<AdminUserPrepareResult>;
+/**
+ * Handle post-creation work for admin-created users.
+ *
+ * Sends an invitation email (password-reset link) if email is configured
+ * and no explicit password was provided. Falls back to returning the
+ * temporary password if email fails or is not configured.
+ */
+export declare function finalizeAdminUserCreation(entity: {
+    id: string;
+    values: Record<string, unknown>;
+}, clearPassword: string | undefined, ctx: AdminUserContext): Promise<{
+    temporaryPassword?: string;
+    invitationSent: boolean;
+}>;

package/dist/auth/admin-users-route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Standalone admin endpoint for user management.
+ *
+ * Mounts:
+ *   GET /users
+ *   GET /users/:userId
+ *   POST /users
+ *   PUT /users/:userId
+ *   DELETE /users/:userId
+ *   POST /bootstrap
+ */
+import { Hono } from "hono";
+import type { AuthRepository } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+import type { EmailService, EmailConfig } from "../email";
+import type { HonoEnv } from "../api/types";
+import type { AuthCollectionConfig } from "@rebasepro/types";
+export interface AdminUsersRouteConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    serviceKey?: string;
+    authHooks?: AuthHooks;
+    collectionAuthConfig?: AuthCollectionConfig;
+    isBootstrapCompleted?: () => Promise<boolean>;
+    setBootstrapCompleted?: () => Promise<void>;
+}
+export declare function createAdminUsersRoute(config: AdminUsersRouteConfig): Hono<HonoEnv>;

package/dist/auth/api-keys/api-key-middleware.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Hono middleware for authenticating requests via Service API Keys.
+ *
+ * This middleware is integrated into `createAuthMiddleware()` and
+ * activates only when the bearer token starts with `rk_`. It:
+ *
+ * 1. Hashes the token with SHA-256
+ * 2. Looks up the hash in the `rebase.api_keys` table
+ * 3. Validates the key is not revoked and not expired
+ * 4. Sets `c.set("user", ...)` and `c.set("apiKey", ...)` for downstream use
+ * 5. Scopes the DataDriver via `withAuth()` using the API key's service identity
+ *
+ * @module
+ */
+import type { Context } from "hono";
+import type { DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../../api/types";
+import type { ApiKeyStore } from "./api-key-store";
+/**
+ * Check whether a token looks like a Rebase API key.
+ */
+export declare function isApiKeyToken(token: string): boolean;
+/**
+ * Options for the API key authentication handler.
+ */
+export interface ApiKeyAuthOptions {
+    store: ApiKeyStore;
+    driver: DataDriver;
+}
+/**
+ * Validate an API key token and populate the Hono context.
+ *
+ * Returns `true` if the key is valid and context has been populated,
+ * or returns an error Response if the key is invalid.
+ *
+ * This is NOT a standalone middleware — it's called from within
+ * `createAuthMiddleware()` when a `rk_` prefixed token is detected.
+ */
+export declare function validateApiKey(c: Context<HonoEnv>, token: string, options: ApiKeyAuthOptions): Promise<Response | true>;

package/{src/auth/api-keys/api-key-permission-guard.ts → dist/auth/api-keys/api-key-permission-guard.d.ts}

@@ -7,12 +7,9 @@
  *
  * @module
  */
-
 import type { ApiKeyPermission } from "./api-key-types";
-
 /** Operations that map to HTTP methods. */
 export type ApiKeyOperation = "read" | "write" | "delete";
-
 /**
  * Map an HTTP method string to an `ApiKeyOperation`.
  *
@@ -20,24 +17,7 @@ export type ApiKeyOperation = "read" | "write" | "delete";
  * - `POST`, `PUT`, `PATCH`  → `"write"`
  * - `DELETE`                → `"delete"`
  */
-export function httpMethodToOperation(method: string): ApiKeyOperation {
-    const upper = method.toUpperCase();
-    switch (upper) {
-        case "GET":
-        case "HEAD":
-        case "OPTIONS":
-            return "read";
-        case "POST":
-        case "PUT":
-        case "PATCH":
-            return "write";
-        case "DELETE":
-            return "delete";
-        default:
-            return "read";
-    }
-}
-
+export declare function httpMethodToOperation(method: string): ApiKeyOperation;
 /**
  * Check whether the given permissions array allows `operation` on `collection`.
  *
@@ -49,16 +29,4 @@ export function httpMethodToOperation(method: string): ApiKeyOperation {
  * @param operation   - The requested operation.
  * @returns `true` if the operation is permitted.
  */
-export function isOperationAllowed(
-    permissions: ApiKeyPermission[],
-    collection: string,
-    operation: ApiKeyOperation
-): boolean {
-    for (const perm of permissions) {
-        const collectionMatch = perm.collection === "*" || perm.collection === collection;
-        if (collectionMatch && perm.operations.includes(operation)) {
-            return true;
-        }
-    }
-    return false;
-}
+export declare function isOperationAllowed(permissions: ApiKeyPermission[], collection: string, operation: ApiKeyOperation): boolean;

package/dist/auth/api-keys/api-key-routes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Admin routes for managing Service API Keys.
+ *
+ * Mounted under `/api/admin/api-keys` with `requireAuth` + `requireAdmin`.
+ * All routes return masked keys (never the hash). The full plaintext key
+ * is returned exactly once in the POST response.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import type { HonoEnv } from "../../api/types";
+import type { ApiKeyStore } from "./api-key-store";
+export interface ApiKeyRouteOptions {
+    store: ApiKeyStore;
+    serviceKey?: string;
+}
+/**
+ * Create admin routes for API key management.
+ */
+export declare function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv>;

package/dist/auth/api-keys/api-key-store.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Database operations for Service API Keys.
+ *
+ * Uses the DataDriver's `admin.executeSql` capability (same pattern as
+ * the cron-store and ensure-tables modules). All data lives in the
+ * `rebase.api_keys` table.
+ *
+ * @module
+ */
+import type { DataDriver } from "@rebasepro/types";
+import type { ApiKey, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types";
+export interface ApiKeyStore {
+    /** Ensure the `rebase.api_keys` table exists. Called once on startup. */
+    ensureTable(): Promise<void>;
+    /** Create a new API key. Returns the full plaintext key exactly once. */
+    createApiKey(request: CreateApiKeyRequest, createdBy: string): Promise<ApiKeyWithSecret>;
+    /** Look up an API key by its SHA-256 hash. Returns `null` if not found. */
+    findByKeyHash(hash: string): Promise<ApiKey | null>;
+    /** List all API keys (masked, never includes hash). */
+    listApiKeys(): Promise<ApiKeyMasked[]>;
+    /** Get a single API key by ID (masked). */
+    getApiKeyById(id: string): Promise<ApiKeyMasked | null>;
+    /** Update name, permissions, rate_limit, or expires_at. */
+    updateApiKey(id: string, updates: UpdateApiKeyRequest): Promise<ApiKeyMasked | null>;
+    /** Soft-delete: set `revoked_at` to now. */
+    revokeApiKey(id: string): Promise<boolean>;
+    /** Touch `last_used_at` to the current timestamp. */
+    updateLastUsed(id: string): Promise<void>;
+}
+/**
+ * Create an `ApiKeyStore` backed by the driver's SQL admin capability.
+ *
+ * Returns `undefined` if the driver does not support `executeSql`.
+ */
+export declare function createApiKeyStore(driver: DataDriver): ApiKeyStore | undefined;