@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/auth/mfa-routes.d.ts

@@ -1,12 +1,18 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
-import type { AuthModuleConfig } from "./routes.js";
+import { type AuthLimiters } from "./rate-limiter.js";
+import type { JwtService } from "./jwt.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import { resolveAuthHooks } from "./auth-hooks.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 interface MfaRoutesConfig {
     router: Hono<HonoEnv>;
     config: AuthModuleConfig;
+    /** The backend these routes sign and verify for; its secret is also the TOTP key's last fallback. */
+    jwt: JwtService;
+    /** The backend's auth limiters. */
+    limiters: AuthLimiters;
     /**
      * The caller's guard for a signed-in user, with the revocation watermark
      * consulted. Enrolling, confirming or removing a factor is a persistence
@@ -27,14 +33,7 @@ interface MfaRoutesConfig {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string, options?: {
-        skipMfaGate?: boolean;
-        aal?: "aal1" | "aal2";
-    }) => Promise<{
-        roleIds: string[];
-        accessToken: string;
-        refreshToken: string;
-    }>;
+    createSessionAndTokens: CreateSessionAndTokens;
     applyTransformHook?: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
 }
 export declare function mountMfaRoutes(opts: MfaRoutesConfig): void;

package/dist/auth/middleware.d.ts

@@ -1,7 +1,7 @@
 import { MiddlewareHandler, Context } from "hono";
-import type { AuthRepository } from "./interfaces.js";
+import { type AccessJudgeRepository } from "./token-revocation.js";
 import { DataDriver } from "@rebasepro/types";
-import { AccessTokenPayload } from "./jwt.js";
+import { AccessTokenPayload, type JwtService } from "./jwt.js";
 import type { HonoEnv } from "../api/types.js";
 import { ApiError } from "../api/errors.js";
 import type { ApiKeyStore } from "./api-keys/api-key-store.js";
@@ -131,11 +131,15 @@ export declare function createRequireAuth(options?: {
      * invalidated by `logout` or a password reset stops working on admin routes
      * too, not just on the data plane.
      */
-    revocationRepo?: Pick<AuthRepository, "getTokensValidAfter">;
+    revocationRepo?: AccessJudgeRepository;
 }): MiddlewareHandler<HonoEnv>;
 /**
- * Middleware that requires the user to have an admin or schema-admin role.
- * Must be used AFTER requireAuth or on a route where user is guaranteed.
+ * Middleware that requires the user to hold the `admin` role, which holds
+ * every scope. Must be used AFTER requireAuth or on a route where user is
+ * guaranteed.
+ *
+ * Prefer `requireScope` from `./access` for anything a scope names: a scope
+ * can be granted to a narrower role and to a key, and `admin` cannot.
  */
 export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
 /**
@@ -147,7 +151,14 @@ export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
  */
 export declare const optionalAuth: MiddlewareHandler<HonoEnv>;
 /**
- * Extract user from token - for WebSocket authentication
+ * Who a session token names, as `jwt` verifies it — or "nobody" rather than a
+ * throw on a backend with no JWT of its own, so a socket closes as
+ * unauthenticated, which is the outcome this describes.
+ */
+export declare function userFromToken(jwt: JwtService, token: string): Promise<AccessTokenPayload | null>;
+/**
+ * Extract user from token - for WebSocket authentication. Answers for the
+ * process default; a backend's own socket verifies with its own keys.
  */
 export declare function extractUserFromToken(token: string): Promise<AccessTokenPayload | null>;
 /**
@@ -197,6 +208,14 @@ export declare const queryTokenAuth: MiddlewareHandler<HonoEnv>;
  * requested object path is public, it sets a minimal "public" principal so the
  * downstream `requireAuth` gate lets the read through. Private paths are left
  * untouched, so they still require a valid token.
+ *
+ * Public means the object the route will serve is public, so the decision is
+ * made on that object's canonical key, derived by the route's own function
+ * (`requestedStorageObject`). It used to be made on the raw path, through a
+ * check that strips a `scheme://`: `notes://public/secret.txt` read as
+ * `public/secret.txt` here while the route served the private
+ * `notes:/public/secret.txt`, and the authorize hook — not asked about this
+ * principal — never saw it.
  */
 export declare const publicObjectAuth: MiddlewareHandler<HonoEnv>;
 /**
@@ -217,7 +236,7 @@ export declare const publicObjectAuth: MiddlewareHandler<HonoEnv>;
  * Hono routes the request, so this comparison already runs on a resolved path.
  * But that is a guarantee of the runtime rather than of this code, and it is
  * one line to not depend on it. The same rule already guards the public-object
- * path — see `isPublicStoragePath`.
+ * path — see `isPublicStorageKey`.
  */
 export declare function isPathMatch(requested: string, allowed: string): boolean;
 /**

package/dist/auth/otp-routes.d.ts

@@ -42,9 +42,10 @@
 import { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
 import { z } from "zod";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
 import type { HonoEnv } from "../api/types.js";
+import { type AuthLimiters } from "./rate-limiter.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 /** How long a code is good for. */
 export declare const OTP_TTL_MS: number;
@@ -67,6 +68,8 @@ export declare function otpTokenMaterial(email: string, code: string): string;
 export declare function mountOtpRoutes(deps: {
     router: Hono<HonoEnv>;
     config: AuthModuleConfig;
+    /** The backend's auth limiters; the per-address ones count where they do. */
+    limiters: AuthLimiters;
     ops: ResolvedAuthHooks;
     parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
     buildAuthResponse: (user: {
@@ -78,11 +81,7 @@ export declare function mountOtpRoutes(deps: {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string) => Promise<{
-        roleIds: string[];
-        accessToken: string;
-        refreshToken: string;
-    }>;
+    createSessionAndTokens: CreateSessionAndTokens;
     applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
     /** Built by the caller, as for magic link. Absent when captcha is off. */
     captchaMiddleware?: MiddlewareHandler<HonoEnv>;

package/dist/auth/passwordless-signup.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Sign-up by magic link or email code (`auth.magicLinkCreatesUsers`).
+ *
+ * Both passwordless doors refuse an address with no account — silently, so
+ * they do not say which addresses have one. A passwordless-only app then had
+ * no way to create accounts at all. With the option on, and registration open,
+ * an unknown address gets an account at request time — no password, unverified
+ * — and the link or code mailed to it is what proves the address and signs it
+ * in, exactly as for an existing account. Supabase's `shouldCreateUser`.
+ *
+ * @module
+ */
+import type { AuthModuleConfig } from "./routes.js";
+import type { ResolvedAuthHooks } from "./auth-hooks.js";
+import type { UserData } from "./interfaces.js";
+/**
+ * The account a passwordless request for `email` should mail, creating it
+ * when the deployment lets passwordless requests sign people up. `null` when
+ * there is none and none may be made — the caller answers as for any unknown
+ * address.
+ *
+ * Registration's controls hold: the kill switch, `allowRegistration` (with no
+ * first-user exception: the first admin is made by registering or by the
+ * operator, never by whoever asks for a link first), `beforeUserCreate`,
+ * `afterUserCreate` and the default role.
+ */
+export declare function accountForPasswordlessRequest(config: AuthModuleConfig, ops: ResolvedAuthHooks, email: string): Promise<UserData | null>;

package/dist/auth/platform-token.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Platform tokens: a short-lived credential the platform hosting this server
+ * mints for one person, for one project, for a few read-only scopes.
+ *
+ * ## Why this exists
+ *
+ * On Rebase Cloud the owner of a project is signed in to the *control plane*,
+ * not to their own app. Their app's admin surfaces — the cron job list and its
+ * run history first — accept an admin user of the app, an `rk_` key, or the
+ * service key, and an owner may hold none of them: a fresh deploy has no admin
+ * account, and the service key is admin on the whole API, which is the wrong
+ * thing to hand someone who wants to read why last night's job failed.
+ *
+ * So the control plane signs a token instead. It checks the caller's project
+ * membership, then signs `{ aud: <project>, sub: <who>, scope: "cron:read" }`
+ * with a key only it holds, valid for minutes. This server verifies it against
+ * the public half — `REBASE_PLATFORM_TOKEN_KEY` — which the platform sets at
+ * deploy. Nothing secret lives in the tenant: the env holds a public key, and
+ * leaking it lets nobody mint anything.
+ *
+ * ## What a platform token can never do
+ *
+ * - **Exceed {@link PLATFORM_TOKEN_SCOPES}.** The token names scopes; this
+ *   server grants only the ones on that list, whatever the platform signed. The
+ *   ceiling lives here, in the tenant's code, so a compromised or buggy control
+ *   plane cannot widen it.
+ * - **Outlive {@link PLATFORM_TOKEN_MAX_LIFETIME_SECONDS}.** A token whose
+ *   `exp - iat` is longer is refused, not clamped: a long-lived platform token
+ *   is a static secret by another name.
+ * - **Reach another project.** One platform key signs for every tenant, so the
+ *   audience is what binds a token to this one: `aud` must equal
+ *   `REBASE_PLATFORM_TOKEN_AUDIENCE`.
+ * - **Act as a person of this app.** The caller is `platform:<sub>` with no
+ *   roles: row-level security sees nobody it knows, and every surface that
+ *   checks a scope other than the granted ones refuses it.
+ *
+ * ## Wire format
+ *
+ * `rpt_` followed by a compact ES256 JWS. The prefix keeps the credential
+ * classes apart the way `rk_` does: a platform token is never tried as a user
+ * session, and a user session is never tried as a platform token.
+ *
+ * @module
+ */
+import type { MiddlewareHandler } from "hono";
+import type { AdminScope } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+/** Marks a bearer token as a platform token. */
+export declare const PLATFORM_TOKEN_PREFIX = "rpt_";
+/** The `iss` every platform token carries. */
+export declare const PLATFORM_TOKEN_ISSUER = "rebase-cloud";
+/**
+ * Everything a platform token can be granted on this server.
+ *
+ * Read-only on purpose. Adding a scope here is a decision about what the
+ * platform may do inside a customer's app on a person's behalf, and belongs in
+ * its own change.
+ */
+export declare const PLATFORM_TOKEN_SCOPES: readonly AdminScope[];
+/** The longest `exp - iat` a platform token may declare. */
+export declare const PLATFORM_TOKEN_MAX_LIFETIME_SECONDS = 600;
+/** The environment variables a platform sets to turn platform tokens on. */
+export declare const PLATFORM_TOKEN_KEY_ENV = "REBASE_PLATFORM_TOKEN_KEY";
+export declare const PLATFORM_TOKEN_AUDIENCE_ENV = "REBASE_PLATFORM_TOKEN_AUDIENCE";
+/** What this server verifies platform tokens against. */
+export interface PlatformTokenConfig {
+    /**
+     * PEM-encoded SPKI public keys, EC P-256. More than one during a key
+     * rotation: a token verifies against any of them.
+     */
+    publicKeys: string[];
+    /** This project, as the platform names it in `aud`. */
+    audience: string;
+}
+/** A verified platform token, as the request will act. */
+export interface PlatformCaller {
+    /** Who the platform minted it for — a control-plane account. */
+    subject: string;
+    /** The granted scopes: what the token asked for, within the ceiling. */
+    scopes: string[];
+    /** `jti`, when the platform set one — what an audit line quotes. */
+    tokenId?: string;
+}
+/** Why a presented platform token does not authenticate. */
+export interface PlatformTokenRefusal {
+    refusal: string;
+}
+export declare function isPlatformToken(token: string): boolean;
+/**
+ * The PEM blocks in an env value: real newlines, `\n`-escaped ones (what a
+ * one-line `.env` holds), or the whole thing base64-encoded.
+ */
+export declare function parsePublicKeys(value: string): string[];
+/**
+ * Read the platform-token configuration from the environment.
+ *
+ * `undefined` when platform tokens are off — neither variable set, which is
+ * every self-hosted server — or misconfigured. A misconfiguration is logged and
+ * leaves them off rather than failing the boot: the platform set these values,
+ * the app's owner cannot fix them, and the app serving traffic matters more
+ * than its cron history being readable from the CLI.
+ */
+export declare function platformTokensFromEnv(env: Record<string, string | undefined>): Promise<PlatformTokenConfig | undefined>;
+/**
+ * Verify a presented platform token: signature, issuer, audience, lifetime, and
+ * the scopes it may be granted here.
+ */
+export declare function verifyPlatformToken(token: string, config: PlatformTokenConfig, nowSeconds?: number): Promise<PlatformCaller | PlatformTokenRefusal>;
+/**
+ * Authenticate an `rpt_` bearer token ahead of an admin gate.
+ *
+ * Mounted where the `rk_` pre-auth is, and shaped like it: a request it does not
+ * recognise passes through untouched, a recognised one either becomes a caller
+ * with narrowed `scopes` or is refused here. The gate's scope check then decides
+ * — so a token holding `cron:read` reads cron, and is a 403 on every other
+ * surface.
+ *
+ * With `config` undefined, platform tokens are off on this server; an `rpt_`
+ * token is still recognised, so its holder learns that rather than the generic
+ * "invalid token" a JWT parser would answer.
+ */
+export declare function createPlatformTokenPreAuth(config: PlatformTokenConfig | undefined): MiddlewareHandler<HonoEnv>;

package/dist/auth/rate-limiter.d.ts

@@ -8,7 +8,7 @@ import { RateLimitDecision, RateLimitStore } from "./rate-limit-store.js";
  * The counting lives in a {@link RateLimitStore} — in this process's memory by
  * default, which is a per-replica limit and says so. See `rate-limit-store.ts`.
  */
-interface RateLimiterOptions {
+export interface RateLimiterOptions {
     /** Time window in milliseconds (default: 15 minutes) */
     windowMs?: number;
     /** Maximum requests per window (default: 100) */
@@ -30,12 +30,13 @@ interface RateLimiterOptions {
      */
     store?: RateLimitStore;
     /**
-     * Count in the deployment's shared store once one is configured, under
+     * Count in the process default's shared store once one is installed, under
      * this name. For a limiter declared at module load, which runs before any
      * configuration exists and so cannot be handed a `store` — see
      * {@link setSharedRateLimitStore}. The name namespaces the limiter's keys
      * there: two limiters keyed by the same IP must not share one count.
-     * Ignored when `store` is given.
+     * Ignored when `store` is given. A backend's own limiters are built by
+     * {@link createAuthLimiters} and never read the process's store.
      */
     name?: string;
     /**
@@ -44,6 +45,14 @@ interface RateLimiterOptions {
      * `limit`; returning `null` skips the limiter for this request.
      */
     resolveLimit?: (c: Parameters<MiddlewareHandler<HonoEnv>>[0]) => number | null | undefined | Promise<number | null | undefined>;
+    /**
+     * How many requests this one counts as. Default 1. For a request that
+     * does the work of several — a batch — so batching is cheaper than the
+     * requests it replaces without being free. Charged one hit at a time, and
+     * refused at the first that does not fit; the hits before it stay charged,
+     * as the requests a batch replaces would have been.
+     */
+    cost?: (c: Parameters<MiddlewareHandler<HonoEnv>>[0]) => number | Promise<number>;
     /**
      * Number of trusted reverse-proxy hops in front of this server. Each hop
      * appends the address it saw to `X-Forwarded-For`, so the real client IP is
@@ -70,13 +79,15 @@ interface RateLimiterOptions {
     trustedProxyHops?: number;
 }
 /**
- * Point every named limiter at the deployment's shared store — or, with
- * `undefined`, back at its own memory. Called once per boot with the store
- * the data limiters use, and only when that store is shared (SQL, or one the
- * operator supplied): the default memory store is swept on the data window,
- * which is not every limiter's window.
+ * Point every named limiter of the process default at a shared store — or,
+ * with `undefined`, back at its own memory. `setDefaultBackend` calls it with
+ * the store the installed backend shares (SQL, or one the operator supplied):
+ * the default memory store is swept on the data window, which is not every
+ * limiter's window.
  */
 export declare function setSharedRateLimitStore(store: RateLimitStore | undefined): void;
+/** @internal The process default's shared store, to snapshot or restore it. */
+export declare function sharedRateLimitStoreOfProcess(): RateLimitStore | undefined;
 /**
  * Create a rate-limiting middleware.
  *
@@ -84,14 +95,41 @@ export declare function setSharedRateLimitStore(store: RateLimitStore | undefine
  */
 export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
 /**
- * Pre-configured rate limiter for general auth endpoints (login, register).
- * 200 requests per 15 minutes per IP.
+ * Default key generator: the client's address, from the most trustworthy source
+ * this deployment has.
+ *
+ * `X-Forwarded-For` is a client-writable header; only the entries appended by
+ * trusted reverse proxies can be believed. With `trustedProxyHops` proxies in
+ * front, each appends the address it saw, so the real client IP is the
+ * `trustedProxyHops`-th entry from the right — everything further left is
+ * client-supplied and must be ignored. This is what prevents a caller from
+ * spoofing `X-Forwarded-For` to spread its requests across many rate-limit keys.
+ *
+ * `X-Real-IP` is the *same* kind of header and needs the same rule, which it
+ * did not have: it was read unconditionally, including under
+ * `trustedProxyHops === 0` — the mode whose entire meaning is "no proxy is in
+ * front of me". With no proxy there, nothing writes `X-Real-IP` except the
+ * caller, so the key was theirs to choose: one header per request bought an
+ * unlimited number of buckets, and the limiters on login, registration and
+ * password reset counted to one. The reasoning had been done carefully for one
+ * spelling of a proxy header and not carried to its twin.
+ *
+ * So `X-Real-IP` is now believed only where a proxy is declared to exist. With
+ * none, the connection's own address is used — unforgeable, and available
+ * because the server runs on `@hono/node-server`. `"unknown"` is the last
+ * resort only, and it is a single shared bucket by design: better that
+ * anonymous callers throttle each other than that any of them throttles nobody.
  */
-export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
 /**
- * Pre-configured strict rate limiter for sensitive endpoints (password reset, verification).
- * 50 requests per 15 minutes per IP.
+ * Where a request comes from, as the rate limiters judge it: the socket's own
+ * address, or — only behind as many proxies as `TRUSTED_PROXY_HOPS` declares —
+ * the address they report. What a session row records as its IP, so the
+ * sessions list shows the same address the limiter counted, rather than the
+ * raw `X-Forwarded-For` (whose leftmost entry the caller chooses) or
+ * `"unknown"` for every direct connection.
  */
+export declare function requestClientAddress(c: Parameters<MiddlewareHandler<HonoEnv>>[0]): string;
+export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
 export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
 /**
  * Limiter for `POST /auth/send-verification`, keyed by the authenticated user.
@@ -124,22 +162,6 @@ export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
  * that names the field; failing here would answer 429 to bad JSON.
  */
 export declare const captureRecipientEmail: MiddlewareHandler<HonoEnv>;
-/**
- * Per-ADDRESS throttle for a route that mails an address the caller named.
- *
- * `strictAuthLimiter` bounds a machine, and a machine is the attacker's to
- * multiply. The mailbox being filled belongs to somebody who cannot rotate
- * anything, and the domain the messages come from is this deployment's
- * reputation — so a distributed run against one address passed the IP limiter
- * untouched and cost the operator their sender score.
- *
- * Five per fifteen minutes: generous for "I didn't get it, send it again",
- * useless as a mail bomb. The same numbers as `verificationEmailLimiter`,
- * which bounds the same act for a signed-in caller.
- *
- * Falls back to the IP bucket for a request whose body named no address, so
- * the limiter is never silently a no-op.
- */
 export declare const recipientEmailLimiter: MiddlewareHandler<HonoEnv>;
 /**
  * How long a route that answers "if an account exists…" takes, whoever asked.
@@ -163,6 +185,43 @@ export declare const RECIPIENT_ROUTE_FLOOR_MS = 400;
 /** Hold a result until at least `floorMs` has passed since `startedAt`. */
 export declare function notBefore<T>(startedAt: number, floorMs: number, result: T): Promise<T>;
 export declare const verificationEmailLimiter: MiddlewareHandler<HonoEnv>;
+/** A limiter's options, with the name it counts under in a shared store. */
+export type NamedRateLimiterOptions = Omit<RateLimiterOptions, "store" | "name"> & {
+    name: string;
+};
+/**
+ * One backend's auth limiters — login and registration, the sensitive
+ * endpoints, the per-address and per-account mail budgets — and the way its
+ * route modules build the rest of theirs (the OTP and MFA attempt limits).
+ *
+ * Every backend has its own set ({@link createAuthLimiters}), so a caller
+ * spending one backend's allowance spends nothing of another's in the same
+ * process. The module constants above ({@link defaultAuthLimiter} and its
+ * siblings) are the process default's set, for a router built outside any
+ * backend.
+ */
+export interface AuthLimiters {
+    /** General auth endpoints (login, register): 200 requests per 15 minutes per address. */
+    default: MiddlewareHandler<HonoEnv>;
+    /** Sensitive endpoints (password reset, verification): 50 requests per 15 minutes per address. */
+    strict: MiddlewareHandler<HonoEnv>;
+    /** Mail to an address the caller named: 5 per 15 minutes per address. See {@link recipientEmailLimiter}. */
+    recipientEmail: MiddlewareHandler<HonoEnv>;
+    /** Verification mail for a signed-in caller: 5 per 15 minutes per account. See {@link verificationEmailLimiter}. */
+    verificationEmail: MiddlewareHandler<HonoEnv>;
+    /** Another limiter that counts where these do, under its own name. */
+    named(options: NamedRateLimiterOptions): MiddlewareHandler<HonoEnv>;
+}
+/**
+ * Build a backend's auth limiters.
+ *
+ * With `store` — a shared one: SQL, or what the operator passed as
+ * `rateLimit.store` — every limiter counts there under its own name, so the
+ * replicas of one deployment agree. Without one each limiter counts in its own
+ * memory: the data limiter's memory store is swept on the data window, which
+ * is not every limiter's window.
+ */
+export declare function createAuthLimiters(store?: RateLimitStore): AuthLimiters;
 /**
  * Key generator for API-key-based rate limiting.
  *
@@ -209,6 +268,12 @@ export interface DataRateLimitConfig {
     anonymousFunctions?: number | null;
     /** Share counts across replicas. Defaults to this process's memory. */
     store?: RateLimitStore;
+    /**
+     * The deployment's service key, recognised as a Bearer before any auth
+     * middleware has run — the storage router's limiter runs ahead of its
+     * routes' auth — and never limited. See {@link dataRateLimitBuckets}.
+     */
+    serviceKey?: string;
 }
 /** @see DataRateLimitConfig.anonymousFunctions */
 export declare const DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3000;
@@ -229,7 +294,11 @@ export declare const DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3000;
  * set them, and one that already has a proxy doing this should pass
  * `enabled: false` rather than pay for it twice.
  */
-export declare function createDataRateLimiter(config?: DataRateLimitConfig): MiddlewareHandler<HonoEnv>;
+export declare function createDataRateLimiter(config?: DataRateLimitConfig, 
+/** See {@link RateLimiterOptions.cost}: what one request on this router counts as. */
+options?: {
+    cost?: RateLimiterOptions["cost"];
+}): MiddlewareHandler<HonoEnv>;
 /**
  * The data API's per-caller limit, as a check rather than a middleware — for
  * the door into the same data that is not an HTTP request.
@@ -242,4 +311,3 @@ export declare function createDataRateLimiter(config?: DataRateLimitConfig): Mid
  * same key: one person's allowance, spent through either door.
  */
 export declare function createDataRateLimitCheck(config?: DataRateLimitConfig): (caller: DataRateLimitCaller) => Promise<RateLimitDecision | null>;
-export {};

package/dist/auth/registration-policy.d.ts

@@ -1,3 +1,4 @@
+import type { AuthRepository } from "./interfaces.js";
 /**
  * Whether a registration may proceed — computed in exactly one place.
  *
@@ -66,6 +67,21 @@ export interface RegistrationPolicy {
 export declare function isBootstrapWindowOpen(env?: {
     NODE_ENV?: string;
 }): boolean;
+type UserPresenceRepository = Pick<AuthRepository, "firstUserIds" | "listUsersPaginated">;
+/**
+ * Whether the users table is empty — the question behind the bootstrap window.
+ *
+ * Through `AuthRepository.firstUserIds` when the repository has it: one
+ * unordered `LIMIT 1` read. Otherwise through `listUsersPaginated`, which also
+ * counts and sorts the whole table, so it is only the fallback.
+ */
+export declare function isUserTableEmpty(repo: UserPresenceRepository): Promise<boolean>;
+/**
+ * Whether the account just created is the only one there is. Two ids at most:
+ * whether anyone else exists, and, when nobody does, whether it is this one.
+ * Same fallback as {@link isUserTableEmpty}.
+ */
+export declare function isOnlyUser(repo: UserPresenceRepository, uid: string): Promise<boolean>;
 /**
  * What to tell a caller who hit an empty production database with the window
  * shut. Named here so the register route and the bootstrap route say the same
@@ -113,3 +129,4 @@ export declare function isAnonymousAuthOpen(policy: {
     allowAnonymous?: boolean;
     disableSelfRegistration?: boolean;
 }): boolean;
+export {};

package/dist/auth/require-auth.d.ts

@@ -1,5 +1,5 @@
 import type { AuthAdapter } from "@rebasepro/types";
-import type { RebaseAuthConfig } from "../init.js";
+import type { RebaseAuthConfig } from "../backend/options.js";
 /**
  * Whether the `auth` config is an `AuthAdapter` (it can verify a request) or a
  * plain `RebaseAuthConfig`. Lives here rather than in `init.ts` so this module

package/dist/auth/routes.d.ts

@@ -1,14 +1,32 @@
 import { Hono } from "hono";
 import type { AuthRepository, OAuthProvider } from "./interfaces.js";
+import { type JwtService } from "./jwt.js";
 import type { AuthHooks } from "./auth-hooks.js";
 import { EmailService, EmailConfig } from "../email/index.js";
 import { HonoEnv } from "../api/types.js";
+import { type AuthLimiters } from "./rate-limiter.js";
 import { type CaptchaConfig } from "./captcha.js";
+import { type AccessControl } from "./access.js";
+import { isDeliverableAddress } from "./deliverable-address.js";
+export { isDeliverableAddress };
 /**
  * Shared configuration for auth and admin route factories.
  */
 export interface AuthModuleConfig {
     authRepo: AuthRepository;
+    /**
+     * The backend these routes sign sessions for: its JWT keys and token
+     * lifetimes. The process default when omitted — the one `configureJwt`
+     * sets.
+     */
+    jwt?: JwtService;
+    /** The backend's auth limiters, counting in its own store. The process default's set when omitted. */
+    limiters?: AuthLimiters;
+    /**
+     * The backend's access model — what the default role may hold is checked
+     * against it. The process default when omitted.
+     */
+    access?: AccessControl;
     /**
      * Bot protection. Off unless `enabled`.
      *
@@ -86,7 +104,30 @@ export interface AuthModuleConfig {
      * how long a captured token stays useful to someone who copied it.
      */
     refreshTokenReuseIntervalSeconds?: number;
+    /**
+     * Let a magic-link or email-code request for an address with no account
+     * create one (no password, unverified until the link or code is used),
+     * while registration is open. Off by default. See `passwordless-signup.ts`.
+     */
+    magicLinkCreatesUsers?: boolean;
+    /**
+     * What a refresh token presented after its reuse window does to its
+     * session. See `RebaseAuthConfig.refreshTokenReuse`. Default `"reject"`.
+     */
+    refreshTokenReuse?: RefreshTokenReusePolicy;
+    /**
+     * Refuse password sign-in until the account's address is verified, and
+     * register confirm-first: `POST /auth/register` answers the same "check
+     * your inbox" whether or not the address already has an account, and
+     * signs nobody in. Off by default. Needs email; the boot refuses it
+     * without. See `RebaseAuthConfig.requireEmailVerification`.
+     */
+    requireEmailVerification?: boolean;
 }
+/** What a refresh token replayed after its reuse window does to its session. */
+export type RefreshTokenReusePolicy = "reject" | "revoke-session";
+/** How long an email-verification link stays usable. */
+export declare const EMAIL_VERIFICATION_TTL_MS: number;
 /**
  * Configuration for httpOnly refresh-token cookies.
  */
@@ -109,4 +150,24 @@ export interface CookieAuthConfig {
      */
     secure?: boolean;
 }
+/**
+ * What {@link CreateSessionAndTokens} is told about the sign-in it opens.
+ *
+ * `method` is what `providerId` says for the session from now on — stored on
+ * its refresh token and carried across every rotation — so each door names
+ * its own rather than leaving it to a default.
+ */
+export interface SessionOptions {
+    /** `"password"`, `"anonymous"`, `"magic-link"`, `"otp"`, `"mfa"` or a provider id. */
+    method: string;
+    /** Only for the route that has just seen the second factor. */
+    skipMfaGate?: boolean;
+    aal?: "aal1" | "aal2";
+}
+/** Mint a session, as every sign-in door does. See `createSessionAndTokens`. */
+export type CreateSessionAndTokens = (uid: string, userAgent: string, ipAddress: string, options: SessionOptions) => Promise<{
+    roleIds: string[];
+    accessToken: string;
+    refreshToken: string;
+}>;
 export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

package/dist/auth/scope-routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `GET /auth/scopes` — every scope this backend knows, described, and the
+ * ones the caller holds.
+ *
+ * What a screen needs to offer scopes for a key or a role: the built-in ones,
+ * the app's own `auth.scopes`, their wording and what their targets name. Any
+ * authenticated caller may read it; it describes the backend's vocabulary,
+ * not anybody's data.
+ *
+ * @module
+ */
+import { Hono, type MiddlewareHandler } from "hono";
+import type { AccessJudgeRepository } from "./token-revocation.js";
+import type { HonoEnv } from "../api/types.js";
+export interface ScopeRouteOptions {
+    serviceKey?: string;
+    resolveRoles?: (uid: string) => Promise<string[]>;
+    revocationRepo?: AccessJudgeRepository;
+    /** Authenticates `rk_` keys first, so a key can read what it holds. */
+    apiKeyPreAuth?: MiddlewareHandler<HonoEnv>;
+}
+export declare function createScopeRoutes(options: ScopeRouteOptions): Hono<HonoEnv>;