@rebasepro/server 0.22.0 → 0.24.0

package/dist/auth/jwt.d.ts

@@ -61,6 +61,23 @@ export interface AccessTokenPayload {
      * comparison and the watermark was read on exactly one path — refresh.
      */
     iat?: number;
+    /**
+     * When the token expires, in seconds since the epoch — the standard `exp`
+     * claim. Carried through because a socket authenticated with this token
+     * has to stop honouring it at this instant, and has no request to refuse.
+     */
+    exp?: number;
+    /**
+     * The sign-in this token was minted for: the session id its refresh
+     * tokens share, carried across every rotation.
+     *
+     * What lets one device be signed out — `POST /auth/logout`,
+     * `DELETE /auth/sessions/:id` — reach that device's access token rather
+     * than only its refresh token, and what lets `GET /auth/sessions` mark the
+     * caller's own session. Absent on tokens minted before it existed; those
+     * keep working until they expire, judged by the watermark alone.
+     */
+    sid?: string;
     /** Email claim from the JWT, if present */
     email?: string;
     /** Display name claim from the JWT, if present */
@@ -89,6 +106,14 @@ export interface AccessTokenPayload {
      */
     claims?: Record<string, unknown>;
 }
+/**
+ * The custom half of a verified token, or nothing when there is none.
+ *
+ * Exported for the one other place that builds a request identity's claims
+ * without a token to verify — `resolveUser`, which reads what a token minted
+ * now would carry — so both drop the same identity claims.
+ */
+export declare function customClaimsOf(decoded: Record<string, unknown>): Record<string, unknown> | undefined;
 /**
  * Configure JWT settings - call this during initialization.
  * Validates the secret strength to prevent deployment with default/weak secrets.
@@ -105,6 +130,12 @@ export declare function configureJwt(config: JwtConfig): void;
 export declare function getJwks(): {
     keys: PublicJwk[];
 };
+/**
+ * The secret `configureJwt` was given, or undefined before it is called. For
+ * `mfa-crypto.ts`, which falls back to it when no MFA key is set — the secret
+ * passed in code, not only the one in `JWT_SECRET`.
+ */
+export declare function configuredJwtSecret(): string | undefined;
 /** Is this backend signing access tokens asymmetrically? */
 export declare function hasAsymmetricSigningKey(): boolean;
 /**
@@ -128,11 +159,28 @@ export declare function generateAccessToken(uid: string, roles: string[], aal?:
  * account. Written into the token so the RLS identity and the WebSocket
  * path can tell the two apart without a database lookup.
  */
-isAnonymous?: boolean): Promise<string>;
+isAnonymous?: boolean, 
+/**
+ * The sign-in this token belongs to — see {@link AccessTokenPayload.sid}.
+ * Every token the auth routes mint carries one.
+ */
+sessionId?: string): Promise<string>;
 /**
  * Get the expiration time of an access token in milliseconds from now
  */
 export declare function getAccessTokenExpiryMs(): number;
+/**
+ * A lifetime setting in milliseconds, or null when it is not one.
+ *
+ * The grammar is vercel/ms, because that is what `jsonwebtoken` reads
+ * `expiresIn` with: the token's `exp` and the expiry this module reports
+ * have to come from one reading of the same string, and they used to come
+ * from two — ours understood `<integer><d|h|m|s>` and nothing else.
+ *
+ * Stricter than ms in two ways, both about values nobody means: a bare number
+ * (ms reads "3600" as 3.6 seconds) and a lifetime of zero or less.
+ */
+export declare function parseDurationMs(value: string): number | null;
 /**
  * Get the expiration timestamp for an access token
  */
@@ -153,7 +201,8 @@ export declare function getAccessTokenExpiry(): number;
  */
 export declare function verifyAccessToken(token: string): Promise<AccessTokenPayload | null>;
 /**
- * Generate a random refresh token (long-lived, 30 days by default)
+ * Generate a random refresh token. Long-lived: 400 days by default, sliding —
+ * see {@link getRefreshTokenTtlMs}.
  */
 export declare function generateRefreshToken(): string;
 /**
@@ -205,9 +254,14 @@ export declare function generateMfaPendingToken(uid: string, expiresInSeconds?:
  *
  * Returns `null` for anything else — including a perfectly valid *access*
  * token, which must not be interchangeable with this one in either direction.
+ *
+ * `iat` comes back with the uid because this token is a first factor that was
+ * accepted at that instant, and a sign-out everywhere after it has to void it
+ * the way it voids an access token — see `isAccessTokenRevoked`.
  */
 export declare function verifyMfaPendingToken(token: string): Promise<{
     uid: string;
+    iat?: number;
 } | null>;
 export interface DownloadTokenPayload {
     purpose: "file-read";
@@ -219,6 +273,13 @@ export interface DownloadTokenPayload {
      * existed are read.
      */
     storageId: string;
+    /**
+     * An opaque mark of the user who minted the token, for rate limiting only:
+     * a read that spends the token is charged to that user's allowance rather
+     * than to the reader's address. A hash, because the token travels in a URL.
+     * Absent for a token minted for nobody.
+     */
+    rl?: string;
 }
 /**
  * Generate a short-lived download token scoped to a specific file path or prefix
@@ -237,7 +298,9 @@ export interface DownloadTokenPayload {
  * site that forgets to pass a named source produces a default-scoped token,
  * which fails closed at `/file/*` rather than over-granting.
  */
-export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null): Promise<string>;
+export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null, 
+/** The user minting it, so the reads it buys are charged to them. */
+principal?: string | null): Promise<string>;
 /**
  * Verify and decode a download token.
  *

package/dist/auth/magic-link-routes.d.ts

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
-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 { z } from "zod";
@@ -24,11 +24,7 @@ export declare function mountMagicLinkRoutes(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 so a misconfiguration fails the boot once, rather

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

@@ -1,7 +1,7 @@
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import { resolveAuthHooks } from "./auth-hooks.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 interface MfaRoutesConfig {
@@ -27,14 +27,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,5 +1,5 @@
 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 type { HonoEnv } from "../api/types.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>;
 /**
@@ -197,6 +201,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 +229,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/oauth-signin-policy.d.ts

@@ -13,7 +13,16 @@ export type AutoLinkRefusal =
  * address. Attaching a provider identity to it would hand the session to
  * whoever registered the address first — the classic pre-hijack.
  */
- | "local-account-unverified";
+ | "local-account-unverified"
+/**
+ * The local account has no password, and its address was never proven
+ * either: it was made by a sign-in through a provider that did not vouch
+ * for the address, or by someone who never had to. Its sign-in methods are
+ * whatever that someone attached, so this is the same pre-hijack as a
+ * password would be. Reported apart from `local-account-unverified` only
+ * so a login screen does not tell its owner to use a password.
+ */
+ | "local-account-unverified-passwordless";
 export type AutoLinkDecision = {
     allowed: true;
 } | {
@@ -28,17 +37,25 @@ export interface AutoLinkExistingUser {
 /**
  * May an OAuth identity be attached to a pre-existing account found *by email*?
  *
- * Both sides have to be trustworthy, and only one of them used to be checked:
+ * Both sides have to be trustworthy:
  *
  *  - the **provider** must have verified the address, or the caller has not
  *    shown they control it;
- *  - the **local account** must itself be trustworthy — either its address was
- *    verified, or it has no password at all (it was created by an OAuth
- *    sign-in or an invitation, so there is no credential an attacker could
- *    have planted in advance).
+ *  - the **local account**'s address must have been verified too. Whoever
+ *    made an unverified account never proved the address, and every way in
+ *    they left on it — a password, an identity from a provider that did not
+ *    vouch for the address — would go on opening the account the owner is
+ *    about to be signed into.
+ *
+ * The second rule used to exempt an account with no password, on the theory
+ * that one made by an OAuth sign-in holds no credential an attacker could have
+ * planted. It holds exactly one: the identity it was made with, which is an
+ * attacker's whenever the provider did not vouch for the address.
  *
- * A refusal is not a dead end: `POST /auth/link/<provider>` attaches the
- * identity once the caller proves ownership by holding a session.
+ * A refusal is not a dead end. `POST /auth/link/<provider>` attaches the
+ * identity once the caller proves ownership by holding a session, and proving
+ * the address (a magic link, an email code, a password reset) verifies the
+ * account — removing what nobody proved — after which this answers yes.
  */
 export declare function decideOAuthAutoLink(args: {
     providerEmailVerified: boolean | undefined;

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

@@ -42,7 +42,7 @@
 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 { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
@@ -78,11 +78,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

@@ -1,6 +1,7 @@
 import { MiddlewareHandler } from "hono";
+import { type DataRateLimitCaller } from "@rebasepro/types";
 import { HonoEnv } from "../api/types.js";
-import { RateLimitStore } from "./rate-limit-store.js";
+import { RateLimitDecision, RateLimitStore } from "./rate-limit-store.js";
 /**
  * Sliding-window rate limiting for Hono.
  *
@@ -28,6 +29,15 @@ interface RateLimiterOptions {
      * shared one to have several limiters (or several processes) agree.
      */
     store?: RateLimitStore;
+    /**
+     * Count in the deployment's shared store once one is configured, 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.
+     */
+    name?: string;
     /**
      * Per-request limit override, for buckets whose allowance is data rather
      * than config (an API key's own `rate_limit`). Returning `undefined` uses
@@ -59,12 +69,55 @@ 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.
+ */
+export declare function setSharedRateLimitStore(store: RateLimitStore | undefined): void;
 /**
  * Create a rate-limiting middleware.
  *
  * Uses a sliding window: only hits within the last `windowMs` are counted.
  */
 export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * 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.
+ */
+/**
+ * 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;
 /**
  * Pre-configured rate limiter for general auth endpoints (login, register).
  * 200 requests per 15 minutes per IP.
@@ -191,6 +244,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;
@@ -212,4 +271,16 @@ export declare const DEFAULT_FUNCTIONS_ANONYMOUS_LIMIT = 3000;
  * `enabled: false` rather than pay for it twice.
  */
 export declare function createDataRateLimiter(config?: DataRateLimitConfig): 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.
+ *
+ * The realtime socket serves the rows the data API serves, one frame per
+ * request. It counted them per connection only, so a caller bought more budget
+ * by opening more sockets, and a frame never met the per-person limit its HTTP
+ * twin does. Built from the same config and store as
+ * {@link createDataRateLimiter}, it puts a caller in the same bucket under the
+ * 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/routes.d.ts

@@ -4,6 +4,8 @@ import type { AuthHooks } from "./auth-hooks.js";
 import { EmailService, EmailConfig } from "../email/index.js";
 import { HonoEnv } from "../api/types.js";
 import { type CaptchaConfig } from "./captcha.js";
+import { isDeliverableAddress } from "./deliverable-address.js";
+export { isDeliverableAddress };
 /**
  * Shared configuration for auth and admin route factories.
  */
@@ -86,7 +88,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 +134,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>;