@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/init.d.ts

@@ -1,621 +1,30 @@
-import { AuthAdapter, BackendBootstrapper, BootstrappedAuth, DatabaseAdapter, DataDriver, CollectionCallbacks, AnyCollectionConfig, HealthCheckResult, HistoryConfig, InitializedDriver, RealtimeProvider } from "@rebasepro/types";
-import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry.js";
-import { DriverRegistry } from "./services/driver-registry.js";
-import { Server } from "http";
-import { Hono } from "hono";
-import { HonoEnv } from "./api/types.js";
-import type { SchemaEditPolicy, RemoteRepositoryConfig } from "./schema-edit/schema-edit-permissions.js";
 /**
- * Who may change this project's schema through a running backend.
+ * `initializeRebaseBackend` — the one-call boot, written as the public steps it
+ * stands for.
  *
- * An alias rather than its own shape: the policy is defined next to the code
- * that enforces it, and a second declaration here would be a second place for
- * it to drift.
+ * Everything it does is a call a reader can make themselves: build the backend
+ * (`createRebaseBackend`), make it the process default (`setDefaultBackend`),
+ * mount it on the application's Hono app, attach the realtime websocket to its
+ * server, start the timers. Copy the body and change
+ * one line — mount only the data API, put it under another path, leave the
+ * timers to another process — and you have the variant you need, built from
+ * the same pieces.
  *
- * @see `packages/server/src/schema-edit/schema-edit-permissions.ts`
+ * @module
  */
-export interface LiveSchemaConfig extends SchemaEditPolicy {
-    /**
-     * A repository to commit to when the source is not on this machine.
-     *
-     * A bundle deployment ships compiled output, so there is nothing for the
-     * collection editor to rewrite locally. Configure this and the change is
-     * read from the repository, rewritten, and committed back through the Git
-     * Data API — no clone, no working tree.
-     *
-     * Absent, live schema editing needs the project mounted and says so.
-     */
-    repository?: RemoteRepositoryConfig;
-}
-import { type RlsAuditConfig } from "./rls-audit/index.js";
-import type { CaptchaConfig } from "./auth/captcha.js";
-import { type RuntimeOwnershipOptions, type RuntimeSurfaceOptions } from "./init/surfaces.js";
-import type { JwtSigningKeyConfig } from "./auth/jwt-keys.js";
-import type { JobQueueOptions } from "./jobs/types.js";
-import { BackendStorageConfig, StorageController, StorageRegistry } from "./storage/index.js";
-import { type DataRateLimitConfig } from "./auth/rate-limiter.js";
-import { EmailConfig } from "./email/index.js";
-import type { OAuthProvider } from "./auth/interfaces.js";
-import type { AuthHooks } from "./auth/auth-hooks.js";
-export interface RebaseAuthConfig {
-    /**
-     * The collection that represents auth users.
-     *
-     * When provided, this collection's underlying database table is used
-     * for all auth operations (login, registration, password reset, etc.).
-     *
-     * Import the built-in default:
-     * ```ts
-     * import { defaultUsersCollection } from "@rebasepro/common";
-     * auth: { collection: defaultUsersCollection, jwtSecret: "..." }
-     * ```
-     *
-     * Or pass your own collection with the required auth fields
-     * (email, passwordHash, displayName, etc.).
-     */
-    /**
-     * Accepts a collection of any row type: `defineCollection` infers `M` from
-     * the properties, and `CollectionConfig` is invariant in `M`, so a bare
-     * `CollectionConfig` here rejects everything the builder returns.
-     */
-    collection?: AnyCollectionConfig;
-    jwtSecret?: string;
-    /**
-     * Asymmetric keys for signing access tokens, newest first. Additive —
-     * without them tokens stay HS256, exactly as before. With them, anyone can
-     * verify a session from `/.well-known/jwks.json` without holding the key
-     * that mints one, and a key can be rotated without signing users out.
-     *
-     * ```ts
-     * auth: {
-     *   jwtSecret: process.env.JWT_SECRET,
-     *   signingKeys: [{ kid: "2026-08", privateKey: process.env.JWT_PRIVATE_KEY! }]
-     * }
-     * ```
-     */
-    signingKeys?: JwtSigningKeyConfig[];
-    /** Which of {@link signingKeys} mints new tokens. Defaults to the first. */
-    activeKid?: string;
-    accessExpiresIn?: string;
-    refreshExpiresIn?: string;
-    requireAuth?: boolean;
-    allowRegistration?: boolean;
-    /**
-     * Block self-registration outright — the hard kill switch.
-     *
-     * `allowRegistration: false` still admits the very first user on an empty
-     * database, because otherwise a fresh deployment has no way to create its
-     * own admin: `POST /admin/bootstrap` needs an authenticated caller. This
-     * closes that window too, for operators who provision every account out of
-     * band and never want a public first-come-first-admin race.
-     *
-     * With this set, an empty backend has no self-service path in at all —
-     * create the first user with the CLI or a seed script.
-     */
-    disableSelfRegistration?: boolean;
-    /**
-     * Opt-in: allow `POST /auth/anonymous` to mint a user with no credentials.
-     *
-     * Off by default. Anonymous sign-in inserts a `users` row and assigns
-     * `defaultRole` exactly as registration does, so leaving it always-on meant
-     * a backend with `allowRegistration: false` and `disableSelfRegistration:
-     * true` still handed out permanent accounts: `/auth/anonymous` for the row
-     * and the session, then `/auth/anonymous/link` to put an email and password
-     * on it. `disableSelfRegistration` overrides this key.
-     */
-    allowAnonymous?: boolean;
-    /**
-     * Opt-in: expose `POST /auth/find-user` so an authenticated user can resolve
-     * an email address to a minimal public profile (`uid`, `displayName`,
-     * `photoURL` only). This powers invite-by-email flows without a custom
-     * admin server function. Off by default because it enables user enumeration
-     * by any signed-in user. Available on the client as `auth.findUserByEmail`.
-     */
-    allowUserLookup?: boolean;
-    /**
-     * Bot protection on the auth routes that cost something to hit.
-     *
-     * Off unless `enabled`. Rate limiting bounds one caller; a botnet of a
-     * thousand addresses sending one request each never touches a per-IP window,
-     * and `/register` and `/forgot-password` both send mail — so the bill for an
-     * unprotected form is paid in reputation on a sending domain.
-     *
-     * ```ts
-     * auth: { captcha: { enabled: true, provider: "turnstile", secret: process.env.TURNSTILE_SECRET } }
-     * ```
-     *
-     * Verification fails closed: if the provider cannot be reached, the request
-     * is refused. See `auth/captcha.ts` for why that is the safe direction.
-     */
-    captcha?: CaptchaConfig;
-    /**
-     * A static secret key for server-to-server / script authentication.
-     *
-     * When a request includes `Authorization: Bearer <serviceKey>`, it is
-     * granted admin-level access without JWT verification. This is the
-     * Rebase equivalent of a Service Account key.
-     *
-     * Generate with: `node -e "logger.info(require('crypto').randomBytes(48).toString('base64'))"`
-     *
-     * Set via `REBASE_SERVICE_KEY` in your `.env`.
-     * Must be at least 32 characters.
-     */
-    serviceKey?: string;
-    email?: EmailConfig;
-    google?: {
-        clientId: string;
-        clientSecret?: string;
-    };
-    linkedin?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    github?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    microsoft?: {
-        clientId: string;
-        clientSecret: string;
-        tenantId?: string;
-    };
-    apple?: {
-        clientId: string;
-        teamId: string;
-        keyId: string;
-        privateKey: string;
-    };
-    facebook?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    twitter?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    discord?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    gitlab?: {
-        clientId: string;
-        clientSecret: string;
-        baseUrl?: string;
-    };
-    bitbucket?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    slack?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    spotify?: {
-        clientId: string;
-        clientSecret: string;
-    };
-    defaultRole?: string;
-    /**
-     * Canonical array of OAuth providers.
-     *
-     * This is the primary extension point for **all** OAuth integrations.
-     * Each entry is an `OAuthProvider<unknown>` constructed via one of
-     * the `create*Provider` factories exported from `@rebasepro/server`
-     * (e.g. `createGoogleProvider`, `createGitHubProvider`).
-     *
-     * The named convenience fields above (`google`, `github`, etc.) are
-     * automatically resolved into this array at startup. You can mix both
-     * approaches; named fields and explicit entries are merged (named
-     * fields are appended after explicit entries).
-     *
-     * @example
-     * ```ts
-     * import { createGoogleProvider } from "@rebasepro/server";
-     *
-     * auth: {
-     *   providers: [
-     *     createGoogleProvider({ clientId: "…", clientSecret: "…" }),
-     *   ],
-     * }
-     * ```
-     */
-    providers?: OAuthProvider<unknown>[];
-    /**
-     * Redirect URIs the OAuth sign-in routes will accept, for every provider.
-     *
-     * Left unset, the only check is the provider's own registered-URI match —
-     * which authorises *every* URI registered on that OAuth client, including
-     * the `localhost` entry someone added for development and the staging host
-     * nobody removed. List the origins this backend actually serves to narrow
-     * it. Compared on origin plus path; query, fragment and a trailing slash
-     * are ignored.
-     *
-     * @example
-     * ```ts
-     * auth: { allowedRedirectUris: ["https://admin.example.com/"] }
-     * ```
-     */
-    allowedRedirectUris?: string[];
-    /**
-     * 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";
-     *
-     * hooks: {
-     *     hashPassword: (pw) => bcrypt.hash(pw, 12),
-     *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
-     * }
-     * ```
-     */
-    hooks?: AuthHooks;
-    /**
-     * Enable magic link (passwordless email) authentication.
-     * Requires email to be configured.
-     */
-    magicLink?: boolean;
-    /**
-     * Enable email one-time codes — six digits, typed in, instead of a link.
-     *
-     * A magic link opens the session on whichever device holds the mailbox,
-     * which is the wrong device whenever those are two different machines: a
-     * television, a terminal, a second browser. A code crosses that gap because
-     * a person carries it.
-     *
-     * `POST /auth/otp` sends one; `POST /auth/otp/verify` trades it for a
-     * session. Requires email to be configured, as magic link does.
-     */
-    emailOtp?: boolean;
-    /**
-     * Opt-in httpOnly cookie mode for refresh tokens.
-     *
-     * When set, the refresh token is delivered as an `httpOnly`, `Secure`,
-     * `SameSite` cookie instead of in the JSON response body. This
-     * prevents XSS from stealing the long-lived refresh token.
-     *
-     * The access token remains in the JSON body so the client can use it
-     * in `Authorization: Bearer` headers for API calls.
-     *
-     * **Requires** `credentials: "include"` on client-side fetch calls to
-     * auth endpoints, and CORS must allow credentials (no `origin: "*"`).
-     */
-    cookieAuth?: import("./auth/index.js").CookieAuthConfig;
-    /**
-     * Refuse password sign-in until the account's email address is verified,
-     * and make registration confirm-first. Off by default.
-     *
-     * Off, `POST /auth/register` signs the new account in and mails it a
-     * verification link; an address that already has an account is answered
-     * `409 EMAIL_EXISTS`. On, register signs nobody in and answers the same
-     * "check your inbox" whether or not the address has an account (an
-     * unconfirmed one is mailed its link again), and `POST /auth/login`
-     * answers `403 EMAIL_NOT_CONFIRMED` for an unverified account —
-     * only once the password is right. Following the link with the password completes
-     * the sign-up (`POST /auth/verify-email`).
-     *
-     * Needs email: the boot refuses it without, since nobody could ever
-     * confirm. Set by `AUTH_REQUIRE_EMAIL_VERIFICATION=true`.
-     */
-    requireEmailVerification?: boolean;
-    /**
-     * How long a refresh token that was rotated away still mints a sibling of
-     * the same session, in seconds. Default 10 (GoTrue's
-     * `refresh_token_reuse_interval`): a client that lost a refresh answer —
-     * a deploy, a suspended laptop, two tabs at once — is not signed out.
-     */
-    refreshTokenReuseIntervalSeconds?: number;
-    /**
-     * What a refresh token presented *after* that window does. Default
-     * `"reject"`: the request is refused and logged, and the session stands,
-     * because its live token is still good — which also means a thief who
-     * refreshed first keeps it. `"revoke-session"` ends the whole sign-in on
-     * such a replay, thief and owner alike, as GoTrue does: the owner signs
-     * in again. Set by `AUTH_REFRESH_TOKEN_REUSE`; anything else fails the boot.
-     */
-    refreshTokenReuse?: "reject" | "revoke-session";
-    /**
-     * Let a magic-link or email-code request for an address with no account
-     * create one — passwordless sign-up — while registration is open
-     * (`allowRegistration`, not `disableSelfRegistration`). The account has no
-     * password and is unverified until the link or code is used, which proves
-     * the address and signs it in. Off by default, so those requests answer an
-     * unknown address the same as a known one and create nothing. Set by
-     * `AUTH_MAGIC_LINK_CREATES_USERS`.
-     */
-    magicLinkCreatesUsers?: boolean;
-}
-/** @see RebaseBackendConfig.baas */
-export interface BaasOptions {
-    /**
-     * What to do with introspected tables that have row-level security
-     * disabled.
-     *
-     * Such a table carries no authorization model. Every authenticated request
-     * runs as `rebase_user`, which is granted DML on the schema, so serving one
-     * hands every row to every logged-in user — the API would be an open door
-     * onto whatever the database happens to contain.
-     *
-     * - `"exclude"` (default) — do not serve it. Each excluded table is logged
-     *   with the SQL to protect it. Secure by default, consistent with the rest
-     *   of the driver, which fails a boot rather than serve unenforced requests.
-     * - `"serve"` — serve it anyway. Only sensible when every caller is already
-     *   trusted, e.g. an internal service behind its own authorization.
-     */
-    unprotectedTables?: "exclude" | "serve";
-}
-export interface RebaseBackendConfig {
-    /** Invariance again — see the note on `RebaseAuthConfig.collection`. */
-    collections?: AnyCollectionConfig[];
-    collectionsDir?: string;
+import type { Server } from "node:http";
+import type { Hono } from "hono";
+import type { HonoEnv } from "./api/types.js";
+import { type RebaseBackend } from "./backend/create-backend.js";
+import type { RebaseBackendOptions } from "./backend/options.js";
+/** What {@link initializeRebaseBackend} takes: a backend's options, and where to serve it. */
+export interface RebaseBackendConfig extends Omit<RebaseBackendOptions, "provision"> {
+    /** The HTTP server the realtime websocket attaches to, and that `shutdown()` drains and closes. */
     server: Server;
+    /** The application's Hono app, which the backend is mounted onto. */
     app: Hono<HonoEnv>;
+    /** The prefix every route group is mounted under. Default `/api`. */
     basePath?: string;
-    /**
-     * Rate limiting for the data API, per caller: an API key by its id, a
-     * signed-in user by their uid, anyone else by IP.
-     *
-     * On by default with loose limits — a floor against a runaway client, not a
-     * quota. Counts live in this process's memory unless you pass a `store`, so
-     * N replicas enforce N times the limit between them; set real quotas at a
-     * proxy or supply a shared store if that matters. `{ enabled: false }` for
-     * a deployment whose edge already does this.
-     */
-    rateLimit?: DataRateLimitConfig;
-    /**
-     * Force the schema-editor routes on or off.
-     *
-     * Defaults to enabled when `collectionsDir` is set, outside production, in
-     * `cms` mode. The editor rewrites collection files, so it needs a
-     * `collectionsDir` to write to.
-     */
-    schemaEditor?: boolean;
-    /**
-     * Live schema editing — changing the database and committing the change.
-     *
-     * Distinct from `schemaEditor`, which only rewrites collection source.
-     * There is nothing to switch on here: the surface mounts whenever there is
-     * a `collectionsDir`, and refuses in its own words when it cannot act. What
-     * this configures is *who* may act.
-     */
-    liveSchema?: LiveSchemaConfig;
-    /** Options that only apply when collections are derived from the database. */
-    baas?: BaasOptions;
-    /**
-     * The pre-init handle to hand the boot-time schema hooks, when the caller
-     * has one.
-     *
-     * Those hooks run before any driver is initialized, so there is no driver
-     * result to pass — the bundle boot path can still supply a stand-in built
-     * from the connection its coordinator opened, and does, because a driver
-     * written before this was optional dereferences `driverResult.internals`
-     * unconditionally. An application that constructed its own adapter has no
-     * such handle to give (it gave the connection to the adapter instead), so it
-     * leaves this unset and the adapter falls back to its own connection.
-     *
-     * @internal Set by `bootFromBundle`; not part of the ordinary configuration
-     * surface.
-     */
-    provisioningDriverResult?: InitializedDriver;
-    /**
-     * Database bootstrappers, one per data source.
-     *
-     * The `id` of each is the key `collection.dataSource` routes against, so a
-     * project with several databases passes several — `initializeDataSources`
-     * builds them from the declared graph. The list of *declared* sources is no
-     * longer an option here: it is read from the resource graph, which is the
-     * one place a project declares them.
-     *
-     * @internal Built by `initializeDataSources` from the declared resource graph. Pass `database` instead.
-     */
-    bootstrappers?: BackendBootstrapper[];
-    /**
-     * Database adapter.
-     *
-     * When set, this takes precedence over `bootstrappers`.
-     *
-     * @example
-     * ```ts
-     * import { createPostgresAdapter } from "@rebasepro/server-postgres";
-     * database: createPostgresAdapter({ connection: db, schema }),
-     * ```
-     */
-    database?: DatabaseAdapter;
-    logging?: {
-        level?: "error" | "warn" | "info" | "debug";
-    };
-    /**
-     * 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:
-     *
-     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3' | 'gcs', ... }`)
-     * - A `StorageController` instance (for custom providers like Azure, etc.)
-     * - A `Record<string, ...>` of either, for multi-backend setups
-     */
-    storage?: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController>;
-    /**
-     * Declared storage sources. Drives the client-side StorageSourceRegistry
-     * and the transport distinction (server vs direct).
-     *
-     * Server-backed sources are auto-derived from the `storage` map — you
-     * only need explicit entries for "direct" transport sources (e.g.
-     * external storage) that the backend does not proxy.
-     */
-    /**
-     * Per-object access control for storage — the analogue of a collection's
-     * security rules, and the thing `requireAuth` / `publicRead` cannot
-     * express because they are global switches.
-     *
-     * Called after authentication on every storage route with the key, bucket,
-     * operation (`read` / `write` / `delete` / `list`) and resolved user.
-     * Return false to deny with a 403; throwing denies too.
-     *
-     * ```ts
-     * storageAuthorize: async ({ key, user, operation }) => {
-     *     if (!user) return false;
-     *     const [ownerId] = key.split("/");
-     *     return ownerId === user.uid || operation === "read";
-     * }
-     * ```
-     *
-     * Without it, any authenticated caller may read any key they can name, so
-     * multi-tenant apps should treat this as required rather than optional.
-     *
-     * In production, storage refuses to boot unless one of `storageAuthorize`,
-     * {@link storagePublicRead}, or {@link storageInsecureAllowAnyAuthenticated}
-     * is set — see `assertStorageAccessControlConfigured`.
-     */
-    storageAuthorize?: import("./storage/types.js").StorageAuthorize;
-    /**
-     * Per-object access control, declared rather than coded.
-     *
-     * Storage is not under row-level security, so without this or
-     * {@link storageAuthorize} any authenticated caller may read, overwrite,
-     * delete or list any key they can name — the keys share one flat namespace.
-     *
-     * ```ts
-     * storagePolicies: [
-     *     { path: "public/**", operations: ["read"], allow: "public" },
-     *     { path: "users/:uid/**", allow: ({ params, user }) => user?.uid === params.uid }
-     * ]
-     * ```
-     *
-     * **A key matched by no policy is refused.** Every widening is an explicit
-     * line, and a mistake here denies rather than grants.
-     *
-     * `storageAuthorize` still runs when no policy matched, so ownership that
-     * lives in a row — which no path pattern can express — stays expressible.
-     * Neither can narrow the other: each only says yes.
-     *
-     * Satisfies the production boot guard on its own.
-     */
-    storagePolicies?: import("./storage/policies.js").StoragePolicy[];
-    /**
-     * Allow unauthenticated read access to stored files (default: false).
-     *
-     * Set this only when the bucket is genuinely a public, read-only CDN.
-     * Because it is a deliberate statement that reads are public, it also
-     * satisfies the production storage boot guard (see {@link storageAuthorize}).
-     *
-     * On its own — no {@link storagePolicies}, no {@link storageAuthorize} — it
-     * means public READ and nothing else: writes, deletes and listings are
-     * admin-only. The sentence "writes still require authentication" used to be
-     * the whole of it, and it was not enough, because the deployment this flag
-     * is for is the public site, which commonly runs with `requireAuth` off —
-     * so "requires authentication" required nothing. A deployment that wants
-     * anonymous or per-user writes says where, with a policy or a hook.
-     */
-    storagePublicRead?: boolean;
-    /**
-     * Keep derived image renditions — the results of `?width=`, `?format=` and
-     * friends — in the storage source rather than only in this process's
-     * memory.
-     *
-     * Without it a transform is recomputed by every instance, and again by all
-     * of them after every deploy: the cache is per-process and does not survive
-     * a restart. With it, the first instance to compute a variant writes it
-     * under a reserved prefix in the same bucket as the source, and every
-     * instance reads it from there.
-     *
-     * ```ts
-     * storageRenditionCache: { enabled: true }
-     * ```
-     *
-     * Off by default because turning it on makes a `GET` write to your bucket:
-     * it costs per object, and on read-only credentials it cannot work. When a
-     * write does fail the request still succeeds — the transform is served from
-     * memory and the failure is logged once.
-     *
-     * Renditions are keyed by the source object's version, so replacing an
-     * image serves the new one immediately; the superseded rendition is left
-     * behind. Set a lifecycle rule on `_rebase/renditions/` to collect them.
-     */
-    storageRenditionCache?: import("./storage/rendition-cache.js").RenditionCacheConfig;
-    /**
-     * How long a private file's download URL works, in seconds — the lifetime
-     * of the token `GET /storage/metadata/*` mints. Default 300; at most a week.
-     * `STORAGE_DOWNLOAD_TOKEN_TTL` on a bundle deployment.
-     *
-     * Five minutes renders a page; a private `<video>` that plays longer asks
-     * for its next range with an expired token. The token travels in the URL,
-     * which is the reason for the ceiling: an object that must be linked
-     * indefinitely belongs under the public prefix instead.
-     */
-    storageDownloadTokenTtl?: number;
-    /**
-     * Run something when an object lands, or when one goes.
-     *
-     * Every other write in the product can be reacted to — a row has
-     * `beforeSave` and `afterSave`, a schedule has a cron job — and an upload
-     * had nothing, so the work an upload implies had to be done by the client
-     * after the upload returned, which means it is not done at all when the
-     * client goes away between the two calls.
-     *
-     * ```ts
-     * storageTriggers: [
-     *     {
-     *         path: "uploads/:uid/**",
-     *         events: ["finalize"],
-     *         handler: async ({ key, params }) => { … }
-     *     }
-     * ]
-     * ```
-     *
-     * Same pattern language as {@link storagePolicies}. Fires for the
-     * multipart and resumable paths alike, after the object is durably
-     * written, and never for internal writes such as the image-rendition cache.
-     * Handlers are awaited and a throwing one is logged rather than failing the
-     * request — the object is already stored, so telling the client otherwise
-     * would invite it to repeat a write that succeeded. Enqueue a job for
-     * anything that must happen or is slow.
-     */
-    storageTriggers?: import("./storage/triggers.js").StorageTrigger[];
-    /**
-     * Opt out of the storage access-control boot guard, keeping the legacy
-     * behaviour where **any** authenticated user can read, overwrite, delete or
-     * list **any** key (storage keys share one flat namespace and are not under
-     * RLS).
-     *
-     * Only safe for single-tenant apps where every signed-in user is trusted
-     * with every file. Multi-tenant apps must use `storageAuthorize` instead.
-     * Without one of these, storage refuses to boot in production.
-     */
-    storageInsecureAllowAnyAuthenticated?: boolean;
-    /**
-     * Entity history / audit-log configuration.
-     *
-     * - `true` — enable history with default settings
-     * - `{ retention?: number }` — enable with optional retention period (days)
-     */
-    history?: HistoryConfig;
-    enableSwagger?: boolean;
-    /**
-     * Which HTTP surfaces this process mounts. Every one, unless named.
-     *
-     * The point of naming a subset is to run the same bundle as several
-     * cooperating processes — one answering `/api/data`, another `/api/functions`
-     * — so a custom function that pins the event loop does not do it in the
-     * process serving the data API. `bootFromBundle` derives this from
-     * `REBASE_ROLE`; passing it directly is for tests and for embedders.
-     *
-     * Omitting it, or naming only some surfaces, leaves the rest mounted. That
-     * default is deliberate: a surface added in a later version is served by
-     * every existing deployment without anyone editing a list.
-     */
     /**
      * Whether this process provisions the collection schema and its RLS
      * policies at boot. Default `true` — what every deployment does today.
@@ -625,268 +34,43 @@ export interface RebaseBackendConfig {
      * provision the same schema is a state nobody designed. `bootFromBundle`
      * derives it from `REBASE_ROLE`.
      *
+     * Becomes `createRebaseBackend`'s `provision`: everything when `true`; the
+     * framework's own tables and role but neither the collection schema nor
+     * change capture when `false`.
+     *
      * @internal Derived from `REBASE_ROLE` by `bootFromBundle`.
      */
     provisionSchema?: boolean;
-    surfaces?: RuntimeSurfaceOptions;
-    /**
-     * Which background singletons this process runs. All of them, unless named.
-     *
-     * Separate from {@link surfaces} because "which URLs answer" and "which
-     * timers fire" are independent: a process can serve the cron *admin* surface
-     * without being the one that fires the jobs, and vice versa.
-     *
-     * Neither is a correctness control — the cron scheduler claims each
-     * `(job, slot)` pair and the job store claims rows `FOR UPDATE SKIP LOCKED`,
-     * so running several of each is already safe. It is about not handing
-     * scheduled work to a process whose replica count is a scaling decision.
-     */
-    ownership?: RuntimeOwnershipOptions;
-    functionsDir?: string;
-    /**
-     * Per-request ceiling for `/api/functions/*`, in milliseconds.
-     *
-     * Custom functions run code the framework did not write, and nothing else
-     * in the stack bounds it. Defaults to 30000 (or
-     * `REBASE_FUNCTIONS_TIMEOUT_MS`). `0` disables the ceiling — for a function
-     * that legitimately runs long, or a deployment whose proxy already imposes
-     * one. Timed-out requests answer 504; the handler itself cannot be
-     * cancelled, so give outbound calls an `AbortSignal`.
-     */
-    functionsTimeoutMs?: number;
-    /**
-     * Serve only some of the bundle's functions.
-     *
-     * How one expensive function gets its own replica count and its own blast
-     * radius without its code moving anywhere. `bootFromBundle` fills this from
-     * `REBASE_FUNCTIONS_ONLY` / `REBASE_FUNCTIONS_EXCLUDE`.
-     *
-     * A name that is not in the bundle fails the boot — see `selectFunctions`.
-     *
-     * @internal Filled from `REBASE_FUNCTIONS_ONLY` / `REBASE_FUNCTIONS_EXCLUDE`.
-     */
-    functionsSelection?: import("./functions/selection.js").FunctionSelection;
-    /**
-     * Forward `/api/functions/*` to another process instead of serving it here.
-     *
-     * Only consulted when the `functions` surface is off — a process that serves
-     * them has nothing to forward. `bootFromBundle` fills this from
-     * `REBASE_FUNCTIONS_UPSTREAM` on the `api` role.
-     *
-     * @internal Filled from `REBASE_FUNCTIONS_UPSTREAM` on the `api` role.
-     */
-    functionsUpstream?: 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;
-    /**
-     * The durable job queue: background work that survives a restart.
-     *
-     * Off unless `enabled` is set, because a worker polls the database forever
-     * and that is not a default anyone chose. Requires a driver that can run
-     * SQL; on one that cannot, the queue is unavailable and callers are told
-     * so at boot rather than at the first enqueue.
-     *
-     * ```ts
-     * jobs: {
-     *   enabled: true,
-     *   tasks: {
-     *     "send-welcome": async ({ payload }) => { await sendEmail(payload.email); }
-     *   }
-     * }
-     * ```
-     */
-    jobs?: JobQueueOptions;
-    /**
-     * Maximum request body size in bytes for API routes (default: 10MB).
-     * Set to 0 to disable the global limit entirely.
-     *
-     * Note: `POST /storage/upload` is not under this limit. It is capped by the
-     * storage config's `maxFileSize` instead (default: 50MB), whether that is
-     * larger or smaller than this. Every other route stays under this limit,
-     * the rest of `/storage` included. A TUS upload is many requests, so this
-     * caps each chunk (`PATCH /storage/tus/:id`), and `maxFileSize` caps the
-     * whole file.
-     */
-    maxBodySize?: number;
-    /**
-     * Response compression for API routes. **Enabled by default.**
-     *
-     * Compresses responses with gzip/deflate, negotiated from the request's
-     * `Accept-Encoding`. Bodies that are already compressed (images, video),
-     * streamed (`text/event-stream`), or explicitly marked
-     * `Cache-Control: no-transform` are left untouched, so this is safe to
-     * leave on — a large JSON list response typically drops by ~20x.
-     *
-     * Set to `false` when something in front of the app already compresses
-     * (nginx, Cloudflare, or another reverse proxy / load balancer), to avoid
-     * paying for it twice.
-     */
-    compression?: boolean;
-    /**
-     * CSRF protection configuration. **Opt-in** — disabled by default.
-     *
-     * BaaS APIs are consumed by mobile apps, SPAs on different domains,
-     * and CLI tools, so CSRF is intentionally not enabled unless you
-     * explicitly configure it with allowed origins.
-     *
-     * @example
-     * ```ts
-     * csrf: { origin: ["https://myapp.com", "https://admin.myapp.com"] }
-     * ```
-     */
-    csrf?: {
-        /** Allowed origins for CSRF validation. */
-        origin: string | string[] | ((origin: string) => boolean);
-    };
-    /**
-     * Global lifecycle callbacks applied to every collection.
-     *
-     * Same type as per-collection `callbacks` — fires on **every** data path
-     * (REST API, WebSocket / realtime, server-side `rebase.dataAsAdmin`).
-     *
-     * Execution order: global callbacks → collection callbacks → property callbacks.
-     *
-     * @example
-     * ```ts
-     * callbacks: {
-     *     afterRead({ row, collection }) {
-     *         console.log(`Read ${collection.slug}/${row.id}`);
-     *         return row;
-     *     }
-     * }
-     * ```
-     */
-    callbacks?: CollectionCallbacks;
-    /**
-     * Declare that this application installs its own CORS middleware.
-     *
-     * Suppresses the "no CORS configuration detected" warning, which exists for
-     * hand-wired backends that genuinely have no origin policy.
-     *
-     * @internal Set by the boot path that installs CORS itself.
-     */
-    corsHandled?: boolean;
-    /**
-     * The schema version this deployment serves, as recorded when it was built.
-     *
-     * Published by the contract endpoint so a client generated elsewhere can
-     * tell whether it is current. Leave unset and the runtime computes one from
-     * the live collections — correct, but it means the value moves whenever the
-     * collections do, which is exactly right for `baas` mode and slightly less
-     * useful for a built bundle that already knows its own answer.
-     */
-    schemaVersion?: string;
-    /**
-     * Runtime version reported by the contract endpoint. Informational.
-     *
-     * @internal Read from the bundle manifest by `bootFromBundle`.
-     */
-    runtimeVersion?: string;
-    /**
-     * Periodic row-level-security audit of the database this server uses.
-     *
-     * Off unless `enabled` is set. `@rebasepro/rls-check` is thorough and
-     * read-only, and the reason nobody runs it is that it is a command — so this
-     * runs it on a timer and serves the result at `GET /api/admin/rls-audit`.
-     *
-     * Needs the optional peer `@rebasepro/rls-check`, which is not a hard
-     * dependency because it carries a Postgres driver and this package is
-     * engine-agnostic.
-     */
-    rlsAudit?: RlsAuditConfig;
 }
-export { isAuthAdapter } from "./auth/require-auth.js";
 /**
- * Type guard to detect whether `database` is a `DatabaseAdapter`.
+ * The backend {@link initializeRebaseBackend} returns: a {@link RebaseBackend}
+ * that is already mounted, attached and started, whose `shutdown()` also
+ * drains and closes the server it was given.
  */
-export declare function isDatabaseAdapter(db: unknown): db is DatabaseAdapter;
-export interface RebaseBackendInstance {
-    driverRegistry: DriverRegistry;
-    driver: DataDriver;
-    realtimeServices: Record<string, RealtimeProvider>;
-    realtimeService: RealtimeProvider;
-    auth?: BootstrappedAuth;
-    history?: {
-        historyService: import("./history/history-routes.js").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?: import("./metrics/history-recorder.js").MetricsHistory;
-    storageRegistry?: StorageRegistry;
-    storageController?: StorageController;
-    collectionRegistry: BackendCollectionRegistry;
-    cronScheduler?: import("./cron/index.js").CronScheduler;
-    /**
-     * The durable job queue, when `jobs.enabled` is set and the driver can run
-     * SQL. Present on the instance because the *producers* live in application
-     * code — a `WebhookDispatcher` is constructed by the app, so this is what
-     * it gets handed:
-     *
-     * ```ts
-     * const { jobQueue } = await initializeRebaseBackend({ jobs: { enabled: true } });
-     * const dispatcher = new WebhookDispatcher({ jobQueue });
-     * jobQueue?.register(WEBHOOK_DELIVERY_TASK, ctx => dispatcher.deliverQueuedJob(ctx.payload));
-     * ```
-     */
-    jobQueue?: import("./jobs/index.js").JobQueue;
-    /**
-     * Attach collection callbacks AFTER initialization.
-     *
-     * 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.
-     *
-     * (Assignment, not `Object.defineProperty`: the driver resolves callbacks
-     * with a spread, which copies only enumerable properties, and
-     * defineProperty defaults `enumerable` to false.)
-     */
-    setCollectionCallbacks(slug: string, callbacks: import("@rebasepro/types").CollectionCallbacks): void;
-    /**
-     * Deep health check that verifies database connectivity.
-     * Returns latency and component status.
-     */
-    healthCheck(): Promise<HealthCheckResult>;
-    /**
-     * Graceful shutdown helper for the BaaS instance.
-     * Stops the cron scheduler and closes the HTTP server, allowing
-     * in-flight requests to drain within the given timeout.
-     *
-     * @param timeoutMs - Maximum time (ms) to wait for drain before force-exit (default: 15000).
-     *                    Pass 0 to skip the force-exit timer (useful in tests).
-     */
-    shutdown(timeoutMs?: number): Promise<void>;
-}
+export type RebaseBackendInstance = RebaseBackend;
 /**
- * Present a `DatabaseAdapter` as a `BackendBootstrapper`.
+ * Build a backend and serve it: the process default, mounted on `config.app`
+ * under `config.basePath`, its websocket on `config.server`, its timers
+ * started.
+ *
+ * Exactly these steps, and nothing else:
+ *
+ * ```ts
+ * installUnhandledRejectionHandler();
+ * const backend = await createRebaseBackend({ ...options, provision: true });
+ * setDefaultBackend(backend);
+ * backend.mount(app, { basePath });
+ * await backend.attachRealtime(server);
+ * backend.start();
+ * ```
  *
- * The `config.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.
+ * The default is what the module-level API answers for — `rebase` outside a
+ * request, `verifyAccessToken`, `getAccessModel`, `verifyCredential` — so code
+ * written against those keeps answering for the one backend this process
+ * serves.
  *
- * Extracted from the middle of `initializeRebaseBackend` so it can be tested.
- * 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.
+ * No try/catch: an init error propagates to the caller. The app entry point
+ * (e.g. `startServer()`) should catch it and `process.exit(1)` — returning a
+ * fake instance hides critical failures and leads to silent data loss.
  */
-export declare function wrapDatabaseAdapter(dbAdapter: DatabaseAdapter): BackendBootstrapper;
 export declare function initializeRebaseBackend(config: RebaseBackendConfig): Promise<RebaseBackendInstance>;