@rebasepro/server-core 0.2.3 → 0.2.4

package/dist/server-core/src/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/server-core/src/api/rest/api-generator.d.ts

@@ -17,6 +17,12 @@ export declare class RestApiGenerator {
      * 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 typed RestFetchService from a driver if it exposes one (for include support).
      */

package/dist/server-core/src/api/types.d.ts

@@ -1,7 +1,8 @@
-import { EntityCollection } from "@rebasepro/types";
+import { EntityCollection, VectorSearchParams } from "@rebasepro/types";
 import { AuthResult } from "../auth/middleware";
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
 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()`
@@ -13,6 +14,8 @@ export type HonoEnv = {
             roles?: string[];
         };
         driver?: DataDriver;
+        /** Set when the request is authenticated via a Service API Key. */
+        apiKey?: ApiKeyMasked;
     };
 };
 /**
@@ -79,6 +82,8 @@ export interface QueryOptions {
     include?: string[];
     /** Columns to return in the response (field-level selection) */
     fields?: string[];
+    /** Vector similarity search configuration */
+    vectorSearch?: VectorSearchParams;
 }
 /**
  * Relation resolution configuration

package/dist/server-core/src/auth/adapter-middleware.d.ts

@@ -6,9 +6,10 @@
  * an `AuthAdapter` to `initializeRebaseBackend()`.
  *
  * The middleware:
- * 1. Calls `adapter.verifyRequest(request)` to resolve the user
- * 2. Scopes the DataDriver via `withAuth()` for RLS
- * 3. Enforces auth (401) when `requireAuth` is true and no user is found
+ * 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.
@@ -16,6 +17,7 @@
 import type { MiddlewareHandler } 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;
@@ -26,6 +28,8 @@ export interface AdapterAuthMiddlewareOptions {
      * 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.

package/dist/server-core/src/auth/admin-routes.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import type { AuthOverrides } from "./auth-overrides";
+import type { AuthHooks } from "./auth-hooks";
 import { AuthModuleConfig } from "./routes";
 import type { BackendHooks } from "@rebasepro/types";
 interface AdminRouteOptions extends AuthModuleConfig {
@@ -14,10 +14,10 @@ interface AdminRouteOptions extends AuthModuleConfig {
      */
     hooks?: BackendHooks;
     /**
-     * Auth overrides for customizing password hashing, credential
+     * Auth hooks for customizing password hashing, credential
      * verification, lifecycle hooks, etc.
      */
-    overrides?: AuthOverrides;
+    authHooks?: AuthHooks;
 }
 import { HonoEnv } from "../api/types";
 /**

package/dist/server-core/src/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/server-core/src/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/server-core/src/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/server-core/src/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;

package/dist/server-core/src/auth/api-keys/api-key-types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Type definitions for Service API Keys.
+ *
+ * API keys provide machine-to-machine authentication for scripts, cron jobs,
+ * and third-party integrations. Each key is scoped to specific collections
+ * and operations via the `ApiKeyPermission` model.
+ *
+ * @module
+ */
+/**
+ * A single permission entry scoping an API key to a collection and set of operations.
+ *
+ * Use `"*"` as the collection value to grant access to all collections.
+ */
+export interface ApiKeyPermission {
+    /** Collection slug, or `"*"` for all collections. */
+    collection: string;
+    /** Allowed operations on the collection. */
+    operations: ("read" | "write" | "delete")[];
+}
+/**
+ * Full database row for an API key.
+ * The `key_hash` is never exposed via the API — only stored for lookup.
+ */
+export interface ApiKey {
+    id: string;
+    name: string;
+    /** First 12 characters of the plaintext key, for display only. */
+    key_prefix: string;
+    /** SHA-256 hash of the full plaintext key. */
+    key_hash: string;
+    permissions: ApiKeyPermission[];
+    /** Requests per 15-minute window. `null` means unlimited. */
+    rate_limit: number | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+/**
+ * Masked version of an API key, safe for API responses.
+ * Omits `key_hash` and shows only the prefix.
+ */
+export interface ApiKeyMasked {
+    id: string;
+    name: string;
+    key_prefix: string;
+    permissions: ApiKeyPermission[];
+    rate_limit: number | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+}
+/**
+ * Request body for creating a new API key.
+ */
+export interface CreateApiKeyRequest {
+    name: string;
+    permissions: ApiKeyPermission[];
+    /** Requests per 15-minute window. Omit or `null` for unlimited. */
+    rate_limit?: number | null;
+    /** ISO-8601 expiration timestamp. Omit for no expiration. */
+    expires_at?: string | null;
+}
+/**
+ * Request body for updating an existing API key.
+ * All fields are optional — only provided fields are updated.
+ */
+export interface UpdateApiKeyRequest {
+    name?: string;
+    permissions?: ApiKeyPermission[];
+    rate_limit?: number | null;
+    expires_at?: string | null;
+}
+/**
+ * Returned exactly once when a key is created.
+ * The `key` field contains the full plaintext key — it is never stored
+ * or returned again after creation.
+ */
+export interface ApiKeyWithSecret extends ApiKeyMasked {
+    /** Full plaintext API key (e.g. `rk_live_abc123...`). */
+    key: string;
+}

package/dist/server-core/src/auth/api-keys/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Service API Keys module.
+ *
+ * Re-exports types, store, middleware, permission guard, and routes
+ * for the API key authentication system.
+ *
+ * @module
+ */
+export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, } from "./api-key-types";
+export { createApiKeyStore } from "./api-key-store";
+export type { ApiKeyStore } from "./api-key-store";
+export { isApiKeyToken, validateApiKey } from "./api-key-middleware";
+export type { ApiKeyAuthOptions } from "./api-key-middleware";
+export { httpMethodToOperation, isOperationAllowed, } from "./api-key-permission-guard";
+export type { ApiKeyOperation } from "./api-key-permission-guard";
+export { createApiKeyRoutes } from "./api-key-routes";
+export type { ApiKeyRouteOptions } from "./api-key-routes";

package/dist/server-core/src/auth/{auth-overrides.d.ts → auth-hooks.d.ts}

@@ -1,20 +1,20 @@
 /**
- * AuthOverrides
+ * AuthHooks
  *
- * Override specific behaviors of the built-in Rebase auth system.
+ * Customize specific behaviors of the built-in Rebase auth system.
  *
  * Each method replaces one piece of the default implementation.
  * Unset methods fall through to the built-in defaults (scrypt passwords,
  * standard validation rules, etc.).
  *
- * This interface is intentionally open for extension — new overrides
+ * This interface is intentionally open for extension — new hooks
  * can be added as optional methods without breaking existing configurations.
  *
  * @example bcrypt password support
  * ```ts
  * import bcrypt from "bcrypt";
  *
- * const overrides: AuthOverrides = {
+ * const hooks: AuthHooks = {
  *     hashPassword: (pw) => bcrypt.hash(pw, 12),
  *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
  *     validatePasswordStrength: (pw) => ({
@@ -26,7 +26,7 @@
  *
  * @example Override the entire login credential check
  * ```ts
- * const overrides: AuthOverrides = {
+ * const hooks: AuthHooks = {
  *     verifyCredentials: async (email, password, repo) => {
  *         const user = await repo.getUserByEmail(email);
  *         if (!user || !user.passwordHash) return null;
@@ -41,14 +41,14 @@ import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
 /**
  * Authentication method identifier for lifecycle hooks.
  */
-export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset";
+export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset" | "anonymous" | "magic-link" | "mfa";
 /**
- * Override specific parts of the built-in Rebase auth implementation.
+ * Hook specific parts of the built-in Rebase auth implementation.
  *
  * Every method is optional. The built-in defaults apply for any method
  * that is not provided.
  */
-export interface AuthOverrides {
+export interface AuthHooks {
     /**
      * Hash a cleartext password for storage.
      *
@@ -118,10 +118,68 @@ export interface AuthOverrides {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserCreate?(user: UserData): Promise<void>;
+    /**
+     * Pre-login validation. Called before credential verification.
+     *
+     * Throw an error to reject the login attempt (e.g. for account lockout,
+     * IP-based restrictions, etc.).
+     */
+    beforeLogin?(email: string, method: AuthMethod): Promise<void>;
+    /**
+     * Post-logout cleanup.
+     *
+     * Called after a user's session has been invalidated.
+     * Use for audit logging, cleanup of temporary resources, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterLogout?(userId: string): Promise<void>;
+    /**
+     * Called after successful MFA verification.
+     *
+     * Use for audit logging, notifying external systems, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onMfaVerified?(userId: string, factorId: string): Promise<void>;
+    /**
+     * Customize JWT access token claims before signing.
+     *
+     * Return the modified claims object. The returned claims are merged
+     * into the JWT payload alongside standard claims (userId, roles).
+     *
+     * @param claims - The default claims that would be included.
+     * @param user - The authenticated user data.
+     * @returns Modified claims to include in the JWT.
+     */
+    customizeAccessToken?(claims: Record<string, unknown>, user: UserData): Promise<Record<string, unknown>>;
+    /**
+     * Called after a successful password reset.
+     *
+     * Use for audit logging, sending confirmation notifications, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onPasswordReset?(userId: string): Promise<void>;
+    /**
+     * Called before a user is deleted.
+     *
+     * Throw an error to prevent deletion (e.g. for users with active
+     * subscriptions, pending transactions, etc.).
+     */
+    beforeUserDelete?(userId: string): Promise<void>;
+    /**
+     * Called after a user is deleted.
+     *
+     * Use for cleaning up external resources, audit logging, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterUserDelete?(userId: string): Promise<void>;
 }
 /**
  * Resolved auth operations — every method is guaranteed to exist.
- * Created by `resolveAuthOverrides()` which merges user overrides
+ * Created by `resolveAuthHooks()` which merges user hooks
  * with built-in defaults.
  */
 export interface ResolvedAuthOperations {
@@ -130,10 +188,10 @@ export interface ResolvedAuthOperations {
     validatePasswordStrength(password: string): PasswordValidationResult;
 }
 /**
- * Merge user-provided overrides with the built-in defaults to produce
+ * Merge user-provided hooks with the built-in defaults to produce
  * a complete set of resolved operations.
  *
  * This is the single point where defaults are applied — all consumers
  * call this once and use the resolved operations throughout.
  */
-export declare function resolveAuthOverrides(overrides?: AuthOverrides): ResolvedAuthOperations;
+export declare function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthOperations;

package/dist/server-core/src/auth/builtin-auth-adapter.d.ts

@@ -11,7 +11,7 @@
  */
 import type { AuthAdapter, BackendHooks } from "@rebasepro/types";
 import type { AuthRepository, OAuthProvider } from "./interfaces";
-import type { AuthOverrides } from "./auth-overrides";
+import type { AuthHooks } from "./auth-hooks";
 import type { EmailService, EmailConfig } from "../email";
 /**
  * Configuration for the built-in Rebase auth adapter.
@@ -36,8 +36,8 @@ export interface BuiltinAuthAdapterConfig {
     serviceKey?: string;
     /** Backend hooks for intercepting admin data. */
     hooks?: BackendHooks;
-    /** Auth overrides for customizing password, credentials, lifecycle, etc. */
-    overrides?: AuthOverrides;
+    /** Auth hooks for customizing password, credentials, lifecycle, etc. */
+    authHooks?: AuthHooks;
 }
 /**
  * Create the built-in Rebase auth adapter.

package/dist/server-core/src/auth/index.d.ts

@@ -3,8 +3,8 @@ export { configureJwt, generateAccessToken, verifyAccessToken, generateRefreshTo
 export type { JwtConfig, AccessTokenPayload } from "./jwt";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export type { PasswordValidationResult } from "./password";
-export type { AuthOverrides, AuthMethod, ResolvedAuthOperations } from "./auth-overrides";
-export { resolveAuthOverrides } from "./auth-overrides";
+export type { AuthHooks, AuthMethod, ResolvedAuthOperations } from "./auth-hooks";
+export { resolveAuthHooks } from "./auth-hooks";
 export { createGoogleProvider } from "./google-oauth";
 export type { GoogleProviderConfig } from "./google-oauth";
 export { createLinkedinProvider } from "./linkedin-oauth";
@@ -23,7 +23,9 @@ export type { AuthMiddlewareOptions, AuthResult } from "./middleware";
 export { createAuthRoutes } from "./routes";
 export type { AuthModuleConfig } from "./routes";
 export { createAdminRoutes } from "./admin-routes";
-export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter } from "./rate-limiter";
+export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter, createApiKeyRateLimiter, apiKeyKeyGenerator } from "./rate-limiter";
+export { createApiKeyStore, createApiKeyRoutes, isApiKeyToken, validateApiKey, httpMethodToOperation, isOperationAllowed } from "./api-keys";
+export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest, ApiKeyStore, ApiKeyOperation } from "./api-keys";
 export { createBuiltinAuthAdapter } from "./builtin-auth-adapter";
 export type { BuiltinAuthAdapterConfig } from "./builtin-auth-adapter";
 export { createCustomAuthAdapter } from "./custom-auth-adapter";

package/dist/server-core/src/auth/interfaces.d.ts

@@ -18,6 +18,7 @@ export interface UserData {
     emailVerified: boolean;
     emailVerificationToken?: string | null;
     emailVerificationSentAt?: Date | null;
+    isAnonymous?: boolean;
     metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
@@ -31,6 +32,7 @@ export interface CreateUserData {
     displayName?: string;
     photoUrl?: string;
     emailVerified?: boolean;
+    isAnonymous?: boolean;
     metadata?: Record<string, unknown>;
 }
 /**
@@ -84,7 +86,6 @@ export interface RoleData {
         edit?: boolean;
         delete?: boolean;
     }> | null;
-    config: Record<string, unknown> | null;
 }
 /**
  * Data for creating a new role
@@ -95,7 +96,6 @@ export interface CreateRoleData {
     isAdmin?: boolean;
     defaultPermissions?: RoleData["defaultPermissions"];
     collectionPermissions?: RoleData["collectionPermissions"];
-    config?: RoleData["config"];
 }
 /**
  * Refresh token info
@@ -304,8 +304,98 @@ export interface TokenRepository {
      */
     deleteExpiredTokens(): Promise<void>;
 }
+/**
+ * MFA factor data structure
+ */
+export interface MfaFactor {
+    id: string;
+    userId: string;
+    factorType: "totp";
+    friendlyName?: string;
+    verified: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * MFA challenge information
+ */
+export interface MfaChallengeInfo {
+    id: string;
+    factorId: string;
+    createdAt: Date;
+    verifiedAt?: Date;
+    ipAddress?: string;
+}
+/**
+ * Recovery code data structure
+ */
+export interface RecoveryCode {
+    id: string;
+    userId: string;
+    usedAt?: Date;
+}
+/**
+ * Abstract MFA repository interface.
+ * Handles all MFA-related database operations.
+ */
+export interface MfaRepository {
+    /**
+     * Create a new MFA factor for a user
+     */
+    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    /**
+     * Get all MFA factors for a user
+     */
+    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    /**
+     * Get a specific MFA factor by ID
+     */
+    getMfaFactorById(factorId: string): Promise<(MfaFactor & {
+        secretEncrypted: string;
+    }) | null>;
+    /**
+     * Mark an MFA factor as verified
+     */
+    verifyMfaFactor(factorId: string): Promise<void>;
+    /**
+     * Delete an MFA factor
+     */
+    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    /**
+     * Create an MFA challenge
+     */
+    createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
+    /**
+     * Get an MFA challenge by ID
+     */
+    getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
+    /**
+     * Mark an MFA challenge as verified
+     */
+    verifyMfaChallenge(challengeId: string): Promise<void>;
+    /**
+     * Create recovery codes for a user
+     */
+    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
+    /**
+     * Use a recovery code (mark as used)
+     */
+    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
+    /**
+     * Get unused recovery code count for a user
+     */
+    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
+    /**
+     * Delete all recovery codes for a user
+     */
+    deleteAllRecoveryCodes(userId: string): Promise<void>;
+    /**
+     * Check if a user has any verified MFA factors
+     */
+    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+}
 /**
  * Combined auth repository interface for convenience
  */
-export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository {
+export interface AuthRepository extends UserRepository, RoleRepository, TokenRepository, MfaRepository {
 }