@rebasepro/server 0.23.0 → 0.24.0

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,11 @@ 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
@@ -125,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>;
     /**
@@ -209,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.
@@ -258,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/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;

package/dist/auth/email-change-routes.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A signed-in user changes their own email address.
+ *
+ * `POST /auth/change-email { newEmail }` records the change and mails a link to
+ * the new address, and a notice without a link to the old one.
+ * `POST /auth/confirm-email-change { token }` — the link's landing screen calls
+ * it — moves the account onto the new address.
+ *
+ * The address moves only when its inbox answers, so the account is never
+ * pointed at an address nobody proved, and nothing is reserved meanwhile: a
+ * pending change that held the address would let any account keep a stranger
+ * from signing up with their own address. Whoever has the address when the link
+ * is followed keeps it, and the link answers 409.
+ *
+ * On confirmation the address is the account's, verified. The identities whose
+ * provider vouched for the old address are detached: the old address may be
+ * the reason for the change — a job left, an inbox lost — and whoever controls
+ * it now would otherwise sign in through that provider. The sessions stay: the
+ * change was asked for from one, and the link proves the new inbox, not
+ * anything about the others.
+ *
+ * @module
+ */
+import { Hono } from "hono";
+import { z } from "zod";
+import type { HonoEnv } from "../api/types.js";
+import type { MiddlewareHandler } from "hono";
+import type { resolveAuthHooks } from "./auth-hooks.js";
+import type { AuthModuleConfig } from "./routes.js";
+/** How long an address-change link stays usable. */
+export declare const EMAIL_CHANGE_TTL_MS: number;
+interface EmailChangeRoutesConfig {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ReturnType<typeof resolveAuthHooks>;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    /** A signed-in user, with the revocation watermark consulted. */
+    requireLiveSession: MiddlewareHandler<HonoEnv>;
+}
+export declare function mountEmailChangeRoutes(opts: EmailChangeRoutesConfig): void;
+export {};

package/dist/auth/expired-token-sweep.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Deleting the auth tokens nobody can use any more, on a schedule.
+ *
+ * `TokenRepository.deleteExpiredTokens` was declared, implemented and never
+ * called. Every expired reset link, magic link, email code, abandoned refresh
+ * token and stale MFA challenge stayed in the database for good: the tables
+ * grew by a row per sign-in attempt and nothing took one away.
+ *
+ * Runs on the process that owns the timers (`ownership.cronScheduler`), once
+ * an hour, and across instances once per hour in all: each tick claims its
+ * hour's slot in `rebase.cron_claims` — the claim the cron scheduler takes for
+ * a job's run — and only the instance that wins it sweeps. A store that cannot
+ * answer the claim means no sweep this hour rather than every instance at
+ * once; the tokens are already refused when presented, so a late sweep costs
+ * space, not safety.
+ *
+ * @module
+ */
+import type { DataDriver } from "@rebasepro/types";
+import type { TokenRepository } from "./interfaces.js";
+/** The slot key in `rebase.cron_claims`. Namespaced so no job file can take it. */
+export declare const EXPIRED_TOKEN_SWEEP_JOB_ID = "rebase:auth:expired-tokens";
+/** One sweep an hour, fleet-wide. */
+export declare const EXPIRED_TOKEN_SWEEP_INTERVAL_MS: number;
+export interface ExpiredTokenSweepOptions {
+    authRepo: Pick<TokenRepository, "deleteExpiredTokens">;
+    /**
+     * Claim `slot` for `jobId` across every instance: `true` for the one that
+     * wins it. Throws when the store cannot tell. Without it — a driver with
+     * no SQL, cron persistence switched off — every instance sweeps, which is
+     * wasted work but harmless: deleting what has expired is idempotent.
+     */
+    claimSlot?: (jobId: string, slot: string) => Promise<boolean>;
+    intervalMs?: number;
+    /** Clock, for tests. */
+    now?: () => number;
+}
+/** What one tick did. */
+export type ExpiredTokenSweepOutcome = "swept" | "claimed-elsewhere" | "unclaimed" | "failed";
+export interface ExpiredTokenSweep {
+    /** Sweep now, then once per interval. */
+    start(): void;
+    stop(): void;
+    /** One tick: claim this interval's slot and, if it is ours, sweep. */
+    runSlot(): Promise<ExpiredTokenSweepOutcome>;
+}
+export declare function createExpiredTokenSweep(options: ExpiredTokenSweepOptions): ExpiredTokenSweep;
+/** What {@link startExpiredTokenSweep} is given by the boot. */
+export interface ExpiredTokenSweepWiring {
+    /** The auth repository, when the backend has one. */
+    authRepo?: Partial<Pick<TokenRepository, "deleteExpiredTokens">>;
+    /** The default data driver: its SQL admin backs the slot claim. */
+    driver: DataDriver;
+    /** Whether this process owns the timers (`ownership.cronScheduler`). */
+    ownsTimers: boolean;
+    /** `cronPersistence: false` keeps the claims table out of the database, here too. */
+    persistClaims?: boolean;
+}
+/**
+ * Start the sweep where it belongs, or answer `undefined` where it does not:
+ * a process that does not own the timers, or a backend whose auth repository
+ * cannot delete expired tokens.
+ *
+ * The claim is the cron store's, made on the first tick rather than at boot so
+ * the boot does not wait on its tables.
+ */
+export declare function startExpiredTokenSweep(wiring: ExpiredTokenSweepWiring): ExpiredTokenSweep | undefined;