@udibo/oauth2 0.29.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/jwks-token-reader.d.ts

@@ -2,10 +2,11 @@
  * Token reader that validates JWT access tokens locally against the
  * issuer's published JWKS, with no per-request network hop.
  *
- * This is the validating half of RFC 9068 (`at+jwt`): the authorization
- * server signs access tokens and publishes its public keys at a `jwks_uri`;
- * the resource server fetches those keys once, caches them, and verifies
- * every subsequent token in-process. Signature verification uses Web Crypto
+ * It validates RFC 9068 (`at+jwt`) access tokens: the authorization server
+ * signs access tokens and publishes its public keys at a `jwks_uri`; the
+ * resource server fetches those keys once, caches them, and verifies every
+ * subsequent token in-process, including the `typ` header and every claim
+ * RFC 9068 §2.2 makes REQUIRED. Signature verification uses Web Crypto
  * only — the package takes no JOSE dependency.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc9068
@@ -27,19 +28,25 @@ import type { TokenReaderInterface } from "./services/token.ts";
 export interface JwtAccessTokenClaims {
     /** Issuer that signed the token. Verified against the configured issuer. */
     iss: string;
-    /** Subject — the end user, or the client itself for client-credentials tokens. */
-    sub?: string;
+    /** Subject — the end user, or the client itself for client-credentials tokens. Required. */
+    sub: string;
     /** Audience(s) the token is intended for. Verified against the configured audience. */
     aud: string | string[];
     /** Expiration time, seconds since the epoch. */
     exp: number;
-    /** Issued-at time, seconds since the epoch. */
-    iat?: number;
+    /** Issued-at time, seconds since the epoch. Required. */
+    iat: number;
     /** Not-before time, seconds since the epoch. */
     nbf?: number;
-    /** Unique token identifier. */
+    /**
+     * Unique token identifier. Required unless
+     * {@linkcode JwksTokenReaderOptions.tokenIdClaim} names another claim.
+     */
     jti?: string;
-    /** Client the token was issued to. */
+    /**
+     * Client the token was issued to. Required unless
+     * {@linkcode JwksTokenReaderOptions.clientIdClaim} names another claim.
+     */
     client_id?: string;
     /** Space-delimited granted scopes. */
     scope?: string;
@@ -105,9 +112,18 @@ export interface JwksTokenReaderOptions<Client extends ClientInterface, User, S
      * §2.2 makes `client_id` REQUIRED, and its absence is what tells an
      * `id_token` apart from an access token). Defaults to `"client_id"`; point
      * it at the vendor claim for issuers that deviate — Okta's `cid`, Azure
-     * AD v1's `appid`. There is deliberately no way to drop the requirement.
+     * AD v1's `appid`. The requirement cannot be turned off, but pointing this
+     * at a claim every token carries defeats it.
      */
     clientIdClaim?: string;
+    /**
+     * Claim carrying the unique token identifier, required on every accepted
+     * token (RFC 9068 §2.2 makes `jti` REQUIRED). Defaults to `"jti"`; point it
+     * at the vendor claim for issuers that deviate — Microsoft Entra ID's
+     * `uti`. The requirement cannot be turned off, but pointing this at a claim
+     * every token carries defeats it.
+     */
+    tokenIdClaim?: string;
     /**
      * Leeway in seconds applied to `exp` and `nbf` to absorb clock drift
      * between the issuer and this server. Defaults to 30. Must be finite and
@@ -239,7 +255,8 @@ export declare class JwksTokenReader<Client extends ClientInterface, User, S ext
     #private;
     /**
      * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
-     * required as `typ`, `client_id` as the required client-id claim, 30
+     * required as `typ`, `client_id` as the required client-id claim, `jti` as
+     * the required token-identifier claim, 30
      * seconds of clock skew, a 10-minute cache with a 30-second minimum
      * between fetches, a 5-second request deadline, a 256 KiB response cap,
      * {@linkcode BasicScope}, and the global `fetch`.

package/dist/server/jwks-token-reader.js

@@ -2,10 +2,11 @@
  * Token reader that validates JWT access tokens locally against the
  * issuer's published JWKS, with no per-request network hop.
  *
- * This is the validating half of RFC 9068 (`at+jwt`): the authorization
- * server signs access tokens and publishes its public keys at a `jwks_uri`;
- * the resource server fetches those keys once, caches them, and verifies
- * every subsequent token in-process. Signature verification uses Web Crypto
+ * It validates RFC 9068 (`at+jwt`) access tokens: the authorization server
+ * signs access tokens and publishes its public keys at a `jwks_uri`; the
+ * resource server fetches those keys once, caches them, and verifies every
+ * subsequent token in-process, including the `typ` header and every claim
+ * RFC 9068 §2.2 makes REQUIRED. Signature verification uses Web Crypto
  * only — the package takes no JOSE dependency.
  *
  * @see https://datatracker.ietf.org/doc/html/rfc9068
@@ -208,6 +209,7 @@ export class JwksTokenReader {
     #algorithms;
     #types;
     #clientIdClaim;
+    #tokenIdClaim;
     #clockSkewSeconds;
     #cacheMaxAgeMs;
     #minFetchIntervalMs;
@@ -225,7 +227,8 @@ export class JwksTokenReader {
     #inFlight;
     /**
      * Defaults: every Web Crypto asymmetric algorithm accepted, `at+jwt`
-     * required as `typ`, `client_id` as the required client-id claim, 30
+     * required as `typ`, `client_id` as the required client-id claim, `jti` as
+     * the required token-identifier claim, 30
      * seconds of clock skew, a 10-minute cache with a 30-second minimum
      * between fetches, a 5-second request deadline, a 256 KiB response cap,
      * {@linkcode BasicScope}, and the global `fetch`.
@@ -254,6 +257,7 @@ export class JwksTokenReader {
         }
         this.#types = (options.types ?? ["at+jwt"]).map(normalizeType);
         this.#clientIdClaim = options.clientIdClaim ?? "client_id";
+        this.#tokenIdClaim = options.tokenIdClaim ?? "jti";
         this.#clockSkewSeconds = options.clockSkewSeconds ?? 30;
         assertClockSkewSeconds(this.#clockSkewSeconds);
         this.#cacheMaxAgeMs = options.cacheMaxAgeMs ?? 600_000;
@@ -336,9 +340,14 @@ export class JwksTokenReader {
     #validClaims(claims) {
         if (claims.iss !== this.#issuer)
             return false;
-        const clientId = claims[this.#clientIdClaim];
-        if (typeof clientId !== "string" || !clientId)
+        for (const claim of [this.#clientIdClaim, this.#tokenIdClaim, "sub"]) {
+            const value = claims[claim];
+            if (typeof value !== "string" || !value)
+                return false;
+        }
+        if (typeof claims.iat !== "number" || !Number.isFinite(claims.iat)) {
             return false;
+        }
         for (const claim of ID_TOKEN_ONLY_CLAIMS) {
             if (claims[claim] !== undefined)
                 return false;

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.29.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",