@udibo/oauth2 0.4.1 → 0.5.1

package/esm/adapters/hono/bff/session-store.js

@@ -17,8 +17,9 @@
  *
  * A raw "token in cookie" store is deliberately **not** shipped: a leaked
  * log line containing the cookie would yield a working bearer token. The
- * AES-GCM encryption in the stateless store is what makes that pattern
- * safe.
+ * AES-GCM encryption in the stateless store keeps the tokens unreadable, but
+ * a leaked encrypted cookie still works as a session cookie against the BFF
+ * until it expires.
  *
  * @module
  */

package/esm/adapters/hono/bff/testing.d.ts

@@ -60,7 +60,10 @@ export interface CreateTestSessionOptions {
  * const cookie = await createTestSession(bff, {
  *   user: { sub: "u1", name: "Alice" },
  * });
- * const res = await app.request("/auth/session", { headers: { cookie } });
+ * // With CSRF on (the default), a request carrying the cookie needs the header.
+ * const res = await app.request("/auth/session", {
+ *   headers: { cookie, "x-csrf": "1" },
+ * });
  * ```
  */
 export declare function createTestSession(bff: HonoBff, options?: CreateTestSessionOptions): Promise<string>;
@@ -105,7 +108,9 @@ export interface CreateAuthenticatedTestSessionOptions<Client extends ClientInte
  *   scope: new BasicScope("read write"),
  *   claims: { sub: "u1", name: "Alice" },
  * });
- * const res = await app.request("/api/me", { headers: { cookie } });
+ * const res = await app.request("/api/me", {
+ *   headers: { cookie, "x-csrf": "1" },
+ * });
  * ```
  */
 export declare function createAuthenticatedTestSession<Client extends ClientInterface, User, Scope extends AbstractScope>(bff: HonoBff, options: CreateAuthenticatedTestSessionOptions<Client, User, Scope>): Promise<string>;
@@ -161,5 +166,11 @@ export interface SessionStoreContractOptions {
      */
     makeBoundedStore?(maxAgeMs: number): Promise<SessionStore> | SessionStore;
 }
-/** Contract test suite for {@link SessionStore} implementations. */
+/**
+ * Contract test suite for {@link SessionStore} implementations. Registers
+ * `describe`/`it` blocks from `@std/testing/bdd`, so call it at a test
+ * module's top level. It does not check that a stateful store's `update`
+ * rejects a missing or destroyed session, which {@link SessionStore.update}
+ * requires — test that yourself.
+ */
 export declare function runSessionStoreContractTests(options: SessionStoreContractOptions): void;

package/esm/adapters/hono/bff/testing.js

@@ -42,7 +42,10 @@ import { sessionStoreMaxAgeMs, } from "./session-store.js";
  * const cookie = await createTestSession(bff, {
  *   user: { sub: "u1", name: "Alice" },
  * });
- * const res = await app.request("/auth/session", { headers: { cookie } });
+ * // With CSRF on (the default), a request carrying the cookie needs the header.
+ * const res = await app.request("/auth/session", {
+ *   headers: { cookie, "x-csrf": "1" },
+ * });
  * ```
  */
 export async function createTestSession(bff, options = {}) {
@@ -86,7 +89,9 @@ export async function createTestSession(bff, options = {}) {
  *   scope: new BasicScope("read write"),
  *   claims: { sub: "u1", name: "Alice" },
  * });
- * const res = await app.request("/api/me", { headers: { cookie } });
+ * const res = await app.request("/api/me", {
+ *   headers: { cookie, "x-csrf": "1" },
+ * });
  * ```
  */
 export async function createAuthenticatedTestSession(bff, options) {
@@ -163,7 +168,13 @@ function parseCookieHeader(header, name) {
     throw new Error(`parseCookieHeader: cookie "${name}" not found in header "${header}"`);
 }
 const BOUND_MS = 1000;
-/** Contract test suite for {@link SessionStore} implementations. */
+/**
+ * Contract test suite for {@link SessionStore} implementations. Registers
+ * `describe`/`it` blocks from `@std/testing/bdd`, so call it at a test
+ * module's top level. It does not check that a stateful store's `update`
+ * rejects a missing or destroyed session, which {@link SessionStore.update}
+ * requires — test that yourself.
+ */
 export function runSessionStoreContractTests(options) {
     const destroyClearsRead = options.destroyClearsRead ?? true;
     const makeBoundedStore = options.makeBoundedStore;

package/esm/adapters/hono/identity.d.ts

@@ -10,7 +10,7 @@
  * (the `IdentityService` stays usable directly from your own
  * routes/loaders/actions).
  *
- * **Scope — password path only, by design.** The newer flows are intentionally
+ * **Scope — password path only, by design.** The other flows are intentionally
  * *not* mounted here, because their safe wiring carries app-owned policy the
  * factory can't guess. Drive them by calling the service methods from your own
  * handlers, as each guide shows:
@@ -76,8 +76,10 @@ export interface HonoIdentityOptions<User extends IdentityUser> {
      * Cross-site request protection, **on by default**. These routes carry no
      * token of their own, so the guard reads what the browser states about the
      * request: a `Sec-Fetch-Site` of `same-origin`/`none` passes, any other value
-     * is refused, and browsers too old to send it fall back to matching the
-     * `Origin` header's host against the request's. A request with neither header
+     * is refused unless `Origin` is in
+     * {@link HonoIdentityCsrfOptions.allowedOrigins}, and browsers too old to
+     * send it fall back to matching `Origin` against that list or the request's
+     * own host. A request with neither header
      * — curl, a server-side call, a native app — passes, since cross-site request
      * forgery needs a browser.
      *

package/esm/adapters/hono/identity.js

@@ -10,7 +10,7 @@
  * (the `IdentityService` stays usable directly from your own
  * routes/loaders/actions).
  *
- * **Scope — password path only, by design.** The newer flows are intentionally
+ * **Scope — password path only, by design.** The other flows are intentionally
  * *not* mounted here, because their safe wiring carries app-owned policy the
  * factory can't guess. Drive them by calling the service methods from your own
  * handlers, as each guide shows:
@@ -42,12 +42,6 @@
 import "../../_dnt.polyfills.js";
 import { Hono } from "hono";
 import { identityErrorStatus, isIdentityError, } from "../../identity/errors.js";
-/**
- * Wrap a handler so a thrown {@link IdentityError} (e.g. `identifier_taken` from
- * your user store, or `weak_password` from a policy check) becomes a consistent
- * `{ error: code }` response with the conventional status; other errors
- * propagate untouched.
- */
 function handle(fn) {
     return async (c) => {
         try {
@@ -64,12 +58,6 @@ function handle(fn) {
     };
 }
 const STRING_FIELDS = new Set(["password", "identifier", "email", "token"]);
-/**
- * Reads a JSON or form-encoded request body. A JSON body keeps each value's
- * type except for {@link STRING_FIELDS}; a body that is not a JSON object
- * (array, string, `null`) reads as empty. A form-encoded body is all strings by
- * construction.
- */
 async function readBody(c) {
     const contentType = c.req.header("content-type") ?? "";
     if (contentType.includes("application/json")) {
@@ -124,10 +112,6 @@ function isTrustedOrigin(c, allowedOrigins) {
     return allowedOrigins.has(origin) ||
         hostOf(origin) === new URL(c.req.url).host;
 }
-/**
- * Refuses an unsafe-method request a browser reports as coming from another
- * site, per {@link HonoIdentityOptions.csrf}.
- */
 function sameOriginGuard(options) {
     const allowedOrigins = new Set(options.allowedOrigins ?? []);
     return async (c, next) => {

package/esm/adapters/hono/resource-server.d.ts

@@ -45,8 +45,9 @@ export declare class HonoResourceServer<Client extends ClientInterface, User, S
      *
      * On success, sets the authenticated context at `c.get("@udibo/oauth2")`
      * (typed via {@link HonoResourceServerVariables}) and calls `next()`. On
-     * failure, returns an RFC 6749 error response with a `WWW-Authenticate`
-     * header per RFC 6750 Section 3.
+     * failure, returns an error response, with a `WWW-Authenticate` challenge
+     * (RFC 6750 Section 3) on a 401 or 403, or rethrows when `throwOnError` is
+     * set.
      */
     protect(requiredScope?: S | string): MiddlewareHandler;
     /**

package/esm/adapters/hono/resource-server.js

@@ -42,8 +42,9 @@ export class HonoResourceServer extends ResourceServer {
      *
      * On success, sets the authenticated context at `c.get("@udibo/oauth2")`
      * (typed via {@link HonoResourceServerVariables}) and calls `next()`. On
-     * failure, returns an RFC 6749 error response with a `WWW-Authenticate`
-     * header per RFC 6750 Section 3.
+     * failure, returns an error response, with a `WWW-Authenticate` challenge
+     * (RFC 6750 Section 3) on a 401 or 403, or rethrows when `throwOnError` is
+     * set.
      */
     protect(requiredScope) {
         return createProtectMiddleware(this, requiredScope);

package/esm/client/_http.d.ts

@@ -1,11 +1,8 @@
 /**
- * The response ladder every {@link DirectClient} network call climbs: bounded
- * read, deadline, redirect refusal, JSON validation, RFC 6749 §5.2 error
- * mapping.
- *
- * Not part of the public API. The authorization server's bytes become either a
- * typed {@link OAuth2Error} or a validated JSON object here and nowhere else,
- * so the guards sit next to the tests that pin them.
+ * Not part of the public API. The guarded request/response path the clients'
+ * calls to the authorization server (and `BffClient`'s session probe) share:
+ * deadline, redirect refusal, bounded read, JSON validation, and RFC 6749 §5.2
+ * error mapping to a typed {@link OAuth2Error}.
  *
  * @module
  */

package/esm/client/_http.js

@@ -1,11 +1,8 @@
 /**
- * The response ladder every {@link DirectClient} network call climbs: bounded
- * read, deadline, redirect refusal, JSON validation, RFC 6749 §5.2 error
- * mapping.
- *
- * Not part of the public API. The authorization server's bytes become either a
- * typed {@link OAuth2Error} or a validated JSON object here and nowhere else,
- * so the guards sit next to the tests that pin them.
+ * Not part of the public API. The guarded request/response path the clients'
+ * calls to the authorization server (and `BffClient`'s session probe) share:
+ * deadline, redirect refusal, bounded read, JSON validation, and RFC 6749 §5.2
+ * error mapping to a typed {@link OAuth2Error}.
  *
  * @module
  */
@@ -15,11 +12,6 @@ import { sanitizeProviderText } from "../utils/text.js";
 export const MAX_RESPONSE_BYTES = 64 * 1024;
 /** Wall-clock budget for one call, covering the connect and the body read. */
 export const REQUEST_TIMEOUT_MS = 10_000;
-/**
- * Maps an OAuth2 error code to the specific error class so callers can
- * `catch (e) { if (e instanceof InvalidGrantError) … }` instead of
- * inspecting `e.extensions.error` at every call site.
- */
 const ERROR_CLASS_BY_CODE = {
     access_denied: AccessDeniedError,
     authorization_pending: AuthorizationPendingError,
@@ -167,16 +159,6 @@ export function assertField(body, field, what) {
         throw new ServerError(`the ${what} returned a success response with no "${field}"`);
     }
 }
-/**
- * Reads up to {@link MAX_RESPONSE_BYTES} and reports whether more was coming.
- *
- * Never throws for being too large: on a **failed** response the bytes are the
- * only place the OAuth2 error code lives, and refusing to look would turn a
- * `invalid_grant` that happens to arrive oversized into a generic transport
- * error — which reads as "retry later" instead of "this grant is dead", so the
- * client would keep presenting a revoked refresh token forever. Truncation is
- * reported instead, and the success path refuses it.
- */
 async function readBounded(res) {
     if (!res.body)
         return { text: "", truncated: false };
@@ -235,11 +217,6 @@ function reportedError(value) {
             : undefined,
     };
 }
-/**
- * `status` is passed through only when it is a real error status: a server
- * that reports `error` inside a `200` still needs a throwable, and `HttpError`
- * refuses to carry a 2xx.
- */
 function buildError(reported, status) {
     const ErrorClass = ERROR_CLASS_BY_CODE[reported.error] ?? OAuth2ErrorClass;
     return new ErrorClass(reported.description ?? reported.error, {
@@ -251,16 +228,6 @@ function buildError(reported, status) {
         },
     });
 }
-/**
- * Recovers the `error` code from a body that did not parse.
- *
- * The realistic reason a failed token response is unparseable here is that the
- * cap cut it mid-string — a server padding `error_description`, or a proxy
- * appending a page of HTML. The code itself is short and near the front, and
- * losing it costs the caller the difference between "this grant is dead" and
- * "something went wrong", so it is worth one bounded scan. Restricted to the
- * lowercase-underscore shape RFC 6749 §5.2 defines, so nothing else matches.
- */
 function scanErrorCode(text) {
     const match = /"error"\s*:\s*"([a-z_]{1,64})"/.exec(text);
     return match ? { error: match[1] } : null;

package/esm/client/base.d.ts

@@ -42,12 +42,9 @@ export interface BaseOptions {
     fetch?: typeof fetch;
 }
 /**
- * The `login` options every client understands.
- *
- * Named apart from {@link LoginOptions} — which keeps the richer
- * `DirectClient` shape it has always had — so that a consumer importing
- * `LoginOptions` and passing `scope` still compiles. Reach for this one only
- * when writing against {@link OAuth2ClientBase}.
+ * The `login` options every client understands. Use it when writing against
+ * {@link OAuth2ClientBase}; `DirectClient.login` accepts the richer
+ * {@link LoginOptions}.
  */
 export interface BaseLoginOptions {
     /** Path or URL to return to after a successful login. */

package/esm/client/bff-client.d.ts

@@ -57,10 +57,11 @@ export interface BffClientOptions extends BaseOptions {
  * OAuth2 client for a browser app whose sessions live in a
  * Backend-for-Frontend.
  *
- * Every method here is a same-origin call to the BFF with `credentials:
- * "include"`, never a call to the authorization server. There is no token
- * storage, no PKCE, and no access token to read — if you need one, the app
- * wants a {@link DirectClient} instead.
+ * Nothing here calls the authorization server: the session probe and
+ * {@link BffClient.fetch} send `credentials: "include"` requests, and the login
+ * and logout methods only build BFF URLs. There is no token storage, no PKCE,
+ * and no access token to read — if you need one, the app wants a
+ * {@link DirectClient} instead.
  *
  * @example Same-origin BFF
  * ```ts
@@ -146,8 +147,8 @@ export declare class BffClient extends OAuth2ClientBase {
      * (an HTML error page from a misrouted path is the common one) all read as
      * signed out. A failure that was not simply "nobody is signed in" — anything
      * other than a `401` — also emits an `error` event so a UI can tell the two
-     * apart. The read is bounded and deadlined like every other call this
-     * package makes.
+     * apart. The probe is refused if the BFF answers with a redirect, and is
+     * bounded in size and time.
      *
      * Only `isAuthenticated: true` carries `user` / `sessionExpiresIn` /
      * `logoutUrl` through; an anonymous payload always reports them as `null`,

package/esm/client/bff-client.js

@@ -15,10 +15,11 @@ import { mergedHeaders, OAuth2ClientBase, SIGNED_OUT, } from "./base.js";
  * OAuth2 client for a browser app whose sessions live in a
  * Backend-for-Frontend.
  *
- * Every method here is a same-origin call to the BFF with `credentials:
- * "include"`, never a call to the authorization server. There is no token
- * storage, no PKCE, and no access token to read — if you need one, the app
- * wants a {@link DirectClient} instead.
+ * Nothing here calls the authorization server: the session probe and
+ * {@link BffClient.fetch} send `credentials: "include"` requests, and the login
+ * and logout methods only build BFF URLs. There is no token storage, no PKCE,
+ * and no access token to read — if you need one, the app wants a
+ * {@link DirectClient} instead.
  *
  * @example Same-origin BFF
  * ```ts
@@ -136,8 +137,8 @@ export class BffClient extends OAuth2ClientBase {
      * (an HTML error page from a misrouted path is the common one) all read as
      * signed out. A failure that was not simply "nobody is signed in" — anything
      * other than a `401` — also emits an `error` event so a UI can tell the two
-     * apart. The read is bounded and deadlined like every other call this
-     * package makes.
+     * apart. The probe is refused if the BFF answers with a redirect, and is
+     * bounded in size and time.
      *
      * Only `isAuthenticated: true` carries `user` / `sessionExpiresIn` /
      * `logoutUrl` through; an anonymous payload always reports them as `null`,

package/esm/client/browser-storage.d.ts

@@ -2,14 +2,10 @@
  * Browser-storage implementations of {@link RefreshTokenStorage} and
  * {@link AuthRequestStorage}.
  *
- * Both ship from the `@udibo/oauth2/client` subpath alongside the
- * `Memory*` defaults so non-React browser consumers (vanilla JS,
- * Vue, Svelte, …) can use them too.
- *
- * Both implementations are **SSR-safe**: if `window` / `indexedDB` /
- * `sessionStorage` is undefined at construction, the storage degrades
- * to a no-op (`get` returns `null`, `set`/`clear` do nothing). The
- * client constructs the real backing on first use in the browser.
+ * Both are **SSR-safe**: construction touches no browser API, and each method
+ * checks for `indexedDB` / `sessionStorage` when it runs. Where the API is
+ * missing the call is a no-op (`get` returns `null`, `set`/`clear` do
+ * nothing), so the same instance works once the code runs in a browser.
  *
  * @module
  */
@@ -32,17 +28,12 @@ export interface IndexedDBRefreshTokenStorageOptions {
 /**
  * Refresh token storage backed by IndexedDB.
  *
- * IndexedDB is preferred over `localStorage` because the latter is
- * synchronously readable from any script that runs in the document
- * (including injected XSS payloads). IndexedDB's same-origin guarantees
- * are similar but its async API and per-database isolation make
- * exfiltration somewhat harder. Combined with refresh-token rotation +
- * reuse detection on the authorization server, it's the recommended
- * default for a browser `DirectClient`.
- *
- * No `localStorage`-backed variant is shipped: it is synchronously
- * readable by any in-document script (including injected XSS), which
- * defeats the protection above.
+ * Keeps the refresh token across reloads without putting it in a cookie
+ * (sent with every request) or `localStorage`. It is stored in plain text and
+ * **is not a defense against XSS**: any script running on the origin can open
+ * the same database and read it. Pair it with refresh-token rotation and
+ * reuse detection on the authorization server, which limit how long a stolen
+ * token stays useful.
  *
  * Every instance needs a
  * {@link IndexedDBRefreshTokenStorageOptions.clientId} — the token is stored
@@ -77,25 +68,28 @@ export declare class IndexedDBRefreshTokenStorage implements RefreshTokenStorage
      */
     constructor(options: IndexedDBRefreshTokenStorageOptions);
     /**
-     * Returns the stored refresh token, or `null` when none is stored, when
-     * `indexedDB` is unavailable (SSR / non-browser), or when another tab is
-     * blocking the store's creation.
+     * Returns the stored refresh token, or `null` when none is stored or
+     * `indexedDB` is unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the read.
+     * @throws {DOMException} when IndexedDB rejects the read, or when another
+     * open connection (another tab) blocks the store's creation.
      */
     get(): Promise<string | null>;
     /**
-     * Persists {@linkcode value} as the refresh token. A no-op when `indexedDB`
-     * is unavailable (SSR / non-browser).
+     * Persists {@linkcode value} as the refresh token. A silent no-op when
+     * `indexedDB` is unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the write.
+     * @throws {DOMException} when IndexedDB rejects the write, or when another
+     * open connection (another tab) blocks the store's creation — the token was
+     * not persisted.
      */
     set(value: string): Promise<void>;
     /**
-     * Discards the stored refresh token. A no-op when `indexedDB` is unavailable
-     * (SSR / non-browser).
+     * Discards the stored refresh token. A silent no-op when `indexedDB` is
+     * unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the delete.
+     * @throws {DOMException} when IndexedDB rejects the delete, or when another
+     * open connection (another tab) blocks the store's creation.
      */
     clear(): Promise<void>;
 }
@@ -104,11 +98,10 @@ export interface SessionStorageAuthRequestStorageOptions {
     /** sessionStorage key prefix. Defaults to `"oauth2:auth-req:"`. */
     keyPrefix?: string;
     /**
-     * Maximum age of an auth request before it's treated as expired
-     * (epoch-ms). Reads of older entries return `null` and the entry is
-     * removed. Defaults to 10 minutes — long enough for a slow
-     * authorize-redirect round-trip, short enough that stale state from a
-     * previous abandoned login doesn't accumulate.
+     * Maximum age of an auth request before it's treated as expired, in ms.
+     * Reading an older entry returns `null` and removes it; an entry that is
+     * never read again stays until {@link SessionStorageAuthRequestStorage.clear}
+     * or the tab closes. Defaults to 10 minutes.
      */
     ttlMs?: number;
 }
@@ -133,6 +126,12 @@ export declare class SessionStorageAuthRequestStorage implements AuthRequestStor
      * unavailable (SSR / non-browser). Expired or unparseable entries are pruned.
      */
     get(state: string): AuthRequestRecord | null;
+    /**
+     * Returns the record for {@linkcode state} and removes it, under the same
+     * rules as {@link get}. `sessionStorage` is synchronous and confined to one
+     * tab, so the read and the removal cannot interleave with another caller.
+     */
+    take(state: string): AuthRequestRecord | null;
     /**
      * Stores {@linkcode value} under {@linkcode state}. A no-op when
      * `sessionStorage` is unavailable (SSR / non-browser).

package/esm/client/browser-storage.js

@@ -2,31 +2,22 @@
  * Browser-storage implementations of {@link RefreshTokenStorage} and
  * {@link AuthRequestStorage}.
  *
- * Both ship from the `@udibo/oauth2/client` subpath alongside the
- * `Memory*` defaults so non-React browser consumers (vanilla JS,
- * Vue, Svelte, …) can use them too.
- *
- * Both implementations are **SSR-safe**: if `window` / `indexedDB` /
- * `sessionStorage` is undefined at construction, the storage degrades
- * to a no-op (`get` returns `null`, `set`/`clear` do nothing). The
- * client constructs the real backing on first use in the browser.
+ * Both are **SSR-safe**: construction touches no browser API, and each method
+ * checks for `indexedDB` / `sessionStorage` when it runs. Where the API is
+ * missing the call is a no-op (`get` returns `null`, `set`/`clear` do
+ * nothing), so the same instance works once the code runs in a browser.
  *
  * @module
  */
 /**
  * Refresh token storage backed by IndexedDB.
  *
- * IndexedDB is preferred over `localStorage` because the latter is
- * synchronously readable from any script that runs in the document
- * (including injected XSS payloads). IndexedDB's same-origin guarantees
- * are similar but its async API and per-database isolation make
- * exfiltration somewhat harder. Combined with refresh-token rotation +
- * reuse detection on the authorization server, it's the recommended
- * default for a browser `DirectClient`.
- *
- * No `localStorage`-backed variant is shipped: it is synchronously
- * readable by any in-document script (including injected XSS), which
- * defeats the protection above.
+ * Keeps the refresh token across reloads without putting it in a cookie
+ * (sent with every request) or `localStorage`. It is stored in plain text and
+ * **is not a defense against XSS**: any script running on the origin can open
+ * the same database and read it. Pair it with refresh-token rotation and
+ * reuse detection on the authorization server, which limit how long a stolen
+ * token stays useful.
  *
  * Every instance needs a
  * {@link IndexedDBRefreshTokenStorageOptions.clientId} — the token is stored
@@ -71,11 +62,11 @@ export class IndexedDBRefreshTokenStorage {
         this.#key = options.clientId;
     }
     /**
-     * Returns the stored refresh token, or `null` when none is stored, when
-     * `indexedDB` is unavailable (SSR / non-browser), or when another tab is
-     * blocking the store's creation.
+     * Returns the stored refresh token, or `null` when none is stored or
+     * `indexedDB` is unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the read.
+     * @throws {DOMException} when IndexedDB rejects the read, or when another
+     * open connection (another tab) blocks the store's creation.
      */
     async get() {
         const db = await this.#openDb();
@@ -90,10 +81,12 @@ export class IndexedDBRefreshTokenStorage {
         });
     }
     /**
-     * Persists {@linkcode value} as the refresh token. A no-op when `indexedDB`
-     * is unavailable (SSR / non-browser).
+     * Persists {@linkcode value} as the refresh token. A silent no-op when
+     * `indexedDB` is unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the write.
+     * @throws {DOMException} when IndexedDB rejects the write, or when another
+     * open connection (another tab) blocks the store's creation — the token was
+     * not persisted.
      */
     async set(value) {
         const db = await this.#openDb();
@@ -110,10 +103,11 @@ export class IndexedDBRefreshTokenStorage {
         });
     }
     /**
-     * Discards the stored refresh token. A no-op when `indexedDB` is unavailable
-     * (SSR / non-browser).
+     * Discards the stored refresh token. A silent no-op when `indexedDB` is
+     * unavailable (SSR / non-browser).
      *
-     * @throws {DOMException} when IndexedDB rejects the delete.
+     * @throws {DOMException} when IndexedDB rejects the delete, or when another
+     * open connection (another tab) blocks the store's creation.
      */
     async clear() {
         const db = await this.#openDb();
@@ -133,7 +127,7 @@ export class IndexedDBRefreshTokenStorage {
         if (typeof indexedDB === "undefined")
             return null;
         const db = await this.#open();
-        if (!db || db.objectStoreNames.contains(this.#storeName))
+        if (db.objectStoreNames.contains(this.#storeName))
             return db;
         const nextVersion = db.version + 1;
         db.close();
@@ -150,9 +144,20 @@ export class IndexedDBRefreshTokenStorage {
                     db.createObjectStore(this.#storeName);
                 }
             };
-            req.onsuccess = () => resolve(req.result);
+            let blocked = false;
+            req.onsuccess = () => {
+                if (blocked)
+                    req.result.close();
+                else
+                    resolve(req.result);
+            };
             req.onerror = () => reject(req.error);
-            req.onblocked = () => resolve(null);
+            req.onblocked = () => {
+                blocked = true;
+                reject(new DOMException(`opening IndexedDB "${this.#databaseName}" to create its ` +
+                    `"${this.#storeName}" store was blocked by another open ` +
+                    `connection, such as another tab`, "InvalidStateError"));
+            };
         });
     }
 }
@@ -200,6 +205,16 @@ export class SessionStorageAuthRequestStorage {
             return null;
         }
     }
+    /**
+     * Returns the record for {@linkcode state} and removes it, under the same
+     * rules as {@link get}. `sessionStorage` is synchronous and confined to one
+     * tab, so the read and the removal cannot interleave with another caller.
+     */
+    take(state) {
+        const record = this.get(state);
+        this.delete(state);
+        return record;
+    }
     /**
      * Stores {@linkcode value} under {@linkcode state}. A no-op when
      * `sessionStorage` is unavailable (SSR / non-browser).

package/esm/client/check.d.ts

@@ -58,8 +58,11 @@ export interface CheckPermissionsOptions {
      */
     resource?: CheckResource;
     /**
-     * `fetch` implementation used to call the endpoint. Defaults to the global
-     * `fetch`; inject to add timeouts or stub the network in tests.
+     * `fetch` implementation used to call the endpoint, e.g. to stub the network
+     * in tests. Defaults to the global `fetch`. Whichever is used, the call runs
+     * under this package's deadline and response-size cap, and a redirect is
+     * refused rather than followed so the bearer token never reaches the host
+     * it names.
      */
     fetch?: typeof fetch;
 }
@@ -91,7 +94,11 @@ export interface CheckPermissionsResult {
  * tenant no longer resolves is a 404 and lands there too. Echoing an `org_id`
  * off a signed claim is how you meet it, because the organization can be
  * deleted after the signature, so catch it on that path rather than reading a
- * throw as a bug in your own setup.
+ * throw as a bug in your own setup. A redirect, or a `2xx` whose body is not a
+ * JSON object or exceeds the response-size cap, also throws
+ * {@linkcode ServerError}, and a request whose response headers do not
+ * arrive before the deadline throws {@linkcode TemporarilyUnavailableError}.
+ * The body's shape is not validated beyond being a JSON object.
  *
  * @example
  * ```ts