@udibo/oauth2 0.30.0 → 0.31.0

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

@@ -64,7 +64,13 @@ export interface RefreshTokenGrantOptions<Client extends ClientInterface, User,
      *
      * Needs a token service that sets {@linkcode RefreshToken.rotatedAt} in
      * `revokeRotated` and implements `hasLiveRefreshToken`; with any other
-     * service the grace never applies.
+     * service the grace never applies. The window is measured by the token
+     * service's `isWithinReplayGrace` when it implements one, on the store's
+     * clock, and otherwise by comparing `rotatedAt` with this process's clock.
+     * The store's answer is honored only while `rotatedAt` is no more than five
+     * minutes ahead of this process's clock and no more than the grace plus
+     * five minutes behind it, so a faulty store check cannot excuse replays
+     * indefinitely.
      */
     replayGraceSeconds?: number;
 }

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

@@ -5,6 +5,7 @@
  */
 import { InvalidClientError, InvalidGrantError, InvalidRequestError, InvalidScopeError, } from "../../errors.js";
 import { AbstractGrant, } from "./grant.js";
+const REPLAY_GRACE_CLOCK_TOLERANCE_SECONDS = 300;
 /**
  * The refresh token grant type.
  * https://datatracker.ietf.org/doc/html/rfc6749.html#section-6
@@ -16,7 +17,7 @@ export class RefreshTokenGrant extends AbstractGrant {
     /** The OAuth2 grant type: `refresh_token`. */
     grantType = "refresh_token";
     #onTokenReuse;
-    #replayGraceMs;
+    #replayGraceSeconds;
     /** Creates the grant from its {@linkcode RefreshTokenGrantOptions}. */
     constructor(options) {
         super({ ...options, allowRefreshToken: true });
@@ -25,7 +26,7 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (!Number.isFinite(graceSeconds) || graceSeconds < 0) {
             throw new RangeError(`replayGraceSeconds must be a non-negative number of seconds, got ${graceSeconds}`);
         }
-        this.#replayGraceMs = graceSeconds * 1000;
+        this.#replayGraceSeconds = graceSeconds;
     }
     /**
      * Handles a token request for the refresh token grant. Issues a new access
@@ -143,12 +144,23 @@ export class RefreshTokenGrant extends AbstractGrant {
     }
     async #withinReplayGrace(tokenService, replayed) {
         const { rotatedAt, familyId } = replayed;
-        if (this.#replayGraceMs === 0 || !rotatedAt || !familyId)
+        if (this.#replayGraceSeconds === 0 || !rotatedAt || !familyId) {
             return false;
-        if (Date.now() - rotatedAt.getTime() > this.#replayGraceMs)
+        }
+        const elapsedMs = Date.now() - rotatedAt.getTime();
+        const withinWindow = tokenService.isWithinReplayGrace
+            ? this.#withinClockTolerance(elapsedMs) &&
+                (await tokenService.isWithinReplayGrace(replayed, this.#replayGraceSeconds))
+            : elapsedMs <= this.#replayGraceSeconds * 1000;
+        if (!withinWindow)
             return false;
         return (await tokenService.hasLiveRefreshToken?.(familyId)) ?? false;
     }
+    #withinClockTolerance(elapsedMs) {
+        const toleranceMs = REPLAY_GRACE_CLOCK_TOLERANCE_SECONDS * 1000;
+        return (elapsedMs >= -toleranceMs &&
+            elapsedMs <= this.#replayGraceSeconds * 1000 + toleranceMs);
+    }
     async #notifyTokenReuse(event) {
         if (!this.#onTokenReuse)
             return;

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

@@ -175,9 +175,10 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * 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.
+     * `RefreshTokenGrantOptions.replayGraceSeconds`, judged on the store's clock
+     * by {@linkcode isWithinReplayGrace} when it needs one, 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>;
     /**
@@ -209,6 +210,25 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * never applies and every replay is treated as reuse.
      */
     hasLiveRefreshToken?(familyId: string): Promise<boolean>;
+    /**
+     * Whether `tombstone`, a record {@linkcode getRevokedRefreshToken} just
+     * returned, was rotated out no more than `graceSeconds` ago, measured on the
+     * clock that stamped its rotation. Implement it when that clock is the
+     * store's own, such as a database's, so instances whose clocks drift
+     * apart agree on the refresh grant's `replayGraceSeconds` window. Without
+     * it, the grant compares {@linkcode RefreshToken.rotatedAt} with its own
+     * `Date.now()`.
+     *
+     * The grant calls it only when `replayGraceSeconds` is above zero and the
+     * tombstone carries `rotatedAt` and a `familyId`; `graceSeconds` may be
+     * fractional. The window still needs {@linkcode hasLiveRefreshToken}.
+     * The grant treats the replay as outside the window, whatever this
+     * resolves, once `rotatedAt` is more than five minutes ahead of the
+     * grant's clock or more than `graceSeconds` plus five minutes behind it.
+     * Implementing this never licenses hiding a tombstone from
+     * `getRevokedRefreshToken`.
+     */
+    isWithinReplayGrace?(tombstone: RefreshToken<Client, User, Scope>, graceSeconds: number): Promise<boolean>;
 }
 /** Options for configuring an abstract token service. */
 export interface AbstractTokenServiceOptions<Client extends ClientInterface, User> {

package/dist/testing/contract/token.js

@@ -17,6 +17,7 @@
  *
  * @module
  */
+import { setTimeout as delay } from "node:timers/promises";
 import { assert, beforeEach, describe, expect, it } from "vitest";
 import { BasicScope } from "../../models/scope.js";
 const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
@@ -368,6 +369,41 @@ export function runTokenServiceContractTests(options) {
                     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);
                 });
+                async function rotateOut(skip) {
+                    skip(typeof tokenService.isWithinReplayGrace !== "function", "the service does not implement isWithinReplayGrace");
+                    skip(typeof tokenService.rotate !== "function" &&
+                        typeof tokenService.revokeRotated !== "function", "the service implements neither rotate nor revokeRotated");
+                    const parent = await saveFamilyMember(FAMILY);
+                    const successor = await familyMember(FAMILY);
+                    if (tokenService.rotate) {
+                        assert(await tokenService.rotate(parent, successor));
+                    }
+                    else {
+                        assert(await tokenService.revokeRotated(parent));
+                        await tokenService.save(successor);
+                    }
+                    const tombstone = await tokenService.getRevokedRefreshToken(parent.refreshToken);
+                    assert(tombstone?.familyId === FAMILY && tombstone.rotatedAt, "a store that judges the replay grace must still return every " +
+                        "rotated-out tombstone, with its family and rotatedAt; hiding " +
+                        "one inside the window hides the family from a sign-out " +
+                        "racing the refresh, which then leaves the successor live");
+                    return { tombstone, successor };
+                }
+                it("returns the tombstone of a token inside its replay grace, so revoking it ends the successor", async ({ skip, }) => {
+                    const { tombstone, successor } = await rotateOut(skip);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 60), "a token rotated out a moment ago is inside a 60-second grace").toBe(true);
+                    expect(await tokenService.revokeFamily(tombstone.familyId)).toBe(true);
+                    expect(await tokenService.getRefreshToken(successor.refreshToken)).toBe(undefined);
+                });
+                it("judges a rotated-out token inside a one-second grace, then outside it once the second has passed", async ({ skip, }) => {
+                    const { tombstone } = await rotateOut(skip);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 1), "a token rotated out a moment ago is inside a one-second grace").toBe(true);
+                    await delay(1_200);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 1), "a grace that answers true regardless of elapsed time excuses " +
+                        "every replay while the family is live, which turns reuse " +
+                        "detection off").toBe(false);
+                    expect(await tokenService.isWithinReplayGrace(tombstone, 3600)).toBe(true);
+                });
             });
         }
         else {

package/dist/testing/services.d.ts

@@ -256,6 +256,13 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
     rotate(current: RefreshToken<C, U, S>, next: RefreshToken<C, U, S>): Promise<RefreshToken<C, U, S> | undefined>;
     /** Whether the family has a live refresh token that has not expired. */
     hasLiveRefreshToken(familyId: string): Promise<boolean>;
+    /**
+     * Whether the tombstone was rotated out no more than `graceSeconds` ago,
+     * judged from the rotation time this store recorded rather than the one on
+     * the record passed in. Resolves `false` for a token it holds no rotated-out
+     * tombstone for.
+     */
+    isWithinReplayGrace(tombstone: RefreshToken<C, U, S>, graceSeconds: number): 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

@@ -427,6 +427,18 @@ export class MemoryTokenService {
         }
         return Promise.resolve(false);
     }
+    /**
+     * Whether the tombstone was rotated out no more than `graceSeconds` ago,
+     * judged from the rotation time this store recorded rather than the one on
+     * the record passed in. Resolves `false` for a token it holds no rotated-out
+     * tombstone for.
+     */
+    async isWithinReplayGrace(tombstone, graceSeconds) {
+        const rotatedAt = this.#revokedByRefreshHash.get(await sha256Hash(tombstone.refreshToken))?.rotatedAt;
+        if (!rotatedAt)
+            return false;
+        return Date.now() - rotatedAt.getTime() <= graceSeconds * 1000;
+    }
     #tombstone(refreshTokenHash, stored) {
         this.#revokedByRefreshHash.set(refreshTokenHash, stored);
     }

package/package.json

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