@udibo/oauth2 0.23.0 → 0.24.0

package/dist/adapters/hono/bff/bff.d.ts

@@ -327,7 +327,9 @@ export interface HonoBffOptions {
      * - A {@link SessionStore} over a database or cache every instance shares,
      *   for server-side revocation and back-channel logout. Implement
      *   `RefreshLockStore` (`withRefreshLock`) on it so instances refresh a
-     *   session one at a time, and check it with `runSessionStoreContractTests`.
+     *   session one at a time, pass each refresh a `RefreshLease` so a holder
+     *   whose lock expired cannot overwrite or end the session, and check it
+     *   with `runSessionStoreContractTests`.
      * - {@link MemorySessionStore} for a single process, tests and local
      *   development. A session it holds is unknown to every other instance, so
      *   behind a load balancer the user appears signed out.
@@ -681,7 +683,7 @@ export interface HonoBffOptions {
     /**
      * Resolves the per-request origin (scheme + host) used to build the
      * browser-facing authorize URL and `redirect_uri`. Lets ONE build-once BFF
-     * serve every deployment host (preview URLs, multi-tenant subdomains): the
+     * serve every deployment host (preview URLs, per-application subdomains): the
      * configured client's authorize/redirect paths are retargeted at this
      * origin per request. Return only allowlisted/trusted origins (never a raw
      * forged `Host`). When omitted, the client's configured origin is used.

package/dist/adapters/hono/bff/bff.js

@@ -1080,7 +1080,7 @@ export class HonoBff {
             return await this.#exchangeRefresh(entry);
         const { cookieValue } = entry;
         try {
-            return await store.withRefreshLock(cookieValue, async () => {
+            return await store.withRefreshLock(cookieValue, async (lease) => {
                 const current = await store.read(cookieValue);
                 if (!current)
                     return { status: "revoked" };
@@ -1090,28 +1090,31 @@ export class HonoBff {
                         entry: { cookieValue, data: current },
                     };
                 }
-                return await this.#exchangeRefresh({ cookieValue, data: current });
+                return await this.#exchangeRefresh({ cookieValue, data: current }, lease);
             });
         }
         catch {
             return { status: "unavailable" };
         }
     }
-    async #exchangeRefresh(entry) {
+    async #exchangeRefresh(entry, lease) {
         const { cookieValue, data } = entry;
-        if (!data.refreshToken)
+        const refreshToken = data.refreshToken;
+        if (!refreshToken)
             return { status: "unavailable" };
         try {
-            const result = await this.#client.exchangeRefreshToken(data.refreshToken);
+            const result = await this.#client.exchangeRefreshToken(refreshToken);
             const refreshed = {
                 tokens: result.tokens,
-                refreshToken: result.refreshToken ?? data.refreshToken,
+                refreshToken: result.refreshToken ?? refreshToken,
                 user: data.user,
                 sid: data.sid,
                 createdAt: data.createdAt,
                 updatedAt: Date.now(),
             };
-            const newCookieValue = await this.#store.update(cookieValue, refreshed);
+            const newCookieValue = lease
+                ? await lease.update(refreshed)
+                : await this.#store.update(cookieValue, refreshed);
             return {
                 status: "refreshed",
                 entry: { cookieValue: newCookieValue, data: refreshed },
@@ -1121,12 +1124,28 @@ export class HonoBff {
             if (!isRevokedGrant(error))
                 return { status: "unavailable" };
             const current = await this.#store.read(cookieValue);
-            if (current && current.refreshToken !== data.refreshToken) {
+            if (current && current.refreshToken !== refreshToken) {
                 return { status: "refreshed", entry: { cookieValue, data: current } };
             }
-            await this.#destroySession(cookieValue);
+            if (!lease) {
+                await this.#destroySession(cookieValue);
+                return { status: "revoked" };
+            }
+            if (current && !(await lease.destroy(refreshToken))) {
+                return await this.#afterRefusedDestroy(cookieValue, refreshToken);
+            }
+            await this.#rotatedCookies?.forget(cookieValue);
+            return { status: "revoked" };
+        }
+    }
+    async #afterRefusedDestroy(cookieValue, refreshToken) {
+        const current = await this.#store.read(cookieValue);
+        if (!current)
             return { status: "revoked" };
+        if (current.refreshToken !== refreshToken) {
+            return { status: "refreshed", entry: { cookieValue, data: current } };
         }
+        return { status: "unavailable" };
     }
     /**
      * Middleware that reads the session cookie, refreshes the access token

package/dist/adapters/hono/bff/mod.d.ts

@@ -21,4 +21,4 @@
 export { type BackchannelLogoutSubject, type BffCallbackError, HonoBff, type HonoBffBackchannelOptions, type HonoBffCookieOptions, type HonoBffCsrfOptions, type HonoBffOptions, type HonoBffPaths, type HonoBffResourceServer, } from "./bff.ts";
 export { type AuthRequestCookieOptions, type AuthRequestStorageFactory, EncryptedCookieAuthRequestStorage, encryptedCookieAuthRequestStorage, type EncryptedCookieAuthRequestStorageOptions, MemoryAuthRequestStorageFactory, } from "./auth-request-store.ts";
 export { DEFAULT_PROXY_FORWARD_HEADERS, type HonoBffProxyOptions, } from "./proxy.ts";
-export { type BackchannelLogoutStore, type BoundedSessionStore, DEFAULT_SESSION_MAX_AGE_MS, EncryptedCookieSessionStore, type EncryptedCookieSessionStoreOptions, MemorySessionStore, type RefreshLockStore, type SessionData, type SessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.ts";
+export { type BackchannelLogoutStore, type BoundedSessionStore, DEFAULT_SESSION_MAX_AGE_MS, EncryptedCookieSessionStore, type EncryptedCookieSessionStoreOptions, MemorySessionStore, type MemorySessionStoreOptions, type RefreshLease, type RefreshLockStore, type SessionData, type SessionStore, sessionStoreMaxAgeMs, supportsBackchannelLogout, } from "./session-store.ts";

package/dist/adapters/hono/bff/session-store.d.ts

@@ -101,19 +101,59 @@ export interface RefreshLockStore {
      *   seconds when its discovery cache is cold, since discovery tries two
      *   well-known paths and every request has a 10-second deadline. If the
      *   lock expires when its holder dies, expire it only after that plus the
-     *   store's own I/O, or renew the lease while it is held. A lock that
-     *   expires mid-refresh lets a second instance spend the same token.
+     *   store's own I/O, or renew it while `refresh` runs.
+     * - Pass `refresh` a {@link RefreshLease} for this call. The parameter is
+     *   optional only so stores written before it keep compiling. `HonoBff` writes
+     *   and destroys the session through it, so a holder that lost the lock
+     *   (it stalled past the expiry and another instance took it) can no
+     *   longer overwrite or end the session that instance refreshed. A store
+     *   that calls `refresh()` with no lease still works, but a lock that
+     *   expires mid-refresh then lets the former holder's write or sign-out
+     *   land on top of the new holder's.
      * - Reject when the lock cannot be acquired within a bound you choose.
      *   `HonoBff` then answers `502` `temporarily_unavailable` and keeps the
      *   session.
      *
-     * A Postgres store can hold `pg_advisory_xact_lock` on a hash of the session
-     * key in a transaction around `refresh`, with a `lock_timeout`. A Redis
-     * store can take a key with `SET NX PX` and wait for it with a deadline. Key
-     * the lock by the same digest the store keys its records by, never the raw
-     * cookie value, and include the tenant in a tenant-scoped store.
+     * Keep the lock beside the session record, so the lease's conditional
+     * write is one atomic compare-and-set on that record: for example a lease
+     * token and a lease expiry on the session row, taken by an update that
+     * matches only when no unexpired lease is set, and checked by the lease's
+     * `update` and `destroy`. Never hold a database transaction open across
+     * `refresh`: it spans a network call to the authorization server. Key the
+     * lock by the same key the store keys its records by — the digest, never
+     * the raw cookie value, plus any prefix or scope the store adds to it.
      */
-    withRefreshLock<T>(cookieValue: string, refresh: () => Promise<T>): Promise<T>;
+    withRefreshLock<T>(cookieValue: string, refresh: (lease?: RefreshLease) => Promise<T>): Promise<T>;
+}
+/**
+ * The fence a {@link RefreshLockStore} passes to the refresh it runs: an
+ * `update` and a `destroy` of the locked session that take effect only while
+ * this call still holds the lock. The lease is current from when the call
+ * acquires the lock until the call releases the lock or another call takes
+ * it; a store may also end it when the lock expires. Once another call has
+ * taken the lock, the lease is never current again.
+ */
+export interface RefreshLease {
+    /**
+     * Writes the locked session like {@link SessionStore.update}, as one atomic
+     * step that also checks this lease is current. Resolves with the cookie
+     * value to set.
+     *
+     * @throws {InvalidGrantError} When the lease is no longer current, or the
+     * session is missing, expired or revoked. It never creates or restores a
+     * session.
+     */
+    update(data: SessionData): Promise<string>;
+    /**
+     * Destroys the locked session, as one atomic step, only while this lease
+     * is current and the session still stores `refreshToken`. `HonoBff` calls
+     * it after the authorization server refuses that refresh token.
+     *
+     * @returns `true` when it destroyed the session; `false` when it destroyed
+     * nothing, because the lease is no longer current, the session stores a
+     * different refresh token, or the session no longer exists.
+     */
+    destroy(refreshToken: string): Promise<boolean>;
 }
 /** Whether a store implements the {@link RefreshLockStore} capability. */
 export declare function supportsRefreshLock(store: SessionStore): store is SessionStore & RefreshLockStore;
@@ -172,6 +212,30 @@ export interface SessionStore {
     /** Destroy the session identified by `cookieValue`. */
     destroy(cookieValue: string): Promise<void>;
 }
+/** Options for {@link MemorySessionStore}. */
+export interface MemorySessionStoreOptions {
+    /**
+     * How long a `withRefreshLock` call holds the lock without renewing it, in
+     * milliseconds. The store renews it every third of this while the refresh
+     * runs. A lease that still lapses, because its holder's timers were
+     * starved, is lost at once: another call may take the lock, and the lost
+     * lease's `update` and `destroy` are refused.
+     *
+     * Defaults to no expiry, which is right for one process: a holder cannot
+     * die without the store dying with it. Set it in tests that model an
+     * instance losing its lock mid-refresh. Must be a positive number no
+     * larger than 2147483647 (2^31 − 1, the longest timer delay).
+     */
+    refreshLeaseMs?: number;
+    /**
+     * How long `withRefreshLock` waits for a lock another call holds, in
+     * milliseconds, before it rejects. `HonoBff` then answers `502` and keeps
+     * the session. Defaults to waiting until the lock is released or expires.
+     * Must be a positive number no larger than 2147483647 (2^31 − 1, the
+     * longest timer delay).
+     */
+    refreshLockWaitMs?: number;
+}
 /**
  * In-memory stateful session store. Data is lost when the process
  * restarts. Suitable for single-process development or tests; use a
@@ -179,6 +243,11 @@ export interface SessionStore {
  */
 export declare class MemorySessionStore implements SessionStore, BackchannelLogoutStore, RefreshLockStore {
     #private;
+    /**
+     * @throws {RangeError} When `refreshLeaseMs` or `refreshLockWaitMs` is not
+     * a positive number of at most 2^31 − 1 milliseconds.
+     */
+    constructor(options?: MemorySessionStoreOptions);
     /** Stores the session under a fresh random id and returns it as the cookie value. */
     create(data: SessionData): Promise<string>;
     /** Looks up the session by its id, or `null` if no live session matches. */
@@ -188,11 +257,15 @@ export declare class MemorySessionStore implements SessionStore, BackchannelLogo
     /** Removes the session record for the given id. */
     destroy(cookieValue: string): Promise<void>;
     /**
-     * Runs `refresh` once every earlier call for the same session has settled,
-     * so every `HonoBff` sharing this store object refreshes a session once.
-     * Calls for other sessions run alongside.
+     * Runs `refresh` once no other call holds the session's lock, so every
+     * `HonoBff` sharing this store object refreshes a session once. Calls for
+     * other sessions run alongside. `refresh` gets a {@link RefreshLease} that
+     * writes and destroys the session only while this call holds the lock.
+     *
+     * @throws {Error} When the lock stays held past
+     * {@linkcode MemorySessionStoreOptions.refreshLockWaitMs}.
      */
-    withRefreshLock<T>(cookieValue: string, refresh: () => Promise<T>): Promise<T>;
+    withRefreshLock<T>(cookieValue: string, refresh: (lease: RefreshLease) => Promise<T>): Promise<T>;
     /**
      * Destroys the sessions a validated logout_token targets: the specific `sid`
      * when given, otherwise every session for `sub`. Returns the number

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

@@ -55,6 +55,16 @@ export function sessionStoreMaxAgeMs(store) {
         ? maxAgeMs
         : undefined;
 }
+const MAX_TIMER_MS = 2 ** 31 - 1;
+function timerMs(name, value) {
+    if (value === undefined)
+        return Infinity;
+    if (!(value > 0 && value <= MAX_TIMER_MS)) {
+        throw new RangeError(`${name} must be a positive number of milliseconds no larger than ` +
+            `${MAX_TIMER_MS}, got ${value}. Leave it unset for no limit.`);
+    }
+    return value;
+}
 /**
  * In-memory stateful session store. Data is lost when the process
  * restarts. Suitable for single-process development or tests; use a
@@ -62,7 +72,18 @@ export function sessionStoreMaxAgeMs(store) {
  */
 export class MemorySessionStore {
     #sessions = new Map();
-    #refreshLocks = new Map();
+    #leases = new Map();
+    #lockWaiters = new Map();
+    #leaseMs;
+    #lockWaitMs;
+    /**
+     * @throws {RangeError} When `refreshLeaseMs` or `refreshLockWaitMs` is not
+     * a positive number of at most 2^31 − 1 milliseconds.
+     */
+    constructor(options = {}) {
+        this.#leaseMs = timerMs("refreshLeaseMs", options.refreshLeaseMs);
+        this.#lockWaitMs = timerMs("refreshLockWaitMs", options.refreshLockWaitMs);
+    }
     /** Stores the session under a fresh random id and returns it as the cookie value. */
     create(data) {
         const id = crypto.randomUUID();
@@ -87,24 +108,97 @@ export class MemorySessionStore {
         return Promise.resolve();
     }
     /**
-     * Runs `refresh` once every earlier call for the same session has settled,
-     * so every `HonoBff` sharing this store object refreshes a session once.
-     * Calls for other sessions run alongside.
+     * Runs `refresh` once no other call holds the session's lock, so every
+     * `HonoBff` sharing this store object refreshes a session once. Calls for
+     * other sessions run alongside. `refresh` gets a {@link RefreshLease} that
+     * writes and destroys the session only while this call holds the lock.
+     *
+     * @throws {Error} When the lock stays held past
+     * {@linkcode MemorySessionStoreOptions.refreshLockWaitMs}.
      */
     async withRefreshLock(cookieValue, refresh) {
-        const previous = this.#refreshLocks.get(cookieValue) ?? Promise.resolve();
-        const run = previous.then(refresh);
-        const released = run.then(() => undefined, () => undefined);
-        this.#refreshLocks.set(cookieValue, released);
+        const lease = await this.#acquire(cookieValue);
+        const renewal = Number.isFinite(this.#leaseMs)
+            ? setInterval(() => {
+                if (this.#holds(cookieValue, lease)) {
+                    lease.expiresAt = Date.now() + this.#leaseMs;
+                }
+                else {
+                    clearInterval(renewal);
+                }
+            }, this.#leaseMs / 3)
+            : undefined;
         try {
-            return await run;
+            return await refresh(this.#fence(cookieValue, lease));
         }
         finally {
-            if (this.#refreshLocks.get(cookieValue) === released) {
-                this.#refreshLocks.delete(cookieValue);
+            clearInterval(renewal);
+            if (this.#leases.get(cookieValue) === lease) {
+                this.#leases.delete(cookieValue);
+            }
+            this.#wakeLockWaiters(cookieValue);
+        }
+    }
+    async #acquire(cookieValue) {
+        const deadline = Date.now() + this.#lockWaitMs;
+        for (;;) {
+            const now = Date.now();
+            const held = this.#leases.get(cookieValue);
+            if (!held || held.expiresAt <= now) {
+                const lease = { expiresAt: now + this.#leaseMs };
+                this.#leases.set(cookieValue, lease);
+                return lease;
+            }
+            if (now >= deadline) {
+                throw new Error("timed out waiting for the session's refresh lock");
+            }
+            await this.#lockChange(cookieValue, Math.min(held.expiresAt, deadline) - now);
+        }
+    }
+    #lockChange(cookieValue, timeoutMs) {
+        const { promise, resolve } = Promise.withResolvers();
+        const waiters = this.#lockWaiters.get(cookieValue) ?? new Set();
+        this.#lockWaiters.set(cookieValue, waiters);
+        let timer;
+        const wake = () => {
+            clearTimeout(timer);
+            waiters.delete(wake);
+            if (waiters.size === 0 &&
+                this.#lockWaiters.get(cookieValue) === waiters) {
+                this.#lockWaiters.delete(cookieValue);
             }
+            resolve();
+        };
+        waiters.add(wake);
+        if (Number.isFinite(timeoutMs))
+            timer = setTimeout(wake, timeoutMs);
+        return promise;
+    }
+    #wakeLockWaiters(cookieValue) {
+        for (const wake of [...(this.#lockWaiters.get(cookieValue) ?? [])]) {
+            wake();
         }
     }
+    #holds(cookieValue, lease) {
+        return (this.#leases.get(cookieValue) === lease && lease.expiresAt > Date.now());
+    }
+    #fence(cookieValue, lease) {
+        return {
+            update: (data) => this.#holds(cookieValue, lease)
+                ? this.update(cookieValue, data)
+                : Promise.reject(new InvalidGrantError("the session's refresh lock was lost")),
+            destroy: (refreshToken) => {
+                const session = this.#sessions.get(cookieValue);
+                if (!session ||
+                    session.refreshToken !== refreshToken ||
+                    !this.#holds(cookieValue, lease)) {
+                    return Promise.resolve(false);
+                }
+                this.#sessions.delete(cookieValue);
+                return Promise.resolve(true);
+            },
+        };
+    }
     /**
      * Destroys the sessions a validated logout_token targets: the specific `sid`
      * when given, otherwise every session for `sub`. Returns the number

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

@@ -174,8 +174,12 @@ export interface SessionStoreContractOptions {
  * requires — test that yourself.
  *
  * A store that implements `withRefreshLock` ({@link RefreshLockStore}) also
- * runs the lock checks; they are skipped for a store without it. They use one
- * store object, so they prove the lock's behavior, not that separate
+ * runs the lock checks; they are skipped for a store without it. The lease
+ * checks ({@link RefreshLease}) are skipped for a store whose
+ * `withRefreshLock` passes no lease. They prove that a lease stops acting once
+ * its call releases the lock or another call holds it, not that it stops
+ * when the lock expires: expire a lease in a test of your own for that. They
+ * use one store object, so they prove the lock's behavior, not that separate
  * instances share it: point two store objects at one backend in a test of
  * your own for that.
  */

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

@@ -17,6 +17,7 @@
  */
 import { assert, beforeEach, describe, expect, it } from "vitest";
 import { delay } from "../../../utils/_delay.js";
+import { InvalidGrantError } from "../../../errors.js";
 import { sessionStoreMaxAgeMs, supportsRefreshLock, } from "./session-store.js";
 /**
  * Seeds a session in `bff.sessionStore` and returns a `Cookie` header
@@ -184,6 +185,16 @@ async function settlesWithin(promise, message) {
         timer.abort();
     }
 }
+function required(lease) {
+    assert(lease !== undefined, "withRefreshLock passed a lease to one refresh and none to another");
+    return lease;
+}
+async function rejection(promise) {
+    const fulfilled = Symbol("fulfilled");
+    const outcome = await promise.then(() => fulfilled, (error) => error);
+    assert(outcome !== fulfilled, "expected the lease to refuse");
+    return outcome;
+}
 /**
  * Contract test suite for {@link SessionStore} implementations. Registers
  * `describe`/`it` blocks from Vitest, so call it at a test
@@ -192,8 +203,12 @@ async function settlesWithin(promise, message) {
  * requires — test that yourself.
  *
  * A store that implements `withRefreshLock` ({@link RefreshLockStore}) also
- * runs the lock checks; they are skipped for a store without it. They use one
- * store object, so they prove the lock's behavior, not that separate
+ * runs the lock checks; they are skipped for a store without it. The lease
+ * checks ({@link RefreshLease}) are skipped for a store whose
+ * `withRefreshLock` passes no lease. They prove that a lease stops acting once
+ * its call releases the lock or another call holds it, not that it stops
+ * when the lock expires: expire a lease in a test of your own for that. They
+ * use one store object, so they prove the lock's behavior, not that separate
  * instances share it: point two store objects at one backend in a test of
  * your own for that.
  */
@@ -358,6 +373,85 @@ export function runSessionStoreContractTests(options) {
             expect(await settlesWithin(locking.withRefreshLock(value, () => Promise.resolve("next")), "a refresh that threw kept the lock, so the session can never " +
                 "refresh again")).toBe("next");
         });
+        async function leaseOf(locking, value, skip) {
+            const lease = await locking.withRefreshLock(value, (given) => Promise.resolve(given));
+            skip(lease === undefined, "withRefreshLock passes the refresh no lease, so a holder that lost " +
+                "the lock can still write and destroy the session");
+            return required(lease);
+        }
+        function refreshedSession() {
+            return {
+                ...sampleSession(),
+                tokens: { ...sampleSession().tokens, accessToken: "access-2" },
+                refreshToken: "refresh-2",
+            };
+        }
+        it("withRefreshLock passes a lease that writes the session while the lock is held", async ({ skip, }) => {
+            const locking = lockStore(skip);
+            const value = await locking.create(sampleSession());
+            await leaseOf(locking, value, skip);
+            const next = await settlesWithin(locking.withRefreshLock(value, (lease) => required(lease).update(refreshedSession())), "a lease's update blocked on the lock its own call holds");
+            const fetched = await locking.read(next);
+            expect(fetched?.refreshToken).toBe("refresh-2");
+        });
+        it("withRefreshLock's lease refuses to write or destroy once its call has settled", async ({ skip, }) => {
+            const locking = lockStore(skip);
+            const value = await locking.create(sampleSession());
+            const former = await leaseOf(locking, value, skip);
+            const error = await rejection(former.update(refreshedSession()));
+            expect(error, "a holder whose lock was released wrote the session, so a holder " +
+                "that stalled past its lock would overwrite the next holder's refresh").toBeInstanceOf(InvalidGrantError);
+            expect(await former.destroy("refresh-1"), "a holder whose lock was released destroyed the session").toBe(false);
+            expect((await locking.read(value))?.refreshToken).toBe("refresh-1");
+        });
+        it("withRefreshLock's lease cannot act while a later call holds the lock", async ({ skip, }) => {
+            const locking = lockStore(skip);
+            const value = await locking.create(sampleSession());
+            const former = await leaseOf(locking, value, skip);
+            const holding = Promise.withResolvers();
+            const releaseHolder = Promise.withResolvers();
+            const holder = locking.withRefreshLock(value, async (given) => {
+                const lease = required(given);
+                holding.resolve(lease);
+                await releaseHolder.promise;
+                return await lease.update(refreshedSession());
+            });
+            await settlesWithin(holding.promise, "the second call never took the lock");
+            const refusedWrite = await rejection(former.update(sampleSession()));
+            const refusedDestroy = await former.destroy("refresh-1");
+            releaseHolder.resolve();
+            await holder;
+            expect(refusedWrite).toBeInstanceOf(InvalidGrantError);
+            expect(refusedDestroy).toBe(false);
+            expect((await locking.read(value))?.refreshToken, "the current holder's write must stand").toBe("refresh-2");
+        });
+        it("withRefreshLock's lease destroys the session only while it stores the given refresh token", async ({ skip, }) => {
+            const locking = lockStore(skip);
+            const value = await locking.create(sampleSession());
+            await leaseOf(locking, value, skip);
+            const results = await locking.withRefreshLock(value, async (given) => {
+                const lease = required(given);
+                return [
+                    await lease.destroy("refresh-0"),
+                    (await locking.read(value)) !== null,
+                    await lease.destroy("refresh-1"),
+                ];
+            });
+            expect(results, "a destroy for a refresh token the session no longer stores would end " +
+                "a session a peer has just refreshed").toStrictEqual([false, true, true]);
+            expect(await locking.read(value)).toBe(null);
+        });
+        it("withRefreshLock's lease never restores a destroyed session", async ({ skip, }) => {
+            const locking = lockStore(skip);
+            const value = await locking.create(sampleSession());
+            await leaseOf(locking, value, skip);
+            const error = await locking.withRefreshLock(value, async (lease) => {
+                await locking.destroy(value);
+                return await rejection(required(lease).update(refreshedSession()));
+            });
+            expect(error).toBeInstanceOf(InvalidGrantError);
+            expect(await locking.read(value)).toBe(null);
+        });
         if (makeBoundedStore) {
             it("reports the max age it was built with, so a BFF can outlive it", async () => {
                 const bounded = await makeBoundedStore(BOUND_MS);

package/dist/client/direct-client.d.ts

@@ -129,7 +129,7 @@ export interface LoginOptions extends BaseLoginOptions {
      * Override the origin (scheme + host) of the authorize endpoint and the
      * `redirect_uri` for THIS call, keeping their configured paths. Lets one
      * build-once client serve multiple deployment origins (preview URLs,
-     * multi-tenant subdomains) — e.g. the Hono BFF passes the trusted request
+     * per-application subdomains) — e.g. the Hono BFF passes the trusted request
      * origin so sign-in works on whichever host the request arrived at. The
      * callback returns to the same origin, so the matching `exchange` call is
      * given the same origin.
@@ -139,7 +139,7 @@ export interface LoginOptions extends BaseLoginOptions {
      * Store the pending authorization request here instead of in the client's
      * configured `authRequestStorage`, for THIS call. Lets a server bind the
      * record to the request it belongs to — a per-request cookie store, or a
-     * per-tenant table — rather than sharing one process-wide store. The
+     * per-application table — rather than sharing one process-wide store. The
      * matching `exchangeAuthorizationCode` call MUST be given a storage that
      * can read the record back.
      */

package/dist/client/discovery-cache.d.ts

@@ -44,7 +44,7 @@ export interface DiscoveryCacheEntry {
  * collapse concurrent misses into one `load` call — a get/set pair cannot.
  *
  * Metadata is issuer-scoped and public: it carries no client id, secret, or
- * tenant data, so one cache may serve many tenants pointed at the same issuer.
+ * user data, so one cache may serve many clients pointed at the same issuer.
  * Do share a cache across clients that reach an issuer the same way; do not
  * share one between a stubbed transport and live traffic.
  *
@@ -90,8 +90,8 @@ export interface MemoryDiscoveryCacheOptions {
     /**
      * Maximum number of issuers held. Defaults to
      * {@link DEFAULT_DISCOVERY_CACHE_MAX_ENTRIES}. Expired entries are dropped
-     * first, then the least recently used, so a multi-tenant server with an
-     * unbounded issuer list cannot grow without limit.
+     * first, then the least recently used, so a server that reaches an
+     * unbounded list of issuers cannot grow without limit.
      */
     maxEntries?: number;
 }

package/dist/identity/captcha.d.ts

@@ -118,8 +118,8 @@ export interface VerifyCaptchaOptions {
      * What to do when the provider throws (an outage). `true` (the default)
      * fails open — the request passes with `degraded: true` — so a provider
      * outage falls back to your rate-limit/lockout floor instead of blocking
-     * every user. `false` fails closed for a tenant that would rather refuse than
-     * degrade.
+     * every user. `false` fails closed for a deployment that would rather refuse
+     * than degrade.
      */
     failOpen?: boolean;
 }

package/dist/models/authorization.d.ts

@@ -47,7 +47,7 @@ export interface RequireConditions {
     scope?: string | string[];
     /** Permission(s) the subject must hold ({@link Authorization.can}). */
     permission?: string | string[];
-    /** Tenant-wide role(s) the subject must hold ({@link Authorization.hasRole}). */
+    /** Issuer-wide role(s) the subject must hold ({@link Authorization.hasRole}). */
     role?: string | string[];
     /**
      * Role(s) the subject must hold in the active organization
@@ -78,9 +78,9 @@ export interface AuthorizationFailure {
 export interface AuthorizationInit {
     /** The scope granted to the client, when known. */
     scope?: AbstractScope | null;
-    /** Tenant-wide role slugs the subject holds. */
+    /** Issuer-wide role slugs the subject holds, outside any organization. */
     roles?: Iterable<string>;
-    /** Permissions the subject holds (tenant-level plus the active organization's). */
+    /** Permissions the subject holds (issuer-wide plus the active organization's). */
     permissions?: Iterable<string>;
     /** The active organization context, when the credential carries one. */
     organization?: OrganizationContext | null;
@@ -111,7 +111,7 @@ export interface AuthorizationInit {
 export declare class Authorization {
     /** The scope granted to the client, or `null` when unknown. */
     readonly scope: AbstractScope | null;
-    /** Tenant-wide role slugs the subject holds. */
+    /** Issuer-wide role slugs the subject holds, outside any organization. */
     readonly roles: ReadonlySet<string>;
     /** Permissions the subject holds in the credential's scope of issue. */
     readonly permissions: ReadonlySet<string>;
@@ -130,7 +130,7 @@ export declare class Authorization {
      * permission is the contract, role names are presentation.
      */
     can(permission: string): boolean;
-    /** Whether the subject holds the tenant-wide role `role`. */
+    /** Whether the subject holds the issuer-wide role `role`. */
     hasRole(role: string): boolean;
     /** Whether the subject holds `role` in the active organization. */
     hasOrgRole(role: string): boolean;

package/dist/models/authorization.js

@@ -42,7 +42,7 @@
 export class Authorization {
     /** The scope granted to the client, or `null` when unknown. */
     scope;
-    /** Tenant-wide role slugs the subject holds. */
+    /** Issuer-wide role slugs the subject holds, outside any organization. */
     roles;
     /** Permissions the subject holds in the credential's scope of issue. */
     permissions;
@@ -70,7 +70,7 @@ export class Authorization {
     can(permission) {
         return this.permissions.has(permission);
     }
-    /** Whether the subject holds the tenant-wide role `role`. */
+    /** Whether the subject holds the issuer-wide role `role`. */
     hasRole(role) {
         return this.roles.has(role);
     }

package/dist/models/client.d.ts

@@ -11,7 +11,7 @@
  * interface MyClient extends ClientInterface {
  *   name: string;
  *   confidential: boolean;
- *   tenantId: string;
+ *   logoUri: string;
  * }
  * ```
  */

package/dist/react/components/class-names.d.ts

@@ -32,12 +32,12 @@ import type { AuthFormClassNames } from "./types.ts";
  *
  * @example Theme a custom field to match the form around it
  * ```tsx
- * function TenantField(props: { fieldProps: AuthFieldProps }) {
+ * function InviteCodeField(props: { fieldProps: AuthFieldProps }) {
  *   const classNames = useAuthFormClassNames();
  *   return (
  *     <div className={classNames.field}>
  *       <label className={classNames.label} htmlFor={props.fieldProps.id}>
- *         Tenant
+ *         Invite code
  *       </label>
  *       <input {...props.fieldProps} className={classNames.input} />
  *     </div>

package/dist/react/components/class-names.js

@@ -49,12 +49,12 @@ function slotKey(classNames) {
  *
  * @example Theme a custom field to match the form around it
  * ```tsx
- * function TenantField(props: { fieldProps: AuthFieldProps }) {
+ * function InviteCodeField(props: { fieldProps: AuthFieldProps }) {
  *   const classNames = useAuthFormClassNames();
  *   return (
  *     <div className={classNames.field}>
  *       <label className={classNames.label} htmlFor={props.fieldProps.id}>
- *         Tenant
+ *         Invite code
  *       </label>
  *       <input {...props.fieldProps} className={classNames.input} />
  *     </div>

package/dist/server/authorization-server.d.ts

@@ -9,12 +9,13 @@
  * - Server metadata (RFC 8414)
  * - Device authorization (RFC 8628)
  *
- * **Configuration.** A single instance serves every tenant/origin. The only
- * configuration seam is `resolve(request)`, which returns the services the
- * server's own endpoints need (`{ clientService, tokenService }`) plus the
- * issuer/endpoints. Each grant resolves its own services independently. For a
- * single-tenant server, `resolve` is a constant function (create the services
- * once, outside it, and return them every time).
+ * **Configuration.** The only configuration seam is `resolve(request)`, which
+ * returns the per-request configuration: the services the server's own
+ * endpoints need (`{ clientService, tokenService }`) plus the issuer and
+ * endpoint URLs. Because it runs per request, one server can serve the origins
+ * or applications a business operates. Each grant resolves its own services
+ * independently. For a single deployment, `resolve` is a constant function
+ * (create the services once, outside it, and return them every time).
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749
  * @module
@@ -161,9 +162,11 @@ export interface AuthorizationServerContext<Client extends ClientInterface, User
  */
 export interface AuthorizationServerOptions<Client extends ClientInterface, User, S extends AbstractScope> extends Omit<ResourceServerOptions<Client, User, S>, "resolve"> {
     /**
-     * Resolves the per-request context — the server's own services plus the
-     * issuer/endpoints. This is the only services seam: for a single-tenant
-     * server it is a constant function returning the same context every time.
+     * Resolves the per-request configuration — the server's own services plus
+     * the issuer and endpoint URLs — so one server can serve the origins or
+     * applications a business operates. This is the only services seam: for a
+     * single deployment it is a constant function returning the same context
+     * every time.
      */
     resolve: (request: Request) => AuthorizationServerContext<Client, User, S> | Promise<AuthorizationServerContext<Client, User, S>>;
     /** Grants the server supports, keyed by `grant_type` (each key must equal `grant.grantType`). */
@@ -406,8 +409,8 @@ export declare const ENDPOINT_METHODS: Readonly<Record<EndpointKey, readonly str
  * Framework-agnostic: each `handle*Request` method takes a web `Request` and
  * returns a `Response`, so an adapter routes its endpoints to them. Extends
  * {@linkcode ResourceServer}, so the same instance also validates bearer
- * tokens. A single instance serves every tenant/origin via the `resolve`
- * callback in {@linkcode AuthorizationServerOptions}.
+ * tokens. Its issuer, endpoint URLs and services come per request from the
+ * `resolve` callback in {@linkcode AuthorizationServerOptions}.
  *
  * The handlers throw {@linkcode HttpError} subclasses on failure (e.g.
  * {@linkcode InvalidRequestError}, {@linkcode InvalidClientError},

package/dist/server/authorization-server.js

@@ -9,12 +9,13 @@
  * - Server metadata (RFC 8414)
  * - Device authorization (RFC 8628)
  *
- * **Configuration.** A single instance serves every tenant/origin. The only
- * configuration seam is `resolve(request)`, which returns the services the
- * server's own endpoints need (`{ clientService, tokenService }`) plus the
- * issuer/endpoints. Each grant resolves its own services independently. For a
- * single-tenant server, `resolve` is a constant function (create the services
- * once, outside it, and return them every time).
+ * **Configuration.** The only configuration seam is `resolve(request)`, which
+ * returns the per-request configuration: the services the server's own
+ * endpoints need (`{ clientService, tokenService }`) plus the issuer and
+ * endpoint URLs. Because it runs per request, one server can serve the origins
+ * or applications a business operates. Each grant resolves its own services
+ * independently. For a single deployment, `resolve` is a constant function
+ * (create the services once, outside it, and return them every time).
  *
  * @see https://datatracker.ietf.org/doc/html/rfc6749
  * @module
@@ -154,8 +155,8 @@ function isDeviceAuthorizationGrant(grant) {
  * Framework-agnostic: each `handle*Request` method takes a web `Request` and
  * returns a `Response`, so an adapter routes its endpoints to them. Extends
  * {@linkcode ResourceServer}, so the same instance also validates bearer
- * tokens. A single instance serves every tenant/origin via the `resolve`
- * callback in {@linkcode AuthorizationServerOptions}.
+ * tokens. Its issuer, endpoint URLs and services come per request from the
+ * `resolve` callback in {@linkcode AuthorizationServerOptions}.
  *
  * The handlers throw {@linkcode HttpError} subclasses on failure (e.g.
  * {@linkcode InvalidRequestError}, {@linkcode InvalidClientError},

package/dist/server/resource-server.d.ts

@@ -22,17 +22,18 @@ export interface ResourceServerServices<Client extends ClientInterface, User, S
 }
 /** Per-request context resolved by a {@link ResourceServer}. */
 export interface ResourceServerContext<Client extends ClientInterface, User, S extends AbstractScope> {
-    /** Tenant-scoped services to use for this request. */
+    /** The services to use for this request. */
     services: ResourceServerServices<Client, User, S>;
 }
 /** Options for configuring the resource server. */
 export interface ResourceServerOptions<Client extends ClientInterface, User, S extends AbstractScope> {
     /**
-     * Resolves the per-request context — the (e.g. tenant-scoped) {@link
-     * ResourceServerServices} for THIS request — so a single instance serves
-     * every tenant/origin. This is the only services seam: for a single-tenant
-     * server it is a constant function returning the same services every time
-     * (create the services once, outside `resolve`, and return them here).
+     * Resolves the per-request configuration — the {@link
+     * ResourceServerServices} for THIS request — so one server can serve the
+     * origins or applications a business operates. This is the only services
+     * seam: for a single deployment it is a constant function returning the
+     * same services every time (create the services once, outside `resolve`,
+     * and return them here).
      */
     resolve: (request: Request) => ResourceServerContext<Client, User, S> | Promise<ResourceServerContext<Client, User, S>>;
     /** Scope constructor used to parse and compare scopes. Defaults to {@linkcode BasicScope}. */
@@ -133,10 +134,9 @@ export interface AuthenticatedContext<Client extends ClientInterface, User, S ex
  * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
  * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
  *
- * A single instance serves every tenant/origin; per-request services come from
- * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
- * single-tenant server, `resolve` is a constant function returning the same
- * services every time.
+ * Per-request services come from the `resolve` callback in
+ * {@linkcode ResourceServerOptions}. For a single deployment, `resolve` is a
+ * constant function returning the same services every time.
  *
  * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
  * ({@linkcode AccessDeniedError} when no token is sent,

package/dist/server/resource-server.js

@@ -31,10 +31,9 @@ const CHALLENGE_ERROR_CODES = new Set([
  * authentication. Framework-agnostic: it works on web `Request`/`Response`, so
  * an adapter (Hono, etc.) wires {@linkcode authenticate} into its middleware.
  *
- * A single instance serves every tenant/origin; per-request services come from
- * the `resolve` callback in {@linkcode ResourceServerOptions}. For a
- * single-tenant server, `resolve` is a constant function returning the same
- * services every time.
+ * Per-request services come from the `resolve` callback in
+ * {@linkcode ResourceServerOptions}. For a single deployment, `resolve` is a
+ * constant function returning the same services every time.
  *
  * {@linkcode authenticate} throws {@linkcode HttpError} subclasses on failure
  * ({@linkcode AccessDeniedError} when no token is sent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "A flexible OAuth2 toolkit: framework-agnostic authorization & resource servers, a typed client, Hono adapters (including a backend-for-frontend), and React bindings.",
   "keywords": [
     "authorization-server",