@rebasepro/server 0.23.0 → 0.24.1-canary.g56af4a4

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

@@ -44,6 +44,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
@@ -83,6 +91,41 @@ export declare function setSharedRateLimitStore(store: RateLimitStore | undefine
  * 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.
@@ -209,6 +252,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 +278,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.

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

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

@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { z } from "zod";
 import { HonoEnv } from "../api/types.js";
 import type { MiddlewareHandler } from "hono";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 import type { resolveAuthHooks } from "./auth-hooks.js";
 interface SessionRoutesConfig {
@@ -28,11 +28,7 @@ interface SessionRoutesConfig {
         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>;
     /**
      * The `register` captcha, built by the caller so a misconfiguration fails
@@ -41,6 +37,15 @@ interface SessionRoutesConfig {
      * `/register`. Absent when captcha is off or `register` is not protected.
      */
     registerCaptcha?: MiddlewareHandler<HonoEnv>;
+    /**
+     * Mail the account a verification link, in the background. Upgrading a
+     * guest is registration, and registration starts the address proof.
+     */
+    sendVerificationMail?: (user: {
+        id: string;
+        email: string;
+        displayName?: string | null;
+    }) => void;
 }
 export declare function mountSessionRoutes(opts: SessionRoutesConfig): void;
 export {};

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

@@ -37,6 +37,55 @@ import type { AccessTokenPayload } from "./jwt.js";
  * failure is logged at warn so it is visible rather than silent.
  */
 export declare function isAccessTokenRevoked(authRepo: Pick<AuthRepository, "getTokensValidAfter">, payload: Pick<AccessTokenPayload, "uid" | "iat">): Promise<boolean>;
+/**
+ * The repository reads {@link judgeAccessToken} may make. All optional: a
+ * repository answers what it can, and the judge says what it could not ask.
+ */
+export type AccessJudgeRepository = Partial<Pick<AuthRepository, "getAccountAccessState" | "getUserWithRoles" | "getTokensValidAfter">>;
+/**
+ * Why an access token that verifies is not honoured.
+ *
+ * - `revoked`: issued before the account's revocation watermark — a sign-out
+ *   everywhere, a password change or reset.
+ * - `session-revoked`: its own sign-in was ended — `POST /auth/logout`, or
+ *   `DELETE /auth/sessions/:id` from another device. Needs the token's `sid`.
+ * - `account-deleted`: the account it names no longer exists.
+ * - `account-disabled`: an administrator switched the account off.
+ */
+export type AccessTokenRefusal = "revoked" | "session-revoked" | "account-deleted" | "account-disabled";
+export type AccessTokenVerdict = {
+    live: true;
+    /**
+     * The account's roles now, or `undefined` when the repository could
+     * not say (it reads neither the account nor its roles).
+     */
+    roles?: string[];
+} | {
+    live: false;
+    refusal: AccessTokenRefusal;
+};
+/**
+ * Is the account behind this verified access token still the one that may use
+ * it — and with which roles?
+ *
+ * A verified signature says who the token was minted for, an hour ago at
+ * most. This asks the database what has happened to that account since. Every
+ * door that honours an access token — the data plane, the admin gates, the
+ * realtime socket — asks it here, so they cannot disagree about it.
+ *
+ * They did. A deleted account read as "not revoked": the watermark lives on
+ * the user row, so once the row was gone there was no watermark, and the
+ * roles lookup answered `[]` rather than "nobody". A token its owner had
+ * revoked came back to life when an administrator deleted the account, as an
+ * authenticated principal with that uid, for the rest of its lifetime. MCP
+ * refresh and personal API keys already treated a missing account as revoked;
+ * the main door did not.
+ *
+ * Throws when the repository does. Unlike the watermark read on its own, this
+ * one decides the roles a request runs with, so a failure is a refusal (the
+ * callers answer 503) rather than a guess.
+ */
+export declare function judgeAccessToken(authRepo: AccessJudgeRepository, payload: Pick<AccessTokenPayload, "uid" | "iat" | "sid">): Promise<AccessTokenVerdict>;
 /**
  * End every session this user holds, on every device.
  *
@@ -72,4 +121,4 @@ export declare function revokeAllSessions(authRepo: Pick<AuthRepository, "delete
  * `null` removes the password instead, for the same reason and with the same
  * revocation: see `confirmAddressOwnership`.
  */
-export declare function replaceUserPassword(authRepo: Pick<AuthRepository, "updatePassword" | "deleteAllRefreshTokensForUser" | "setTokensValidAfter">, uid: string, passwordHash: string | null): Promise<void>;
+export declare function replaceUserPassword(authRepo: Pick<AuthRepository, "updatePassword" | "deleteAllRefreshTokensForUser" | "setTokensValidAfter"> & Partial<Pick<AuthRepository, "deleteAllPasswordResetTokensForUser">>, uid: string, passwordHash: string | null): Promise<void>;

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

@@ -0,0 +1,35 @@
+/**
+ * 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 read through a getter configured at boot, 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 picker which collections this backend serves. Called once at boot. */
+export declare function configureUserPicking(collections: () => readonly CollectionConfig[]): void;
+/** 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

@@ -0,0 +1,28 @@
+/**
+ * Verify a bearer credential outside the HTTP middlewares — for a custom
+ * socket, a tunnel, anything an app authenticates from a frame or a header it
+ * read itself.
+ *
+ * One answer for the two kinds of credential a person can hold: a session
+ * 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.
+ *
+ * @module
+ */
+import type { ApiKeyStore } from "./api-keys/api-key-store.js";
+/** Who a verified credential acts as, and what it may do. */
+export interface VerifiedCredential {
+    uid: string;
+    roles: string[];
+    scopes: string[];
+    /** `"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. */
+export declare function configureCredentialStore(store: ApiKeyStore | undefined): void;
+/**
+ * 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.
+ */
+export declare function verifyCredential(token: string): Promise<VerifiedCredential | null>;