@rebasepro/server 0.10.1-canary.6f89f77 → 0.10.1-canary.7801eed

package/bin/rebase-server.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * The Rebase runtime entrypoint.
+ *
+ * Runs a built project bundle. This is what the official `rebasepro/server`
+ * container image executes, and what a self-hosted deployment runs directly:
+ *
+ *     rebase-server ./dist-bundle
+ *     REBASE_BUNDLE=/bundle rebase-server
+ *
+ * The bundle is the project; this process is the engine. Keeping them separate
+ * is what allows the engine to be upgraded — a security patch, a performance
+ * fix — without rebuilding anyone's application.
+ */
+import { runFromBundle } from "../dist/index.es.js";
+
+const args = process.argv.slice(2);
+
+if (args[0] === "--help" || args[0] === "-h") {
+    console.log(`
+rebase-server — run a built Rebase project bundle
+
+Usage:
+  rebase-server [bundle-dir]
+
+Arguments:
+  bundle-dir            Path to the bundle. Defaults to $REBASE_BUNDLE, then ./dist-bundle
+
+Key environment variables:
+  DATABASE_URL          Connection string for the default database (required)
+  JWT_SECRET            Signing secret, >=32 chars (required in production)
+  PORT                  Port to bind (default 3001)
+  CORS_ORIGINS          Comma-separated allowed origins (required in production)
+  REBASE_METRICS        "true" to expose Prometheus metrics at /metrics
+  REBASE_MIGRATE_ON_BOOT  none | ensure  (collection tables: run 'rebase db push')
+
+Additional databases and buckets are configured by suffixing the variable with
+the source key, e.g. DATABASE_URL__ANALYTICS or S3_BUCKET__MEDIA.
+
+Docs: https://rebase.pro/docs/deployment/self-hosting/
+`.trim());
+    process.exit(0);
+}
+
+if (args[0] === "--version" || args[0] === "-v") {
+    const { readFileSync } = await import("node:fs");
+    const { fileURLToPath } = await import("node:url");
+    const { dirname, join } = await import("node:path");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+    console.log(pkg.version);
+    process.exit(0);
+}
+
+await runFromBundle({ bundleDir: args[0] });

package/dist/api/ast-schema-editor.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Move presentation keys into the `admin` block.
+ *
+ * `ADMIN_COLLECTION_KEYS` comes from `@rebasepro/types` rather than being spelled
+ * out here, so adding a field to `AdminCollectionOptions` cannot leave this writer
+ * behind. Any such key already inside `admin` wins over a top-level copy: the
+ * nested one is what the file said, and a flat duplicate is the view model's
+ * flattening leaking back.
+ */
+export declare function nestAdminKeys(collectionData: Record<string, unknown>): Record<string, unknown>;
 export declare class AstSchemaEditor {
     private project;
     private collectionsDir;

package/dist/api/contract-routes.d.ts

@@ -0,0 +1,36 @@
+import { Hono } from "hono";
+import { type CollectionConfig } from "@rebasepro/types";
+import type { HonoEnv } from "./types";
+/**
+ * The project contract endpoint.
+ *
+ * This is what makes a repository able to build against a project it does not
+ * contain. Without it, a typed client can only be generated from local
+ * collection *source*, which means every frontend must live in the same
+ * repository as the backend. Serving the contract turns that around: an app
+ * asks the project what its shape is, so a web app, a second web app and a
+ * mobile app can each live wherever they like and none of them needs to know
+ * about the others.
+ *
+ * Admin-gated. Collection definitions describe every table, column and relation
+ * in the project, including ones no security rule would ever expose — that is a
+ * map of the database, not public API documentation.
+ */
+export interface ContractRoutesConfig {
+    collectionRegistry: {
+        getRawCollections(): CollectionConfig[];
+    };
+    /**
+     * The schema version recorded at build time.
+     *
+     * Preferred over recomputing, so that what a client is told matches exactly
+     * what the bundle claims. It is recomputed only when a bundle did not record
+     * one — a `baas`-mode project derives its collections from the live database
+     * at boot, so there was nothing to hash when it was built.
+     */
+    schemaVersion?: string;
+    mode: "cms" | "baas";
+    /** Runtime package version, surfaced so a client can report what it built against. */
+    runtimeVersion?: string;
+}
+export declare function createContractRoutes(config: ContractRoutesConfig): Hono<HonoEnv>;

package/dist/api/rest/api-generator.d.ts

@@ -41,6 +41,20 @@ export declare class RestApiGenerator {
      * slug, never an id.
      */
     private enforceSubcollectionApiKeyPermission;
+    /**
+     * The collection a nested path writes into — the target of the relation its
+     * last segment names.
+     *
+     * Needed so a nested write can be checked against a schema at all. Without
+     * it these routes skipped `assertKnownWriteFields` entirely, which is why a
+     * typo `POST /posts` rejected with a 400 while the same typo on
+     * `POST /authors/1/posts` reached the database.
+     *
+     * Returns `undefined` rather than throwing when the path cannot be walked:
+     * the driver raises the authoritative error a moment later, and duplicating
+     * it here would report a resolution failure as a validation failure.
+     */
+    private resolveNestedWriteCollection;
     /**
      * Get the request-scoped driver. Throws if none is set — never falls
      * back to the unscoped `this.driver` to avoid bypassing RLS/auth.

package/dist/auth/rate-limit-store.d.ts

@@ -42,7 +42,14 @@ export interface RateLimitStore {
 export declare class MemoryRateLimitStore implements RateLimitStore {
     private store;
     private cleanupInterval?;
-    constructor(sweepMs?: number);
+    private now;
+    /**
+     * `now` exists so the window can be driven directly instead of by sleeping:
+     * a test that waits half a real window is a test that fails on a loaded
+     * machine, where the sleep overruns and the hits it expects to still be in
+     * the window have left it.
+     */
+    constructor(sweepMs?: number, now?: () => number);
     hit(key: string, windowMs: number, limit: number): Promise<RateLimitDecision>;
     private sweep;
     dispose(): void;

package/dist/boot/boot.d.ts

@@ -0,0 +1,59 @@
+import { type Server } from "http";
+import { Hono } from "hono";
+import { type RebaseBackendInstance } from "../init";
+import type { HonoEnv } from "../api/types";
+import { type RebaseBootEnv } from "./env";
+import { type LoadedBundle } from "./bundle";
+import { type InitializedDataSource } from "./driver";
+/** A running runtime, and the handle to stop it. */
+export interface BootedRuntime {
+    app: Hono<HonoEnv>;
+    server: Server;
+    backend: RebaseBackendInstance;
+    bundle: LoadedBundle;
+    env: RebaseBootEnv;
+    /** The port actually bound, which in development may not be the one asked for. */
+    port: number;
+    dataSources: InitializedDataSource[];
+    shutdown: () => Promise<void>;
+}
+export interface BootOptions {
+    /** Bundle directory. Defaults to `REBASE_BUNDLE` or `./dist-bundle`. */
+    bundleDir?: string;
+    /**
+     * A bundle that has already been resolved.
+     *
+     * `rebase dev` passes one built from source (see `createSourceBundle`), so
+     * development and production run the identical boot path rather than two
+     * implementations that drift apart.
+     */
+    bundle?: LoadedBundle;
+    /** Skip binding a port. Used by tests that drive `app.fetch` directly. */
+    listen?: boolean;
+    /** Install SIGTERM/SIGINT handlers. Off for tests. */
+    handleSignals?: boolean;
+}
+/**
+ * Boot a Rebase runtime from a built bundle.
+ *
+ * This is the entrypoint the official container image runs, and it is the same
+ * code path a self-hosted deployment uses — there is no separate "platform"
+ * runtime. Everything it does was previously the responsibility of a
+ * hand-written `backend/src/index.ts` in every project: wiring CORS and security
+ * headers, opening database connections, resolving storage, mounting health and
+ * metrics, serving the client bundle, and shutting all of it down cleanly.
+ *
+ * Moving it here is what makes a project's *code* separable from the *engine*
+ * that runs it: the bundle can then be handed to a newer runtime without being
+ * rebuilt, which is the precondition for patching a fleet.
+ */
+export declare function bootFromBundle(options?: BootOptions): Promise<BootedRuntime>;
+/**
+ * Boot and keep running, reporting failures the way a container should.
+ *
+ * A `BundleError` is a configuration problem with a known fix, so it prints the
+ * message and its hint without a stack trace — the stack is noise when the
+ * answer is "set DATABASE_URL". Anything else keeps its stack, because it is a
+ * bug and the trace is the point.
+ */
+export declare function runFromBundle(options?: BootOptions): Promise<BootedRuntime>;

package/dist/boot/bundle.d.ts

@@ -0,0 +1,134 @@
+import { type CollectionConfig, type CollectionCallbacks, type DataSourceDefinition, type RebaseBundleManifest, type StorageSourceDefinition } from "@rebasepro/types";
+import type { StorageAuthorize } from "../storage/types";
+/** Thrown when a bundle cannot be read, or claims a contract this runtime cannot honour. */
+export declare class BundleError extends Error {
+    readonly hint?: string | undefined;
+    constructor(message: string, hint?: string | undefined);
+}
+/** A bundle that has been located and whose manifest has been validated. */
+export interface LoadedBundle {
+    dir: string;
+    manifest: RebaseBundleManifest;
+    /** Absolute path to the compiled collections directory, when present. */
+    collectionsDir?: string;
+    functionsDir?: string;
+    cronsDir?: string;
+    /** Absolute path to built admin assets, when the admin panel is bundled. */
+    adminDir?: string;
+    /** Absolute path to built static assets to serve from this process. */
+    staticDir?: string;
+}
+/**
+ * Read and validate a bundle's manifest.
+ *
+ * The checks here are the runtime half of the compatibility contract, and they
+ * all fail loudly at boot rather than at the first request. A container that
+ * refuses to start is a deploy that rolls back; a container that starts and then
+ * misbehaves is an incident.
+ */
+export declare function readBundleManifest(bundleDir: string): RebaseBundleManifest;
+/**
+ * Locate a bundle and resolve every directory the runtime needs from it.
+ *
+ * Entry paths in the manifest are bundle-relative and are resolved here, once,
+ * so nothing downstream has to know the layout. A declared directory that does
+ * not exist is dropped with a warning rather than failing the boot: an empty
+ * `functions/` is a perfectly ordinary project, and refusing to start over one
+ * would be the runtime inventing a requirement the developer never stated.
+ */
+/**
+ * Resolve a bundle-relative entry, refusing anything that escapes the bundle.
+ *
+ * Applied to the entries that are `import()`ed — the schema, the config index,
+ * the users collection — and not only to the ones that are merely scanned. Those
+ * three *execute code*, so they are precisely the ones a malformed or hostile
+ * manifest would target, and leaving them unchecked while guarding the read-only
+ * paths would be defending the wrong door.
+ */
+export declare function resolveBundlePath(bundleDir: string, entry: string, label: string): string;
+export declare function loadBundle(bundleDir: string): LoadedBundle;
+/**
+ * The Drizzle schema a bundle ships: tables, enums and relations, as generated
+ * from the project's collections.
+ */
+export interface BundleSchemaExports {
+    tables?: Record<string, unknown>;
+    enums?: Record<string, unknown>;
+    relations?: Record<string, unknown>;
+}
+/**
+ * Import the bundle's Drizzle schema module.
+ *
+ * Returns `undefined` when the bundle declares none — `baas` mode introspects the
+ * live database instead of shipping a schema.
+ */
+export declare function loadBundleSchema(bundle: LoadedBundle): Promise<BundleSchemaExports | undefined>;
+/**
+ * Build a bundle view over a project's **source** directories.
+ *
+ * `rebase dev` runs TypeScript directly through tsx, so there is no compiled
+ * bundle to load — but everything downstream of loading (drivers, storage, auth,
+ * routes) should be identical, or development stops predicting production. This
+ * produces the same {@link LoadedBundle} shape from source paths, so the one boot
+ * path serves both.
+ *
+ * The schema version is left empty deliberately: nothing has been built, so
+ * there is no build-time answer, and the runtime computes one from the live
+ * collections instead.
+ */
+export declare function createSourceBundle(options: {
+    projectRoot: string;
+    config?: string;
+    collections?: string;
+    functions?: string;
+    crons?: string;
+    schema?: string;
+    mode?: "cms" | "baas" | "static";
+    app?: string;
+}): LoadedBundle;
+/**
+ * Declarations a bundle's config package exports alongside its collections.
+ *
+ * These describe *topology* — which databases and which buckets exist — so they
+ * belong to the project rather than to the environment. The environment then
+ * supplies credentials for each declared key. Splitting it this way is what lets
+ * a deploy be validated before it runs: the set of things needing configuration
+ * is known from the bundle, without reading anyone's secrets.
+ */
+export interface BundleConfigExports {
+    dataSources?: DataSourceDefinition[];
+    storageSources?: StorageSourceDefinition[];
+    /**
+     * Per-object storage access control.
+     *
+     * A function, so it can only come from the project's own code — there is no
+     * environment variable that could express "this user may read this key".
+     * Without a way to supply it, a production deployment with a bucket would be
+     * forced to choose between `STORAGE_PUBLIC_READ` (world-readable) and
+     * `STORAGE_ALLOW_ANY_AUTHENTICATED` (every signed-in user can read, overwrite
+     * and delete every other user's files) — the runtime would be making an
+     * insecure choice on the developer's behalf.
+     */
+    storageAuthorize?: StorageAuthorize;
+    /** Lifecycle callbacks applied to every collection. */
+    callbacks?: CollectionCallbacks;
+}
+/**
+ * Read the config package's `index` for declarations.
+ *
+ * Absent, empty or unreadable all mean the same thing: a single default database
+ * and a single default bucket. That is the overwhelmingly common project, and it
+ * must not be required to say so. A malformed export is reported and ignored
+ * rather than fatal — a typo in an optional declaration should not take down a
+ * server whose collections are fine.
+ */
+export declare function loadBundleConfigExports(bundle: LoadedBundle): Promise<BundleConfigExports>;
+/**
+ * Import the collection that backs authentication.
+ *
+ * Auth needs to know which table holds users. The bundle names the module; the
+ * convention (`collections/users`) covers every project that did not rename it.
+ * Returning `undefined` is valid — a `baas`-mode project has no config package,
+ * and the auth bootstrapper falls back to its own default users table.
+ */
+export declare function loadUsersCollection(bundle: LoadedBundle): Promise<CollectionConfig | undefined>;

package/dist/boot/driver.d.ts

@@ -0,0 +1,57 @@
+import type { BackendBootstrapper } from "@rebasepro/types";
+import type { ResolvedDataSourceConfig } from "./sources";
+/** The connection handle a driver hands back. */
+export interface DatabaseConnection {
+    db: unknown;
+    /**
+     * Present for pool-based drivers. Closed during shutdown, and used to probe
+     * the source for health — `query` lives here, not on the connection itself.
+     */
+    pool?: {
+        end: () => Promise<void>;
+        query?: (sql: string) => Promise<unknown>;
+    };
+    /** Some drivers expose a query directly instead of via a pool. */
+    query?: (sql: string) => Promise<unknown>;
+    connectionString?: string;
+}
+/**
+ * Run a trivial query against a source, to see whether it answers.
+ *
+ * Returns `undefined` when the driver exposes no way to ask — a driver that
+ * cannot be probed must not be reported as unhealthy, only as unknown.
+ */
+export declare function probeDataSource(source: InitializedDataSource): Promise<{
+    healthy: boolean;
+    error?: string;
+} | undefined>;
+/** One initialized data source: its bootstrapper plus the handle to close. */
+export interface InitializedDataSource {
+    key: string;
+    engine: string;
+    driverPackage: string;
+    bootstrapper: BackendBootstrapper;
+    connection: DatabaseConnection;
+}
+export interface BundleSchema {
+    tables?: Record<string, unknown>;
+    enums?: Record<string, unknown>;
+    relations?: Record<string, unknown>;
+}
+/**
+ * Build a driver for one data source.
+ *
+ * Only the default source receives the bundle's Drizzle schema: the schema
+ * describes the tables generated from this project's collections, which live in
+ * the default database. Handing it to a secondary source would tell that
+ * driver's adapter about tables it does not have.
+ */
+export declare function initializeDataSource(source: ResolvedDataSourceConfig, schema: BundleSchema | undefined, resolveFrom?: string[]): Promise<InitializedDataSource>;
+/**
+ * Build drivers for every resolved data source.
+ *
+ * Sequential on purpose: a failure on the second source should not leave a
+ * half-opened pool from a third racing behind it, and the log then reads in the
+ * order a human would expect.
+ */
+export declare function initializeDataSources(sources: ResolvedDataSourceConfig[], schema: BundleSchema | undefined, resolveFrom?: string[]): Promise<InitializedDataSource[]>;

package/dist/boot/env.d.ts

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { type RebaseEnv } from "../env";
+/**
+ * The environment a bundle-booted runtime understands.
+ *
+ * This extends the base {@link loadEnv} schema with the variables an application
+ * used to declare for itself in its own `env.ts`. They live here now because the
+ * runtime, not the application, is what reads them: a project ships a bundle and
+ * a set of environment variables, and everything either side needs to agree on
+ * has to be part of the contract rather than a convention each project reinvents.
+ */
+declare const bootEnvExtension: z.ZodObject<{
+    SMTP_HOST: z.ZodOptional<z.ZodString>;
+    SMTP_PORT: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<number, string>>;
+    SMTP_SECURE: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    SMTP_USER: z.ZodOptional<z.ZodString>;
+    SMTP_PASS: z.ZodOptional<z.ZodString>;
+    SMTP_FROM: z.ZodOptional<z.ZodString>;
+    SMTP_NAME: z.ZodOptional<z.ZodString>;
+    APP_NAME: z.ZodDefault<z.ZodString>;
+    REBASE_SERVE_STATIC: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    REBASE_MIGRATE_ON_BOOT: z.ZodOptional<z.ZodEnum<{
+        "": "";
+        push: "push";
+        none: "none";
+        ensure: "ensure";
+    }>>;
+    REBASE_METRICS: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    REBASE_METRICS_TOKEN: z.ZodOptional<z.ZodString>;
+    LOG_LEVEL: z.ZodOptional<z.ZodEnum<{
+        "": "";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+        error: "error";
+    }>>;
+    STORAGE_PUBLIC_READ: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    STORAGE_ALLOW_ANY_AUTHENTICATED: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    AUTH_REQUIRE: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    AUTH_ALLOW_USER_LOOKUP: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    AUTH_COOKIE_SAME_SITE: z.ZodOptional<z.ZodEnum<{
+        "": "";
+        Strict: "Strict";
+        Lax: "Lax";
+        None: "None";
+    }>>;
+    AUTH_DEFAULT_ROLE: z.ZodOptional<z.ZodString>;
+    GITHUB_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    GITHUB_CLIENT_SECRET: z.ZodOptional<z.ZodString>;
+    MICROSOFT_CLIENT_ID: z.ZodOptional<z.ZodString>;
+    MICROSOFT_CLIENT_SECRET: z.ZodOptional<z.ZodString>;
+    REBASE_BASE_PATH: z.ZodDefault<z.ZodString>;
+    REBASE_ENABLE_SWAGGER: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    REBASE_MAX_BODY_SIZE: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    REBASE_COMPRESSION: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    REBASE_HISTORY: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        "": "";
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "" | "true" | "false">>;
+    CORS_ORIGINS: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RebaseBootEnv = RebaseEnv & z.infer<typeof bootEnvExtension>;
+/**
+ * Load and validate the environment for a bundle boot.
+ *
+ * Does not read `.env` files — that is the deployment's job (a container gets
+ * real environment variables; `rebase dev` and `rebase start` load dotenv before
+ * calling in).
+ */
+export declare function loadBootEnv(): RebaseBootEnv;
+/**
+ * Whether an origin is a loopback address.
+ *
+ * In development the runtime reflects only localhost origins. It cannot reflect
+ * an arbitrary `Origin`, because credentials are enabled: any site the developer
+ * happened to visit could otherwise make credentialed requests against the dev
+ * server with the developer's session and read the responses.
+ */
+export declare function isLocalhostOrigin(origin: string): boolean;
+/** A CORS origin resolver of the shape Hono's `cors()` middleware expects. */
+export type CorsOriginResolver = (origin: string) => string | null;
+/**
+ * Build the CORS origin policy.
+ *
+ * Production serves an explicit allow-list and nothing else. `loadEnv` already
+ * refuses to start a production process with neither `CORS_ORIGINS` nor
+ * `FRONTEND_URL`, so an empty list here can only mean the values were blank
+ * strings — still worth failing on, because the alternative is an API that
+ * quietly rejects its own frontend.
+ */
+export declare function resolveCorsOrigin(env: RebaseBootEnv): CorsOriginResolver;
+export {};

package/dist/boot/options.d.ts

@@ -0,0 +1,20 @@
+import type { CollectionConfig } from "@rebasepro/types";
+import type { RebaseAuthConfig } from "../init";
+import type { EmailConfig } from "../email";
+import type { RebaseBootEnv } from "./env";
+/**
+ * Build the email configuration, or `undefined` when no SMTP host is set.
+ *
+ * Without it the auth adapter still works; password-reset and verification mail
+ * simply has nowhere to go, which the auth routes report for themselves.
+ */
+export declare function resolveEmailOptions(env: RebaseBootEnv): EmailConfig | undefined;
+/**
+ * Build the auth configuration from the environment and the bundle's users
+ * collection.
+ *
+ * OAuth providers are included only when both halves of a credential pair are
+ * present. Google is the exception the template already made: a client id alone
+ * is enough, because the ID-token flow needs no secret.
+ */
+export declare function resolveAuthOptions(env: RebaseBootEnv, usersCollection: CollectionConfig | undefined): RebaseAuthConfig;

package/dist/boot/sources.d.ts

@@ -0,0 +1,77 @@
+import { type DataSourceDefinition, type StorageSourceDefinition } from "@rebasepro/types";
+import type { BackendStorageConfig } from "../storage/types";
+/**
+ * Resolving *named* data and storage sources from the environment.
+ *
+ * A project is not required to have one database and one bucket. Collections
+ * already route by `collection.dataSource`, storage properties already route by
+ * `storageSource`, and the backend already registers one driver per source key —
+ * so the only piece missing was a way to *configure* the second, third and fourth
+ * of each without hand-writing an entrypoint.
+ *
+ * The naming rule is mechanical, and deliberately derives the variable name from
+ * the declared key rather than trying to discover keys by scanning the
+ * environment. Scanning would have to guess how `DATABASE_URL_READ_REPLICA` splits
+ * into a key; deriving cannot be ambiguous, and a typo shows up as a missing
+ * source at boot instead of a silently ignored variable.
+ *
+ * ```
+ *   <BASE>            the default source        DATABASE_URL, S3_BUCKET
+ *   <BASE>__<KEY>     a named source            DATABASE_URL__ANALYTICS, S3_BUCKET__MEDIA
+ * ```
+ *
+ * The double underscore matters: single-underscore suffixes collide with real
+ * variable names (`S3_BUCKET_NAME` would parse as bucket "name").
+ */
+/** Environment lookup, injectable so tests need not mutate `process.env`. */
+export type EnvBag = Record<string, string | undefined>;
+/**
+ * Convert a source key into the suffix used in environment variable names.
+ *
+ * The default key maps to no suffix at all, which is what keeps every existing
+ * single-database deployment working untouched.
+ */
+export declare function envSuffixForKey(key: string, defaultKey: string): string;
+/** A data source resolved to everything needed to build a driver for it. */
+export interface ResolvedDataSourceConfig {
+    /** Data-source key — becomes the driver-registry id collections route by. */
+    key: string;
+    engine: string;
+    /** npm package implementing the driver. */
+    driverPackage: string;
+    connectionString: string;
+    adminConnectionString?: string;
+    readConnectionString?: string;
+    isDefault: boolean;
+    poolConfig?: Record<string, number>;
+}
+/**
+ * Resolve every server-transport data source to a connection.
+ *
+ * `direct` and `custom` transports are skipped: the client talks to those
+ * itself, so the backend holds no connection for them and must not demand one.
+ *
+ * A declared source with no connection string is an error rather than a warning.
+ * The alternative — starting without it — means every collection routed to that
+ * source silently falls back to the default database, which is data landing in
+ * the wrong place with a healthy-looking server in front of it.
+ */
+export declare function resolveDataSources(env: EnvBag, definitions: DataSourceDefinition[] | undefined): ResolvedDataSourceConfig[];
+/**
+ * Build one storage configuration from the variables for a single source.
+ *
+ * Returns `undefined` when the source has no configuration at all, so an
+ * optional bucket that was never set does not fail a boot. The production
+ * "local storage is off" rule deliberately does *not* live here — it is enforced
+ * once, in `initializeStorage`, which logs precisely why storage is disabled.
+ * Duplicating it would mean two places to keep in agreement.
+ */
+export declare function resolveStorageBackend(env: EnvBag, key: string, engineHint: string | undefined, defaultBasePath: string): BackendStorageConfig | undefined;
+/**
+ * Resolve every server-transport storage source into a controller config map.
+ *
+ * The returned shape is the `Record<key, config>` the backend already accepts,
+ * so multiple buckets need nothing new downstream — they were always supported,
+ * they just had no way to be configured from the environment.
+ */
+export declare function resolveStorageSources(env: EnvBag, definitions: StorageSourceDefinition[] | undefined, defaultBasePath: string): Record<string, BackendStorageConfig> | undefined;

package/dist/chunk-DSJWtz9O.js

@@ -0,0 +1,40 @@
+import { createRequire as __createRequire } from "module";
+import "process";
+const require = __createRequire(import.meta.url);
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, { get: (a, b) => (typeof require !== "undefined" ? require : a)[b] }) : x)(function(x) {
+	if (typeof require !== "undefined") return require.apply(this, arguments);
+	throw Error("Calling `require` for \"" + x + "\" in an environment that doesn't expose the `require` function. See https://rolldown.rs/in-depth/bundling-cjs#require-external-modules for more details.");
+});
+//#endregion
+export { __toESM as i, __exportAll as n, __require as r, __commonJSMin as t };