@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/auth/jwt.d.ts

@@ -1,3 +1,5 @@
+import type { Context } from "hono";
+import type { HonoEnv } from "../api/types.js";
 import { type JwtSigningKeyConfig, type PublicJwk } from "./jwt-keys.js";
 export interface JwtConfig {
     secret: string;
@@ -61,6 +63,23 @@ export interface AccessTokenPayload {
      * comparison and the watermark was read on exactly one path — refresh.
      */
     iat?: number;
+    /**
+     * When the token expires, in seconds since the epoch — the standard `exp`
+     * claim. Carried through because a socket authenticated with this token
+     * has to stop honouring it at this instant, and has no request to refuse.
+     */
+    exp?: number;
+    /**
+     * The sign-in this token was minted for: the session id its refresh
+     * tokens share, carried across every rotation.
+     *
+     * What lets one device be signed out — `POST /auth/logout`,
+     * `DELETE /auth/sessions/:id` — reach that device's access token rather
+     * than only its refresh token, and what lets `GET /auth/sessions` mark the
+     * caller's own session. Absent on tokens minted before it existed; those
+     * keep working until they expire, judged by the watermark alone.
+     */
+    sid?: string;
     /** Email claim from the JWT, if present */
     email?: string;
     /** Display name claim from the JWT, if present */
@@ -90,48 +109,284 @@ export interface AccessTokenPayload {
     claims?: Record<string, unknown>;
 }
 /**
- * Configure JWT settings - call this during initialization.
- * Validates the secret strength to prevent deployment with default/weak secrets.
+ * The custom half of a verified token, or nothing when there is none.
+ *
+ * Exported for the one other place that builds a request identity's claims
+ * without a token to verify — `resolveUser`, which reads what a token minted
+ * now would carry — so both drop the same identity claims.
  */
-export declare function configureJwt(config: JwtConfig): void;
+export declare function customClaimsOf(decoded: Record<string, unknown>): Record<string, unknown> | undefined;
 /**
- * The public keys, in JWKS form, for `/.well-known/jwks.json`.
+ * How long a refresh token survives inactivity when no lifetime is configured.
+ * Sliding: every rotation re-ups it, so an active user stays signed in.
+ */
+export declare const DEFAULT_REFRESH_EXPIRES_IN = "30d";
+/**
+ * One backend's tokens: what it signs with, what it verifies against, and how
+ * long what it mints lives.
  *
- * An empty `keys` array on a backend with no asymmetric keys configured is the
- * correct answer rather than a 404: it says "this issuer publishes none",
- * which a verifier can act on, where a 404 is indistinguishable from a
- * misconfigured URL.
+ * Every backend built by `createRebaseBackend` holds its own
+ * (`backend.services.jwt`), so two backends in one process sign and verify
+ * with their own secrets and keys and a token one minted means nothing to the
+ * other. {@link createJwtService} builds one by hand.
+ *
+ * The module-level functions of the same names — `generateAccessToken`,
+ * `verifyAccessToken`, … — answer for the process default instead: what
+ * {@link configureJwt} set, or the backend `initializeRebaseBackend` installed.
  */
-export declare function getJwks(): {
-    keys: PublicJwk[];
-};
-/** Is this backend signing access tokens asymmetrically? */
-export declare function hasAsymmetricSigningKey(): boolean;
+export interface JwtService {
+    /** The access-token lifetime, in the grammar {@link parseDurationMs} reads. */
+    readonly accessExpiresIn: string;
+    /** The refresh-token lifetime, in the grammar {@link parseDurationMs} reads. */
+    readonly refreshExpiresIn: string;
+    /**
+     * Has this service been given a JWT secret?
+     *
+     * False on every backend that authenticates through an adapter — Firebase,
+     * Clerk, anything with its own tokens — because nothing gives it one there.
+     * Signing paths still throw when it is false, since asking for a token from
+     * a server that cannot mint one is a mistake worth hearing about. Paths
+     * whose contract is *"tolerate the absence of auth"* must ask first:
+     * `optionalAuth` crashing a request because this backend does not do JWT is
+     * a 500 on a route that had already decided anonymous was acceptable.
+     */
+    isConfigured(): boolean;
+    /** Is this service signing access tokens asymmetrically? */
+    hasAsymmetricSigningKey(): boolean;
+    /**
+     * The public keys, in JWKS form, for `/.well-known/jwks.json`.
+     *
+     * An empty `keys` array on a backend with no asymmetric keys configured is
+     * the correct answer rather than a 404: it says "this issuer publishes
+     * none", which a verifier can act on, where a 404 is indistinguishable from
+     * a misconfigured URL.
+     */
+    getJwks(): {
+        keys: PublicJwk[];
+    };
+    /**
+     * The symmetric secret this service signs purpose-scoped tokens with, or
+     * undefined when it has none — for deriving a key of the backend's own.
+     * MFA's encryption falls back to it when no `MFA_ENCRYPTION_KEY` is set.
+     * A method rather than a field, so serialising the service never prints it.
+     */
+    hmacSecret(): string | undefined;
+    /**
+     * Generate an access token (short-lived, 1 hour by default).
+     *
+     * @param isAnonymous Whether this session is a guest — anonymous sign-in
+     *   rather than an account. Written into the token so the RLS identity and
+     *   the WebSocket path can tell the two apart without a database lookup.
+     * @param sessionId The sign-in this token belongs to — see
+     *   {@link AccessTokenPayload.sid}. Every token the auth routes mint
+     *   carries one.
+     */
+    generateAccessToken(uid: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>, isAnonymous?: boolean, sessionId?: string): Promise<string>;
+    /**
+     * Verify and decode an access token.
+     *
+     * Every token this service issues is signed with the same secret, so what a
+     * token *is* comes from its claims, not from its signature. A download
+     * token ({@link JwtService.generateDownloadToken}) is therefore a
+     * validly-signed string that must never authenticate anybody: it is scoped
+     * to one file path and handed out in URLs, which is a far weaker thing to
+     * hold than a session.
+     *
+     * Today it is rejected below for want of an id — but only by luck, since
+     * nothing stops a future download token from carrying one. So the purpose
+     * is checked explicitly: a token minted for reading a file is not a token
+     * for being a user.
+     */
+    verifyAccessToken(token: string): Promise<AccessTokenPayload | null>;
+    /** The access-token lifetime in milliseconds. */
+    getAccessTokenExpiryMs(): number;
+    /** When an access token minted now expires, in milliseconds since the epoch. */
+    getAccessTokenExpiry(): number;
+    /**
+     * How long a refresh token is valid for, in milliseconds.
+     *
+     * Every rotation issues a token with a fresh TTL, so this is a sliding
+     * window: a user who visits at all keeps their session indefinitely, and
+     * one who disappears loses it this long after their last visit. That is
+     * what both Firebase and Supabase do by default, and it is the behaviour
+     * people mean when they say they expect to still be signed in.
+     */
+    getRefreshTokenTtlMs(): number;
+    /** When a refresh token minted now expires. */
+    getRefreshTokenExpiry(): Date;
+    /**
+     * Mint the short-lived credential handed back with an `MFA_REQUIRED`
+     * response.
+     *
+     * Short-lived on purpose: it is the window in which a caller who has
+     * proven the first factor may present the second, not a session to be
+     * carried around. Five minutes matches the challenge TTL.
+     */
+    generateMfaPendingToken(uid: string, expiresInSeconds?: number): Promise<string>;
+    /**
+     * Verify a pre-auth token and return the user it was minted for.
+     *
+     * Returns `null` for anything else — including a perfectly valid *access*
+     * token, which must not be interchangeable with this one in either
+     * direction.
+     *
+     * `iat` comes back with the uid because this token is a first factor that
+     * was accepted at that instant, and a sign-out everywhere after it has to
+     * void it the way it voids an access token — see `isAccessTokenRevoked`.
+     */
+    verifyMfaPendingToken(token: string): Promise<{
+        uid: string;
+        iat?: number;
+    } | null>;
+    /**
+     * Generate a short-lived download token scoped to a specific file path or
+     * prefix *within one storage source*.
+     *
+     * Both halves of that scope are load-bearing. A key is only unique inside
+     * its own bucket, and a project with more than one source routinely holds
+     * the same key in several of them — `avatars/u1.png` in `(default)` and in
+     * `media` are different objects, quite possibly with different owners. A
+     * token that names only the path is therefore a grant on every source at
+     * once: authorize a read on the source whose `storageAuthorize` hook says
+     * yes, then spend the token against `?storageId=` pointing somewhere else.
+     *
+     * `storageId` is optional here only because omitting it *is* the default
+     * source, which is what the overwhelming majority of deployments have. A
+     * mint site that forgets to pass a named source produces a default-scoped
+     * token, which fails closed at `/file/*` rather than over-granting.
+     *
+     * @param principal The user minting it, so the reads it buys are charged
+     *   to them.
+     */
+    generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null, principal?: string | null): Promise<string>;
+    /**
+     * Verify and decode a download token.
+     *
+     * A token minted before `storageId` existed carries no such claim. It is
+     * read as a grant on the **default source** rather than on all of them:
+     * that is the fail-closed reading, and it is what such a token almost
+     * always was, since a named source has to be asked for explicitly. The
+     * cost is bounded by the five-minute TTL — for at most that long after a
+     * deploy, an in-flight token for a *named* source is refused and the
+     * client re-fetches `/metadata`.
+     */
+    verifyDownloadToken(token: string): Promise<DownloadTokenPayload | null>;
+    /**
+     * Sign a short-lived token that carries state across a redirect.
+     *
+     * The generalisation of the MFA-pending token: a signed blob the server
+     * hands out and expects back, where the point is that the holder cannot
+     * edit it. The OAuth authorize flow needs one to carry the authorization
+     * request across the sign-in hop — without it, the endpoint the consent
+     * page posts to would mint a code for whatever `client_id` and
+     * `redirect_uri` its caller typed, skipping every check the authorize
+     * endpoint performs.
+     *
+     * The `purpose` is not decoration. {@link JwtService.verifyAccessToken}
+     * refuses any token that has one, so nothing minted here can be replayed
+     * as a session, and {@link JwtService.verifyPurposeToken} refuses a token
+     * whose purpose is not the one the caller named — so a token minted for
+     * one hop cannot be spent on another.
+     */
+    signPurposeToken(purpose: string, claims: Record<string, unknown>, expiresInSeconds: number): Promise<string>;
+    /** Verify a token minted by {@link JwtService.signPurposeToken}, for one named purpose. */
+    verifyPurposeToken<T>(purpose: string, token: string): Promise<T | null>;
+    /**
+     * Mint an access token for the MCP endpoint.
+     *
+     * Deliberately **not** an ordinary session token, and the `purpose` claim
+     * is what enforces that: {@link JwtService.verifyAccessToken} refuses any
+     * token carrying one, so a credential issued to a third-party MCP client —
+     * Claude, an IDE, anything that completed the OAuth flow — cannot be
+     * replayed against `/api/data`, `/api/admin` or the websocket. It buys
+     * exactly the one resource it names.
+     *
+     * That asymmetry matters more than it first looks. These tokens are handed
+     * to software the user authorized but the operator never vetted, they
+     * live in that software's storage, and they are the only credential in
+     * this system minted for a third party. Without the purpose separation,
+     * "connect Claude to your data" would silently mean "give Claude a full
+     * session".
+     *
+     * The audience is the canonical resource URI, and
+     * {@link JwtService.verifyMcpAccessToken} requires the caller to say which
+     * resource it is checking for. A token minted for another Rebase project —
+     * or another path on this one — fails there.
+     *
+     * HS256 with the shared secret, like the download token: the authorization
+     * server and the resource server are the same process, so nothing outside
+     * it ever needs to verify one, and an asymmetric key here would be a
+     * second key surface bought for nobody.
+     */
+    generateMcpAccessToken(payload: Omit<McpAccessTokenPayload, "purpose">, expiresInSeconds: number): Promise<string>;
+    /**
+     * Verify an MCP access token **for a specific resource**.
+     *
+     * `expectedAudience` has no default. The MCP specification requires a
+     * resource server to validate that a token was issued for it
+     * specifically, and a default would be the thing that quietly turns that
+     * check off — the caller has to say what it is, every time, so a new call
+     * site cannot forget by omission.
+     */
+    verifyMcpAccessToken(token: string, expectedAudience: string): Promise<McpAccessTokenPayload | null>;
+}
 /**
- * Has this server been given a JWT secret?
+ * Build a {@link JwtService} from a configuration, refusing one it would sign
+ * badly with: a short or well-known secret, an `activeKid` no key carries, a
+ * lifetime that is not one.
+ *
+ * Unset lifetimes take the defaults — an hour for access tokens,
+ * {@link DEFAULT_REFRESH_EXPIRES_IN} for refresh tokens.
  *
- * False on every backend that authenticates through an adapter — Firebase,
- * Clerk, anything with its own tokens — because nothing calls
- * {@link configureJwt} there. Signing paths still throw when it is false, since
- * asking for a token from a server that cannot mint one is a mistake worth
- * hearing about. Paths whose contract is *"tolerate the absence of auth"* must
- * ask first: `optionalAuth` crashing a request because this backend does not do
- * JWT is a 500 on a route that had already decided anonymous was acceptable.
+ * @example
+ * ```ts
+ * const jwt = createJwtService({ secret: process.env.JWT_SECRET! });
+ * const token = await jwt.generateAccessToken("u1", ["editor"]);
+ * const payload = await jwt.verifyAccessToken(token); // { uid: "u1", roles: ["editor"], … }
+ * ```
  */
-export declare function isJwtConfigured(): boolean;
+export declare function createJwtService(config: JwtConfig): JwtService;
 /**
- * Generate an access token (short-lived, 1 hour by default)
+ * Configure the process default's JWT settings — what `verifyAccessToken`,
+ * `generateAccessToken` and the other module-level functions sign and verify
+ * with.
+ *
+ * Validates the secret strength to prevent deployment with default/weak
+ * secrets. A lifetime left unset keeps the one already configured; a
+ * configuration that fails validation leaves the previous one standing rather
+ * than half-applying a new one.
+ */
+export declare function configureJwt(config: JwtConfig): void;
+/**
+ * @internal The process default itself, to install another or to restore it.
+ * `setDefaultBackend` and tests use these; an application calls
+ * {@link configureJwt} or `setDefaultBackend`.
  */
-export declare function generateAccessToken(uid: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>, 
+export declare function defaultJwtService(): JwtService;
+/** @internal See {@link defaultJwtService}. */
+export declare function setDefaultJwtService(service: JwtService): void;
 /**
- * Whether this session is a guest — anonymous sign-in rather than an
- * account. Written into the token so the RLS identity and the WebSocket
- * path can tell the two apart without a database lookup.
+ * The JWT service serving this request: the backend's whose route group is
+ * answering it, or the process default for a route mounted outside any
+ * backend.
  */
-isAnonymous?: boolean): Promise<string>;
+export declare function jwtOf(c: Context<HonoEnv>): JwtService;
+/** See {@link JwtService.getJwks}. Answers for the process default. */
+export declare function getJwks(): {
+    keys: PublicJwk[];
+};
 /**
- * Get the expiration time of an access token in milliseconds from now
+ * The secret {@link configureJwt} was given, or undefined before it is called.
+ * Answers for the process default — see {@link JwtService.hmacSecret}.
  */
+export declare function configuredJwtSecret(): string | undefined;
+/** See {@link JwtService.hasAsymmetricSigningKey}. Answers for the process default. */
+export declare function hasAsymmetricSigningKey(): boolean;
+/** See {@link JwtService.isConfigured}. Answers for the process default. */
+export declare function isJwtConfigured(): boolean;
+/** See {@link JwtService.generateAccessToken}. Answers for the process default. */
+export declare function generateAccessToken(uid: string, roles: string[], aal?: "aal1" | "aal2", customClaims?: Record<string, unknown>, isAnonymous?: boolean, sessionId?: string): Promise<string>;
+/** See {@link JwtService.getAccessTokenExpiryMs}. Answers for the process default. */
 export declare function getAccessTokenExpiryMs(): number;
 /**
  * A lifetime setting in milliseconds, or null when it is not one.
@@ -145,27 +400,13 @@ export declare function getAccessTokenExpiryMs(): number;
  * (ms reads "3600" as 3.6 seconds) and a lifetime of zero or less.
  */
 export declare function parseDurationMs(value: string): number | null;
-/**
- * Get the expiration timestamp for an access token
- */
+/** See {@link JwtService.getAccessTokenExpiry}. Answers for the process default. */
 export declare function getAccessTokenExpiry(): number;
-/**
- * Verify and decode an access token.
- *
- * Every token this server issues is signed with the same secret, so what a
- * token *is* comes from its claims, not from its signature. A download token
- * ({@link generateDownloadToken}) is therefore a validly-signed string that
- * must never authenticate anybody: it is scoped to one file path and handed out
- * in URLs, which is a far weaker thing to hold than a session.
- *
- * Today it is rejected below for want of an id — but only by luck, since
- * nothing stops a future download token from carrying one. So the purpose is
- * checked explicitly: a token minted for reading a file is not a token for
- * being a user.
- */
+/** See {@link JwtService.verifyAccessToken}. Answers for the process default. */
 export declare function verifyAccessToken(token: string): Promise<AccessTokenPayload | null>;
 /**
- * Generate a random refresh token (long-lived, 30 days by default)
+ * Generate a random refresh token. Long-lived: 30 days by default, sliding —
+ * see {@link JwtService.getRefreshTokenTtlMs}.
  */
 export declare function generateRefreshToken(): string;
 /**
@@ -179,49 +420,24 @@ export declare function hashRefreshToken(token: string): Promise<string>;
  * what is actually enforced, which is worse than knowing the ceiling.
  */
 export declare const MAX_COOKIE_AGE_MS: number;
-/**
- * How long a refresh token is valid for, in milliseconds.
- *
- * Every rotation issues a token with a fresh TTL, so this is a sliding window:
- * a user who visits at all keeps their session indefinitely, and one who
- * disappears loses it this long after their last visit. That is what both
- * Firebase and Supabase do by default, and it is the behaviour people mean
- * when they say they expect to still be signed in.
- */
+/** See {@link JwtService.getRefreshTokenTtlMs}. Answers for the process default. */
 export declare function getRefreshTokenTtlMs(): number;
-/**
- * Calculate refresh token expiration date
- */
+/** See {@link JwtService.getRefreshTokenExpiry}. Answers for the process default. */
 export declare function getRefreshTokenExpiry(): Date;
 /**
  * The `purpose` claim carried by a credential that stands between "first factor
  * accepted" and "session issued".
  *
  * A pre-auth token is NOT a session and must never be usable as one:
- * {@link verifyAccessToken} refuses any token carrying a `purpose`, so this
- * value cannot authenticate a request no matter which route it is presented to.
- * The only thing that reads it is the MFA challenge pair, which exchanges it —
- * plus a second factor — for a real session.
+ * {@link JwtService.verifyAccessToken} refuses any token carrying a `purpose`,
+ * so this value cannot authenticate a request no matter which route it is
+ * presented to. The only thing that reads it is the MFA challenge pair, which
+ * exchanges it — plus a second factor — for a real session.
  */
 export declare const MFA_PENDING_PURPOSE = "mfa-pending";
-/**
- * Mint the short-lived credential handed back with an `MFA_REQUIRED` response.
- *
- * Short-lived on purpose: it is the window in which a caller who has proven the
- * first factor may present the second, not a session to be carried around. Five
- * minutes matches the challenge TTL.
- */
+/** See {@link JwtService.generateMfaPendingToken}. Answers for the process default. */
 export declare function generateMfaPendingToken(uid: string, expiresInSeconds?: number): Promise<string>;
-/**
- * Verify a pre-auth token and return the user it was minted for.
- *
- * Returns `null` for anything else — including a perfectly valid *access*
- * token, which must not be interchangeable with this one in either direction.
- *
- * `iat` comes back with the uid because this token is a first factor that was
- * accepted at that instant, and a sign-out everywhere after it has to void it
- * the way it voids an access token — see `isAccessTokenRevoked`.
- */
+/** See {@link JwtService.verifyMfaPendingToken}. Answers for the process default. */
 export declare function verifyMfaPendingToken(token: string): Promise<{
     uid: string;
     iat?: number;
@@ -232,57 +448,27 @@ export interface DownloadTokenPayload {
     /**
      * The storage source the grant is good for, canonicalized by
      * {@link canonicalStorageId}. Always present on a decoded payload; see
-     * {@link verifyDownloadToken} for how tokens minted before this claim
-     * existed are read.
+     * {@link JwtService.verifyDownloadToken} for how tokens minted before this
+     * claim existed are read.
      */
     storageId: string;
+    /**
+     * An opaque mark of the user who minted the token, for rate limiting only:
+     * a read that spends the token is charged to that user's allowance rather
+     * than to the reader's address. A hash, because the token travels in a URL.
+     * Absent for a token minted for nobody.
+     */
+    rl?: string;
 }
-/**
- * Generate a short-lived download token scoped to a specific file path or prefix
- * *within one storage source*.
- *
- * Both halves of that scope are load-bearing. A key is only unique inside its
- * own bucket, and a project with more than one source routinely holds the same
- * key in several of them — `avatars/u1.png` in `(default)` and in `media` are
- * different objects, quite possibly with different owners. A token that names
- * only the path is therefore a grant on every source at once: authorize a read
- * on the source whose `storageAuthorize` hook says yes, then spend the token
- * against `?storageId=` pointing somewhere else.
- *
- * `storageId` is optional here only because omitting it *is* the default
- * source, which is what the overwhelming majority of deployments have. A mint
- * site that forgets to pass a named source produces a default-scoped token,
- * which fails closed at `/file/*` rather than over-granting.
- */
-export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null): Promise<string>;
-/**
- * Verify and decode a download token.
- *
- * A token minted before `storageId` existed carries no such claim. It is read
- * as a grant on the **default source** rather than on all of them: that is the
- * fail-closed reading, and it is what such a token almost always was, since a
- * named source has to be asked for explicitly. The cost is bounded by the
- * five-minute TTL — for at most that long after a deploy, an in-flight token
- * for a *named* source is refused and the client re-fetches `/metadata`.
- */
+/** See {@link JwtService.generateDownloadToken}. Answers for the process default. */
+export declare function generateDownloadToken(path: string, expiresInSeconds?: number, storageId?: string | null, 
+/** The user minting it, so the reads it buys are charged to them. */
+principal?: string | null): Promise<string>;
+/** See {@link JwtService.verifyDownloadToken}. Answers for the process default. */
 export declare function verifyDownloadToken(token: string): Promise<DownloadTokenPayload | null>;
-/**
- * Sign a short-lived token that carries state across a redirect.
- *
- * The generalisation of the MFA-pending token: a signed blob the server hands
- * out and expects back, where the point is that the holder cannot edit it. The
- * OAuth authorize flow needs one to carry the authorization request across the
- * sign-in hop — without it, the endpoint the consent page posts to would mint a
- * code for whatever `client_id` and `redirect_uri` its caller typed, skipping
- * every check the authorize endpoint performs.
- *
- * The `purpose` is not decoration. {@link verifyAccessToken} refuses any token
- * that has one, so nothing minted here can be replayed as a session, and
- * {@link verifyPurposeToken} refuses a token whose purpose is not the one the
- * caller named — so a token minted for one hop cannot be spent on another.
- */
+/** See {@link JwtService.signPurposeToken}. Answers for the process default. */
 export declare function signPurposeToken(purpose: string, claims: Record<string, unknown>, expiresInSeconds: number): Promise<string>;
-/** Verify a token minted by {@link signPurposeToken}, for one named purpose. */
+/** See {@link JwtService.verifyPurposeToken}. Answers for the process default. */
 export declare function verifyPurposeToken<T>(purpose: string, token: string): Promise<T | null>;
 /** The `purpose` that marks a token as belonging to the MCP resource. */
 export declare const MCP_ACCESS_PURPOSE = "mcp-access";
@@ -299,37 +485,13 @@ export interface McpAccessTokenPayload {
     aud: string;
     iss: string;
 }
-/**
- * Mint an access token for the MCP endpoint.
- *
- * Deliberately **not** an ordinary session token, and the `purpose` claim is
- * what enforces that: {@link verifyAccessToken} refuses any token carrying one,
- * so a credential issued to a third-party MCP client — Claude, an IDE, anything
- * that completed the OAuth flow — cannot be replayed against `/api/data`,
- * `/api/admin` or the websocket. It buys exactly the one resource it names.
- *
- * That asymmetry matters more than it first looks. These tokens are handed to
- * software the user authorized but the operator never vetted, they live in that
- * software's storage, and they are the only credential in this system minted
- * for a third party. Without the purpose separation, "connect Claude to your
- * data" would silently mean "give Claude a full session".
- *
- * The audience is the canonical resource URI, and {@link verifyMcpAccessToken}
- * requires the caller to say which resource it is checking for. A token minted
- * for another Rebase project — or another path on this one — fails there.
- *
- * HS256 with the shared secret, like the download token: the authorization
- * server and the resource server are the same process, so nothing outside it
- * ever needs to verify one, and an asymmetric key here would be a second key
- * surface bought for nobody.
- */
+/** See {@link JwtService.generateMcpAccessToken}. Answers for the process default. */
 export declare function generateMcpAccessToken(payload: Omit<McpAccessTokenPayload, "purpose">, expiresInSeconds: number): Promise<string>;
+/** See {@link JwtService.verifyMcpAccessToken}. Answers for the process default. */
+export declare function verifyMcpAccessToken(token: string, expectedAudience: string): Promise<McpAccessTokenPayload | null>;
 /**
- * Verify an MCP access token **for a specific resource**.
- *
- * `expectedAudience` has no default. The MCP specification requires a resource
- * server to validate that a token was issued for it specifically, and a default
- * would be the thing that quietly turns that check off — the caller has to say
- * what it is, every time, so a new call site cannot forget by omission.
+ * The process default as a service object that follows it — every call reads
+ * whatever {@link configureJwt} or `setDefaultBackend` installed last. What a
+ * route built outside any backend falls back to.
  */
-export declare function verifyMcpAccessToken(token: string, expectedAudience: string): Promise<McpAccessTokenPayload | null>;
+export declare const processJwtService: JwtService;

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

@@ -1,8 +1,9 @@
 import { Hono } from "hono";
 import type { MiddlewareHandler } from "hono";
-import type { AuthModuleConfig } from "./routes.js";
+import type { AuthModuleConfig, CreateSessionAndTokens } from "./routes.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
 import type { HonoEnv } from "../api/types.js";
+import { 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: {
@@ -24,11 +27,7 @@ export declare function mountMagicLinkRoutes(deps: {
         isAnonymous?: boolean;
         metadata?: Record<string, unknown> | null;
     }, roleIds: string[], accessToken: string, refreshToken: string, providerId: string) => unknown;
-    createSessionAndTokens: (uid: string, userAgent: string, ipAddress: string) => Promise<{
-        roleIds: string[];
-        accessToken: string;
-        refreshToken: string;
-    }>;
+    createSessionAndTokens: CreateSessionAndTokens;
     applyTransformHook: (response: AuthResponsePayload, method: TransformAuthResponseContext["method"], request: Request, uid: string) => Promise<AuthResponsePayload>;
     /**
      * Built by the caller so a misconfiguration fails the boot once, rather

package/dist/auth/mfa-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>;