@rebasepro/server 0.22.0 → 0.24.0

package/dist/auth/api-keys/api-key-middleware.d.ts

@@ -1,34 +1,48 @@
 /**
- * Hono middleware for authenticating requests via Service API Keys.
+ * Authenticating requests that present an API key (`rk_`).
  *
- * This middleware is integrated into `createAuthMiddleware()` and
- * activates only when the bearer token starts with `rk_`. It:
+ * {@link resolveApiKey} turns a presented key into the identity it acts as and
+ * the scopes it holds; the HTTP middlewares, the realtime socket and `/mcp`
+ * all call it, so a key means the same thing on every surface.
  *
- * 1. Hashes the token with SHA-256
- * 2. Looks up the hash in the `rebase.api_keys` table
- * 3. Validates the key is not revoked and not expired
- * 4. Sets `c.set("user", ...)` and `c.set("apiKey", ...)` for downstream use
- * 5. Scopes the DataDriver via `withAuth()` using the API key's service identity
+ * - A **service key** acts as `api-key:<id>`, with the RLS roles `service`
+ *   plus whatever it was given, and holds exactly its scopes.
+ * - A **personal key** acts as its owner — their uid and their roles as they
+ *   are *now*, read on every use — and holds its scopes narrowed to what the
+ *   owner's roles still hold. Demote the owner and the key shrinks with them;
+ *   delete the account and the key stops.
  *
- * Authorization is double-gated for API keys: the key's own permission list
- * (checked by the REST generator) is one ceiling, and Postgres RLS is another,
- * independent one — `withAuth()` runs API-key requests as the restricted
- * `rebase_user` role like any other caller. An `admin` key passes RLS via the
- * injected `default_admin` policies; a non-admin key (roles `["service"]`,
- * uid `api-key:<id>`) only sees rows that a policy explicitly grants to the
- * `service` role or to the public. Owner-style policies
- * (`owner_id = rebase.uid()`) never match an API key's synthetic uid.
+ * A key never bypasses RLS: the request's driver is scoped to the identity
+ * like any other caller's, so the scopes are one ceiling and the database's
+ * policies another, independent one.
  *
  * @module
  */
 import type { Context, MiddlewareHandler } from "hono";
-import type { DataDriver } from "@rebasepro/types";
+import { type DataDriver } from "@rebasepro/types";
 import type { HonoEnv } from "../../api/types.js";
 import type { ApiKeyStore } from "./api-key-store.js";
+import type { ApiKeyMasked } from "./api-key-types.js";
 /**
  * Check whether a token looks like a Rebase API key.
  */
 export declare function isApiKeyToken(token: string): boolean;
+/** Who a verified key acts as, and what it may do. */
+export interface ApiKeyIdentity {
+    uid: string;
+    roles: string[];
+    scopes: string[];
+    apiKey: ApiKeyMasked;
+}
+/** A presented key that does not authenticate, and why. */
+export interface ApiKeyRefusal {
+    message: string;
+}
+/**
+ * Verify a presented key: it exists, is live, and — for a personal key —
+ * personal keys are on and its owner still exists. Records the use.
+ */
+export declare function resolveApiKey(store: ApiKeyStore, token: string): Promise<ApiKeyIdentity | ApiKeyRefusal>;
 /**
  * Options for the API key authentication handler.
  */
@@ -37,59 +51,46 @@ export interface ApiKeyAuthOptions {
     driver: DataDriver;
 }
 /**
- * Validate an API key token and populate the Hono context.
- *
- * Returns `true` if the key is valid and context has been populated,
- * or returns an error Response if the key is invalid.
+ * Validate an API key token and populate the Hono context: `user`, `apiKey`,
+ * `scopes` and the RLS-scoped `driver`.
  *
- * This is NOT a standalone middleware — it's called from within
- * `createAuthMiddleware()` when a `rk_` prefixed token is detected.
+ * Returns `true` when the context is populated, or the error Response.
  */
 export declare function validateApiKey(c: Context<HonoEnv>, token: string, options: ApiKeyAuthOptions): Promise<Response | true>;
 /**
- * Permission guard for API-key requests to the storage router.
- *
- * Storage previously did not accept API keys at all (`rk_` tokens were
- * misparsed as JWTs and 401'd). Now that the pre-auth middleware
- * authenticates them, this guard decides what they may do: the key needs a
- * `"storage"` permission entry (or the global `"*"` wildcard) covering the
- * operation derived from the HTTP method. Requests not authenticated via an
- * API key pass through to the storage router's own auth gates.
- *
- * TUS resumable-upload routes (`/tus`, `/tus/:id`) are classified as `write`
- * for EVERY method: the protocol's offset check is a GET and its cancel is a
- * DELETE, but both are steps of an upload — a write-scoped key must be able
- * to complete (and abort) its own resumable upload without also holding
- * `read`/`delete` on stored objects.
+ * The 403 for a credential that lacks a data-plane scope outside the REST
+ * generator (storage and functions). Names the scope that would grant it.
  */
-export declare function createStorageApiKeyGuard(): MiddlewareHandler<HonoEnv>;
+export declare function forbidScope(c: Context<HonoEnv>, scope: string, target?: string): Response;
 /**
- * Permission guard for API-key requests to the custom-functions router.
+ * Scope guard for the resumable-upload routes (`/tus/:id`).
  *
- * The collection permission guard lives in the REST generator and never sees
- * function routes, so before this middleware existed ANY valid API key —
- * however narrowly scoped — could invoke every custom function. This guard
- * closes that: API-key requests must hold a `"functions"`/`"functions/<name>"`
- * permission entry (or the global `"*"` wildcard) for the derived operation.
+ * Every step of an upload — the offset check (HEAD), the chunks (PATCH), the
+ * cancel (DELETE) — is part of writing it, so all of them need
+ * `storage:write`. Which source the upload writes to was checked when it was
+ * created; these steps only reach an upload the same caller owns.
+ */
+export declare function createTusScopeGuard(): MiddlewareHandler<HonoEnv>;
+/**
+ * Scope guard for the custom-functions router: a narrowed credential needs
+ * `functions:invoke` on the function it calls. The functions index — the
+ * listing at the mount point itself — needs the unqualified scope.
  *
- * Non-API-key requests (JWT, service key, anonymous) pass through untouched —
- * functions decide their own auth for those, as before.
+ * People pass: what a person may do inside a function is the function's own
+ * business, as it always was.
  *
  * @param mountPrefix - The path the functions router is mounted at
  *                      (e.g. `/api/functions`), used to extract the function
  *                      name from the request path.
  */
-export declare function createFunctionApiKeyGuard(mountPrefix: string): MiddlewareHandler<HonoEnv>;
+export declare function createFunctionScopeGuard(mountPrefix: string): MiddlewareHandler<HonoEnv>;
 /**
- * Standalone pre-auth middleware for `rk_` bearer tokens.
+ * Pre-auth middleware for `rk_` bearer tokens.
  *
- * Routers whose auth gate is JWT-based (`requireAuth` / `createRequireAuth` —
- * the admin surfaces: admin users/roles, api-keys management, cron, backups,
- * logs, schema editor) don't know about API keys. Mounting this middleware in
- * front of them authenticates `rk_` tokens and populates the request context;
- * the downstream gates then see the already-resolved user and apply their
- * role checks (`requireAdmin`) as usual — so an `admin: true` key passes and
- * a non-admin key is rejected with 403.
+ * Routers whose auth gate is JWT-based (`createRequireAuth` — the admin
+ * surfaces, the key routes) don't know about API keys. Mounted in front of
+ * them, this authenticates `rk_` tokens and populates the request context; the
+ * downstream gates then see the already-resolved caller and check its scopes.
  *
  * Requests without an `rk_` bearer token pass through untouched. An invalid,
  * revoked, or expired `rk_` token is rejected here (401) rather than falling

package/dist/auth/api-keys/api-key-routes.d.ts

@@ -1,32 +1,62 @@
 /**
- * Admin routes for managing Service API Keys.
+ * Routes for managing API keys.
  *
- * Mounted under `/api/admin/api-keys` with `requireAuth` + `requireAdmin`.
- * All routes return masked keys (never the hash). The full plaintext key
- * is returned exactly once in the POST response.
+ * - {@link createApiKeyRoutes} — the project's service keys, under
+ *   `/api/admin/api-keys`, for holders of `keys:read` / `keys:write`.
+ * - {@link createPersonalKeyRoutes} — the caller's own personal keys, under
+ *   `/api/auth/keys`, when the app enables `auth.personalKeys`.
+ *
+ * All routes return masked keys (never the hash). The full plaintext key is
+ * returned exactly once, in the response that creates it. No API key may call
+ * either router.
  *
  * @module
  */
 import { Hono } from "hono";
+import type { AccessModel } from "@rebasepro/types";
 import type { HonoEnv } from "../../api/types.js";
 import type { ApiKeyStore } from "./api-key-store.js";
+import { type KeyTargets } from "./key-grant.js";
 export interface ApiKeyRouteOptions {
     store: ApiKeyStore;
     serviceKey?: string;
     /**
      * Read the caller's roles from the database rather than from their token.
      *
-     * Without it this router trusted the `roles` claim, and a key minted here
-     * never expires and may carry `admin: true` — so an administrator demoted
-     * an hour ago could still mint themselves permanent admin access, and the
-     * demotion would not take effect until a token nobody can see had run out.
-     * See `createRequireAuth`.
+     * A key minted here may outlive the session that minted it, so the roles
+     * that bound what it may hold must be the caller's roles now — not the
+     * ones a token issued before a demotion still claims. See
+     * `createRequireAuth`.
      */
     resolveRoles?: (uid: string) => Promise<string[]>;
     /** Repository for the token-revocation watermark. See `createRequireAuth`. */
-    revocationRepo?: Pick<import("../interfaces.js").AuthRepository, "getTokensValidAfter">;
+    revocationRepo?: import("../token-revocation.js").AccessJudgeRepository;
+    /** What a scope's target may name. Unset, targets are not checked for existence. */
+    targets?: KeyTargets;
+    /** The access model to validate scopes against. Defaults to the configured one. */
+    accessModel?: () => AccessModel;
 }
 /**
- * Create admin routes for API key management.
+ * The project's service keys: `GET` needs `keys:read`, everything else
+ * `keys:write`.
  */
 export declare function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv>;
+export interface PersonalKeyRouteOptions {
+    store: ApiKeyStore;
+    /** Whether the app enabled `auth.personalKeys`. Off, every route explains how to turn it on. */
+    enabled: boolean;
+    /** Recognised only to be refused with a reason: the service key has no account. */
+    serviceKey?: string;
+    resolveRoles?: (uid: string) => Promise<string[]>;
+    revocationRepo?: import("../token-revocation.js").AccessJudgeRepository;
+    targets?: KeyTargets;
+    accessModel?: () => AccessModel;
+}
+/**
+ * The caller's own keys. Each acts as the caller — their account, their roles
+ * as they are when the key is used — and holds no scope the caller does not.
+ *
+ * For a signed-in account only: not a key, not the service key (it has no
+ * account to act as) and not a guest, whose account is one sign-out from gone.
+ */
+export declare function createPersonalKeyRoutes(options: PersonalKeyRouteOptions): Hono<HonoEnv>;

package/dist/auth/api-keys/api-key-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * Database operations for Service API Keys.
+ * Database operations for API keys.
  *
  * Uses the DataDriver's `admin.executeSql` capability (same pattern as
  * the cron-store and ensure-tables modules). All data lives in the
@@ -8,22 +8,45 @@
  * @module
  */
 import type { DataDriver } from "@rebasepro/types";
-import type { ApiKey, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types.js";
+import type { ApiKey, ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, UpdateApiKeyRequest } from "./api-key-types.js";
+/** What a new key row is made of, already validated by the route that asked. */
+export interface NewApiKey {
+    name: string;
+    kind: ApiKeyKind;
+    scopes: string[];
+    /** RLS roles beside `service`. Always empty for a personal key. */
+    roles: string[];
+    /** The account a personal key acts as. */
+    owner_uid: string | null;
+    rate_limit: number | null;
+    expires_at: string | null;
+}
+/** Which keys a listing returns. */
+export type ApiKeyFilter = {
+    kind: "service";
+} | {
+    kind: "personal";
+    owner_uid: string;
+};
 export interface ApiKeyStore {
     /** Ensure the `rebase.api_keys` table exists. Called once on startup. */
     ensureTable(): Promise<void>;
     /** Create a new API key. Returns the full plaintext key exactly once. */
-    createApiKey(request: CreateApiKeyRequest, createdBy: string): Promise<ApiKeyWithSecret>;
+    createApiKey(key: NewApiKey, createdBy: string): Promise<ApiKeyWithSecret>;
     /** Look up an API key by its SHA-256 hash. Returns `null` if not found. */
     findByKeyHash(hash: string): Promise<ApiKey | null>;
-    /** List all API keys (masked, never includes hash). */
-    listApiKeys(): Promise<ApiKeyMasked[]>;
+    /** List keys (masked, never includes hash), newest first. */
+    listApiKeys(filter: ApiKeyFilter): Promise<ApiKeyMasked[]>;
     /** Get a single API key by ID (masked). */
     getApiKeyById(id: string): Promise<ApiKeyMasked | null>;
-    /** Update name, permissions, rate_limit, or expires_at. */
+    /** Update name, scopes, roles, rate_limit, or expires_at. */
     updateApiKey(id: string, updates: UpdateApiKeyRequest): Promise<ApiKeyMasked | null>;
-    /** Soft-delete: set `revoked_at` to now. */
-    revokeApiKey(id: string): Promise<boolean>;
+    /**
+     * Soft-delete: set `revoked_at` to now. With `owner_uid`, only that
+     * account's personal key is revoked — the answer is false for anyone
+     * else's, so a route can 404 without saying whether the id exists.
+     */
+    revokeApiKey(id: string, owner_uid?: string): Promise<boolean>;
     /** Touch `last_used_at` to the current timestamp. */
     updateLastUsed(id: string): Promise<void>;
 }

package/dist/auth/api-keys/api-key-types.d.ts

@@ -1,15 +1,15 @@
 /**
- * Type definitions for Service API Keys.
+ * Type definitions for API keys.
  *
- * The wire contract — permissions, the masked key, the create/update payloads —
- * lives in `@rebasepro/types`, because the client SDK needs the same shapes and
- * the two declarations had already drifted apart. Only {@link ApiKey}, the
- * database row carrying `key_hash`, is server-side and stays here.
+ * The wire contract — scopes, the masked key, the create/update payloads —
+ * lives in `@rebasepro/types`, because the client SDK needs the same shapes.
+ * Only {@link ApiKey}, the database row carrying `key_hash`, is server-side
+ * and stays here.
  *
  * @module
  */
-import type { ApiKeyPermission } from "@rebasepro/types";
-export type { ApiKeyPermission, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
+import type { ApiKeyKind } from "@rebasepro/types";
+export type { ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
 /**
  * Full database row for an API key.
  * The `key_hash` is never exposed via the API — only stored for lookup.
@@ -17,19 +17,17 @@ export type { ApiKeyPermission, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequ
 export interface ApiKey {
     id: string;
     name: string;
+    kind: ApiKeyKind;
     /** First 12 characters of the plaintext key, for display only. */
     key_prefix: string;
     /** SHA-256 hash of the full plaintext key. */
     key_hash: string;
-    permissions: ApiKeyPermission[];
-    /**
-     * When true, the key is granted the `admin` role: it passes the
-     * admin-gated routes (users, roles, cron, backups, logs, API keys) and
-     * the RLS `default_admin` policies. Non-admin keys carry only the
-     * `service` role — RLS grants them nothing unless a collection policy
-     * explicitly names that role.
-     */
-    admin: boolean;
+    /** `resource:action[:target]` scope strings. */
+    scopes: string[];
+    /** RLS roles a service key runs as, beside `service`. Empty on a personal key. */
+    roles: string[];
+    /** The account a personal key acts as. Null on a service key. */
+    owner_uid: string | null;
     /**
      * Requests per 15-minute window. `null` means "no per-key override" —
      * the data rate limiter then applies its default API-key limit

package/dist/auth/api-keys/http-operation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which data-plane operation an HTTP request performs, for the scope it needs:
+ * `data:read`, `data:write` or `data:delete` (and the same for storage).
+ *
+ * @module
+ */
+/** The operation part of a data-plane scope. */
+export type DataOperation = "read" | "write" | "delete";
+/**
+ * Map an HTTP method to the operation it performs.
+ *
+ * - `GET`, `HEAD`, `OPTIONS` → `"read"`
+ * - `POST`, `PUT`, `PATCH`  → `"write"`
+ * - `DELETE`                → `"delete"`
+ *
+ * Any other method is a `"write"`: a verb this does not know is not assumed
+ * to be harmless.
+ */
+export declare function httpMethodToOperation(method: string): DataOperation;

package/dist/auth/api-keys/index.d.ts

@@ -1,17 +1,17 @@
 /**
- * Service API Keys module.
+ * API keys module.
  *
- * Re-exports types, store, middleware, permission guard, and routes
- * for the API key authentication system.
+ * Re-exports types, store, middleware and routes for API key authentication.
  *
  * @module
  */
-export type { ApiKey, ApiKeyMasked, ApiKeyPermission, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types.js";
+export type { ApiKey, ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, UpdateApiKeyRequest } from "./api-key-types.js";
 export { createApiKeyStore } from "./api-key-store.js";
-export type { ApiKeyStore } from "./api-key-store.js";
-export { isApiKeyToken, validateApiKey, createApiKeyPreAuth, createFunctionApiKeyGuard, createStorageApiKeyGuard } from "./api-key-middleware.js";
-export type { ApiKeyAuthOptions } from "./api-key-middleware.js";
-export { httpMethodToOperation, isOperationAllowed, isFunctionAllowed, isStorageAllowed } from "./api-key-permission-guard.js";
-export type { ApiKeyOperation } from "./api-key-permission-guard.js";
-export { createApiKeyRoutes } from "./api-key-routes.js";
-export type { ApiKeyRouteOptions } from "./api-key-routes.js";
+export type { ApiKeyStore, ApiKeyFilter, NewApiKey } from "./api-key-store.js";
+export { isApiKeyToken, resolveApiKey, validateApiKey, createApiKeyPreAuth, createFunctionScopeGuard, createTusScopeGuard } from "./api-key-middleware.js";
+export type { ApiKeyAuthOptions, ApiKeyIdentity, ApiKeyRefusal } from "./api-key-middleware.js";
+export { httpMethodToOperation } from "./http-operation.js";
+export type { DataOperation } from "./http-operation.js";
+export { createApiKeyRoutes, createPersonalKeyRoutes } from "./api-key-routes.js";
+export type { ApiKeyRouteOptions, PersonalKeyRouteOptions } from "./api-key-routes.js";
+export type { KeyTargets } from "./key-grant.js";

package/dist/auth/api-keys/key-grant.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What a new or changed key may hold, decided against whoever asked for it.
+ *
+ * One rule for every door that mints a credential: **nothing is minted with
+ * more than its minter holds.** A key's scopes must be within the creator's
+ * own; a service key's RLS roles must be roles the creator holds, unless the
+ * creator is an admin; and `keys:*` never goes on a key at all.
+ *
+ * @module
+ */
+import { type AccessModel } from "@rebasepro/types";
+/**
+ * The targets this backend serves, for refusing a key narrowed to something
+ * that does not exist — a typo there is a key that silently reaches nothing.
+ * Each list is read when a key is minted, so it reflects what is loaded then.
+ */
+export interface KeyTargets {
+    collections(): readonly string[];
+    functions(): readonly string[];
+    buckets(): readonly string[];
+}
+/** Read a `scopes` body field: a non-empty array of strings, deduplicated. */
+export declare function readScopesField(value: unknown): string[];
+/** Read a `roles` body field: an array of non-empty strings, deduplicated, without `service`. */
+export declare function readRolesField(value: unknown): string[];
+/**
+ * Refuse scopes that are malformed, unknown, aimed at a target that does not
+ * exist, for key management, or beyond what `minterScopes` covers.
+ */
+export declare function assertScopesGrantable(requested: readonly string[], minterScopes: readonly string[], model: AccessModel, targets?: KeyTargets): void;
+/**
+ * Refuse RLS roles the minter does not hold. An admin may give any role — they
+ * already read every row — and anyone else only their own.
+ */
+export declare function assertRolesGrantable(requested: readonly string[], minterRoles: readonly string[]): void;
+/** Read an optional `expires_at`: absent, null, or a future ISO-8601 instant. */
+export declare function readExpiresAt(value: unknown, requireFuture: boolean): string | null | undefined;
+/** Read an optional `rate_limit`: absent, null, or a positive integer. */
+export declare function readRateLimit(value: unknown): number | null | undefined;
+/** Read a key name: a non-empty string, trimmed. */
+export declare function readName(value: unknown): string;

package/dist/auth/api-keys/legacy-permissions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The scopes a key stored before scopes existed is read as.
+ *
+ * Such a row carries `permissions` — `[{ collection, operations }]`, with
+ * `"*"`, `"storage"`, `"functions"` and `"functions/<name>"` overloading the
+ * collection field — and an `admin` flag. This turns it into the scopes and
+ * RLS roles it now holds, once, when the store backfills the row.
+ *
+ * The rule is that nothing widens. Where a stored grant has no exact
+ * equivalent, it narrows:
+ *
+ * - A function grant without `write` becomes nothing. Functions were checked
+ *   by HTTP method, so a read-only grant let a key call GET functions; a
+ *   function is code, and `functions:invoke` is not a read.
+ * - `admin: true` becomes the `admin` RLS role and the admin surfaces such a
+ *   key could reach (users, schema, backups, cron, logs) — not `database:*`,
+ *   which lived on the realtime socket where no key could authenticate, and
+ *   not `keys:*`, which no key may hold.
+ *
+ * @module
+ */
+/** One stored permission entry, as the old column held it. */
+export interface StoredPermission {
+    collection: string;
+    operations: string[];
+}
+/** Read a stored `permissions` value — JSON text or already-parsed — into entries. */
+export declare function parseStoredPermissions(value: unknown): StoredPermission[];
+/** The scopes and RLS roles a stored key now holds. Never more than it did. */
+export declare function scopesFromStoredPermissions(permissions: readonly StoredPermission[], admin: boolean): {
+    scopes: string[];
+    roles: string[];
+};

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

@@ -37,6 +37,7 @@
  * ```
  */
 import type { PasswordValidationResult } from "./password.js";
+import { ApiError } from "../api/errors.js";
 import type { AuthRepository, UserData, CreateUserData } from "./interfaces.js";
 import type { EmailService, EmailConfig } from "../email/index.js";
 import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
@@ -93,8 +94,12 @@ export interface AuthHooks {
      */
     verifyCredentials?(email: string, password: string, repo: AuthRepository): Promise<UserData | null>;
     /**
-     * Called after any successful authentication event (login, register,
-     * OAuth, token refresh, password reset).
+     * Called after any successful authentication event: password login
+     * (`login`), registration (`register`), an OAuth sign-in (`oauth`), a
+     * token refresh (`refresh`), a password reset (`password-reset`), a
+     * guest session (`anonymous`), a magic link (`magic-link`), an email code
+     * (`otp`) and a second factor (`mfa`). Every value of {@link AuthMethod}
+     * is passed by some route.
      *
      * Use for audit logging, syncing external state, updating
      * last-login timestamps, etc.
@@ -103,7 +108,15 @@ export interface AuthHooks {
      */
     onAuthenticated?(user: UserData, method: AuthMethod): Promise<void>;
     /**
-     * Called before a new user is created (registration or admin creation).
+     * Called before a new user is created: registration, an OAuth sign-in
+     * that creates the account, a guest, and admin creation.
+     *
+     * Throw to refuse: the caller gets 400 `HOOK_REJECTED` with your message,
+     * or the status your error carries (`ApiError`, or a 4xx `status`).
+     *
+     * Also called when a guest becomes an account through
+     * `POST /auth/anonymous/link`, with the email and password hash it is
+     * getting; the guest itself was created with `isAnonymous: true`.
      *
      * Return modified data to alter what gets stored, or throw an error
      * to reject the creation entirely.
@@ -121,10 +134,14 @@ export interface AuthHooks {
      */
     afterUserCreate?(user: UserData): Promise<void>;
     /**
-     * Pre-login validation. Called before credential verification.
-     *
-     * Throw an error to reject the login attempt (e.g. for account lockout,
-     * IP-based restrictions, etc.).
+     * Pre-login validation. Called before credential verification on every
+     * sign-in: password (`login`), OAuth (`oauth`, with the provider's
+     * address), and the requests for a magic link (`magic-link`) or an email
+     * code (`otp`). Not on a token refresh, which is not a sign-in: to stop a
+     * signed-in account, disable it (`PUT /admin/users/:uid { disabled: true }`).
+     *
+     * Throw to refuse: 400 `HOOK_REJECTED` with your message, or the status
+     * your error carries.
      */
     beforeLogin?(email: string, method: AuthMethod): Promise<void>;
     /**
@@ -205,6 +222,19 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserDelete?(uid: string): Promise<void>;
+    /**
+     * Called when a signed-in user asks to move their account to `newEmail`
+     * (`POST /auth/change-email`), before anything is mailed. The address is
+     * normalized, free and deliverable by then.
+     *
+     * The address rule `beforeUserCreate` enforces at sign-up — only your own
+     * domain, say — belongs here too, or a member can sign up with an allowed
+     * address and then move to any other.
+     *
+     * Throw to refuse: 400 `HOOK_REJECTED` with your message, or the status
+     * your error carries.
+     */
+    beforeEmailChange?(user: UserData, newEmail: string): Promise<void>;
     /**
      * Optional hook to customize or override the default user creation flow via the admin panel/REST API.
      * When provided, this replaces the built-in password generation, hashing, and invitation email logic.
@@ -254,4 +284,17 @@ export type ResolvedAuthHooks = Required<Pick<AuthHooks, "hashPassword" | "verif
  * This is the single point where defaults are applied — all consumers
  * call this once and use the resolved hooks throughout.
  */
+/**
+ * What a hook's thrown error answers.
+ *
+ * The hooks that refuse (`beforeUserCreate`, `beforeLogin`,
+ * `beforeUserDelete`, `beforeEmailChange`) are documented as "throw to reject", and a plain
+ * `Error` is what people throw. It reached the error handler as a 500
+ * "Internal Server Error", so a deployment that limits sign-ups to its own
+ * domain answered an outsider with a server fault. A refusal is the caller's
+ * answer: 400 `HOOK_REJECTED` with the hook's message — or the status an
+ * error carries, when the hook chose one (`ApiError`, or any error with a 4xx
+ * `status`/`statusCode`).
+ */
+export declare function hookRefusal(error: unknown, hook: string): ApiError;
 export declare function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthHooks;

package/dist/auth/builtin-auth-adapter.d.ts

@@ -70,6 +70,14 @@ export interface BuiltinAuthAdapterConfig {
     enableEmailOtp?: boolean;
     /** Opt-in httpOnly cookie mode for refresh tokens. */
     cookieAuth?: import("./routes.js").CookieAuthConfig;
+    /** Refuse password sign-in until the address is verified; confirm-first registration. */
+    requireEmailVerification?: boolean;
+    /** Seconds a rotated-away refresh token still mints a sibling. Default 10. */
+    refreshTokenReuseIntervalSeconds?: number;
+    /** What a refresh token replayed after that window does to its session. Default `"reject"`. */
+    refreshTokenReuse?: import("./routes.js").RefreshTokenReusePolicy;
+    /** A magic-link or email-code request for an unknown address creates its account, while registration is open. */
+    magicLinkCreatesUsers?: boolean;
 }
 /**
  * Create the built-in Rebase auth adapter.

package/dist/auth/captcha.d.ts

@@ -39,6 +39,11 @@ export interface CaptchaConfig {
     /** Milliseconds before a verification attempt is abandoned. Default 5000. */
     timeoutMs?: number;
 }
+/**
+ * A protectable auth route. `register` guards both ways an account is made
+ * with a password: `POST /auth/register`, and `POST /auth/anonymous/link`,
+ * which turns a guest into one.
+ */
 export type CaptchaRoute = "register" | "login" | "forgotPassword" | "magicLink" | "emailOtp";
 export declare const DEFAULT_CAPTCHA_ROUTES: CaptchaRoute[];
 /**

package/dist/auth/cookie-utils.d.ts

@@ -22,6 +22,13 @@ export declare function setRefreshCookie(c: Context<HonoEnv>, refreshToken: stri
 export declare function clearRefreshCookie(c: Context<HonoEnv>, config: CookieAuthConfig | undefined): void;
 /**
  * Read the refresh token from the request — cookie first, then body fallback.
+ *
+ * An empty string is no token, wherever it comes from. In cookie mode every
+ * response this server sends carries `refreshToken: ""` (see
+ * `redactRefreshToken`), and a client that echoes it back — `@rebasepro/client`
+ * did, on every refresh from a live tab — is presenting nothing. Taking the
+ * body's `""` as the token, or refusing it at the schema, kept the cookie
+ * beside it from ever being read.
  */
 export declare function readRefreshToken(c: Context<HonoEnv>, body: {
     refreshToken?: string;

package/dist/auth/deliverable-address.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Addresses no mail can reach: the synthetic ones a guest and an X (Twitter)
+ * account are given, because `email` is NOT NULL. Nothing is mailed to them,
+ * and no account may move onto one.
+ */
+export declare function isDeliverableAddress(email: string): boolean;