@udibo/oauth2 0.22.0 → 0.23.0

package/dist/models/token.d.ts

@@ -67,10 +67,10 @@ export interface RefreshToken<Client extends ClientInterface, User, Scope extend
      */
     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.
+     * 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;
 }

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/services/token.d.ts

@@ -122,9 +122,11 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * 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}.
+     * 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>;
     /**
@@ -139,17 +141,32 @@ 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>;
     /**

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

@@ -285,6 +285,24 @@ export function runTokenServiceContractTests(options) {
                         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");
@@ -311,7 +329,7 @@ export function runTokenServiceContractTests(options) {
             });
         }
         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

@@ -256,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.
      *
@@ -340,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);
@@ -408,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.22.0",
+  "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",