@rebasepro/server-core 0.7.0 → 0.8.0

package/dist/auth/mfa.d.ts

@@ -0,0 +1,49 @@
+/**
+ * TOTP (Time-based One-Time Password) implementation.
+ *
+ * Pure Node.js crypto implementation — no external dependencies required.
+ * Implements RFC 6238 (TOTP) and RFC 4226 (HOTP).
+ */
+/**
+ * Encode a Buffer to Base32 string (RFC 4648)
+ */
+export declare function base32Encode(buffer: Buffer): string;
+/**
+ * Decode a Base32 string to Buffer
+ */
+export declare function base32Decode(encoded: string): Buffer;
+/**
+ * Generate a TOTP value for the current time step
+ */
+export declare function generateTotp(secret: Buffer, timeStep?: number): string;
+/**
+ * Verify a TOTP token with a configurable time window
+ *
+ * @param secret - The shared secret as a Buffer
+ * @param token - The 6-digit TOTP code to verify
+ * @param window - Number of time steps to check on each side (default: 1)
+ * @returns true if the token is valid within the window
+ */
+export declare function verifyTotp(secret: Buffer, token: string, window?: number): boolean;
+/**
+ * Generate a new TOTP secret and return the setup information
+ *
+ * @param issuer - The issuer name (app name) for the QR code
+ * @param accountName - The account identifier (usually email)
+ * @returns Object with base32 secret and otpauth URI
+ */
+export declare function generateTotpSecret(issuer: string, accountName: string): {
+    secret: string;
+    uri: string;
+};
+/**
+ * Generate a set of one-time recovery codes
+ *
+ * @param count - Number of recovery codes to generate (default: 10)
+ * @returns Array of formatted recovery code strings (e.g. "A1B2C-D3E4F")
+ */
+export declare function generateRecoveryCodes(count?: number): string[];
+/**
+ * Hash a recovery code for storage
+ */
+export declare function hashRecoveryCode(code: string): string;

package/dist/auth/microsoft-oauth.d.ts

@@ -0,0 +1,16 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Microsoft / Entra ID (Azure AD) OAuth Provider integration.
+ *
+ * Supports both personal Microsoft accounts and work/school (Azure AD) accounts
+ * via the "common" tenant endpoint. Uses the authorization code flow.
+ */
+export declare function createMicrosoftProvider(config: {
+    clientId: string;
+    clientSecret: string;
+    /** Tenant ID. Defaults to "common" which allows both personal and organizational accounts. */
+    tenantId?: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/middleware.d.ts

@@ -0,0 +1,113 @@
+import { MiddlewareHandler, Context } from "hono";
+import { DataDriver } from "@rebasepro/types";
+import { AccessTokenPayload } from "./jwt";
+import { HonoEnv } from "../api/types";
+import type { ApiKeyStore } from "./api-keys/api-key-store";
+/**
+ * Result from a custom auth validator.
+ * - `false`/`null`/`undefined` = not authenticated
+ * - `true` = authenticated as default user
+ * - object with `userId` or `uid` = authenticated with user info
+ */
+export type AuthResult = boolean | null | undefined | {
+    userId?: string;
+    uid?: string;
+    roles?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Options for creating an auth middleware via createAuthMiddleware()
+ */
+export interface AuthMiddlewareOptions {
+    /** DataDriver to scope via withAuth() for RLS */
+    driver: DataDriver;
+    /**
+     * Optional per-request driver resolver for multi-data-source backends.
+     * Given the request context, returns the unscoped delegate to use (e.g.
+     * Postgres vs Mongo, picked by the request's collection data source).
+     * When omitted, `driver` is used for every request.
+     */
+    resolveDriver?: (c: Context<HonoEnv>) => DataDriver;
+    /**
+     * If true, return 401 when no valid token is present.
+     *
+     * **Defaults to `true` (secure by default).** Set to `false` only for
+     * intentionally public endpoints where access control is fully delegated
+     * to Postgres Row-Level Security policies.
+     */
+    requireAuth?: boolean;
+    /** Optional custom validator (for non-JWT auth, e.g. external auth providers) */
+    validator?: (c: Context<HonoEnv>) => Promise<AuthResult>;
+    /**
+     * A static secret key for server-to-server / script authentication.
+     *
+     * When a request sends `Authorization: Bearer <key>` and the key matches
+     * this value, the request is granted admin-level access (uid: `service`,
+     * roles: `["admin"]`) **without** JWT verification. The driver is scoped
+     * via `withAuth()` with the service identity.
+     *
+     * This is the Rebase equivalent of a Service Account key.
+     * Set via `REBASE_SERVICE_KEY` in `.env` and pass through the backend config.
+     *
+     * **Security:** The comparison uses constant-time equality to prevent
+     * timing attacks. The key must be at least 32 characters.
+     */
+    serviceKey?: string;
+    /**
+     * API key store for authenticating `rk_` prefixed tokens.
+     * When set, tokens starting with `rk_` are validated against the
+     * database instead of being treated as JWTs.
+     */
+    apiKeyStore?: ApiKeyStore;
+}
+/**
+ * Hono middleware that requires a valid JWT token
+ * Returns 401 if token is missing or invalid
+ */
+export declare const requireAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Factory that creates a requireAuth middleware with optional service key support.
+ *
+ * When `serviceKey` is provided, the middleware will check if the Bearer token
+ * matches the service key using constant-time comparison. If it matches, the
+ * request is authenticated as a service user with admin privileges.
+ *
+ * This allows admin routes (which use standalone requireAuth + requireAdmin)
+ * to be accessed via service keys for scripts and server-to-server calls.
+ */
+export declare function createRequireAuth(options?: {
+    serviceKey?: string;
+}): MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that requires the user to have an admin or schema-admin role.
+ * Must be used AFTER requireAuth or on a route where user is guaranteed.
+ */
+export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that optionally extracts user from JWT
+ * Does not return 401 if token is missing - allows anonymous access
+ */
+export declare const optionalAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Extract user from token - for WebSocket authentication
+ */
+export declare function extractUserFromToken(token: string): AccessTokenPayload | null;
+/**
+ * Create a configurable auth middleware that handles:
+ * 1. Token extraction (via custom validator or JWT Bearer token)
+ * 2. RLS-scoped DataDriver via withAuth()
+ * 3. Enforcement (401 when requireAuth is true and no user)
+ *
+ * **Secure by default:** `requireAuth` defaults to `true`. Anonymous
+ * access is only allowed when the developer explicitly opts out by
+ * setting `requireAuth: false`, indicating that Postgres RLS policies
+ * fully control access.
+ *
+ * **Fail-closed:** The raw unscoped driver is never placed in the
+ * request context. Every code path either scopes via `withAuth()` or
+ * rejects the request. This prevents silent RLS bypass.
+ *
+ * This is the single source of truth for HTTP auth in Rebase.
+ * Use this instead of manually parsing tokens in route handlers.
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;

package/dist/auth/password.d.ts

@@ -0,0 +1,22 @@
+export interface PasswordValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Password requirements:
+ * - Minimum 8 characters
+ * - At least 1 uppercase letter
+ * - At least 1 lowercase letter
+ * - At least 1 number
+ */
+export declare function validatePasswordStrength(password: string): PasswordValidationResult;
+/**
+ * Hash a password using Node's built-in scrypt
+ * Returns format: salt:hash (both hex encoded)
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify a password against a scrypt hash
+ * Expects format: salt:hash (both hex encoded)
+ */
+export declare function verifyPassword(password: string, storedHash: string): Promise<boolean>;

package/dist/auth/rate-limiter.d.ts

@@ -0,0 +1,50 @@
+import { MiddlewareHandler } from "hono";
+import { HonoEnv } from "../api/types";
+interface RateLimiterOptions {
+    /** Time window in milliseconds (default: 15 minutes) */
+    windowMs?: number;
+    /** Maximum requests per window (default: 100) */
+    limit?: number;
+    /** Key generator function. Defaults to IP-based keying. */
+    keyGenerator?: (c: Parameters<MiddlewareHandler<HonoEnv>>[0]) => string;
+    /** Custom message for rate limit responses */
+    message?: string;
+}
+/**
+ * Create a rate-limiting middleware.
+ *
+ * Uses a sliding window algorithm: only timestamps within the last
+ * `windowMs` milliseconds are counted. Old entries are garbage-collected
+ * every `windowMs` to prevent unbounded memory growth.
+ */
+export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured rate limiter for general auth endpoints (login, register).
+ * 200 requests per 15 minutes per IP.
+ */
+export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured strict rate limiter for sensitive endpoints (password reset, verification).
+ * 50 requests per 15 minutes per IP.
+ */
+export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
+/**
+ * Key generator for API-key-based rate limiting.
+ *
+ * Uses the API key ID (from `c.get("apiKey")`) as the rate limit key.
+ * Falls back to IP-based keying when the request is not authenticated
+ * via an API key.
+ */
+export declare function apiKeyKeyGenerator(c: Parameters<MiddlewareHandler<HonoEnv>>[0]): string;
+/**
+ * Create a rate limiter specifically for API key requests.
+ *
+ * When a request is authenticated via an API key that has a `rate_limit`
+ * configured, this limiter enforces per-key limits using the key's ID
+ * as the rate limit bucket.
+ *
+ * @param defaultLimit - Fallback limit when the key has no `rate_limit` set.
+ * @param windowMs     - Time window in milliseconds (default: 15 minutes).
+ */
+export declare function createApiKeyRateLimiter(defaultLimit?: number, windowMs?: number): MiddlewareHandler<HonoEnv>;
+export {};

package/dist/auth/reset-password-admin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Standalone admin endpoint for resetting a user's password.
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onResetPassword` on the collection)
+ * 2. Backend-level hook (`AuthHooks.onAdminResetPassword`)
+ * 3. Built-in default (send reset email, or generate temp password)
+ */
+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 ResetPasswordRouteConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    serviceKey?: string;
+    authHooks?: AuthHooks;
+    /** The parsed auth config from the collection, if available. */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+/**
+ * Create a standalone admin route for resetting user passwords.
+ *
+ * Mounts: POST /users/:userId/reset-password
+ */
+export declare function createResetPasswordRoute(config: ResetPasswordRouteConfig): Hono<HonoEnv>;

package/dist/auth/rls-scope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared RLS (Row-Level Security) scoping helper.
+ *
+ * DataDrivers may implement a `withAuth()` method that returns a scoped
+ * clone of the driver with RLS policies applied for the given user.
+ * This is database-specific (e.g. Postgres SET LOCAL ROLE) and is not
+ * part of the core DataDriver interface.
+ *
+ * This module provides the shared duck-typing logic used by the
+ * adapter-aware middleware.
+ *
+ * @module
+ */
+import type { DataDriver } from "@rebasepro/types";
+/**
+ * Scope a DataDriver via `withAuth()` for RLS.
+ *
+ * SECURITY: If `withAuth()` is available but fails, the error is re-thrown
+ * so the request is **denied** rather than proceeding with unscoped access
+ * (fail-closed behavior).
+ *
+ * If the driver does not support RLS, the original driver is returned.
+ *
+ * @param driver - The DataDriver to scope.
+ * @param user   - The authenticated user identity for RLS.
+ * @returns The RLS-scoped DataDriver (or the original if RLS is unsupported).
+ */
+export declare function scopeDataDriver(driver: DataDriver, user: {
+    uid: string;
+    roles?: string[];
+}): Promise<DataDriver>;

package/dist/auth/routes.d.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthHooks } from "./auth-hooks";
+import { EmailService, EmailConfig } from "../email";
+import { HonoEnv } from "../api/types";
+/**
+ * Shared configuration for auth and admin route factories.
+ */
+export interface AuthModuleConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    /** Allow new user registration (default: false). */
+    allowRegistration?: boolean;
+    /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
+    defaultRole?: string;
+    /** Optional array of OAuth providers */
+    oauthProviders?: OAuthProvider<unknown>[];
+    /** When true, blocks all self-registration regardless of `allowRegistration`. */
+    disableSelfRegistration?: boolean;
+    /**
+     * Auth hooks for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    authHooks?: AuthHooks;
+    /**
+     * Callback that checks if bootstrap has already been completed.
+     * Used by GET /auth/config to report `needsSetup` status.
+     * When not provided, falls back to checking if any users exist.
+     */
+    isBootstrapCompleted?: () => Promise<boolean>;
+    /** Enable magic link (passwordless email) login. Requires email service. */
+    enableMagicLink?: boolean;
+}
+export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

package/dist/auth/session-routes.d.ts

@@ -0,0 +1,27 @@
+import { Hono } from "hono";
+import { z } from "zod";
+import { HonoEnv } from "../api/types";
+import type { AuthModuleConfig } from "./routes";
+import { resolveAuthHooks } from "./auth-hooks";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
+interface SessionRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    buildAuthResponse: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+        photoUrl?: string | null;
+        metadata?: Record<string, unknown> | null;
+    }, roleIds: string[], accessToken: string, refreshToken: string) => unknown;
+    createSessionAndTokens: (userId: string, userAgent: string, ipAddress: string) => Promise<{
+        roleIds: string[];
+        accessToken: string;
+        refreshToken: string;
+    }>;
+    applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, userId: string) => Promise<AuthResponsePayload>;
+}
+export declare function mountSessionRoutes(opts: SessionRoutesConfig): void;
+export {};

package/dist/auth/slack-oauth.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Slack OAuth Provider integration (OAuth 2.0 / "Sign in with Slack").
+ * Uses the OpenID Connect flow with the "openid,email,profile" scopes.
+ */
+export declare function createSlackProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/spotify-oauth.d.ts

@@ -0,0 +1,12 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Spotify OAuth Provider integration.
+ * Uses the authorization code flow with the "user-read-email" scope.
+ */
+export declare function createSpotifyProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+}>;

package/dist/auth/twitter-oauth.d.ts

@@ -0,0 +1,18 @@
+import type { OAuthProvider } from "./interfaces";
+/**
+ * Creates a Twitter/X OAuth 2.0 Provider integration.
+ *
+ * Uses OAuth 2.0 with PKCE (authorization code flow). The frontend must include
+ * the PKCE `code_verifier` when sending the authorization code.
+ *
+ * Twitter API v2 requires the "tweet.read" and "users.read" scopes at minimum,
+ * plus "offline.access" if refresh tokens are needed on Twitter's side.
+ */
+export declare function createTwitterProvider(config: {
+    clientId: string;
+    clientSecret: string;
+}): OAuthProvider<{
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}>;

package/dist/backend-CIxN4FVm.js

@@ -0,0 +1,15 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+__createRequire(import.meta.url);
+//#region ../types/src/types/backend.ts
+/**
+* Type guard: does this admin support SQL operations?
+* @group Admin
+*/
+function isSQLAdmin(admin) {
+	return !!admin && typeof admin.executeSql === "function";
+}
+//#endregion
+export { isSQLAdmin as t };
+
+//# sourceMappingURL=backend-CIxN4FVm.js.map

package/dist/backend-CIxN4FVm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-CIxN4FVm.js","names":[],"sources":["../../types/src/types/backend.ts"],"sourcesContent":["import type { Entity } from \"./entities\";\nimport type { EntityCollection, FilterValues, WhereFilterOp } from \"./collections\";\nimport type { AuthAdapter } from \"./auth_adapter\";\n\n// =============================================================================\n// DATABASE CONNECTION INTERFACES\n// =============================================================================\n\n/**\n * Abstract database connection interface.\n * Represents a connection to any database system.\n */\nexport interface DatabaseConnection {\n    /**\n     * Type identifier for this database (e.g., 'postgres', 'mongodb', 'mysql')\n     */\n    readonly type: string;\n\n    /**\n     * Whether the connection is currently active\n     */\n    readonly isConnected?: boolean;\n\n    /**\n     * Close the database connection and release resources.\n     */\n    close?(): Promise<void>;\n}\n\n// =============================================================================\n// QUERY BUILDING INTERFACES\n// =============================================================================\n\n/**\n * A single filter condition for database queries\n */\nexport interface QueryFilter {\n    field: string;\n    operator: WhereFilterOp;\n    value: unknown;\n}\n\n/**\n * Options for fetching a collection of entities\n */\nexport interface FetchCollectionOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    offset?: number;\n    startAfter?: unknown;\n    searchString?: string;\n    databaseId?: string;\n    collection?: EntityCollection;\n}\n\n/**\n * Options for searching entities\n */\nexport interface SearchOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    databaseId?: string;\n    collection?: EntityCollection;\n}\n\n/**\n * Options for counting entities\n */\nexport interface CountOptions<M extends Record<string, unknown> = Record<string, unknown>> {\n    filter?: FilterValues<Extract<keyof M, string>>;\n    searchString?: string;\n    databaseId?: string;\n}\n\n/**\n * Abstract condition builder interface.\n * Implementations translate Rebase filter conditions to database-specific queries.\n *\n * Note: This interface can be implemented as instance methods or as a class with static methods.\n * For static implementations (like DrizzleConditionBuilder), use the ConditionBuilderStatic type.\n *\n * @template T The type of condition returned by the builder (e.g., SQL for PostgreSQL, Filter<Document> for MongoDB)\n */\nexport interface ConditionBuilder<T = unknown> {\n    /**\n     * Build filter conditions from Rebase FilterValues\n     */\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        collectionPath: string,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Build search conditions for text search\n     */\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n\n    /**\n     * Combine multiple conditions with AND operator\n     */\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n\n    /**\n     * Combine multiple conditions with OR operator\n     */\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n}\n\n/**\n * Static condition builder type for implementations using static methods.\n * Use this type when the class provides static methods rather than instance methods.\n *\n * @example\n * // DrizzleConditionBuilder satisfies this type\n * const builder: ConditionBuilderStatic<SQL> = DrizzleConditionBuilder;\n */\nexport type ConditionBuilderStatic<T = unknown> = {\n    buildFilterConditions<M extends Record<string, unknown>>(\n        filter: FilterValues<Extract<keyof M, string>>,\n        ...args: unknown[]\n    ): T[];\n    buildSearchConditions(\n        searchString: string,\n        properties: Record<string, unknown>,\n        ...args: unknown[]\n    ): T[];\n    combineConditionsWithAnd(conditions: T[]): T | undefined;\n    combineConditionsWithOr(conditions: T[]): T | undefined;\n};\n\n// =============================================================================\n// ENTITY REPOSITORY INTERFACES\n// =============================================================================\n\n/**\n * Abstract entity repository interface.\n * Handles all CRUD operations for entities in the database.\n *\n * Implementations should handle:\n * - Entity serialization/deserialization\n * - Relation resolution\n * - ID generation and conversion\n */\nexport interface EntityRepository {\n    /**\n     * Fetch a single entity by ID\n     */\n    fetchEntity<M extends Record<string, unknown>>(\n        collectionPath: string,\n        entityId: string | number,\n        databaseId?: string\n    ): Promise<Entity<M> | undefined>;\n\n    /**\n     * Fetch a collection of entities with optional filtering, ordering, and pagination\n     */\n    fetchCollection<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: FetchCollectionOptions<M>\n    ): Promise<Entity<M>[]>;\n\n    /**\n     * Search entities by text\n     */\n    searchEntities<M extends Record<string, unknown>>(\n        collectionPath: string,\n        searchString: string,\n        options?: SearchOptions<M>\n    ): Promise<Entity<M>[]>;\n\n    /**\n     * Count entities in a collection\n     */\n    countEntities<M extends Record<string, unknown>>(\n        collectionPath: string,\n        options?: CountOptions<M>\n    ): Promise<number>;\n\n    /**\n     * Save an entity (create or update)\n     */\n    saveEntity<M extends Record<string, unknown>>(\n        collectionPath: string,\n        values: Partial<M>,\n        entityId?: string | number,\n        databaseId?: string\n    ): Promise<Entity<M>>;\n\n    /**\n     * Delete an entity by ID\n     */\n    deleteEntity(\n        collectionPath: string,\n        entityId: string | number,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Check if a field value is unique in a collection\n     */\n    checkUniqueField(\n        collectionPath: string,\n        fieldName: string,\n        value: unknown,\n        excludeEntityId?: string,\n        databaseId?: string\n    ): Promise<boolean>;\n\n}\n\n// =============================================================================\n// REALTIME INTERFACES\n// =============================================================================\n\n/**\n * Configuration for subscribing to a collection\n */\nexport interface CollectionSubscriptionConfig {\n    clientId: string;\n    path: string;\n    filter?: unknown;\n    orderBy?: string;\n    order?: \"desc\" | \"asc\";\n    limit?: number;\n    startAfter?: unknown;\n    databaseId?: string;\n    searchString?: string;\n}\n\n/**\n * Configuration for subscribing to a single entity\n */\nexport interface EntitySubscriptionConfig {\n    clientId: string;\n    path: string;\n    entityId: string | number;\n}\n\n/**\n * Abstract realtime provider interface.\n * Handles real-time subscriptions and notifications for entity changes.\n */\nexport interface RealtimeProvider {\n    /**\n     * Subscribe to collection changes\n     */\n    subscribeToCollection(\n        subscriptionId: string,\n        config: CollectionSubscriptionConfig,\n        callback?: (entities: Entity[]) => void\n    ): void;\n\n    /**\n     * Subscribe to single entity changes\n     */\n    subscribeToEntity(\n        subscriptionId: string,\n        config: EntitySubscriptionConfig,\n        callback?: (entity: Entity | null) => void\n    ): void;\n\n    /**\n     * Unsubscribe from a subscription\n     */\n    unsubscribe(subscriptionId: string): void;\n\n    /**\n     * Notify all relevant subscribers of an entity update\n     */\n    notifyEntityUpdate(\n        path: string,\n        entityId: string,\n        entity: Entity | null,\n        databaseId?: string\n    ): Promise<void>;\n\n    /**\n     * Called when the HTTP server is ready and listening.\n     * Useful for providers that need the server address for callbacks.\n     */\n    onServerReady?(serverInfo: { port: number; hostname?: string }): void;\n\n    /**\n     * Gracefully shut down the realtime provider.\n     * Called during server shutdown to clean up resources.\n     */\n    destroy?(): Promise<void>;\n\n    /**\n     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).\n     * Called during graceful shutdown before closing database connections.\n     */\n    stopListening?(): Promise<void>;\n}\n\n// =============================================================================\n// COLLECTION REGISTRY INTERFACES\n// =============================================================================\n\n/**\n * Abstract collection registry interface.\n * Manages registration and lookup of entity collections.\n */\nexport interface CollectionRegistryInterface {\n    /**\n     * Register a collection\n     */\n    register(collection: EntityCollection): void;\n\n    /**\n     * Get a collection by its path\n     */\n    getCollectionByPath(path: string): EntityCollection | undefined;\n\n    /**\n     * Get all registered collections\n     */\n    getCollections(): EntityCollection[];\n\n    /**\n     * Get the currently registered global callbacks, if any.\n     */\n    getGlobalCallbacks(): any | undefined;\n}\n\n// =============================================================================\n// DATA TRANSFORMER INTERFACES\n// =============================================================================\n\n/**\n * Abstract data transformer interface.\n * Handles serialization/deserialization between frontend and database formats.\n */\nexport interface DataTransformer {\n    /**\n     * Transform entity data for storage in the database\n     */\n    serializeToDatabase<M extends Record<string, unknown>>(\n        entity: M,\n        collection: EntityCollection\n    ): Record<string, unknown>;\n\n    /**\n     * Transform database data back to entity format\n     */\n    deserializeFromDatabase<M extends Record<string, unknown>>(\n        data: Record<string, unknown>,\n        collection: EntityCollection\n    ): Promise<M>;\n}\n\n// =============================================================================\n// DATABASE ADMIN — CAPABILITY-SPECIFIC INTERFACES (1.3)\n// =============================================================================\n\n/**\n * Administrative operations for SQL-based databases (PostgreSQL, MySQL, etc.).\n * Used by the SQL Editor, RLS Editor, and schema browser.\n *\n * @group Admin\n */\nexport interface SQLAdmin {\n    /**\n     * Execute raw SQL against the database.\n     */\n    executeSql(sql: string, options?: { database?: string; role?: string; params?: unknown[] }): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch the available databases on the server.\n     */\n    fetchAvailableDatabases?(): Promise<string[]>;\n\n    /**\n     * Fetch the available database roles.\n     */\n    fetchAvailableRoles?(): Promise<string[]>;\n\n    /**\n     * Fetch the current database name.\n     */\n    fetchCurrentDatabase?(): Promise<string | undefined>;\n}\n\n/**\n * Administrative operations for document-based databases (MongoDB, Firestore, etc.).\n * Used by future document administration tools.\n *\n * @group Admin\n */\nexport interface DocumentAdmin {\n    /**\n     * Execute an aggregation pipeline or equivalent query.\n     */\n    executeAggregate?(pipeline: Record<string, unknown>[]): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Fetch statistics for a collection (document count, size, etc.).\n     */\n    fetchCollectionStats?(collectionName: string): Promise<{ count: number; sizeBytes?: number }>;\n}\n\n/**\n * Administrative operations for schema management.\n * Shared across SQL and document databases.\n *\n * @group Admin\n */\nexport interface SchemaAdmin {\n    /**\n     * Fetch database tables/collections not yet mapped to a Rebase collection.\n     */\n    fetchUnmappedTables?(mappedPaths?: string[]): Promise<string[]>;\n\n    /**\n     * Fetch column/field metadata for a single table/collection.\n     * The return type is generic — SQL backends return TableMetadata,\n     * document backends may return a different shape.\n     */\n    fetchTableMetadata?(tableName: string): Promise<unknown>;\n}\n\n/**\n * Metadata for a database branch.\n * @group Admin\n */\nexport interface BranchInfo {\n    /** Branch name (without prefix). */\n    name: string;\n    /** The database this branch was created from. */\n    parentDatabase: string;\n    /** When the branch was created. */\n    createdAt: Date;\n    /** Size in bytes, if available from the server. */\n    sizeBytes?: number;\n}\n\n/**\n * Administrative operations for database branching.\n * Allows creating isolated database copies for development/preview workflows.\n *\n * @group Admin\n */\nexport interface BranchAdmin {\n    /** Create a new branch (database copy) from the current or specified source database. */\n    createBranch(name: string, options?: { source?: string }): Promise<BranchInfo>;\n\n    /** Delete a branch database. Cannot delete the main/default database. */\n    deleteBranch(name: string): Promise<void>;\n\n    /** List all branches (databases that were created via branching). */\n    listBranches(): Promise<BranchInfo[]>;\n\n    /** Get info about a specific branch. */\n    getBranchInfo(name: string): Promise<BranchInfo | undefined>;\n}\n\n/**\n * Union type for all admin capabilities.\n * A backend may implement any combination of these interfaces.\n *\n * Use type guards (`isSQLAdmin`, `isDocumentAdmin`, `isSchemaAdmin`, `isBranchAdmin`)\n * to safely narrow the type before calling methods.\n *\n * @group Admin\n */\nexport type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin> & Partial<BranchAdmin>;\n\n/**\n * Type guard: does this admin support SQL operations?\n * @group Admin\n */\nexport function isSQLAdmin(admin: DatabaseAdmin | undefined): admin is SQLAdmin {\n    return !!admin && typeof (admin as SQLAdmin).executeSql === \"function\";\n}\n\n/**\n * Type guard: does this admin support document operations?\n * @group Admin\n */\nexport function isDocumentAdmin(admin: DatabaseAdmin | undefined): admin is DocumentAdmin {\n    return !!admin && (\n        typeof (admin as DocumentAdmin).executeAggregate === \"function\" ||\n        typeof (admin as DocumentAdmin).fetchCollectionStats === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support schema management?\n * @group Admin\n */\nexport function isSchemaAdmin(admin: DatabaseAdmin | undefined): admin is SchemaAdmin {\n    return !!admin && (\n        typeof (admin as SchemaAdmin).fetchUnmappedTables === \"function\" ||\n        typeof (admin as SchemaAdmin).fetchTableMetadata === \"function\"\n    );\n}\n\n/**\n * Type guard: does this admin support database branching?\n * @group Admin\n */\nexport function isBranchAdmin(admin: DatabaseAdmin | undefined): admin is BranchAdmin {\n    return !!admin && typeof (admin as BranchAdmin).createBranch === \"function\";\n}\n\n// =============================================================================\n// LIFECYCLE INTERFACES (1.4)\n// =============================================================================\n\n/**\n * Health check result returned by `healthCheck()`.\n * @group Lifecycle\n */\nexport interface HealthCheckResult {\n    /** Whether the backend is healthy and able to serve requests. */\n    healthy: boolean;\n    /** Round-trip latency to the database in milliseconds. */\n    latencyMs: number;\n    /** Optional details (e.g., pool stats, replication lag). */\n    details?: Record<string, unknown>;\n}\n\n/**\n * Lifecycle contract for backend components that hold resources\n * (database connections, WebSocket pools, timers, etc.).\n *\n * All methods are optional — simple backends (e.g., in-memory) can skip them.\n * @group Lifecycle\n */\nexport interface BackendLifecycle {\n    /**\n     * Initialize the backend: open connections, run migrations, seed data.\n     * Called once during startup. Idempotent.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Check whether the backend is healthy and reachable.\n     * Should be fast (< 1 s) and safe to call frequently.\n     */\n    healthCheck?(): Promise<HealthCheckResult>;\n\n    /**\n     * Gracefully shut down: close connections, flush buffers, cancel timers.\n     * After calling `destroy()`, no other methods should be called.\n     */\n    destroy?(): Promise<void>;\n}\n\n// =============================================================================\n// BACKEND FACTORY INTERFACES\n// =============================================================================\n\n/**\n * Configuration for creating a database backend\n */\nexport interface BackendConfig {\n    /**\n     * Type of database backend\n     */\n    type: string;\n\n    /**\n     * Database connection (implementation-specific)\n     */\n    connection: unknown;\n\n    /**\n     * Schema definition (implementation-specific, e.g., Drizzle schema for PostgreSQL)\n     */\n    schema?: unknown;\n}\n\n/**\n * A complete backend instance with all required services.\n *\n * Now includes optional lifecycle management and admin capabilities.\n */\nexport interface BackendInstance extends BackendLifecycle {\n    /**\n     * Entity repository for CRUD operations\n     */\n    entityRepository: EntityRepository;\n\n    /**\n     * Realtime provider for subscriptions\n     */\n    realtimeProvider: RealtimeProvider;\n\n    /**\n     * Collection registry\n     */\n    collectionRegistry: CollectionRegistryInterface;\n\n    /**\n     * The underlying database connection\n     */\n    connection: DatabaseConnection;\n\n    /**\n     * Administrative operations (SQL, schema, documents).\n     * What's available depends on the backend type — use type guards\n     * (`isSQLAdmin`, `isSchemaAdmin`, etc.) to narrow.\n     */\n    admin?: DatabaseAdmin;\n}\n\n/**\n * Factory function type for creating backend instances\n */\nexport type BackendFactory<TConfig extends BackendConfig = BackendConfig> =\n    (config: TConfig) => BackendInstance;\n\n// =============================================================================\n// BACKEND BOOTSTRAPPER (1.2)\n// =============================================================================\n\n/**\n * A `BackendBootstrapper` encapsulates all driver-specific initialization logic.\n *\n * Instead of hard-coding Postgres setup into `initializeRebaseBackend()`,\n * each database backend provides its own bootstrapper that knows how to:\n * - Create the DataDriver from a config object\n * - Optionally initialize auth tables\n * - Optionally create a realtime service\n * - Mount driver-specific API routes\n *\n * The main `initializeRebaseBackend()` becomes a **coordinator** that iterates\n * registered bootstrappers, calls their hooks, and wires the results together.\n *\n * @group Backend\n *\n * @example\n * ```typescript\n * // Third-party MySQL bootstrapper\n * const mysqlBootstrapper: BackendBootstrapper = {\n *   type: \"mysql\",\n *   initializeDriver: async (config) => new MySQLDataDriver(config.connection),\n *   initializeRealtime: async (config) => new MySQLChangeStreamRealtime(config.connection),\n * };\n *\n * initializeRebaseBackend({\n *   ...config,\n *   bootstrappers: [postgresBootstrapper, mysqlBootstrapper]\n * });\n * ```\n */\nexport interface BackendBootstrapper {\n    /**\n     * Which driver type this bootstrapper handles.\n     * Must match the `type` field on the driver config object\n     * (e.g., `\"postgres\"`, `\"mongodb\"`, `\"mysql\"`).\n     */\n    type: string;\n\n    /**\n     * Unique identifier for this bootstrapper instance.\n     * Used to register the driver in the driver registry.\n     * Defaults to `type` if not set.\n     */\n    id?: string;\n\n    /**\n     * Whether this bootstrapper provides the default driver.\n     * When true, the coordinator uses this driver as the primary one.\n     */\n    isDefault?: boolean;\n\n    /**\n     * Run database migrations for this driver.\n     * Called by the coordinator after all drivers are initialized.\n     */\n    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;\n\n    /**\n     * Create a DataDriver from the given config.\n     * This is the only **required** method.\n     */\n    initializeDriver(config: unknown): Promise<InitializedDriver>;\n\n    /**\n     * Initialize auth tables / services if this driver supports them.\n     * Return undefined if auth is not supported by this backend.\n     */\n    initializeAuth?(config: unknown, driverResult: InitializedDriver): Promise<BootstrappedAuth | undefined>;\n\n    /**\n     * Initialize history tables / services if this driver supports them.\n     * Return undefined if history is not supported by this backend.\n     */\n    initializeHistory?(config: unknown, driverResult: InitializedDriver): Promise<{ historyService: unknown } | undefined>;\n\n    /**\n     * Create a realtime provider for this driver.\n     * Return undefined if the driver does not support realtime.\n     */\n    initializeRealtime?(config: unknown, driverResult: InitializedDriver): Promise<RealtimeProvider | undefined>;\n\n    /**\n     * Mount any driver-specific HTTP routes (e.g., custom admin endpoints).\n     * Called after all drivers are initialized.\n     */\n    mountRoutes?(app: unknown, basePath: string, driverResult: InitializedDriver): void;\n\n    /**\n     * Return admin capabilities for this driver.\n     */\n    getAdmin?(driverResult: InitializedDriver): DatabaseAdmin | undefined;\n\n    /**\n     * Initialize WebSocket server for realtime operations.\n     */\n    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import(\"../controllers/data_driver\").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeDriver()`.\n * @group Backend\n */\nexport interface InitializedDriver {\n    /** The DataDriver instance, ready for use. */\n    driver: import(\"../controllers/data_driver\").DataDriver;\n\n    /** The realtime service, if the driver created one during init. */\n    realtimeProvider?: RealtimeProvider;\n\n    /** A collection registry to register schema / tables into. */\n    collectionRegistry?: CollectionRegistryInterface;\n\n    /** The underlying database connection (for lifecycle management). */\n    connection?: DatabaseConnection;\n\n    /**\n     * Opaque handle that the bootstrapper can use in subsequent hooks\n     * (e.g., `initializeAuth`, `mountRoutes`) to access driver internals.\n     * Not used by the coordinator.\n     */\n    internals?: unknown;\n}\n\n/**\n * Result of `BackendBootstrapper.initializeAuth()`.\n * @group Backend\n */\nexport interface BootstrappedAuth {\n    /** User management service. */\n    userService: unknown;\n    /** Role management service (optional, roles are now simple strings). */\n    roleService?: unknown;\n    /** Email service (optional). */\n    emailService?: unknown;\n    /** Combined Auth Repository for unified token and user management. */\n    authRepository?: unknown;\n}\n"],"mappings":";;;;;;;;AAgeA,SAAgB,WAAW,OAAqD;CAC5E,OAAO,CAAC,CAAC,SAAS,OAAQ,MAAmB,eAAe;AAChE"}