@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/auth_adapter-CIItCTc8.js

@@ -0,0 +1,21 @@
+import { createRequire as __rebaseCreateRequire } from "module";
+import __rebaseProcess from "process";
+globalThis.process ??= __rebaseProcess;
+__rebaseCreateRequire(import.meta.url);
+//#region ../types/src/types/auth_adapter.ts
+/**
+* The request header that asks for a data-plane request to run as another
+* user, named by uid.
+*
+* The server honours it only on a signed-in administrator's own session —
+* never on an API key or the service key — and only through an adapter that
+* implements {@link AuthAdapter.resolveUser}. Everywhere else a request that
+* carries it is refused, never run as its caller.
+*
+* @group Auth
+*/
+var IMPERSONATE_HEADER = "x-rebase-impersonate";
+//#endregion
+export { IMPERSONATE_HEADER as t };
+
+//# sourceMappingURL=auth_adapter-CIItCTc8.js.map

package/dist/auth_adapter-CIItCTc8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth_adapter-CIItCTc8.js","names":[],"sources":["../../types/src/types/auth_adapter.ts"],"sourcesContent":["/**\n * @module AuthAdapter\n *\n * Pluggable authentication abstraction for Rebase.\n *\n * An `AuthAdapter` decouples authentication from the database layer,\n * allowing users to bring their own auth system (Clerk, Auth0, or other\n * external providers) while keeping the Rebase admin frontend fully functional.\n *\n * @example Built-in auth (default — zero config change)\n * ```ts\n * initializeRebaseBackend({\n *   auth: { jwtSecret: \"...\", google: { clientId: \"...\" } },\n *   database: createPostgresAdapter({ ... }),\n * });\n * ```\n *\n * @example Custom auth\n * ```ts\n * import { createCustomAuthAdapter } from \"@rebasepro/server\";\n *\n * initializeRebaseBackend({\n *   auth: createCustomAuthAdapter({\n *     verifyRequest: async (req) => { ... },\n *   }),\n *   database: createPostgresAdapter({ ... }),\n * });\n * ```\n *\n * @group Auth\n */\n\n/**\n * A sub-app an adapter hands back for the framework to mount.\n *\n * Structural on purpose. This was `Hono<any, any, any>`, and that one\n * `import type { Hono } from \"hono\"` was the whole reason `@rebasepro/types`\n * peer-depended on hono — which npm and pnpm auto-install, so **every browser\n * app that installed `@rebasepro/client` got a 2.8 MB server framework in its\n * lockfile and its security scanners**, for a type used by two optional methods\n * that a browser app can never call.\n *\n * The shape is the same duck-type the function loader already validates at\n * runtime (`isHonoLike`: a `fetch` method and a `routes` array), and a real\n * `Hono` satisfies it — asserted in `auth_adapter.test.ts`, which does import\n * hono, because a structural type is only worth having if something proves the\n * real thing still fits.\n *\n * @group Auth\n */\nexport interface MountableRouter {\n    /** Handle a request. Hono, Elysia and a hand-rolled router all have this. */\n    fetch: (request: Request) => Response | Promise<Response>;\n    /** The routes the sub-app declares. Only its presence is contractual. */\n    routes: readonly unknown[];\n}\n\n// ─── Impersonation ───────────────────────────────────────────────────────────\n\n/**\n * The request header that asks for a data-plane request to run as another\n * user, named by uid.\n *\n * The server honours it only on a signed-in administrator's own session —\n * never on an API key or the service key — and only through an adapter that\n * implements {@link AuthAdapter.resolveUser}. Everywhere else a request that\n * carries it is refused, never run as its caller.\n *\n * @group Auth\n */\nexport const IMPERSONATE_HEADER = \"x-rebase-impersonate\";\n\n// ─── Authenticated User ──────────────────────────────────────────────────────\n\n/**\n * The normalized user object returned by `AuthAdapter.verifyRequest()`.\n *\n * Regardless of the auth provider, every request is resolved to this shape\n * so that downstream middleware (RLS scoping, route guards) can work uniformly.\n *\n * @group Auth\n */\nexport interface AuthenticatedUser {\n    /** Unique user identifier (provider-specific). */\n    uid: string;\n    /** Primary email address. */\n    email: string;\n    /** Human-readable display name. */\n    displayName?: string | null;\n    /** Avatar URL. */\n    photoUrl?: string | null;\n    /** Role identifiers the user holds. */\n    roles: string[];\n    /**\n     * Whether `roles` includes `admin`. Informational — every authorization\n     * decision reads `roles` and the scopes they hold, so an adapter that\n     * wants a user treated as an administrator gives them the `admin` role.\n     */\n    isAdmin: boolean;\n    /**\n     * Whether this session is a GUEST — anonymous sign-in rather than an\n     * account.\n     *\n     * Optional, and absent means \"not a guest\", so an external adapter that\n     * has no such concept keeps behaving exactly as it did. When present it\n     * reaches the database as `rebase.is_anonymous()`, which is what lets a\n     * policy say \"a signed-in person, not somebody who pressed Continue as\n     * guest\" — two things that were the same principal inside every rule,\n     * because anonymous sign-in mints a real user row with a real uid.\n     */\n    isAnonymous?: boolean;\n    /** Raw bearer token from the request (for forwarding). */\n    rawToken?: string;\n    /** Extra claims/metadata from the auth provider. */\n    claims?: Record<string, unknown>;\n    /**\n     * What this credential may do, when it is narrower than its person — set\n     * for an API key. Absent means everything the user's roles hold\n     * (`scopesForRoles`).\n     */\n    scopes?: string[];\n}\n\n// ─── Capabilities ────────────────────────────────────────────────────────────\n\n/**\n * Feature flags advertised by an auth adapter.\n *\n * The frontend reads these from `GET /api/auth/config` to dynamically\n * show/hide UI elements (login form, registration, password reset, etc.).\n *\n * @group Auth\n */\nexport interface AuthAdapterCapabilities {\n    /**\n     * Whether this adapter mounts its own `/auth/*` routes.\n     *\n     * - `true` for the built-in Rebase auth (login, register, refresh, etc.)\n     * - `false` for external providers like Clerk or Auth0 that handle\n     *   auth flows outside of the Rebase backend.\n     */\n    hasBuiltInAuthRoutes: boolean;\n\n    /** Supports email/password login. */\n    emailPasswordLogin: boolean;\n    /**\n     * Whether self-registration is open **right now**.\n     *\n     * A runtime answer, not a static feature list: the built-in adapter also\n     * reports `true` during the first-user bootstrap window (an empty user\n     * table) and `false` the moment `disableSelfRegistration` is set. Whatever\n     * this says, `POST /auth/register` does — both read the same predicate, so\n     * the UI can never be sent to a form that can only 403.\n     */\n    registrationEnabled: boolean;\n    /**\n     * Supports the end-user password reset flow (emailing a reset link).\n     *\n     * This is about *self-service* reset, so it is typically tied to whether an\n     * email service is configured. It says nothing about whether an admin can\n     * reset someone else's password — see `adminPasswordReset`.\n     */\n    passwordReset: boolean;\n    /**\n     * Whether the adapter exposes `POST /admin/users/:uid/reset-password`,\n     * letting an admin reset another user's password.\n     *\n     * Independent of `passwordReset`: the built-in adapter supports this even\n     * with no email service configured (it returns a one-time temporary\n     * password instead of sending a link). Adapters that mount their own admin\n     * routes must set this to `true` only once that route actually exists —\n     * the admin UI hides the \"Reset Password\" action when it is `false`.\n     */\n    adminPasswordReset: boolean;\n    /** Supports session listing/revocation. */\n    sessionManagement: boolean;\n    /** Supports profile updates (display name, photo). */\n    profileUpdate: boolean;\n    /** Supports email verification. */\n    emailVerification: boolean;\n    /** Supports passwordless magic link login. */\n    magicLink: boolean;\n    /**\n     * Supports passwordless sign-in with a six-digit code sent by email.\n     *\n     * Optional so that an external adapter written before this existed still\n     * satisfies the interface; absent reads as \"no\", which is what an adapter\n     * that has never heard of the flow means.\n     */\n    emailOtp?: boolean;\n    /** Whether `POST /auth/anonymous` will mint a credential-less session. */\n    anonymousLogin: boolean;\n    /** List of enabled OAuth provider IDs (e.g. `[\"google\", \"github\"]`). */\n    enabledProviders: string[];\n\n    /**\n     * For external auth (Clerk, Auth0, etc.): the URL where the user should\n     * be redirected for login. The Rebase frontend will navigate here instead\n     * of showing its own login form.\n     */\n    externalLoginUrl?: string;\n\n    /**\n     * True when no users exist yet — first-user bootstrap mode.\n     * Only applicable for built-in auth.\n     */\n    needsSetup?: boolean;\n}\n\n/**\n * What `GET /api/auth/config` answers: the auth adapter's capabilities, plus\n * the optional features of the backend around it.\n *\n * The admin panel reads this document before anything else, so it is where\n * the panel learns that a feature is off, without first asking for that\n * feature and getting a refusal.\n *\n * @group Auth\n */\nexport interface AuthConfigDocument extends AuthAdapterCapabilities {\n    /**\n     * Whether this backend serves file storage. When it is `false`, no storage\n     * backend is configured: `GET /storage/sources` lists nothing and every\n     * other `/storage` route answers 501 `STORAGE_NOT_CONFIGURED`. Absent from\n     * a backend that predates the field, so a client must ask\n     * `GET /storage/sources` there.\n     */\n    storage?: boolean;\n}\n\n// ─── User Management ────────────────────────────────────────────────────────\n\n/**\n * Options for paginated user listing.\n * @group Auth\n */\nexport interface AuthUserListOptions {\n    limit?: number;\n    offset?: number;\n    search?: string;\n    orderBy?: string;\n    orderDir?: \"asc\" | \"desc\";\n    roleId?: string;\n}\n\n/**\n * Paginated user listing result.\n * @group Auth\n */\nexport interface AuthUserListResult {\n    users: AuthUserData[];\n    total: number;\n    limit: number;\n    offset: number;\n}\n\n/**\n * User data exposed by the auth adapter.\n * @group Auth\n */\nexport interface AuthUserData {\n    id: string;\n    email: string;\n    displayName?: string | null;\n    photoUrl?: string | null;\n    emailVerified?: boolean;\n    metadata?: Record<string, unknown>;\n    createdAt?: Date;\n    updatedAt?: Date;\n}\n\n/**\n * Data for creating a user.\n * @group Auth\n */\nexport interface AuthCreateUserData {\n    email: string;\n    password?: string;\n    displayName?: string;\n    photoUrl?: string;\n    metadata?: Record<string, unknown>;\n    /**\n     * Store the address as verified: whoever creates the account named it\n     * (an operator, an administrator), so nobody needs to prove it.\n     */\n    emailVerified?: boolean;\n}\n\n/**\n * User management operations for the admin panel.\n *\n * Optional — if not provided by the adapter, the user management UI is hidden.\n *\n * @group Auth\n */\nexport interface UserManagementAdapter {\n    listUsers(options?: AuthUserListOptions): Promise<AuthUserListResult>;\n    getUserById(id: string): Promise<AuthUserData | null>;\n    createUser(data: AuthCreateUserData): Promise<AuthUserData>;\n    updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null>;\n    deleteUser(id: string): Promise<void>;\n    getUserRoles(uid: string): Promise<string[]>;\n    setUserRoles(uid: string, roleIds: string[]): Promise<void>;\n}\n\n// ─── User Creation Lifecycle ─────────────────────────────────────────────────\n\n/**\n * Result of `AuthAdapter.prepareUserCreation()`.\n *\n * Contains the processed values ready for persistence and metadata\n * needed by the finalization step.\n *\n * @group Auth\n */\nexport interface UserCreationPrepareResult {\n    /** Processed values to persist (passwordHash instead of raw password, etc.). */\n    values: Record<string, unknown>;\n    /** Cleartext password for post-save processing (email or admin display). */\n    clearPassword?: string;\n    /**\n     * Whether the hook already handled the invitation (email, etc.). When\n     * `true`, `finalizeUserCreation` is skipped and `clearPassword` is returned\n     * to the admin as the temporary password.\n     */\n    hookHandledEmail: boolean;\n    /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */\n    invitationSent: boolean;\n}\n\n/**\n * What the door creating a user knows about its caller, for\n * `AuthAdapter.prepareUserCreation()`.\n *\n * @group Auth\n */\nexport interface UserCreationOptions {\n    /**\n     * Whether the caller may waive the password policy with\n     * `skipPasswordPolicy: true` in the body. The doors set it for an\n     * administrator (the service key signs in as one) and for nobody else, so\n     * an adapter that reads the flag is taking an administrator at their word —\n     * an import of accounts whose passwords were set under another system's\n     * rules. Absent, the flag waives nothing.\n     */\n    mayWaivePasswordPolicy?: boolean;\n}\n\n/**\n * What a create body for an auth collection may name beyond the collection's\n * own declared fields — see `AuthAdapter.describeUserCreationContract()`.\n *\n * @group Auth\n */\nexport interface UserCreationWriteContract {\n    /**\n     * Whether to check the body for fields neither the collection nor\n     * {@link extraFields} declares. `false` skips the check entirely.\n     */\n    validate: boolean;\n    /**\n     * Credential and provider keys the adapter consumes itself, which the\n     * collection therefore does not declare as columns. `password` is the\n     * canonical one: `prepareUserCreation` hashes it into `passwordHash` and\n     * deletes it before the row is ever built.\n     */\n    extraFields: string[];\n    /**\n     * Each body's `prepareUserCreation` touches nothing but its own result —\n     * no hook, no email, no write — so a bulk create may prepare several at\n     * once. The built-in adapter's path with no `onCreateUser`, no\n     * `onAdminCreateUser` and the default `hashPassword` is: it hashes a\n     * password and normalizes an email, and a 1,000-row bulk spent half a\n     * minute hashing one password at a time. Leave it unset when a hook runs:\n     * preparations then run one at a time, in the order the rows were given.\n     */\n    independent?: boolean;\n}\n\n/**\n * Result of `AuthAdapter.finalizeUserCreation()`.\n *\n * Returned to the REST API for inclusion in the response.\n *\n * @group Auth\n */\nexport interface UserCreationFinalizeResult {\n    /** If set, returned to the admin in the API response. */\n    temporaryPassword?: string;\n    /** Whether an invitation email was sent. */\n    invitationSent: boolean;\n    /**\n     * Whether an email service was configured but delivery failed, causing the\n     * fallback to `temporaryPassword`. Absent when no email service is configured.\n     */\n    emailDeliveryFailed?: boolean;\n}\n\n// ─── Auth Response Transform ─────────────────────────────────────────────────\n\n/**\n * The auth response payload shape that flows through `transformAuthResponse`.\n *\n * For login, register, OAuth, anonymous, and magic-link flows the payload\n * contains both `user` and `tokens`. For refresh and MFA flows the payload\n * contains only `tokens` (no `user`).\n *\n * @group Auth\n */\nexport interface AuthResponsePayload {\n    user?: {\n        uid: string;\n        email: string;\n        displayName: string | null;\n        photoURL: string | null;\n        providerId?: string;\n        isAnonymous?: boolean;\n        emailVerified?: boolean;\n        roles: string[];\n        metadata: Record<string, unknown>;\n    };\n    tokens: {\n        accessToken: string;\n        refreshToken: string;\n        accessTokenExpiresAt: number;\n        /** Additional tokens injected by `transformAuthResponse`. */\n        [key: string]: unknown;\n    };\n}\n\n/**\n * Context passed to the `transformAuthResponse` hook.\n *\n * @group Auth\n */\nexport interface TransformAuthResponseContext {\n    /** The authenticated user's ID. */\n    uid: string;\n    /** The auth method that triggered this response. */\n    method: \"login\" | \"register\" | \"oauth\" | \"refresh\" | \"anonymous\" | \"magic-link\" | \"otp\" | \"mfa\";\n    /** The raw HTTP request (for reading headers, IP, etc.). */\n    request: Request;\n}\n\n// ─── Auth Adapter ────────────────────────────────────────────────────────────\n\n/**\n * Pluggable authentication adapter for Rebase.\n *\n * This is the **key interface** that decouples authentication from the\n * database layer. Each auth adapter knows how to:\n *\n * 1. Verify incoming HTTP requests (`verifyRequest`)\n * 2. Optionally manage users (for the admin panel)\n * 3. Optionally mount auth-specific routes (login, register, etc.)\n * 4. Advertise its capabilities so the frontend can adapt\n *\n * The built-in Rebase auth implements this interface internally.\n * External providers (Clerk, Auth0, or others) provide their own adapters.\n * Users with custom auth can use `createCustomAuthAdapter()` for a minimal setup.\n *\n * @group Auth\n */\nexport interface AuthAdapter {\n    /**\n     * Unique identifier for this auth adapter.\n     *\n     * @example \"rebase-builtin\", \"clerk\", \"auth0\", \"external-provider\", \"custom\"\n     */\n    readonly id: string;\n\n    // ── Request Authentication ──────────────────────────────────────────\n\n    /**\n     * Verify an incoming request and extract the authenticated user.\n     *\n     * This replaces the hardcoded JWT verification in server's middleware.\n     * Each adapter implements its own token verification strategy:\n     * - Built-in: verify Rebase JWT\n     * - Clerk: call Clerk's `verifyToken()`\n     * - Auth0: validate Auth0 JWT with JWKS\n     * - Custom: whatever logic the user provides\n     *\n     * @param request - The raw `Request` object (portable across Hono, Express, Fastify)\n     * @returns The authenticated user, or `null` for unauthenticated requests.\n     *          Throw an error to reject the request with 401.\n     */\n    verifyRequest(request: Request): Promise<AuthenticatedUser | null>;\n\n    /**\n     * Verify a raw bearer token and extract the authenticated user.\n     *\n     * Used for **WebSocket authentication**, where there is no HTTP `Request`\n     * object — only a token string sent over the socket.\n     *\n     * If not implemented, the default behavior synthesizes a minimal `Request`\n     * with an `Authorization: Bearer <token>` header and delegates to\n     * `verifyRequest()`. Adapters should override this if their token\n     * verification logic doesn't depend on request headers/cookies.\n     *\n     * @param token - The raw bearer token string.\n     * @returns The authenticated user, or `null` if the token is invalid.\n     */\n    verifyToken?(token: string): Promise<AuthenticatedUser | null>;\n\n    /**\n     * The identity a verified request from this account would carry right\n     * now, with no credential involved: its uid, its roles as they are now,\n     * its guest flag, and the custom claims a token minted for it now would\n     * hold. `null` when no active account has this uid — none at all, or one\n     * that is disabled.\n     *\n     * This is what lets an administrator run a request as another user (the\n     * {@link IMPERSONATE_HEADER} header). The server calls it only after it\n     * has decided the caller may do that, and it calls it for the caller too,\n     * so the decision rests on the caller's roles as they are now rather than\n     * on the ones their token claims.\n     *\n     * Optional. An adapter without it cannot be impersonated through, and a\n     * request carrying the header is refused rather than run as its caller.\n     */\n    resolveUser?(uid: string): Promise<AuthenticatedUser | null>;\n\n    // ── User Management (for admin panel) ────────────────────────────\n\n    /**\n     * User CRUD for the admin panel's user management UI.\n     * Optional — if not provided, user management UI is hidden.\n     */\n    userManagement?: UserManagementAdapter;\n\n    // ── Auth Routes ─────────────────────────────────────────────────────\n\n    /**\n     * Mount adapter-specific auth routes (login, register, refresh, etc.).\n     *\n     * - Built-in adapter: mounts `/auth/login`, `/auth/register`, etc.\n     * - External adapter: typically returns `undefined` (auth is handled externally).\n     * - Custom adapter: user mounts their own routes.\n     *\n     * The return type is the structural {@link MountableRouter} rather than\n     * `Hono`, so this package needs no hono dependency. A real `Hono<HonoEnv>`\n     * satisfies it, and implementations are free to use their own env.\n     *\n     * @returns A Hono sub-app with auth routes, or `undefined` to skip route mounting.\n     */\n    createAuthRoutes?(): MountableRouter | undefined;\n\n    /**\n     * Mount admin routes (e.g. password reset for users).\n     *\n     * @returns A Hono sub-app with admin routes, or `undefined` to skip.\n     */\n    createAdminRoutes?(): MountableRouter | undefined;\n\n    // ── Feature Detection ───────────────────────────────────────────────\n\n    /**\n     * Advertise what this auth adapter supports.\n     *\n     * The frontend reads this from `GET /api/auth/config` to dynamically\n     * show/hide UI elements. This is the bridge between backend capabilities\n     * and the frontend's `AuthCapabilities` type.\n     */\n    getCapabilities(): AuthAdapterCapabilities | Promise<AuthAdapterCapabilities>;\n\n    // ── Lifecycle ───────────────────────────────────────────────────────\n\n    /**\n     * Called during backend initialization.\n     * Use for running migrations, creating tables, seeding initial data, etc.\n     */\n    initialize?(): Promise<void>;\n\n    /**\n     * Called during graceful shutdown.\n     * Use for closing connections, flushing caches, etc.\n     */\n    destroy?(): Promise<void>;\n\n    // ── Collection User Creation (for auth collections) ───────────────\n\n    /**\n     * Prepare values for creating a user via the auth collection's REST API.\n     *\n     * Called on POST to a collection with `auth: true`. Handles password\n     * hashing, email normalization, and any collection/backend-level hooks.\n     *\n     * If not implemented, the collection saves values as-is (no password hashing).\n     *\n     * A chosen `password` is held to the password policy unless the body says\n     * `skipPasswordPolicy: true` and `options.mayWaivePasswordPolicy` is set.\n     *\n     * @param values - Raw request body from the client.\n     * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).\n     * @param options - What the door knows about its caller.\n     * @returns Processed values ready for `driver.save()`, plus metadata for the post-save step.\n     */\n    prepareUserCreation?(\n        values: Record<string, unknown>,\n        collectionAuth?: unknown,\n        options?: UserCreationOptions\n    ): Promise<UserCreationPrepareResult>;\n\n    /**\n     * Describe what a create body for this auth collection is allowed to name,\n     * so unknown-field validation can run on it.\n     *\n     * A signup body is not the collection's shape: it carries credential fields\n     * like `password` that the users table never declares as columns, and\n     * `prepareUserCreation` maps them onto real ones. Validating the raw body\n     * against the collection alone would reject every legitimate signup — which\n     * is why the check used to be skipped outright for auth collections. That\n     * skip was total, so an undeclared field was silently dropped and the write\n     * still returned 201, while the same typo on a normal collection was a 400.\n     *\n     * This narrows the exemption to the fields the adapter actually consumes.\n     *\n     * `validate: false` disables the check for this collection, and is the right\n     * answer when a custom `onCreateUser` hook is configured: the body is then\n     * the hook's contract, not the collection's, and this layer cannot know what\n     * the hook accepts.\n     *\n     * If not implemented, validation is skipped — the pre-existing behaviour.\n     *\n     * @param collectionAuth - The parsed `AuthCollectionConfig` from the collection (if `auth` is an object).\n     */\n    describeUserCreationContract?(\n        collectionAuth?: unknown\n    ): UserCreationWriteContract;\n\n    /**\n     * Finalize a user creation after the entity has been persisted.\n     *\n     * Handles post-save work: sending invitation emails, generating\n     * password-reset tokens, or falling back to returning a temporary password.\n     *\n     * Not called when `prepareUserCreation` reported `hookHandledEmail`. A\n     * create hook then owns delivery, and the response carries the\n     * `invitationSent` and `clearPassword` the prepare step returned. This\n     * holds for both ways of creating a user: a `POST` to the auth collection\n     * and `POST /admin/users`.\n     *\n     * @param entity - The persisted entity (id + values).\n     * @param clearPassword - The cleartext password from the prepare step (if any).\n     * @returns Metadata for the API response (temporary password, invitation status).\n     */\n    finalizeUserCreation?(\n        entity: { id: string; values: Record<string, unknown> },\n        clearPassword?: string\n    ): Promise<UserCreationFinalizeResult>;\n\n    // ── User Administration Through the Auth Collection ─────────────────\n\n    /**\n     * Check, and put in stored form, updates to rows of the auth collection\n     * that arrive through the data API — `PATCH /<users>/:id`, `PATCH /bulk`,\n     * `_batch`, the realtime socket.\n     *\n     * Those rows are the users, so an update to one is user administration,\n     * and has to hold to what the admin user routes hold to: no update that\n     * leaves the project without an administrator, and an email stored the\n     * way sign-in looks it up. Throws to refuse; the updates are judged\n     * together, so a bulk demotion of every admin is refused even though each\n     * row alone would pass.\n     *\n     * If not implemented, the values are written as they arrived.\n     *\n     * @returns Each update's values, as they should be written, in order.\n     */\n    prepareUserUpdates?(\n        updates: ReadonlyArray<{ uid: string; values: Record<string, unknown> }>\n    ): Promise<Record<string, unknown>[]>;\n\n    /**\n     * Check a deletion of these users through the data API before any row goes,\n     * and run the hooks that may veto it (`beforeUserDelete`). Throws to\n     * refuse — for one that would leave the project without an administrator,\n     * among others.\n     *\n     * If not implemented, the rows are deleted as any other.\n     */\n    prepareUserDeletions?(uids: readonly string[]): Promise<void>;\n\n    /**\n     * After those users' rows are deleted through the data API: end their\n     * sessions and run the after-delete hooks (`afterUserDelete`).\n     */\n    finalizeUserDeletions?(uids: readonly string[]): Promise<void>;\n\n    // ── Service Key (optional) ──────────────────────────────────────────\n\n    /**\n     * A static secret key for server-to-server / script authentication.\n     *\n     * When set, requests with `Authorization: Bearer <serviceKey>` bypass\n     * normal token verification and are granted admin-level access.\n     */\n    serviceKey?: string;\n\n    // ── Response Transform ───────────────────────────────────────────────\n\n    /**\n     * Transform the auth response before sending it to the client.\n     *\n     * Called after successful login, register, refresh, OAuth, anonymous,\n     * magic-link, and MFA flows. The hook receives the fully-formed\n     * response and returns a (potentially enriched) response.\n     *\n     * Use cases:\n     * - Inject tokens from external auth systems (custom provider tokens, etc.)\n     * - Add project-specific metadata to the response\n     * - Enrich the user object with data from external sources\n     *\n     * The hook runs in the request path — keep it fast.\n     * Heavy work should be offloaded to `onAuthenticated` (fire-and-forget).\n     */\n    transformAuthResponse?(\n        response: AuthResponsePayload,\n        context: TransformAuthResponseContext\n    ): Promise<AuthResponsePayload>;\n}\n\n// ─── Custom Auth Adapter Options ─────────────────────────────────────────────\n\n/**\n * Options for creating a minimal custom auth adapter via `createCustomAuthAdapter()`.\n *\n * This is the simplest way to plug an existing auth system into Rebase.\n * Only `verifyRequest` is required — everything else is optional.\n *\n * @group Auth\n */\nexport interface CustomAuthAdapterOptions {\n    /**\n     * Verify an incoming request and return the authenticated user.\n     * This is the only required method.\n     */\n    verifyRequest: (request: Request) => Promise<AuthenticatedUser | null>;\n\n    /**\n     * Verify a raw bearer token for WebSocket authentication.\n     * Optional — if omitted, a synthetic `Request` is constructed and passed\n     * to `verifyRequest`.\n     */\n    verifyToken?: (token: string) => Promise<AuthenticatedUser | null>;\n\n    /** Optional user management for the admin panel. */\n    userManagement?: UserManagementAdapter;\n\n    /** Static service key for server-to-server auth. */\n    serviceKey?: string;\n\n    /** Override default capabilities. */\n    capabilities?: Partial<AuthAdapterCapabilities>;\n\n    /**\n     * Transform the auth response before sending it to the client.\n     * Same semantics as `AuthAdapter.transformAuthResponse`.\n     */\n    transformAuthResponse?: (\n        response: AuthResponsePayload,\n        context: TransformAuthResponseContext\n    ) => Promise<AuthResponsePayload>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAsEA,IAAa,qBAAqB"}

package/dist/backend/create-backend.d.ts

@@ -0,0 +1,281 @@
+/**
+ * A Rebase backend as a value the application holds.
+ *
+ * `createRebaseBackend(options)` builds everything a backend is — the drivers,
+ * auth, storage, the in-process client, every route group — and stops there:
+ * it mounts nothing, starts no timer and adds no process listener. What happens
+ * next is the caller's, one public method at a time:
+ *
+ * ```ts
+ * const backend = await createRebaseBackend({ database, auth, collections, provision: true });
+ * app.route("/api/data", backend.routes.data());   // one group, at a path of your choosing
+ * backend.mount(app, { basePath: "/api" });         // or every group, exactly as initializeRebaseBackend lays them out
+ * await backend.attachRealtime(server);             // the websocket
+ * backend.start();                                  // cron, job workers, sweeps, the metrics sampler, the RLS audit
+ * await backend.shutdown();
+ * ```
+ *
+ * `initializeRebaseBackend` (`../init.ts`) is those calls in that order, and
+ * nothing else.
+ *
+ * @module
+ */
+import { BackendBootstrapper, BootstrappedAuth, DatabaseAdapter, DataDriver, HealthCheckResult, RealtimeProvider, type CollectionCallbacks, type RebaseServerClient } from "@rebasepro/types";
+import type { Server } from "node:http";
+import { Hono } from "hono";
+import { BackendCollectionRegistry } from "../collections/BackendCollectionRegistry.js";
+import { DriverRegistry } from "../services/driver-registry.js";
+import type { HonoEnv } from "../api/types.js";
+import { StorageController, StorageRegistry } from "../storage/index.js";
+import { type VerifiedCredential } from "../auth/verify-credential.js";
+import type { HistoryService } from "../history/history-routes.js";
+import type { CronScheduler } from "../cron/index.js";
+import type { JobQueue } from "../jobs/index.js";
+import type { MetricsHistory } from "../metrics/history-recorder.js";
+import type { RebaseBackendOptions } from "./options.js";
+import type { BackendServices } from "./services.js";
+/**
+ * A backend's HTTP surface, one route group at a time.
+ *
+ * Each group is a self-contained Hono sub-app: it carries the middleware it
+ * needs — the auth context that puts `user`, `driver` and `scopes` on the
+ * request, its rate limits, its admin gate — so it answers the same wherever it
+ * is mounted:
+ *
+ * ```ts
+ * app.route("/v2/data", backend.routes.data());
+ * app.route("/hooks", backend.routes.functions());   // getDriver(c) and getUser(c) work inside
+ * ```
+ *
+ * What a group does not carry is the process-wide HTTP hygiene `mount()`
+ * installs ahead of every group — request ids, the global body limit,
+ * compression, CSRF, the request log and the JSON envelope for errors and
+ * unmatched paths. An application mounting groups one by one adds its own
+ * (`hono/body-limit`, `app.onError(errorHandler)`).
+ *
+ * Every call returns a fresh router over the same handlers, so a group can be
+ * mounted in several places. Asking for a group whose surface is off
+ * (`surfaces: { data: false }`) throws: that backend never built it.
+ */
+export interface RebaseRoutes {
+    /**
+     * The sign-in surface, normally at `/api/auth`: registration, sessions,
+     * OAuth, password reset, `GET /config` (what the login screen offers),
+     * the caller's own API keys (`/keys`) and the scope catalogue (`/scopes`).
+     */
+    auth(): Hono<HonoEnv>;
+    /**
+     * The data API, normally at `/api/data`: the collections' REST routes and
+     * their history, behind authentication, RLS scoping and rate limits.
+     */
+    data(): Hono<HonoEnv>;
+    /**
+     * File storage, normally at `/api/storage` — or, with no storage
+     * configured, the router that says so (`STORAGE_NOT_CONFIGURED`).
+     */
+    storage(): Hono<HonoEnv>;
+    /**
+     * Custom functions, normally at `/api/functions` — or the forwarder to the
+     * process that serves them, when this one has a `functionsUpstream`.
+     */
+    functions(): Hono<HonoEnv>;
+    /**
+     * Every admin-gated surface, normally at `/api/admin`: users and roles,
+     * service API keys, live schema editing and the schema editor, storage
+     * maintenance, backups, the RLS audit, SQL export, the development
+     * mailbox and the log reader. Cron's admin surface is {@link cron}.
+     */
+    admin(): Hono<HonoEnv>;
+    /** The cron admin surface — list, trigger, read runs — normally at `/api/admin/cron`. */
+    cron(): Hono<HonoEnv>;
+    /** The project contract a generated SDK reads, normally at `/api/meta`. */
+    meta(): Hono<HonoEnv>;
+}
+/** Where {@link RebaseBackend.mount} puts the backend. */
+export interface BackendMountOptions {
+    /** The prefix every group is mounted under. Default `/api`. */
+    basePath?: string;
+}
+/** How {@link RebaseBackend.attachRealtime} attaches the websocket. */
+export interface AttachRealtimeOptions {
+    /**
+     * The URL path the socket accepts upgrades on. The SDK dials its `baseUrl`
+     * with no extra segment while HTTP goes to `${baseUrl}/api`, so the default
+     * is the base path given to `mount()` with a trailing `/api` removed —
+     * `/api` → `/`, `/x/api` → `/x` — and `/` when nothing was mounted. An
+     * upgrade to any other path is left for the server's other listeners.
+     */
+    path?: string;
+}
+/**
+ * A backend built by {@link createRebaseBackend}: everything constructed,
+ * nothing mounted, nothing started.
+ */
+export interface RebaseBackend {
+    /**
+     * The in-process client — what `rebase` from `@rebasepro/server` is inside
+     * every request, cron run and job this backend serves (and everywhere,
+     * once it is the process default: {@link setDefaultBackend}).
+     * `dataAsAdmin`, `sql`, `storage`, `bucket` and `email` call the drivers
+     * and controllers directly; `auth`, `admin`, `functions` and `cron` reach
+     * this backend's routes in-process, without an HTTP server and wherever
+     * (or whether) the application mounted them.
+     */
+    rebase: RebaseServerClient;
+    /**
+     * What this backend holds and its requests ask it for: its JWT keys
+     * (`services.jwt` signs and verifies its tokens), its access model, its
+     * API-key store, its rate limiters, its collections. Its own — another
+     * backend in the same process has others.
+     *
+     * ```ts
+     * const token = await backend.services.jwt.generateAccessToken("u1", ["editor"]);
+     * ```
+     */
+    services: BackendServices;
+    /**
+     * The identity and scopes behind a bearer credential — a session token or
+     * an `rk_` API key — as this backend verifies it, or null. For an app's
+     * own socket or tunnel.
+     */
+    verifyCredential(token: string): Promise<VerifiedCredential | null>;
+    driverRegistry: DriverRegistry;
+    driver: DataDriver;
+    realtimeServices: Record<string, RealtimeProvider>;
+    realtimeService: RealtimeProvider;
+    auth?: BootstrappedAuth;
+    history?: {
+        historyService: HistoryService;
+    };
+    /**
+     * Stored metrics for this deployment, when it can keep any.
+     *
+     * Absent on a driver with no SQL admin. The `/metrics/history` route turns
+     * that absence into a named 501 rather than an empty series, because an
+     * empty chart and "this deployment keeps no history" look identical.
+     */
+    metricsHistory?: MetricsHistory;
+    storageRegistry?: StorageRegistry;
+    storageController?: StorageController;
+    collectionRegistry: BackendCollectionRegistry;
+    /** The cron scheduler. Its jobs are registered; `start()` starts its timers. */
+    cronScheduler?: CronScheduler;
+    /**
+     * The durable job queue, when `jobs.enabled` is set and the driver can run
+     * SQL. Enqueueing works at once; `start()` starts the workers. Present on
+     * the instance because the *producers* live in application code:
+     *
+     * ```ts
+     * const dispatcher = new WebhookDispatcher({ jobQueue: backend.jobQueue });
+     * backend.jobQueue?.register(WEBHOOK_DELIVERY_TASK, ctx => dispatcher.deliverQueuedJob(ctx.payload, ctx));
+     * ```
+     */
+    jobQueue?: JobQueue;
+    /** The route groups, each mountable on its own. */
+    routes: RebaseRoutes;
+    /**
+     * The whole backend as one fetch handler, laid out as `mount()` lays it
+     * out at `/api`. For in-process calls, tests and scripts — no server, no
+     * port: `await backend.fetch(new Request("http://local/api/data/posts"))`.
+     */
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Mount every group this backend serves onto `app` under `basePath`, with
+     * the process-wide middleware in front of them — exactly the layout
+     * `initializeRebaseBackend` produces, legacy aliases included. Call it
+     * before adding routes of your own under the same prefix.
+     */
+    mount(app: Hono<HonoEnv>, options?: BackendMountOptions): void;
+    /**
+     * Attach the realtime websocket to an HTTP server. Does nothing when the
+     * `realtime` surface is off or the driver offers no realtime. Once only.
+     */
+    attachRealtime(server: Server, options?: AttachRealtimeOptions): Promise<void>;
+    /**
+     * Start what runs on a timer: the cron scheduler, the job workers, the
+     * expired-token and history-retention sweeps, the metrics sampler and the
+     * scheduled RLS audit — each only where `ownership` gives it to this
+     * process. Idempotent.
+     */
+    start(): void;
+    /**
+     * Attach collection callbacks after the backend is built.
+     *
+     * Use this instead of mutating `collectionRegistry.get(slug).callbacks`.
+     * Every registry normalizes its collections through `{ ...c }`, so the
+     * backend registry and each driver's registry hold **separate copies** of
+     * the same collection — assigning callbacks to one is invisible to the
+     * driver that actually invokes them, and the hooks silently never fire.
+     * This writes to all of them.
+     *
+     * It REPLACES the callbacks the collection declared. To keep them, attach
+     * `composeCallbacks(declared, mine)`.
+     */
+    setCollectionCallbacks(slug: string, callbacks: CollectionCallbacks): void;
+    /**
+     * Deep health check that verifies database connectivity.
+     * Returns latency and component status.
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Stop what `start()` started and `attachRealtime()` attached, waiting for
+     * work in flight (cron runs, jobs, `waitUntil()` tasks) within the budget.
+     *
+     * The HTTP server is the application's: it is closed — drained, then
+     * force-closed at the deadline — only when passed as `options.server`.
+     *
+     * @param timeoutMs - Maximum time (ms) to wait for drain before giving up
+     *                    (default: 15000). Pass 0 to wait without a deadline.
+     */
+    shutdown(timeoutMs?: number, options?: {
+        server?: Server;
+    }): Promise<void>;
+}
+/**
+ * Type guard to detect whether `database` is a `DatabaseAdapter`.
+ */
+export declare function isDatabaseAdapter(db: unknown): db is DatabaseAdapter;
+/**
+ * Present a `DatabaseAdapter` as a `BackendBootstrapper`.
+ *
+ * The `database` convenience path — one adapter, no explicit source keys —
+ * funnels through here. `adapterToBootstrapper` in `boot/driver.ts` does the
+ * same job for the multi-source path, and the two stay separate because only
+ * that one carries a registry id and a default flag; this path has exactly one
+ * driver and needs neither.
+ *
+ * Both wrappers rebuild the bootstrapper field by field, which means any
+ * capability nobody remembers to list is dropped in silence — no type error,
+ * because every one of them is optional, and no runtime error either, because
+ * the caller's own fallback for "driver does not implement this" is to skip.
+ * That is not hypothetical: `ensureCollectionSchema` was missing from both
+ * wrappers for months, so every managed tenant booted with no collection tables
+ * and 500'd on every data route. `bootstrapper-forwarding.test.ts` now asserts
+ * both wrappers pass through the whole optional surface.
+ */
+export declare function wrapDatabaseAdapter(dbAdapter: DatabaseAdapter): BackendBootstrapper;
+/**
+ * Build a backend: open the drivers, provision what `options.provision` allows,
+ * initialise auth, storage and the in-process client, and build every route
+ * group. Mounts nothing, starts no timer, adds no process listener — see
+ * {@link RebaseBackend} for the steps that do.
+ *
+ * Writes no process global either. The backend holds its own JWT keys, access
+ * model, API-key store, rate-limit counts and client (`backend.services`,
+ * `backend.rebase`), and code it runs — a function, a cron job, a hook — sees
+ * it as `rebase`. The module-level API (`rebase` outside any request,
+ * `verifyAccessToken`, `getAccessModel`, …) answers for the process default,
+ * which {@link setDefaultBackend} sets and `initializeRebaseBackend` sets for
+ * its backend. The one process-wide setting it touches is the log level, and
+ * only when `logging.level` is given: the logger is the process's.
+ */
+export declare function createRebaseBackend(options: RebaseBackendOptions): Promise<RebaseBackend>;
+/**
+ * Where the SDK's socket dials for an API mounted at `basePath`.
+ *
+ * The client sends HTTP to `${baseUrl}/api` and opens the socket at `baseUrl`
+ * itself, so the socket's path is the base path without its trailing `/api`:
+ * `/api` → `/`, `/x/api` → `/x`. Any other base path gives `/`, the default an
+ * SDK configured with that path as its `apiPath` dials.
+ */
+export declare function realtimeSocketPath(basePath: string | undefined): string;

package/dist/backend/default-backend.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The process default: the backend the module-level API answers for.
+ *
+ * `rebase` outside any request, `verifyAccessToken` and the other JWT helpers,
+ * `getAccessModel`, `verifyCredential`, `extractUserFromToken`, the auth
+ * limiters exported as constants, and topics and queues published from code
+ * no backend is running. Each is one shallow step above the backend's own
+ * services, for code that has no backend in hand — a function file, a script,
+ * a test.
+ *
+ * `initializeRebaseBackend` installs its backend here. `createRebaseBackend`
+ * does not: a backend built by hand answers for itself
+ * (`backend.services`, `backend.rebase`) and sets nothing anyone else reads,
+ * so two of them in one process stay two. Make one of them the default when
+ * the process uses the module-level API.
+ *
+ * @module
+ */
+import type { RebaseServerClient } from "@rebasepro/types";
+import type { BackendServices } from "./services.js";
+/**
+ * Make `backend` the process default: what `rebase`, the JWT helpers,
+ * `getAccessModel`, `verifyCredential` and topics and queues answer for
+ * outside any request a backend is serving.
+ *
+ * @example
+ * ```ts
+ * const backend = await createRebaseBackend({ database, auth, collections, provision: true });
+ * setDefaultBackend(backend); // `import { rebase } from "@rebasepro/server"` is now this backend, everywhere
+ * ```
+ */
+export declare function setDefaultBackend(backend: {
+    rebase: RebaseServerClient;
+    services: BackendServices;
+}): void;