@udibo/oauth2 0.21.3 → 0.23.0

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

@@ -59,7 +59,24 @@ 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" };
         }
     }

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 sets it in
+     * `revokeRotated` and returns it from `getRevokedRefreshToken`; the refresh
+     * grant's `replayGraceSeconds` and the revocation endpoint's family
+     * revocation both need it. A token revoked any other way has none.
+     */
+    rotatedAt?: Date;
 }
 /**
  * Standard OAuth2 token response.

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

@@ -641,6 +641,18 @@ export declare class AuthorizationServer<Client extends ClientInterface, User, S
      * end another application's live sessions at will. A token belonging to a
      * different client is left alone.
      *
+     * **A refresh token that rotation already replaced revokes its family.** When
+     * the token is no longer live but the token service's
+     * `getRevokedRefreshToken` returns it with {@linkcode RefreshToken.rotatedAt}
+     * and a `familyId`, and it was issued to the authenticated client, the
+     * server calls `revokeFamily`, so the successor rotation issued dies with
+     * it (RFC 7009 §2.1 allows revoking related tokens). A sign-out that races
+     * the client's own refresh therefore still ends the session. A token
+     * revoked other than by rotation, a token with no family, and a service
+     * without `getRevokedRefreshToken` and `revokeFamily` revoke nothing more.
+     * The refresh grant's `replayGraceSeconds` does not apply here, and
+     * `onTokenReuse` does not fire.
+     *
      * Always returns 200 OK, even if the token was invalid, already revoked, or
      * issued to another client: RFC 7009 Section 2.2 requires that answer so the
      * endpoint cannot be used as an oracle for whether a token value is live or

package/dist/server/authorization-server.js

@@ -935,6 +935,18 @@ export class AuthorizationServer extends ResourceServer {
      * end another application's live sessions at will. A token belonging to a
      * different client is left alone.
      *
+     * **A refresh token that rotation already replaced revokes its family.** When
+     * the token is no longer live but the token service's
+     * `getRevokedRefreshToken` returns it with {@linkcode RefreshToken.rotatedAt}
+     * and a `familyId`, and it was issued to the authenticated client, the
+     * server calls `revokeFamily`, so the successor rotation issued dies with
+     * it (RFC 7009 §2.1 allows revoking related tokens). A sign-out that races
+     * the client's own refresh therefore still ends the session. A token
+     * revoked other than by rotation, a token with no family, and a service
+     * without `getRevokedRefreshToken` and `revokeFamily` revoke nothing more.
+     * The refresh grant's `replayGraceSeconds` does not apply here, and
+     * `onTokenReuse` does not fire.
+     *
      * Always returns 200 OK, even if the token was invalid, already revoked, or
      * issued to another client: RFC 7009 Section 2.2 requires that answer so the
      * endpoint cannot be used as an oracle for whether a token value is live or
@@ -962,8 +974,10 @@ export class AuthorizationServer extends ResourceServer {
             const hint = typeof tokenTypeHint === "string" ? tokenTypeHint : null;
             const { tokenService } = context.services;
             const resolved = await this.#resolveToken(tokenService, token, hint);
-            if (resolved &&
-                resolved.token.client.id.toString() === client.id.toString()) {
+            if (!resolved) {
+                await this.#revokeRotatedOutFamily(tokenService, token, client);
+            }
+            else if (resolved.token.client.id.toString() === client.id.toString()) {
                 await tokenService.revoke(token, resolved.tokenType);
             }
             return new Response(null, { status: 200 });
@@ -972,6 +986,17 @@ export class AuthorizationServer extends ResourceServer {
             return this.#handleEndpointError(error, this.prepareClientAuthError(request));
         }
     }
+    async #revokeRotatedOutFamily(tokenService, value, client) {
+        if (!tokenService.getRevokedRefreshToken || !tokenService.revokeFamily) {
+            return;
+        }
+        const rotatedOut = await tokenService.getRevokedRefreshToken(value);
+        if (rotatedOut?.rotatedAt &&
+            rotatedOut.familyId &&
+            rotatedOut.client.id.toString() === client.id.toString()) {
+            await tokenService.revokeFamily(rotatedOut.familyId);
+        }
+    }
     async #resolveToken(tokenService, value, hint) {
         const refreshFirst = hint === "refresh_token";
         if (refreshFirst) {

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,12 @@ 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}.
+     *
+     * Stamp the revoked record with {@linkcode RefreshToken.rotatedAt} here and
+     * return it, with its `familyId`, from {@linkcode getRevokedRefreshToken}.
+     * The refresh grant's `replayGraceSeconds` reads it, and the revocation
+     * endpoint revokes the family of a token presented after rotation replaced
+     * it, so a sign-out racing a refresh still ends the successor.
      */
     revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
     /**
@@ -135,19 +141,40 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      */
     revokeCode(code: string): Promise<boolean>;
     /**
-     * Looks up a refresh token that has already been revoked/rotated out —
-     * the signal the refresh grant's reuse detection needs. Implement this
-     * (with {@linkcode revokeFamily}) by keeping revoked refresh-token records
-     * findable instead of deleting them; when absent, reuse detection is
-     * silently disabled.
+     * Looks up a refresh token that has already been revoked/rotated out. The
+     * refresh grant's reuse detection reads it, and so does the revocation
+     * endpoint, to revoke the family of a token rotation replaced. Implement
+     * this (with {@linkcode revokeFamily}) by keeping revoked refresh-token
+     * records findable instead of deleting them; when absent, reuse detection
+     * is silently disabled and `/revoke` cannot reach a successor.
+     *
+     * Return the tombstone unconditionally. Apply any replay grace through
+     * `RefreshTokenGrantOptions.replayGraceSeconds`, never by hiding recent
+     * tombstones here: a hidden tombstone also hides the family from a sign-out
+     * racing the refresh, which then leaves the successor live.
      */
     getRevokedRefreshToken?(refreshToken: string): Promise<RefreshToken<Client, User, Scope> | undefined>;
     /**
      * Revokes every token belonging to a rotation family — called by the
      * refresh grant when a rotated-out member is replayed, so a stolen token
-     * can't keep a session alive. Returns true if anything was revoked.
+     * can't keep a session alive, and by the revocation endpoint when it is
+     * given a token whose tombstone carries {@linkcode RefreshToken.rotatedAt}.
+     * Returns true if anything was revoked.
+     *
+     * `/revoke` ends the family without firing `onTokenReuse`, so any audit
+     * trail for that case has to come from this method.
+     *
+     * Keep the family revoked: a successor that a concurrent rotation saves
+     * after this call must be stored already revoked, as
+     * `MemoryTokenService` does.
      */
     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.d.ts

@@ -49,7 +49,9 @@ export interface TokenServiceContractOptions<C extends ClientInterface, U extend
      * and {@linkcode TokenServiceInterface.revokeFamily}. The suite then
      * registers an ignored case naming what is not covered — a replayed
      * rotated-out refresh token cannot be detected, so a stolen token keeps
-     * working alongside the victim's — instead of passing in silence. Defaults to
+     * working alongside the victim's, and revoking a rotated-out token at the
+     * revocation endpoint leaves its successor live — instead of passing in
+     * silence. Defaults to
      * `true`, so a service that meant to implement the pair and does not fails
      * loudly rather than losing reuse detection quietly.
      */

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,10 +273,63 @@ 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("finds a rotated-out token's family, so revoking it ends the live successor", async ({ skip, }) => {
+                    skip(typeof tokenService.revokeRotated !== "function", "the service does not implement revokeRotated");
+                    const rotatedOut = await saveFamilyMember(FAMILY);
+                    expect(await tokenService.revokeRotated(rotatedOut)).toBe(true);
+                    const successor = await saveFamilyMember(FAMILY);
+                    const unrelated = await saveFamilyMember(OTHER_FAMILY);
+                    const tombstone = await tokenService.getRevokedRefreshToken(rotatedOut.refreshToken);
+                    assert(tombstone?.familyId === FAMILY && tombstone.rotatedAt, "the revocation endpoint finds the family to end from the " +
+                        "rotated-out token's record; without its familyId and " +
+                        "rotatedAt, a sign-out racing a refresh leaves the successor live");
+                    expect(tombstone.client.id.toString(), "the endpoint revokes the family only for the client the token " +
+                        "was issued to").toBe(client.id.toString());
+                    expect(await tokenService.revokeFamily(tombstone.familyId)).toBe(true);
+                    expect(await tokenService.getRefreshToken(successor.refreshToken)).toBe(undefined);
+                    expect(await tokenService.getToken(successor.accessToken)).toBe(undefined);
+                    assert((await tokenService.getRefreshToken(unrelated.refreshToken)) !==
+                        undefined);
+                });
+                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 {
-            it.skip("refresh-token reuse detection is not implemented — a replayed rotated-out token cannot be detected (refreshTokenReuseDetection: false)", () => { });
+            it.skip("refresh-token reuse detection is not implemented — a replayed rotated-out token cannot be detected, and revoking one does not end its successor (refreshTokenReuseDetection: false)", () => { });
         }
     });
 }

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
@@ -247,8 +256,10 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
      */
     getRevokedRefreshToken(refreshToken: string): Promise<RefreshToken<C, U, S> | undefined>;
     /**
-     * Revokes every live token in a rotation family (reuse detection response).
-     * Resolves `true` when at least one live token was removed.
+     * Revokes every live token in a rotation family (reuse detection response)
+     * and keeps the family revoked, so a successor a concurrent rotation saves
+     * afterwards is stored already revoked. Resolves `true` when at least one
+     * live token was removed.
      */
     revokeFamily(familyId: string): Promise<boolean>;
     /**

package/dist/testing/services.js

@@ -207,6 +207,7 @@ export class MemoryTokenService {
     #tokensByRefreshHash = new Map();
     #tokensByCodeHash = new Map();
     #revokedByRefreshHash = new Map();
+    #revokedFamilies = new Set();
     /**
      * Creates an empty token store.
      *
@@ -290,6 +291,7 @@ export class MemoryTokenService {
                 refreshTokenExpiresAt: stored.refreshTokenExpiresAt,
                 familyId: stored.familyId,
                 familyCreatedAt: stored.familyCreatedAt,
+                rotatedAt: stored.rotatedAt,
             };
         }
         return token;
@@ -339,6 +341,10 @@ export class MemoryTokenService {
             stored.refreshTokenExpiresAt = rt.refreshTokenExpiresAt;
             stored.familyId = rt.familyId;
             stored.familyCreatedAt = rt.familyCreatedAt;
+            if (rt.familyId && this.#revokedFamilies.has(rt.familyId)) {
+                this.#tombstone(stored.refreshTokenHash, stored);
+                return token;
+            }
             this.#tokensByRefreshHash.set(stored.refreshTokenHash, stored);
         }
         this.#tokensByAccessHash.set(accessTokenHash, stored);
@@ -367,6 +373,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);
     }
@@ -382,10 +413,13 @@ export class MemoryTokenService {
         return this.#hydrate(stored, "", refreshToken);
     }
     /**
-     * Revokes every live token in a rotation family (reuse detection response).
-     * Resolves `true` when at least one live token was removed.
+     * Revokes every live token in a rotation family (reuse detection response)
+     * and keeps the family revoked, so a successor a concurrent rotation saves
+     * afterwards is stored already revoked. Resolves `true` when at least one
+     * live token was removed.
      */
     revokeFamily(familyId) {
+        this.#revokedFamilies.add(familyId);
         let revoked = false;
         for (const [hash, stored] of this.#tokensByRefreshHash) {
             if (stored.familyId === familyId) {

package/package.json

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