@rebasepro/server-core 0.1.2 → 0.2.1

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

@@ -0,0 +1,33 @@
+/**
+ * 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. 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
+ *
+ * The behavior is identical to `createAuthMiddleware()` — only the
+ * token verification strategy is pluggable.
+ */
+import type { MiddlewareHandler } from "hono";
+import type { DataDriver, AuthAdapter } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types";
+export interface AdapterAuthMiddlewareOptions {
+    /** The auth adapter to delegate verification to. */
+    adapter: AuthAdapter;
+    /** The DataDriver to scope via withAuth() for RLS. */
+    driver: DataDriver;
+    /**
+     * If true, return 401 when no valid user is resolved.
+     * Defaults to `true` (secure by default).
+     */
+    requireAuth?: boolean;
+}
+/**
+ * Create a Hono middleware that uses an `AuthAdapter` for request verification.
+ */
+export declare function createAdapterAuthMiddleware(options: AdapterAuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;

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

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import type { AuthOverrides } from "./auth-overrides";
 import { AuthModuleConfig } from "./routes";
 import type { BackendHooks } from "@rebasepro/types";
 interface AdminRouteOptions extends AuthModuleConfig {
@@ -12,6 +13,11 @@ interface AdminRouteOptions extends AuthModuleConfig {
      * Backend-level hooks for intercepting admin data.
      */
     hooks?: BackendHooks;
+    /**
+     * Auth overrides for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    overrides?: AuthOverrides;
 }
 import { HonoEnv } from "../api/types";
 /**

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

@@ -0,0 +1,139 @@
+/**
+ * AuthOverrides
+ *
+ * Override 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
+ * can be added as optional methods without breaking existing configurations.
+ *
+ * @example bcrypt password support
+ * ```ts
+ * import bcrypt from "bcrypt";
+ *
+ * const overrides: AuthOverrides = {
+ *     hashPassword: (pw) => bcrypt.hash(pw, 12),
+ *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
+ *     validatePasswordStrength: (pw) => ({
+ *         valid: pw.length >= 6,
+ *         errors: pw.length < 6 ? ["Password must be at least 6 characters"] : []
+ *     })
+ * };
+ * ```
+ *
+ * @example Override the entire login credential check
+ * ```ts
+ * const overrides: AuthOverrides = {
+ *     verifyCredentials: async (email, password, repo) => {
+ *         const user = await repo.getUserByEmail(email);
+ *         if (!user || !user.passwordHash) return null;
+ *         const valid = await myCustomVerify(password, user.passwordHash);
+ *         return valid ? user : null;
+ *     }
+ * };
+ * ```
+ */
+import type { PasswordValidationResult } from "./password";
+import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
+/**
+ * Authentication method identifier for lifecycle hooks.
+ */
+export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset";
+/**
+ * Override 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 {
+    /**
+     * Hash a cleartext password for storage.
+     *
+     * Default: scrypt (Node.js crypto, 64-byte key, random 32-byte salt).
+     *
+     * @param password - The cleartext password.
+     * @returns The hashed password string (format is implementation-defined).
+     */
+    hashPassword?(password: string): Promise<string>;
+    /**
+     * Verify a cleartext password against a stored hash.
+     *
+     * Default: scrypt verification with timing-safe comparison.
+     *
+     * @param password - The cleartext password to check.
+     * @param storedHash - The hash string retrieved from the database.
+     * @returns `true` if the password matches the hash.
+     */
+    verifyPassword?(password: string, storedHash: string): Promise<boolean>;
+    /**
+     * Validate password strength before hashing.
+     *
+     * Default: minimum 8 characters, at least one uppercase, one lowercase, one digit.
+     *
+     * @param password - The cleartext password to validate.
+     * @returns Validation result with `valid` flag and error messages.
+     */
+    validatePasswordStrength?(password: string): PasswordValidationResult;
+    /**
+     * Override the complete credential verification during email/password login.
+     *
+     * When set, this replaces the default flow:
+     *   1. Look up user by email
+     *   2. Verify password hash
+     *
+     * The auth repository is provided for database access. Return the user
+     * data if credentials are valid, or `null` to reject the login.
+     *
+     * Default: `getUserByEmail(email)` + `verifyPassword(password, user.passwordHash)`.
+     */
+    verifyCredentials?(email: string, password: string, repo: AuthRepository): Promise<UserData | null>;
+    /**
+     * Called after any successful authentication event (login, register,
+     * OAuth, token refresh, password reset).
+     *
+     * Use for audit logging, syncing external state, updating
+     * last-login timestamps, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onAuthenticated?(user: UserData, method: AuthMethod): Promise<void>;
+    /**
+     * Called before a new user is created (registration or admin creation).
+     *
+     * Return modified data to alter what gets stored, or throw an error
+     * to reject the creation entirely.
+     *
+     * Default: passthrough (returns data unchanged).
+     */
+    beforeUserCreate?(data: CreateUserData): Promise<CreateUserData>;
+    /**
+     * Called after a new user is created.
+     *
+     * Use for provisioning external resources, sending notifications
+     * to third-party systems, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterUserCreate?(user: UserData): Promise<void>;
+}
+/**
+ * Resolved auth operations — every method is guaranteed to exist.
+ * Created by `resolveAuthOverrides()` which merges user overrides
+ * with built-in defaults.
+ */
+export interface ResolvedAuthOperations {
+    hashPassword(password: string): Promise<string>;
+    verifyPassword(password: string, storedHash: string): Promise<boolean>;
+    validatePasswordStrength(password: string): PasswordValidationResult;
+}
+/**
+ * Merge user-provided overrides 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;

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

@@ -0,0 +1,49 @@
+/**
+ * RebaseBuiltinAuthAdapter
+ *
+ * Wraps Rebase's existing built-in JWT auth system (routes, middleware, user/role
+ * management) into the `AuthAdapter` interface. This is the default adapter used
+ * when the user passes a plain `RebaseAuthConfig` object.
+ *
+ * This is NOT a rewrite — it delegates to the existing `createAuthRoutes()`,
+ * `createAdminRoutes()`, and `verifyAccessToken()` functions. The goal is to
+ * present the same functionality through the pluggable `AuthAdapter` contract.
+ */
+import type { AuthAdapter, BackendHooks } from "@rebasepro/types";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthOverrides } from "./auth-overrides";
+import type { EmailService, EmailConfig } from "../email";
+/**
+ * Configuration for the built-in Rebase auth adapter.
+ *
+ * This mirrors the existing `RebaseAuthConfig` — users pass this and
+ * server-core auto-wraps it in a `RebaseBuiltinAuthAdapter`.
+ */
+export interface BuiltinAuthAdapterConfig {
+    /** The bootstrapper-provided auth repository (users, roles, tokens). */
+    authRepository: AuthRepository;
+    /** Email service for password resets, verification, etc. */
+    emailService?: EmailService;
+    /** Email configuration. */
+    emailConfig?: EmailConfig;
+    /** Whether to allow new user registration. */
+    allowRegistration?: boolean;
+    /** Default role to assign to new users. */
+    defaultRole?: string;
+    /** OAuth providers to register. */
+    oauthProviders?: OAuthProvider<any>[];
+    /** Static service key for server-to-server auth. */
+    serviceKey?: string;
+    /** Backend hooks for intercepting admin data. */
+    hooks?: BackendHooks;
+    /** Auth overrides for customizing password, credentials, lifecycle, etc. */
+    overrides?: AuthOverrides;
+}
+/**
+ * Create the built-in Rebase auth adapter.
+ *
+ * This wraps the existing auth infrastructure (JWT, OAuth, user/role management)
+ * into the `AuthAdapter` interface. It's used internally by `initializeRebaseBackend()`
+ * when the user passes a plain `RebaseAuthConfig` object.
+ */
+export declare function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): AuthAdapter;

package/dist/server-core/src/auth/crypto-utils.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cryptographic utility functions for auth.
+ *
+ * @module
+ */
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ *
+ * Used for comparing service keys, tokens, and other secrets where
+ * timing side-channels could leak information about the expected value.
+ *
+ * @param a - First string to compare.
+ * @param b - Second string to compare.
+ * @returns `true` if the strings are identical, `false` otherwise.
+ */
+export declare function safeCompare(a: string, b: string): boolean;

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

@@ -0,0 +1,39 @@
+/**
+ * Custom Auth Adapter Factory
+ *
+ * Provides a minimal-config way for users with existing auth systems
+ * to plug into Rebase. Only `verifyRequest` is required — everything
+ * else is optional.
+ *
+ * @example
+ * ```ts
+ * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ *
+ * const auth = createCustomAuthAdapter({
+ *   verifyRequest: async (request) => {
+ *     const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+ *     if (!token) return null;
+ *     const decoded = jwt.verify(token, MY_SECRET);
+ *     return {
+ *       uid: decoded.sub,
+ *       email: decoded.email,
+ *       displayName: decoded.name,
+ *       roles: decoded.roles || [],
+ *       isAdmin: decoded.roles?.includes("admin") ?? false,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+import type { AuthAdapter, CustomAuthAdapterOptions } from "@rebasepro/types";
+/**
+ * Create a custom auth adapter from minimal options.
+ *
+ * This is the recommended entry point for users who already have their own
+ * auth system and just need to tell Rebase how to extract the user from
+ * incoming requests.
+ *
+ * @param options - Configuration options. Only `verifyRequest` is required.
+ * @returns A fully-formed `AuthAdapter` ready for `initializeRebaseBackend()`.
+ */
+export declare function createCustomAuthAdapter(options: CustomAuthAdapterOptions): AuthAdapter;

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

@@ -3,6 +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 { createGoogleProvider } from "./google-oauth";
 export type { GoogleProviderConfig } from "./google-oauth";
 export { createLinkedinProvider } from "./linkedin-oauth";
@@ -22,3 +24,8 @@ export { createAuthRoutes } from "./routes";
 export type { AuthModuleConfig } from "./routes";
 export { createAdminRoutes } from "./admin-routes";
 export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter } from "./rate-limiter";
+export { createBuiltinAuthAdapter } from "./builtin-auth-adapter";
+export type { BuiltinAuthAdapterConfig } from "./builtin-auth-adapter";
+export { createCustomAuthAdapter } from "./custom-auth-adapter";
+export { createAdapterAuthMiddleware } from "./adapter-middleware";
+export type { AdapterAuthMiddlewareOptions } from "./adapter-middleware";

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

@@ -18,6 +18,7 @@ export interface UserData {
     emailVerified: boolean;
     emailVerificationToken?: string | null;
     emailVerificationSentAt?: Date | null;
+    metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -30,6 +31,7 @@ export interface CreateUserData {
     displayName?: string;
     photoUrl?: string;
     emailVerified?: boolean;
+    metadata?: Record<string, unknown>;
 }
 /**
  * User Identity Data (OAuth accounts linked to user)

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

@@ -78,4 +78,22 @@ 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/server-core/src/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/server-core/src/auth/routes.d.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthOverrides } from "./auth-overrides";
 import { EmailService, EmailConfig } from "../email";
 import { HonoEnv } from "../api/types";
 /**
@@ -14,9 +15,14 @@ export interface AuthModuleConfig {
     /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
     defaultRole?: string;
     /** Optional array of OAuth providers */
-    oauthProviders?: OAuthProvider[];
+    oauthProviders?: OAuthProvider<any>[];
     /** When true, blocks all self-registration regardless of `allowRegistration`. */
     disableSelfRegistration?: boolean;
+    /**
+     * Auth overrides for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    overrides?: AuthOverrides;
     /**
      * Callback that checks if bootstrap has already been completed.
      * Used by GET /auth/config to report `needsSetup` status.

package/dist/server-core/src/env.d.ts

@@ -0,0 +1,131 @@
+import { z } from "zod";
+/**
+ * The full set of environment variables recognized by a Rebase backend.
+ */
+declare const rebaseEnvSchema: z.ZodObject<{
+    NODE_ENV: z.ZodDefault<z.ZodEnum<["development", "production", "test"]>>;
+    PORT: z.ZodEffects<z.ZodDefault<z.ZodString>, number, string | undefined>;
+    DATABASE_URL: z.ZodString;
+    ADMIN_CONNECTION_STRING: z.ZodOptional<z.ZodString>;
+    JWT_SECRET: z.ZodString;
+    JWT_ACCESS_EXPIRES_IN: z.ZodDefault<z.ZodString>;
+    JWT_REFRESH_EXPIRES_IN: z.ZodDefault<z.ZodString>;
+    GOOGLE_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    GOOGLE_CLIENT_SECRET: z.ZodOptional<z.ZodString>;
+    REBASE_SERVICE_KEY: z.ZodOptional<z.ZodString>;
+    ALLOW_REGISTRATION: z.ZodEffects<z.ZodDefault<z.ZodEnum<["true", "false", ""]>>, boolean, "" | "true" | "false" | undefined>;
+    ALLOW_LOCALHOST_IN_PRODUCTION: z.ZodEffects<z.ZodOptional<z.ZodEnum<["true", "false", ""]>>, boolean, "" | "true" | "false" | undefined>;
+    CORS_ORIGINS: z.ZodOptional<z.ZodString>;
+    FRONTEND_URL: z.ZodOptional<z.ZodString>;
+    DB_POOL_MAX: z.ZodEffects<z.ZodDefault<z.ZodString>, number, string | undefined>;
+    DB_POOL_IDLE_TIMEOUT: z.ZodEffects<z.ZodDefault<z.ZodString>, number, string | undefined>;
+    DB_POOL_CONNECT_TIMEOUT: z.ZodEffects<z.ZodDefault<z.ZodString>, number, string | undefined>;
+    FORCE_LOCAL_STORAGE: z.ZodEffects<z.ZodOptional<z.ZodEnum<["true", "false", ""]>>, boolean, "" | "true" | "false" | undefined>;
+    STORAGE_TYPE: z.ZodDefault<z.ZodEnum<["local", "s3"]>>;
+    STORAGE_PATH: z.ZodOptional<z.ZodString>;
+    S3_BUCKET: z.ZodOptional<z.ZodString>;
+    S3_REGION: z.ZodOptional<z.ZodString>;
+    S3_ACCESS_KEY_ID: z.ZodOptional<z.ZodString>;
+    S3_SECRET_ACCESS_KEY: z.ZodOptional<z.ZodString>;
+    S3_ENDPOINT: z.ZodOptional<z.ZodString>;
+    S3_FORCE_PATH_STYLE: z.ZodEffects<z.ZodOptional<z.ZodEnum<["true", "false", ""]>>, boolean, "" | "true" | "false" | undefined>;
+}, "strip", z.ZodTypeAny, {
+    NODE_ENV: "development" | "production" | "test";
+    PORT: number;
+    DATABASE_URL: string;
+    JWT_SECRET: string;
+    JWT_ACCESS_EXPIRES_IN: string;
+    JWT_REFRESH_EXPIRES_IN: string;
+    ALLOW_REGISTRATION: boolean;
+    ALLOW_LOCALHOST_IN_PRODUCTION: boolean;
+    DB_POOL_MAX: number;
+    DB_POOL_IDLE_TIMEOUT: number;
+    DB_POOL_CONNECT_TIMEOUT: number;
+    FORCE_LOCAL_STORAGE: boolean;
+    STORAGE_TYPE: "local" | "s3";
+    S3_FORCE_PATH_STYLE: boolean;
+    ADMIN_CONNECTION_STRING?: string | undefined;
+    GOOGLE_CLIENT_ID?: string | undefined;
+    GOOGLE_CLIENT_SECRET?: string | undefined;
+    REBASE_SERVICE_KEY?: string | undefined;
+    CORS_ORIGINS?: string | undefined;
+    FRONTEND_URL?: string | undefined;
+    STORAGE_PATH?: string | undefined;
+    S3_BUCKET?: string | undefined;
+    S3_REGION?: string | undefined;
+    S3_ACCESS_KEY_ID?: string | undefined;
+    S3_SECRET_ACCESS_KEY?: string | undefined;
+    S3_ENDPOINT?: string | undefined;
+}, {
+    DATABASE_URL: string;
+    JWT_SECRET: string;
+    NODE_ENV?: "development" | "production" | "test" | undefined;
+    PORT?: string | undefined;
+    ADMIN_CONNECTION_STRING?: string | undefined;
+    JWT_ACCESS_EXPIRES_IN?: string | undefined;
+    JWT_REFRESH_EXPIRES_IN?: string | undefined;
+    GOOGLE_CLIENT_ID?: string | undefined;
+    GOOGLE_CLIENT_SECRET?: string | undefined;
+    REBASE_SERVICE_KEY?: string | undefined;
+    ALLOW_REGISTRATION?: "" | "true" | "false" | undefined;
+    ALLOW_LOCALHOST_IN_PRODUCTION?: "" | "true" | "false" | undefined;
+    CORS_ORIGINS?: string | undefined;
+    FRONTEND_URL?: string | undefined;
+    DB_POOL_MAX?: string | undefined;
+    DB_POOL_IDLE_TIMEOUT?: string | undefined;
+    DB_POOL_CONNECT_TIMEOUT?: string | undefined;
+    FORCE_LOCAL_STORAGE?: "" | "true" | "false" | undefined;
+    STORAGE_TYPE?: "local" | "s3" | undefined;
+    STORAGE_PATH?: string | undefined;
+    S3_BUCKET?: string | undefined;
+    S3_REGION?: string | undefined;
+    S3_ACCESS_KEY_ID?: string | undefined;
+    S3_SECRET_ACCESS_KEY?: string | undefined;
+    S3_ENDPOINT?: string | undefined;
+    S3_FORCE_PATH_STYLE?: "" | "true" | "false" | undefined;
+}>;
+/** Inferred type of the validated environment. */
+export type RebaseEnv = z.infer<typeof rebaseEnvSchema>;
+/**
+ * Load and validate the Rebase environment configuration from `process.env`.
+ *
+ * Call this **after** your `.env` file has been loaded (via `dotenv`, `--env-file`,
+ * container injection, etc.). This function does not load `.env` files itself —
+ * that is a deployment concern, not a framework concern.
+ *
+ * Behavior:
+ * - Auto-generates ephemeral `JWT_SECRET` and `REBASE_SERVICE_KEY` in
+ *   non-production mode so developers can start without manual setup.
+ * - Blocks auto-generated secrets in production.
+ * - Returns a fully typed, validated env object.
+ *
+ * Use `extend` to add your own typed env variables on top of the base Rebase schema:
+ *
+ * @example
+ * ```ts
+ * import dotenv from "dotenv";
+ * import { z } from "zod";
+ * import { loadEnv } from "@rebasepro/server-core";
+ *
+ * dotenv.config({ path: "../../.env" });
+ *
+ * // Basic — just Rebase env vars:
+ * export const env = loadEnv();
+ *
+ * // Extended — add your own typed vars:
+ * export const env = loadEnv({
+ *     extend: z.object({
+ *         SMTP_HOST: z.string().optional(),
+ *         SMTP_PORT: z.string().default("587").transform(Number),
+ *         STRIPE_SECRET_KEY: z.string(),
+ *     })
+ * });
+ * // env.SMTP_HOST  → string | undefined  (fully typed)
+ * // env.STRIPE_SECRET_KEY → string        (validated, required)
+ * ```
+ */
+export declare function loadEnv(): RebaseEnv;
+export declare function loadEnv<E extends z.AnyZodObject>(options: {
+    extend: E;
+}): RebaseEnv & z.infer<E>;
+export {};

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

@@ -27,3 +27,5 @@ export * from "./functions";
 export * from "./cron";
 export * from "./serve-spa";
 export * from "./utils/dev-port";
+export { loadEnv } from "./env";
+export type { RebaseEnv } from "./env";

package/dist/server-core/src/init.d.ts

@@ -1,4 +1,4 @@
-import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider, HealthCheckResult, BackendHooks } from "@rebasepro/types";
+import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider, HealthCheckResult, BackendHooks, AuthAdapter, DatabaseAdapter } from "@rebasepro/types";
 import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
 import { DriverRegistry } from "./services/driver-registry";
 import { Server } from "http";
@@ -7,6 +7,7 @@ import { HonoEnv } from "./api/types";
 import { BackendStorageConfig, StorageController, StorageRegistry } from "./storage";
 import { EmailConfig } from "./email";
 import type { OAuthProvider } from "./auth/interfaces";
+import type { AuthOverrides } from "./auth/auth-overrides";
 export interface RebaseAuthConfig {
     jwtSecret?: string;
     accessExpiresIn?: string;
@@ -81,6 +82,24 @@ export interface RebaseAuthConfig {
     };
     defaultRole?: string;
     providers?: OAuthProvider<any>[];
+    /**
+     * Override specific parts of the built-in auth implementation.
+     *
+     * Each override replaces one piece of the default behavior while
+     * keeping everything else intact. Unset overrides fall through
+     * to the built-in defaults (scrypt passwords, standard validation, etc.).
+     *
+     * @example bcrypt passwords with a custom hash
+     * ```ts
+     * import bcrypt from "bcrypt";
+     *
+     * overrides: {
+     *     hashPassword: (pw) => bcrypt.hash(pw, 12),
+     *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
+     * }
+     * ```
+     */
+    overrides?: AuthOverrides;
     [key: string]: unknown;
 }
 export interface RebaseBackendConfig {
@@ -89,11 +108,36 @@ export interface RebaseBackendConfig {
     server: Server;
     app: Hono<HonoEnv>;
     basePath?: string;
-    bootstrappers: BackendBootstrapper[];
+    /**
+     * Database bootstrappers.
+     */
+    bootstrappers?: BackendBootstrapper[];
+    /**
+     * Database adapter.
+     *
+     * When set, this takes precedence over `bootstrappers`.
+     *
+     * @example
+     * ```ts
+     * import { createPostgresAdapter } from "@rebasepro/server-postgresql";
+     * database: createPostgresAdapter({ connection: db, schema }),
+     * ```
+     */
+    database?: DatabaseAdapter;
     logging?: {
         level?: "error" | "warn" | "info" | "debug";
     };
-    auth?: RebaseAuthConfig;
+    /**
+     * Authentication configuration.
+     *
+     * Accepts **either**:
+     * - `RebaseAuthConfig` — built-in configuration
+     * - `AuthAdapter` — pluggable adapter for external auth (Clerk, Auth0, etc.)
+     *
+     * When a plain config object is provided, the built-in adapter is created
+     * automatically from the bootstrapper's `initializeAuth()` result.
+     */
+    auth?: RebaseAuthConfig | AuthAdapter;
     /**
      * Storage configuration. Accepts:
      *
@@ -106,6 +150,12 @@ export interface RebaseBackendConfig {
     enableSwagger?: boolean;
     functionsDir?: string;
     cronsDir?: string;
+    /**
+     * Enable/disable database persistence for cron job execution logs.
+     * When set to false, cron jobs will run but logs will not be persisted to the database.
+     * Default: true.
+     */
+    cronPersistence?: boolean;
     /**
      * Maximum request body size in bytes for API routes (default: 10MB).
      * Set to 0 to disable the global limit entirely.
@@ -140,6 +190,15 @@ export interface RebaseBackendConfig {
      */
     hooks?: BackendHooks;
 }
+/**
+ * Type guard to detect whether the `auth` config is an `AuthAdapter`
+ * (has a `verifyRequest` method) vs a plain `RebaseAuthConfig` (plain object).
+ */
+export declare function isAuthAdapter(auth: RebaseAuthConfig | AuthAdapter): auth is AuthAdapter;
+/**
+ * Type guard to detect whether `database` is a `DatabaseAdapter`.
+ */
+export declare function isDatabaseAdapter(db: unknown): db is DatabaseAdapter;
 export interface RebaseBackendInstance {
     driverRegistry: DriverRegistry;
     driver: DataDriver;