@rebasepro/server 0.0.1-canary.4829d6e

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Rebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,77 @@
+# @rebasepro/server
+
+Database-agnostic backend core for Rebase.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/server
+```
+
+## 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 API generator — without being coupled to any specific database. Database implementations are plugged in via driver packages like `@rebasepro/server-postgres` or `@rebasepro/server-mongo`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `initializeRebaseBackend(config)` | Main entry point. Wires up drivers, auth, storage, API routes, cron, and custom functions. Returns a `RebaseBackendInstance`. |
+| `rebase` | Server-side singleton (`RebaseClient`). Available after init. Admin-level access to data, auth, email, and storage. |
+| `loadEnv()` | Validates `process.env` against the Rebase env schema (Zod). Auto-generates dev secrets. Supports `extend` for custom vars. |
+| `serveSPA(app, config)` | Mounts SPA static-file serving + index.html fallback on a Hono app. |
+| `RebaseBackendConfig` | Config type for `initializeRebaseBackend`. |
+| `RebaseAuthConfig` | Auth config type (JWT, OAuth providers, hooks, service key). |
+| `RebaseBackendInstance` | Return type — includes `driver`, `healthCheck()`, `shutdown()`, `cronScheduler`, `storageController`, etc. |
+| `RebaseEnv` | Zod-inferred type of validated environment variables. |
+| `z` | Re-exported Zod instance for extending `loadEnv`. |
+| `_setRebaseMock` / `_resetRebaseMock` | Test helpers to mock the `rebase` singleton (NODE_ENV=test only). |
+
+Also re-exports all abstract interfaces (`DatabaseAdapter`, `AuthAdapter`, `DataDriver`, etc.), API types (`HonoEnv`, `ApiConfig`), auth module, email module, storage module, history module, cron module, custom functions, logging utilities, and driver registry.
+
+## Quick Start
+
+```typescript
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { initializeRebaseBackend, loadEnv, serveSPA } from "@rebasepro/server";
+import { createPostgresAdapter } from "@rebasepro/server-postgres";
+
+// 1. Load and validate environment
+const env = loadEnv();
+
+// 2. Create Hono app + HTTP server
+const app = new Hono();
+const server = serve({ fetch: app.fetch, port: env.PORT });
+
+// 3. Initialize Rebase
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database: createPostgresAdapter({ connection: db, schema }),
+  collections: myCollections,
+  auth: {
+    collection: defaultUsersCollection,
+    jwtSecret: env.JWT_SECRET,
+    allowRegistration: env.ALLOW_REGISTRATION,
+    serviceKey: env.REBASE_SERVICE_KEY,
+    google: { clientId: env.GOOGLE_CLIENT_ID },
+  },
+  storage: { type: "s3", bucket: env.S3_BUCKET },
+  functionsDir: "./functions",
+  cronsDir: "./crons",
+});
+
+// 4. Optionally serve a frontend SPA
+serveSPA(app, { frontendPath: "./frontend/dist" });
+```
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| `@rebasepro/server-postgres` | PostgreSQL database driver (Drizzle ORM) |
+| `@rebasepro/server-mongo` | MongoDB database driver |
+| `@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/dist/api/rest/index.d.ts

@@ -0,0 +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,80 @@
+/**
+ * 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;
+    emailDeliveryFailed?: 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/dist/auth/api-keys/api-key-permission-guard.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Permission guard for Service API Keys.
+ *
+ * Checks whether an API key's permission set allows a specific operation
+ * on a specific collection. Used by the REST API generator middleware to
+ * enforce fine-grained access control.
+ *
+ * @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`.
+ *
+ * - `GET`, `HEAD`, `OPTIONS` → `"read"`
+ * - `POST`, `PUT`, `PATCH`  → `"write"`
+ * - `DELETE`                → `"delete"`
+ */
+export declare function httpMethodToOperation(method: string): ApiKeyOperation;
+/**
+ * Check whether the given permissions array allows `operation` on `collection`.
+ *
+ * Supports the `"*"` wildcard for the collection field, which matches any
+ * collection. Returns `true` if at least one permission entry grants access.
+ *
+ * @param permissions - The API key's permission entries.
+ * @param collection  - The target collection slug.
+ * @param operation   - The requested operation.
+ * @returns `true` if the operation is permitted.
+ */
+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>;