@udibo/oauth2 0.21.2 → 0.22.0

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

@@ -26,6 +26,12 @@ export interface HonoResourceServerVariables<Client extends ClientInterface, Use
     /** The authenticated OAuth2 context set by the protect middleware. */
     [OAUTH2_CONTEXT_KEY]: AuthenticatedContext<Client, User, S>;
 }
+/**
+ * Answers with `response` while keeping the headers earlier middleware set on
+ * `c`, such as the `Set-Cookie` a BFF sets when a refresh rotates or ends the
+ * session. A middleware returning a bare `Response` would drop them.
+ */
+export declare function respondInContext(c: Context, response: Response): Response;
 /**
  * Builds a Hono middleware that authenticates bearer tokens, stores the
  * authenticated context at {@link OAUTH2_CONTEXT_KEY}, and on failure returns

package/dist/adapters/hono/_common.js

@@ -13,6 +13,14 @@ import { ResourceServer } from "../../server/resource-server.js";
  * context. Namespaced to avoid collisions with other middleware.
  */
 export const OAUTH2_CONTEXT_KEY = "@udibo/oauth2";
+/**
+ * Answers with `response` while keeping the headers earlier middleware set on
+ * `c`, such as the `Set-Cookie` a BFF sets when a refresh rotates or ends the
+ * session. A middleware returning a bare `Response` would drop them.
+ */
+export function respondInContext(c, response) {
+    return c.newResponse(response.body, response);
+}
 /**
  * Builds a Hono middleware that authenticates bearer tokens, stores the
  * authenticated context at {@link OAUTH2_CONTEXT_KEY}, and on failure returns
@@ -26,7 +34,7 @@ export function createProtectMiddleware(server, requiredScope) {
             await next();
         }
         catch (error) {
-            return server.handleAuthError(error);
+            return respondInContext(c, server.handleAuthError(error));
         }
     };
 }
@@ -45,7 +53,7 @@ export function createRequireScopeMiddleware(server, adapterName, requiredScope)
             server.assertScope(scope, requiredScope);
         }
         catch (error) {
-            return server.handleAuthError(error);
+            return respondInContext(c, server.handleAuthError(error));
         }
         await next();
     };
@@ -63,7 +71,7 @@ export function createRequireMiddleware(server, adapterName, conditions) {
             server.assertAuthorized(context, conditions);
         }
         catch (error) {
-            return server.handleAuthError(error);
+            return respondInContext(c, server.handleAuthError(error));
         }
         await next();
     };

package/dist/adapters/hono/bff/_rotated-cookies.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-instance memory of session cookies a refresh replaced, used by
+ * `HonoBff`'s `rotatedCookieGrace`.
+ *
+ * @module
+ */
+/** A refresh {@link RotatedCookies.start} began, to hand to `finish`. */
+export interface PendingReplacement {
+    readonly key: string;
+    ended: boolean;
+}
+/**
+ * Maps a replaced session cookie, by its SHA-256 digest, to the cookie that
+ * replaced it, for `ttlMs` and at most `maxEntries` cookies. The oldest entry
+ * is evicted first.
+ */
+export declare class RotatedCookies {
+    #private;
+    constructor(ttlMs: number, maxEntries: number);
+    /** Records that `successor` replaced `previous`. */
+    remember(previous: string, successor: string): Promise<void>;
+    /**
+     * Starts a refresh of `previous`. If its chain is forgotten before
+     * {@link finish}, the replacement is not remembered.
+     */
+    start(previous: string): Promise<PendingReplacement>;
+    /** Ends a refresh, remembering `successor` unless its chain was forgotten. */
+    finish(pending: PendingReplacement, successor: string | undefined): Promise<void>;
+    /** The cookie that replaced `cookieValue` within the window, if any. */
+    successor(cookieValue: string): Promise<string | undefined>;
+    /**
+     * Drops every entry on the chain of replacements `cookieValue` belongs to,
+     * so no cookie of a session that ended leads to another.
+     */
+    forget(cookieValue: string): Promise<void>;
+}

package/dist/adapters/hono/bff/_rotated-cookies.js

@@ -0,0 +1,93 @@
+/**
+ * Per-instance memory of session cookies a refresh replaced, used by
+ * `HonoBff`'s `rotatedCookieGrace`.
+ *
+ * @module
+ */
+import { sha256Hash } from "../../../server/utils/hash.js";
+/**
+ * Maps a replaced session cookie, by its SHA-256 digest, to the cookie that
+ * replaced it, for `ttlMs` and at most `maxEntries` cookies. The oldest entry
+ * is evicted first.
+ */
+export class RotatedCookies {
+    #ttlMs;
+    #maxEntries;
+    #successors = new Map();
+    #pending = new Set();
+    constructor(ttlMs, maxEntries) {
+        this.#ttlMs = ttlMs;
+        this.#maxEntries = maxEntries;
+    }
+    /** Records that `successor` replaced `previous`. */
+    async remember(previous, successor) {
+        await this.finish(await this.start(previous), successor);
+    }
+    /**
+     * Starts a refresh of `previous`. If its chain is forgotten before
+     * {@link finish}, the replacement is not remembered.
+     */
+    async start(previous) {
+        const pending = { key: await sha256Hash(previous), ended: false };
+        this.#pending.add(pending);
+        return pending;
+    }
+    /** Ends a refresh, remembering `successor` unless its chain was forgotten. */
+    async finish(pending, successor) {
+        this.#pending.delete(pending);
+        if (pending.ended || successor === undefined)
+            return;
+        const key = pending.key;
+        this.#successors.delete(key);
+        this.#successors.set(key, {
+            cookieValue: successor,
+            digest: await sha256Hash(successor),
+            expiresAt: Date.now() + this.#ttlMs,
+        });
+        this.#evict();
+    }
+    /** The cookie that replaced `cookieValue` within the window, if any. */
+    async successor(cookieValue) {
+        const key = await sha256Hash(cookieValue);
+        const entry = this.#successors.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= Date.now()) {
+            this.#successors.delete(key);
+            return undefined;
+        }
+        return entry.cookieValue;
+    }
+    /**
+     * Drops every entry on the chain of replacements `cookieValue` belongs to,
+     * so no cookie of a session that ended leads to another.
+     */
+    async forget(cookieValue) {
+        const ended = new Set([await sha256Hash(cookieValue)]);
+        let dropped = true;
+        while (dropped) {
+            dropped = false;
+            for (const [key, entry] of this.#successors) {
+                if (ended.has(key) || ended.has(entry.digest)) {
+                    this.#successors.delete(key);
+                    ended.add(key);
+                    ended.add(entry.digest);
+                    dropped = true;
+                }
+            }
+        }
+        for (const pending of this.#pending) {
+            if (ended.has(pending.key))
+                pending.ended = true;
+        }
+    }
+    #evict() {
+        const now = Date.now();
+        for (const [key, entry] of this.#successors) {
+            if (this.#successors.size <= this.#maxEntries && entry.expiresAt > now) {
+                return;
+            }
+            this.#successors.delete(key);
+        }
+    }
+}

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

@@ -322,7 +322,8 @@ export interface HonoBffOptions {
      *   shared {@link SessionStore} when you need revocation. Against an
      *   authorization server that rotates refresh tokens, a request still
      *   carrying the cookie from before a refresh replays the old token and
-     *   trips reuse detection.
+     *   trips reuse detection, unless it reaches the instance that ran the
+     *   refresh within {@link HonoBffOptions.rotatedCookieGrace}.
      * - 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
@@ -637,6 +638,34 @@ export interface HonoBffOptions {
      * refresh proactively. Defaults to 30s.
      */
     refreshSkewSeconds?: number;
+    /**
+     * How this instance answers a request that still carries the session cookie
+     * a refresh replaced. Applies when a refresh hands the browser a new cookie
+     * value, as {@link EncryptedCookieSessionStore} does on every refresh.
+     *
+     * A browser that sent several requests before the refresh's response arrived
+     * still sends the old cookie on the others. Against an authorization server
+     * that rotates refresh tokens, a request that arrives after the refresh has
+     * finished would present the rotated-out token: reuse detection revokes the
+     * family and the user is signed out. With this grace, the instance that ran
+     * the refresh remembers which cookie replaced which for `ttlMs` and answers
+     * such a request with the new session and its cookie, spending nothing.
+     *
+     * Defaults to `{ ttlMs: 10_000, maxEntries: 1000 }`. Pass `false` to turn it
+     * off. Beyond `maxEntries` the oldest entry is dropped. A session that ends
+     * on this instance (sign-out, a sign-in replacing it, a refused refresh)
+     * forgets its whole chain, including a refresh still in flight.
+     *
+     * The cost is that a stolen pre-refresh cookie replayed to the same
+     * instance within `ttlMs` receives the new session, where without the grace
+     * it would trip reuse detection. Only the instance that ran the refresh
+     * remembers, so a request on another instance still replays the token. See
+     * the session limitations in `docs/known-limitations.md`.
+     */
+    rotatedCookieGrace?: {
+        ttlMs?: number;
+        maxEntries?: number;
+    } | false;
     /**
      * Optional resource server. When provided, {@link HonoBff.protect}
      * becomes available — a single middleware that composes

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

@@ -55,11 +55,28 @@ import { defaultFetch } from "../../../utils/_default-fetch.js";
 import { inboundRequestWithHeaders } from "../../../utils/_inbound-request.js";
 import { timingSafeMatchIndex } from "../../../utils/_timing-safe.js";
 import { sha256Hash } from "../../../server/utils/hash.js";
-import { OAUTH2_CONTEXT_KEY } from "../_common.js";
+import { OAUTH2_CONTEXT_KEY, respondInContext } from "../_common.js";
 import { DEFAULT_MAX_RETURN_TO_LENGTH, loginContinuation as computeLoginContinuation, safeReturnTo, } from "../../../utils/url.js";
 import { resolveCookieName, resolvePrefixConstrainedAttributes, } from "./cookie-prefix.js";
 import { DEFAULT_SESSION_MAX_AGE_MS, sessionStoreMaxAgeMs, supportsBackchannelLogout, supportsRefreshLock, } from "./session-store.js";
+import { RotatedCookies } from "./_rotated-cookies.js";
 import { buildDownstreamHeaders, buildUpstreamHeaders, isInvalidTokenChallenge, resolveForwardHeaders, resolveProxyUrl, } from "./proxy.js";
+const DEFAULT_ROTATED_COOKIE_GRACE_MS = 10_000;
+const DEFAULT_ROTATED_COOKIE_MAX_ENTRIES = 1000;
+const MAX_ROTATED_COOKIE_HOPS = 4;
+function rotatedCookies(grace) {
+    if (grace === false)
+        return undefined;
+    const ttlMs = grace?.ttlMs ?? DEFAULT_ROTATED_COOKIE_GRACE_MS;
+    const maxEntries = grace?.maxEntries ?? DEFAULT_ROTATED_COOKIE_MAX_ENTRIES;
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new RangeError(`rotatedCookieGrace.ttlMs must be a positive number of milliseconds, got ${ttlMs}`);
+    }
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new RangeError(`rotatedCookieGrace.maxEntries must be a positive integer, got ${maxEntries}`);
+    }
+    return new RotatedCookies(ttlMs, maxEntries);
+}
 function refreshedSince(seen, current) {
     return (current.refreshToken !== seen.refreshToken ||
         current.tokens.accessToken !== seen.tokens.accessToken);
@@ -319,6 +336,7 @@ export class HonoBff {
     #extraAuthorizeParams;
     #maxReturnToLength;
     #refreshes = new Map();
+    #rotatedCookies;
     /**
      * Defaults are applied for session mode (`"own"`), cookie name, and CSRF.
      * The session store and auth-request storage have no default.
@@ -410,6 +428,7 @@ export class HonoBff {
                 }
             }
         }
+        this.#rotatedCookies = rotatedCookies(options.rotatedCookieGrace);
         if (options.backchannelLogout?.maxBodyBytes !== undefined) {
             assertMaxBodyBytes(options.backchannelLogout.maxBodyBytes, "backchannelLogout.maxBodyBytes");
         }
@@ -475,7 +494,7 @@ export class HonoBff {
             return null;
         if (!this.#isBeyondSessionMaxAge(data))
             return data;
-        await this.#store.destroy(cookieValue);
+        await this.#destroySession(cookieValue);
         deleteCookie(c, this.#cookieName, this.#cookieOptions());
         return null;
     }
@@ -740,7 +759,7 @@ export class HonoBff {
                 const inbound = getCookie(c, this.#cookieName);
                 const existing = this.#sessionMode === "shared" ? inbound : undefined;
                 if (inbound && !existing)
-                    await this.#store.destroy(inbound);
+                    await this.#destroySession(inbound);
                 const cookieValue = existing
                     ? await this.#store.update(existing, data)
                     : await this.#store.create(data);
@@ -784,7 +803,7 @@ export class HonoBff {
                         // best-effort
                     }
                 }
-                await this.#store.destroy(cookieValue);
+                await this.#destroySession(cookieValue);
                 deleteCookie(c, this.#cookieName, this.#cookieOptions());
             }
             const returnTo = this.#safeReturnTo(c.req.query("return_to"));
@@ -1009,12 +1028,52 @@ export class HonoBff {
         const inFlight = this.#refreshes.get(entry.cookieValue);
         if (inFlight)
             return inFlight;
-        const pending = this.#lockedRefresh(entry).finally(() => {
+        const pending = this.#refreshUnlessReplaced(entry).finally(() => {
             this.#refreshes.delete(entry.cookieValue);
         });
         this.#refreshes.set(entry.cookieValue, pending);
         return pending;
     }
+    async #refreshUnlessReplaced(entry) {
+        const memo = this.#rotatedCookies;
+        if (!memo)
+            return await this.#lockedRefresh(entry);
+        let latest = entry.cookieValue;
+        for (let hop = 0; hop < MAX_ROTATED_COOKIE_HOPS; hop++) {
+            const next = await memo.successor(latest);
+            if (next === undefined)
+                break;
+            latest = next;
+        }
+        if (latest !== entry.cookieValue) {
+            try {
+                const data = await this.#store.read(latest);
+                return data
+                    ? { status: "refreshed", entry: { cookieValue: latest, data } }
+                    : { status: "revoked" };
+            }
+            catch {
+                return { status: "unavailable" };
+            }
+        }
+        const pending = await memo.start(entry.cookieValue);
+        let successor;
+        try {
+            const outcome = await this.#lockedRefresh(entry);
+            if (outcome.status === "refreshed" &&
+                outcome.entry.cookieValue !== entry.cookieValue) {
+                successor = outcome.entry.cookieValue;
+            }
+            return outcome;
+        }
+        finally {
+            await memo.finish(pending, successor);
+        }
+    }
+    async #destroySession(cookieValue) {
+        await this.#rotatedCookies?.forget(cookieValue);
+        await this.#store.destroy(cookieValue);
+    }
     async #lockedRefresh(entry) {
         const store = this.#store;
         if (!supportsRefreshLock(store))
@@ -1065,7 +1124,7 @@ export class HonoBff {
             if (current && current.refreshToken !== data.refreshToken) {
                 return { status: "refreshed", entry: { cookieValue, data: current } };
             }
-            await this.#store.destroy(cookieValue);
+            await this.#destroySession(cookieValue);
             return { status: "revoked" };
         }
     }
@@ -1208,7 +1267,7 @@ export class HonoBff {
                 await next();
             }
             catch (error) {
-                return resourceServer.handleAuthError(error);
+                return respondInContext(c, resourceServer.handleAuthError(error));
             }
         };
     }

package/dist/models/token.d.ts

@@ -66,6 +66,13 @@ export interface RefreshToken<Client extends ClientInterface, User, Scope extend
      * with a fresh anchor, so the family is capped from then on.
      */
     familyCreatedAt?: Date;
+    /**
+     * When the refresh grant rotated this token out. A token service that
+     * supports `RefreshTokenGrantOptions.replayGraceSeconds` sets it in
+     * `revokeRotated` and returns it from `getRevokedRefreshToken`. A token
+     * revoked any other way has none.
+     */
+    rotatedAt?: Date;
 }
 /**
  * Standard OAuth2 token response.

package/dist/server/grants/refresh-token.d.ts

@@ -40,6 +40,33 @@ export interface RefreshTokenGrantOptions<Client extends ClientInterface, User,
      * client-facing `invalid_grant` a replayed token always yields.
      */
     onTokenReuse?: (event: TokenReuseEvent<Client, User>) => void | Promise<void>;
+    /**
+     * Seconds after a refresh token is rotated during which presenting it again
+     * is answered with `invalid_grant` but not treated as reuse: the family
+     * keeps its live token and `onTokenReuse` does not fire. Defaults to `0`,
+     * which turns the grace off.
+     *
+     * It covers a client that sends a request with the old refresh token after
+     * its own concurrent request already rotated it, such as a backend-for-
+     * frontend whose instances do not coordinate refreshes, so that one
+     * straggler does not sign the user out. It applies only while the family
+     * still has a live refresh token, and only to a token the grant rotated
+     * out, not to one revoked any other way. Outside the window, or with no
+     * live successor, reuse detection runs as usual.
+     *
+     * The cost is that a stolen refresh token replayed within the window after
+     * the legitimate client rotated it goes unflagged: the family is not
+     * revoked and no reuse event is raised. It cuts the other way too: when a
+     * thief rotates a stolen live token first, the legitimate client's replay
+     * within the window is refused without revoking the family, so the thief
+     * keeps the session and the user is the one signed out. Keep the window to
+     * seconds.
+     *
+     * Needs a token service that sets {@linkcode RefreshToken.rotatedAt} in
+     * `revokeRotated` and implements `hasLiveRefreshToken`; with any other
+     * service the grace never applies.
+     */
+    replayGraceSeconds?: number;
 }
 /**
  * The refresh token grant type.

package/dist/server/grants/refresh-token.js

@@ -16,10 +16,16 @@ export class RefreshTokenGrant extends AbstractGrant {
     /** The OAuth2 grant type: `refresh_token`. */
     grantType = "refresh_token";
     #onTokenReuse;
+    #replayGraceMs;
     /** Creates the grant from its {@linkcode RefreshTokenGrantOptions}. */
     constructor(options) {
         super({ ...options, allowRefreshToken: true });
         this.#onTokenReuse = options.onTokenReuse;
+        const graceSeconds = options.replayGraceSeconds ?? 0;
+        if (!Number.isFinite(graceSeconds) || graceSeconds < 0) {
+            throw new RangeError(`replayGraceSeconds must be a non-negative number of seconds, got ${graceSeconds}`);
+        }
+        this.#replayGraceMs = graceSeconds * 1000;
     }
     /**
      * Handles a token request for the refresh token grant. Issues a new access
@@ -60,7 +66,8 @@ export class RefreshTokenGrant extends AbstractGrant {
             if (tokenService.getRevokedRefreshToken && tokenService.revokeFamily) {
                 const replayed = await tokenService.getRevokedRefreshToken(refreshTokenStr);
                 if (replayed?.familyId &&
-                    replayed.client.id.toString() === client.id.toString()) {
+                    replayed.client.id.toString() === client.id.toString() &&
+                    !(await this.#withinReplayGrace(tokenService, replayed))) {
                     const familyRevoked = await tokenService.revokeFamily(replayed.familyId);
                     await this.#notifyTokenReuse({
                         familyId: replayed.familyId,
@@ -123,6 +130,14 @@ export class RefreshTokenGrant extends AbstractGrant {
         }
         return await tokenService.save(nextRefreshToken);
     }
+    async #withinReplayGrace(tokenService, replayed) {
+        const { rotatedAt, familyId } = replayed;
+        if (this.#replayGraceMs === 0 || !rotatedAt || !familyId)
+            return false;
+        if (Date.now() - rotatedAt.getTime() > this.#replayGraceMs)
+            return false;
+        return (await tokenService.hasLiveRefreshToken?.(familyId)) ?? false;
+    }
     async #notifyTokenReuse(event) {
         if (!this.#onTokenReuse)
             return;

package/dist/server/services/token.d.ts

@@ -121,6 +121,10 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * the token belongs to, cascading to sibling records — so a routine refresh
      * cannot terminate the very session it renews. When absent, the refresh
      * grant falls back to {@linkcode revoke}.
+     *
+     * To support the refresh grant's `replayGraceSeconds`, stamp the revoked
+     * record with {@linkcode RefreshToken.rotatedAt} here and return it from
+     * {@linkcode getRevokedRefreshToken}.
      */
     revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
     /**
@@ -148,6 +152,12 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * can't keep a session alive. Returns true if anything was revoked.
      */
     revokeFamily?(familyId: string): Promise<boolean>;
+    /**
+     * Whether the rotation family still has a live, unexpired refresh token.
+     * Read by the refresh grant's `replayGraceSeconds`: without it, the grace
+     * never applies and every replay is treated as reuse.
+     */
+    hasLiveRefreshToken?(familyId: string): Promise<boolean>;
 }
 /** Options for configuring an abstract token service. */
 export interface AbstractTokenServiceOptions<Client extends ClientInterface, User> {

package/dist/testing/contract/token.js

@@ -212,14 +212,14 @@ export function runTokenServiceContractTests(options) {
             describe("refresh-token rotation family", () => {
                 const FAMILY = "family-1";
                 const OTHER_FAMILY = "family-2";
-                async function saveFamilyMember(familyId) {
+                async function saveFamilyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
                     const accessToken = await tokenService.generateAccessToken(client, user);
                     const refreshToken = (await tokenService.generateRefreshToken(client, user));
                     const token = {
                         accessToken,
                         accessTokenExpiresAt: new Date(Date.now() + 60_000),
                         refreshToken,
-                        refreshTokenExpiresAt: new Date(Date.now() + 600_000),
+                        refreshTokenExpiresAt,
                         familyId,
                         familyCreatedAt: new Date(Date.now() - 60_000),
                         client,
@@ -273,6 +273,41 @@ export function runTokenServiceContractTests(options) {
                 it("returns false when the family has no live tokens", async () => {
                     expect(await tokenService.revokeFamily("never-issued")).toBe(false);
                 });
+                it("stamps a token revokeRotated revoked with its rotation time", async ({ skip, }) => {
+                    skip(typeof tokenService.revokeRotated !== "function", "the service does not implement revokeRotated");
+                    const token = await saveFamilyMember(FAMILY);
+                    const before = Date.now();
+                    expect(await tokenService.revokeRotated(token)).toBe(true);
+                    const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
+                    assert(revoked !== undefined);
+                    assert(revoked.rotatedAt instanceof Date &&
+                        revoked.rotatedAt.getTime() >= before - 1000 &&
+                        revoked.rotatedAt.getTime() <= Date.now() + 1000, "without rotatedAt the refresh grant's replayGraceSeconds never " +
+                        "applies, so every straggler revokes its family");
+                });
+                it("leaves rotatedAt unset on a token revoked other than by rotation", async () => {
+                    const token = await saveFamilyMember(FAMILY);
+                    await tokenService.revoke(token.refreshToken, "refresh_token");
+                    const revoked = await tokenService.getRevokedRefreshToken(token.refreshToken);
+                    expect(revoked?.rotatedAt, "a revoked token that looks rotated gets the replay grace a " +
+                        "signed-out session must never have").toBe(undefined);
+                });
+                it("reports whether a family still has a live refresh token", async ({ skip, }) => {
+                    skip(typeof tokenService.hasLiveRefreshToken !== "function", "the service does not implement hasLiveRefreshToken");
+                    const token = await saveFamilyMember(FAMILY);
+                    await saveFamilyMember(OTHER_FAMILY);
+                    expect(await tokenService.hasLiveRefreshToken(FAMILY)).toBe(true);
+                    await tokenService.revoke(token.refreshToken, "refresh_token");
+                    expect(await tokenService.hasLiveRefreshToken(FAMILY), "a family whose last token was revoked has no successor to protect").toBe(false);
+                    expect(await tokenService.hasLiveRefreshToken(OTHER_FAMILY)).toBe(true);
+                    expect(await tokenService.hasLiveRefreshToken("never-issued")).toBe(false);
+                });
+                it("does not count an expired refresh token as live", async ({ skip, }) => {
+                    skip(typeof tokenService.hasLiveRefreshToken !== "function", "the service does not implement hasLiveRefreshToken");
+                    await saveFamilyMember(FAMILY, new Date(Date.now() - 1000));
+                    expect(await tokenService.hasLiveRefreshToken(FAMILY), "an expired successor cannot be used, so a replay of its " +
+                        "predecessor must not be excused as a straggler").toBe(false);
+                });
             });
         }
         else {

package/dist/testing/services.d.ts

@@ -240,6 +240,15 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
      * token. Resolves `true` when something was removed.
      */
     revoke(token: string, hint?: string | null): Promise<boolean>;
+    /**
+     * Revokes a refresh token the refresh grant just rotated out, as
+     * {@linkcode revoke} does, and stamps its tombstone with the rotation time
+     * so the grant's `replayGraceSeconds` can apply. Resolves `false` when the
+     * token was already claimed.
+     */
+    revokeRotated(token: RefreshToken<C, U, S>): Promise<boolean>;
+    /** Whether the family has a live refresh token that has not expired. */
+    hasLiveRefreshToken(familyId: string): Promise<boolean>;
     /**
      * Looks up a revoked/rotated-out refresh token for the refresh grant's
      * reuse detection: revoked refresh records are kept as tombstones instead

package/dist/testing/services.js

@@ -290,6 +290,7 @@ export class MemoryTokenService {
                 refreshTokenExpiresAt: stored.refreshTokenExpiresAt,
                 familyId: stored.familyId,
                 familyCreatedAt: stored.familyCreatedAt,
+                rotatedAt: stored.rotatedAt,
             };
         }
         return token;
@@ -367,6 +368,31 @@ export class MemoryTokenService {
         }
         return true;
     }
+    /**
+     * Revokes a refresh token the refresh grant just rotated out, as
+     * {@linkcode revoke} does, and stamps its tombstone with the rotation time
+     * so the grant's `replayGraceSeconds` can apply. Resolves `false` when the
+     * token was already claimed.
+     */
+    async revokeRotated(token) {
+        const stored = this.#tokensByRefreshHash.get(await sha256Hash(token.refreshToken));
+        if (!stored)
+            return false;
+        stored.rotatedAt = new Date();
+        return await this.revoke(token);
+    }
+    /** Whether the family has a live refresh token that has not expired. */
+    hasLiveRefreshToken(familyId) {
+        const now = Date.now();
+        for (const stored of this.#tokensByRefreshHash.values()) {
+            if (stored.familyId === familyId &&
+                (!stored.refreshTokenExpiresAt ||
+                    stored.refreshTokenExpiresAt.getTime() > now)) {
+                return Promise.resolve(true);
+            }
+        }
+        return Promise.resolve(false);
+    }
     #tombstone(refreshTokenHash, stored) {
         this.#revokedByRefreshHash.set(refreshTokenHash, stored);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@udibo/oauth2",
-  "version": "0.21.2",
+  "version": "0.22.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",