@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

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

@@ -3,6 +3,7 @@ import type { MiddlewareHandler } from "hono";
 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 { z } from "zod";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 /**
@@ -13,6 +14,8 @@ import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasep
 export declare function mountMagicLinkRoutes(deps: {
     router: Hono<HonoEnv>;
     config: AuthModuleConfig;
+    /** The backend's auth limiters. */
+    limiters: AuthLimiters;
     ops: ResolvedAuthHooks;
     parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
     buildAuthResponse: (user: {

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

@@ -36,13 +36,16 @@
  *
  * @module
  */
+import { type JwtService } from "./jwt.js";
 /**
  * Encrypt a plaintext TOTP secret.
  *
  * @param plaintext - The Base32 TOTP secret to encrypt.
+ * @param jwt - The backend whose JWT secret is the last key fallback. The
+ *   process default when omitted.
  * @returns A string in the format `v1.<keyId>:iv_hex:authTag_hex:ciphertext_hex`.
  */
-export declare function encryptTotpSecret(plaintext: string): string;
+export declare function encryptTotpSecret(plaintext: string, jwt?: JwtService): string;
 /** What a factor's stored secret opened to, and whether it should be re-stored. */
 export interface OpenedTotpSecret {
     /** The Base32 TOTP secret. */
@@ -59,8 +62,10 @@ export interface OpenedTotpSecret {
  *
  * Accepts both the key-stamped format and the original unstamped
  * `iv:authTag:ciphertext`, which is tried against each candidate in turn.
+ * `jwt` is the backend whose JWT secret is the last key fallback — the process
+ * default when omitted.
  */
-export declare function openTotpSecret(ciphertext: string): OpenedTotpSecret;
+export declare function openTotpSecret(ciphertext: string, jwt?: JwtService): OpenedTotpSecret;
 /**
  * Decrypt a previously encrypted TOTP secret.
  *
@@ -69,6 +74,7 @@ export declare function openTotpSecret(ciphertext: string): OpenedTotpSecret;
  * on whichever key it was written with.
  *
  * @param ciphertext - A stored TOTP secret, in either format.
+ * @param jwt - The backend whose JWT secret is the last key fallback.
  * @returns The original Base32 TOTP secret.
  */
-export declare function decryptTotpSecret(ciphertext: string): string;
+export declare function decryptTotpSecret(ciphertext: string, jwt?: JwtService): string;

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

@@ -12,6 +12,7 @@
  *
  * @module
  */
+import type { JwtService } from "./jwt.js";
 import type { AuthRepository } from "./interfaces.js";
 /** Error code a client watches for to switch a sign-in into its second step. */
 export declare const MFA_REQUIRED_CODE = "MFA_REQUIRED";
@@ -37,6 +38,7 @@ export interface MfaRequiredDetails {
  *
  * A 401 rather than a 200 with a different body: a client that has not been
  * taught about MFA must fail, not proceed. The credential in `details` is
- * useless for anything except the challenge routes.
+ * useless for anything except the challenge routes, and is signed by `jwt` —
+ * the backend's own key.
  */
-export declare function assertMfaSatisfied(authRepo: AuthRepository, uid: string): Promise<void>;
+export declare function assertMfaSatisfied(authRepo: AuthRepository, uid: string, jwt: JwtService): Promise<void>;

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 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

package/dist/auth/middleware.d.ts

@@ -1,7 +1,7 @@
 import { MiddlewareHandler, Context } from "hono";
 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";
@@ -151,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>;
 /**

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

@@ -45,6 +45,7 @@ import { z } from "zod";
 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: {

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.
  *
@@ -118,15 +129,7 @@ export declare function createRateLimiter(options?: RateLimiterOptions): Middlew
  * `"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.
- */
 export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
-/**
- * Pre-configured strict rate limiter for sensitive endpoints (password reset, verification).
- * 50 requests per 15 minutes per IP.
- */
 export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
 /**
  * Limiter for `POST /auth/send-verification`, keyed by the authenticated user.
@@ -159,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.
@@ -198,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.
  *
@@ -270,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.
@@ -283,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,9 +1,12 @@
 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 };
 /**
@@ -11,6 +14,19 @@ export { isDeliverableAddress };
  */
 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`.
      *

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

@@ -2,11 +2,17 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
 import type { MiddlewareHandler } from "hono";
+import { type AuthLimiters } from "./rate-limiter.js";
+import { type JwtService } from "./jwt.js";
 import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 import type { resolveAuthHooks } from "./auth-hooks.js";
 interface SessionRoutesConfig {
     router: Hono<HonoEnv>;
+    /** The backend these routes sign and verify for. */
+    jwt: JwtService;
+    /** The backend's auth limiters. */
+    limiters: AuthLimiters;
     config: AuthModuleConfig;
     /**
      * The caller's guard for a signed-in user, with the revocation watermark

package/dist/auth/user-picking.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Who may read the user picker (`GET /api/admin/users/pick`).
+ *
+ * A `userSelect` field stores a user's id, and the person filling it in picks
+ * that user from a list. Listing the users is an admin-plane read
+ * (`users:read`), which an editor does not hold — so the picker answers a
+ * narrower question for a wider audience: id, name, email and avatar, to
+ * anyone who may write a collection that has such a field.
+ *
+ * "May write" is the collection's `securityRules` for an insert or an update,
+ * evaluated the way the admin panel decides whether to offer the form, with
+ * one difference. A rule that depends only on the row (an owner field) counts
+ * as allowing, since the person may write some row. A rule written as SQL the
+ * policy model cannot read cannot be judged ahead, and here it counts as
+ * refusing: read optimistically, it would let any signed-in person list every
+ * user's name and email. A key or token narrowed by scopes must also hold
+ * `data:write` on that collection.
+ *
+ * The collections are the backend's own (`c.var.services`), read when the
+ * question is asked, so a schema edited live is what is judged.
+ *
+ * @module
+ */
+import type { Context } from "hono";
+import { type CollectionConfig, type Properties } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+/** Tell the process default's picker which collections it serves. */
+export declare function configureUserPicking(collections: () => readonly CollectionConfig[]): void;
+/** @internal The process default's collections getter, to snapshot or restore it. */
+export declare function defaultUserPicking(): () => readonly CollectionConfig[];
+/** Whether any property, at any depth, is a `userSelect` field. */
+export declare function propertiesReferenceUsers(properties: Properties | undefined): boolean;
+/**
+ * Whether this request's caller may read the user picker: they hold
+ * `users:read`, or they may write a collection with a `userSelect` field.
+ */
+export declare function mayPickUsers(c: Context<HonoEnv>): boolean;

package/dist/auth/verify-credential.d.ts

@@ -7,9 +7,15 @@
  * token, and an API key (`rk_`). Both come back as who the caller acts as and
  * what it may do, so the endpoint checks a scope the same way either way.
  *
+ * A backend answers for itself — `backend.verifyCredential(token)`, against its
+ * own keys, store and access model. {@link verifyCredential} answers for the
+ * process default.
+ *
  * @module
  */
 import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+import { type AccessControl } from "./access.js";
+import { type JwtService } from "./jwt.js";
 /** Who a verified credential acts as, and what it may do. */
 export interface VerifiedCredential {
     uid: string;
@@ -18,11 +24,26 @@ export interface VerifiedCredential {
     /** `"api-key"` when an `rk_` key was presented, otherwise `"session"`. */
     kind: "session" | "api-key";
 }
-/** Install the key store `verifyCredential` checks `rk_` keys against. Called once at boot. */
+/** What a credential is checked against: one backend's keys, key store and access model. */
+export interface CredentialAuthority {
+    jwt: JwtService;
+    access: AccessControl;
+    apiKeyStore?: ApiKeyStore;
+}
+/** Install the key store the process default's {@link verifyCredential} checks `rk_` keys against. */
 export declare function configureCredentialStore(store: ApiKeyStore | undefined): void;
+/** @internal The process default's key store, to snapshot or restore it. */
+export declare function defaultCredentialStore(): ApiKeyStore | undefined;
+/**
+ * The identity and scopes behind a bearer credential, checked against one
+ * backend, or null when it does not verify — expired, revoked, unknown, or a
+ * key on a backend with no key store.
+ */
+export declare function verifyCredentialAgainst(authority: CredentialAuthority, token: string): Promise<VerifiedCredential | null>;
 /**
- * The identity and scopes behind a bearer credential, or null when it does
- * not verify — expired, revoked, unknown, or a key on a backend with no key
- * store.
+ * The identity and scopes behind a bearer credential, as the process default
+ * answers — expired, revoked, unknown, or a key on a backend with no key store
+ * all come back null. A backend built by `createRebaseBackend` answers for
+ * itself: `backend.verifyCredential(token)`.
  */
 export declare function verifyCredential(token: string): Promise<VerifiedCredential | null>;