@udibo/oauth2 0.24.0 → 0.25.0

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

@@ -86,10 +86,14 @@ export declare class RefreshTokenGrant<Client extends ClientInterface, User, S e
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements

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

@@ -32,10 +32,14 @@ export class RefreshTokenGrant extends AbstractGrant {
      * token (and rotates the refresh token when the token service supports it)
      * from a valid, unexpired refresh token.
      *
-     * Rotation revokes the exchanged token through the token service's
-     * `revokeRotated` when implemented, falling back to `revoke` — so a service
-     * whose `revoke` ends the owning session can keep this bookkeeping step
-     * from signing the person out.
+     * Rotation claims the exchanged token and saves its successor in one call
+     * to the token service's `rotate` when implemented. Otherwise it takes two
+     * calls: it revokes the exchanged token through `revokeRotated` when
+     * implemented, falling back to `revoke` — so a service whose `revoke` ends
+     * the owning session can keep this bookkeeping step from signing the
+     * person out — and then saves the successor. A refresh that presents the
+     * exchanged token between those two calls is treated as reuse
+     * ({@linkcode TokenServiceInterface.rotate} describes the cost).
      *
      * Rotation renews the refresh token's sliding lifetime, bounded by the
      * family's absolute cap when the token service implements
@@ -122,6 +126,13 @@ export class RefreshTokenGrant extends AbstractGrant {
         if (familyExpiresAt) {
             this.capAtFamilyExpiry(nextRefreshToken, familyExpiresAt);
         }
+        if (tokenService.rotate) {
+            const rotated = await tokenService.rotate(currentToken, nextRefreshToken);
+            if (!rotated) {
+                throw new InvalidGrantError("refresh_token was already consumed");
+            }
+            return rotated;
+        }
         const claimed = tokenService.revokeRotated
             ? await tokenService.revokeRotated(currentToken)
             : await tokenService.revoke(currentToken);

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

@@ -129,6 +129,32 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * it, so a sign-out racing a refresh still ends the successor.
      */
     revokeRotated?(token: RefreshToken<Client, User, Scope>): Promise<boolean>;
+    /**
+     * Rotates a refresh token in one atomic step: claims `current` and persists
+     * `next`, its successor in the same family, or does neither. Resolves the
+     * saved successor, or `undefined` with nothing persisted when `current` was
+     * already claimed or revoked, or its family has been revoked. Concurrent
+     * calls for one `current` produce exactly one successor.
+     *
+     * When implemented, the refresh grant calls it instead of
+     * {@linkcode revokeRotated} (or {@linkcode revoke}) followed by
+     * {@linkcode save}. Without it, the grant claims and saves in two calls,
+     * and a request that presents `current` between them finds it revoked with
+     * no live successor: reuse detection revokes the family and fires
+     * `onTokenReuse`, so a benign concurrent refresh signs the person out, and a
+     * store whose `revokeFamily` does not keep the family revoked leaves the
+     * successor live.
+     *
+     * Treat the claim as a rotation, never an end of grant: stamp the
+     * rotated-out record with {@linkcode RefreshToken.rotatedAt} exactly as
+     * {@linkcode revokeRotated} does, keep it findable through
+     * {@linkcode getRevokedRefreshToken}, and revoke its access token as
+     * `revokeRotated` would. Make it linearizable with
+     * {@linkcode revokeFamily}, as that method requires.
+     * `runTokenRotationContractTests` checks it under concurrent callers, with
+     * the store's barrier wired between its claim and its insert.
+     */
+    rotate?(current: RefreshToken<Client, User, Scope>, next: RefreshToken<Client, User, Scope>): Promise<RefreshToken<Client, User, Scope> | undefined>;
     /**
      * Revokes all tokens issued with the given authorization code.
      * Returns true if any tokens were revoked (indicating code replay).
@@ -164,9 +190,17 @@ export interface TokenServiceInterface<Client extends ClientInterface, User, Sco
      * `/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.
+     * Without {@linkcode rotate}, keep the family revoked: a successor that a
+     * concurrent rotation saves after this call must be stored already revoked,
+     * as `MemoryTokenService` does. A store that implements `rotate` meets this
+     * through the linearizability below, since the refresh grant then never
+     * saves a rotation's successor separately.
+     *
+     * With {@linkcode rotate}, make the two linearizable: once this resolves,
+     * the family has no live member and no later `rotate` of a member
+     * succeeds, and a `rotate` that committed before this began has its
+     * successor revoked. A store whose `rotate` can be paused between its claim
+     * and its insert meets this by taking one per-family lock in both methods.
      */
     revokeFamily?(familyId: string): Promise<boolean>;
     /**

package/dist/testing/contract/mod.d.ts

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, type UserServiceContractOptions, } from "./user.ts";
 export { type ClientServiceContractOptions, runClientServiceContractTests, } from "./client.ts";
 export { runTokenServiceContractTests, type TokenServiceContractOptions, } from "./token.ts";
+export { runTokenRotationContractTests, type TokenRotationBarriers, type TokenRotationContractOptions, type TokenRotationContractServices, } from "./token-rotation.ts";
 export { runTokenReaderContractTests, type TokenReaderContractFixture, type TokenReaderContractOptions, } from "./token-reader.ts";
 export { type AuthorizationCodeServiceContractOptions, runAuthorizationCodeServiceContractTests, } from "./authorization-code.ts";
 export { type DeviceAuthorizationServiceContractOptions, runDeviceAuthorizationServiceContractTests, } from "./device-authorization.ts";

package/dist/testing/contract/mod.js

@@ -24,6 +24,12 @@
  * also have separate suites. They use app-owned fixture helpers to verify
  * conditional credential writes and immediate, user-scoped session revocation.
  *
+ * `TokenServiceInterface.rotate` has a runner of its own for concurrent
+ * schedules: two rotations of one refresh token, a family revocation racing a
+ * rotation, and a replay racing a refresh. A store that awaits between its
+ * claim and its insert wires `TokenRotationBarriers` into `rotate`, so the
+ * suite can hold a rotation there.
+ *
  * The service runners take a factory plus seed helpers because `add` /
  * `register` methods aren't part of the public service interfaces — the
  * consumer tells the runner how to populate test data.
@@ -33,6 +39,7 @@
 export { runUserServiceContractTests, } from "./user.js";
 export { runClientServiceContractTests, } from "./client.js";
 export { runTokenServiceContractTests, } from "./token.js";
+export { runTokenRotationContractTests, } from "./token-rotation.js";
 export { runTokenReaderContractTests, } from "./token-reader.js";
 export { runAuthorizationCodeServiceContractTests, } from "./authorization-code.js";
 export { runDeviceAuthorizationServiceContractTests, } from "./device-authorization.js";

package/dist/testing/contract/token-rotation.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface.rotate} and its
+ * linearizability with {@link TokenServiceInterface.revokeFamily}.
+ *
+ * `runTokenServiceContractTests` checks what one caller sees. This suite
+ * checks what concurrent callers see: two rotations of one refresh token, a
+ * family revocation racing a rotation, a replay racing a refresh through the
+ * refresh grant, a rotation in an unrelated family, and a rotation whose
+ * insert fails. Each case asserts the store's end state, the live tokens of
+ * the family, not only the value each call resolved.
+ *
+ * The store under test awaits {@link TokenRotationBarriers.afterClaim} inside
+ * `rotate`, between its claim and its insert, so the suite can hold a rotation
+ * there and race the other call against it; a store that never reaches the
+ * barrier fails every held case. Only a store whose `rotate` never awaits
+ * between its claim and its insert, such as `MemoryTokenService`, opts out with
+ * `rotateAwaitsBarrier: false`; the suite then runs those schedules as
+ * overlapping calls.
+ *
+ * @module
+ */
+import type { ClientInterface } from "../../models/client.ts";
+import type { AbstractScope, BasicScope } from "../../models/scope.ts";
+import type { ClientServiceInterface } from "../../server/services/client.ts";
+import type { TokenServiceInterface } from "../../server/services/token.ts";
+import type { UserServiceInterface } from "../../server/services/user.ts";
+import type { MemoryUserShape } from "../services.ts";
+/**
+ * The point inside a store's {@linkcode TokenServiceInterface.rotate} at which
+ * {@link runTokenRotationContractTests} holds a rotation. Wire it into a test
+ * build of the store.
+ */
+export interface TokenRotationBarriers {
+    /**
+     * Await this inside `rotate` after claiming `current` and before persisting
+     * `next`, still inside the atomic step: within the transaction and holding
+     * the family's lock. When it rejects, fail the rotation as a failed insert
+     * would: leave `current` live, persist nothing, and reject or resolve
+     * `undefined`.
+     */
+    afterClaim(): Promise<void>;
+}
+/** Services built for each case of {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractServices<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /** The user service the token service hydrates users from. */
+    userService: UserServiceInterface<U>;
+    /** The client service the token service hydrates clients from. */
+    clientService: ClientServiceInterface<C, U>;
+    /** The token service under test. It must implement `rotate`. */
+    tokenService: TokenServiceInterface<C, U, S>;
+}
+/** Options for {@link runTokenRotationContractTests}. */
+export interface TokenRotationContractOptions<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope> {
+    /**
+     * Returns fresh services for each case, with `rotate` awaiting
+     * `barriers.afterClaim()` between its claim and its insert. A store that
+     * sets `rotateAwaitsBarrier: false` ignores `barriers`.
+     */
+    makeServices(barriers: TokenRotationBarriers): Promise<TokenRotationContractServices<C, U, S>> | TokenRotationContractServices<C, U, S>;
+    /** Persists a user with the given password into the user service under test. */
+    addUser(service: UserServiceInterface<U>, user: U, password: string): Promise<void>;
+    /** Persists a client into the client service under test. */
+    addClient(service: ClientServiceInterface<C, U>, client: C): Promise<void>;
+    /** Builds a distinct user fixture for the given sequence number. Defaults to a minimal `{ id, username }` shape. */
+    makeUser?(seq: number): U;
+    /** Builds a distinct client fixture for the given sequence number. Defaults to a client granting `authorization_code` and `refresh_token`. */
+    makeClient?(seq: number): C;
+    /**
+     * Whether `rotate` awaits `barriers.afterClaim()`. Defaults to `true`: the
+     * suite holds a rotation between its claim and its insert while it runs a
+     * family revocation, a second rotation, a replayed refresh, or a rotation in
+     * another family, and fails the insert there. Set `false` only when
+     * `rotate` never awaits between its claim and its insert, as in
+     * `MemoryTokenService`; the suite then runs those schedules as overlapping
+     * calls, which cannot reach a gap inside `rotate`.
+     */
+    rotateAwaitsBarrier?: boolean;
+    /**
+     * Milliseconds the suite lets a call run against a held rotation before it
+     * releases the rotation; a call that has not settled by then is taken to
+     * be waiting on it. Defaults to 100. Raise it for a store whose calls take
+     * longer to reach the lock they wait on.
+     */
+    blockedAfterMs?: number;
+    /** Overrides the name passed to the outer `describe` block. */
+    describeName?: string;
+}
+/**
+ * Runs the rotation contract suite: concurrent schedules of
+ * {@linkcode TokenServiceInterface.rotate} against itself, against
+ * {@linkcode TokenServiceInterface.revokeFamily}, and through the refresh
+ * grant. The service must implement `rotate`, `revokeFamily` and
+ * `getRevokedRefreshToken`.
+ */
+export declare function runTokenRotationContractTests<C extends ClientInterface, U extends MemoryUserShape, S extends AbstractScope = BasicScope>(options: TokenRotationContractOptions<C, U, S>): void;

package/dist/testing/contract/token-rotation.js

@@ -0,0 +1,383 @@
+/**
+ * Contract test suite for {@link TokenServiceInterface.rotate} and its
+ * linearizability with {@link TokenServiceInterface.revokeFamily}.
+ *
+ * `runTokenServiceContractTests` checks what one caller sees. This suite
+ * checks what concurrent callers see: two rotations of one refresh token, a
+ * family revocation racing a rotation, a replay racing a refresh through the
+ * refresh grant, a rotation in an unrelated family, and a rotation whose
+ * insert fails. Each case asserts the store's end state, the live tokens of
+ * the family, not only the value each call resolved.
+ *
+ * The store under test awaits {@link TokenRotationBarriers.afterClaim} inside
+ * `rotate`, between its claim and its insert, so the suite can hold a rotation
+ * there and race the other call against it; a store that never reaches the
+ * barrier fails every held case. Only a store whose `rotate` never awaits
+ * between its claim and its insert, such as `MemoryTokenService`, opts out with
+ * `rotateAwaitsBarrier: false`; the suite then runs those schedules as
+ * overlapping calls.
+ *
+ * @module
+ */
+import { assert, beforeEach, describe, expect, it } from "vitest";
+import { InvalidGrantError } from "../../errors.js";
+import { RefreshTokenGrant } from "../../server/grants/refresh-token.js";
+import { race } from "./_race.js";
+const defaultMakeUser = (seq) => ({ id: `u${seq}`, username: `user${seq}` });
+const defaultMakeClient = (seq) => ({
+    id: `client-${seq}`,
+    grants: ["authorization_code", "refresh_token"],
+});
+async function settledWithin(promise, ms) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(false), ms);
+    });
+    try {
+        return await Promise.race([
+            promise.then(() => true, () => true),
+            timeout,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs the rotation contract suite: concurrent schedules of
+ * {@linkcode TokenServiceInterface.rotate} against itself, against
+ * {@linkcode TokenServiceInterface.revokeFamily}, and through the refresh
+ * grant. The service must implement `rotate`, `revokeFamily` and
+ * `getRevokedRefreshToken`.
+ */
+export function runTokenRotationContractTests(options) {
+    const makeUser = options.makeUser ?? defaultMakeUser;
+    const makeClient = options.makeClient ?? defaultMakeClient;
+    const pausable = options.rotateAwaitsBarrier ?? true;
+    const blockedAfterMs = options.blockedAfterMs ?? 100;
+    describe(options.describeName ?? "TokenServiceInterface.rotate contract", () => {
+        let clientService;
+        let tokenService;
+        let user;
+        let client;
+        let armed;
+        let family;
+        let otherFamily;
+        const barriers = {
+            async afterClaim() {
+                const hold = armed;
+                if (!hold)
+                    return;
+                armed = undefined;
+                hold.reached.resolve();
+                await hold.release.promise;
+            },
+        };
+        beforeEach(async () => {
+            armed = undefined;
+            family = crypto.randomUUID();
+            otherFamily = crypto.randomUUID();
+            const services = await options.makeServices(barriers);
+            clientService = services.clientService;
+            tokenService = services.tokenService;
+            user = makeUser(1);
+            client = makeClient(1);
+            await options.addUser(services.userService, user, "pw");
+            await options.addClient(clientService, client);
+        });
+        function rotate(current, next) {
+            assert(typeof tokenService.rotate === "function", "runTokenRotationContractTests needs a token service that implements rotate");
+            return tokenService.rotate(current, next);
+        }
+        async function member(familyId) {
+            return {
+                accessToken: await tokenService.generateAccessToken(client, user),
+                accessTokenExpiresAt: new Date(Date.now() + 60_000),
+                refreshToken: (await tokenService.generateRefreshToken(client, user)),
+                refreshTokenExpiresAt: new Date(Date.now() + 600_000),
+                familyId,
+                familyCreatedAt: new Date(Date.now() - 60_000),
+                client,
+                user,
+            };
+        }
+        async function savedMember(familyId) {
+            const token = await member(familyId);
+            await tokenService.save(token);
+            return token;
+        }
+        async function live(tokens) {
+            const found = [];
+            for (const token of tokens) {
+                if ((await tokenService.getRefreshToken(token.refreshToken)) ||
+                    (await tokenService.getToken(token.accessToken))) {
+                    found.push(token);
+                }
+            }
+            return found;
+        }
+        async function liveOf(refreshTokens) {
+            const found = [];
+            for (const refreshToken of refreshTokens) {
+                if (await tokenService.getRefreshToken(refreshToken)) {
+                    found.push(refreshToken);
+                }
+            }
+            return found;
+        }
+        function arm() {
+            const hold = {
+                reached: Promise.withResolvers(),
+                release: Promise.withResolvers(),
+            };
+            armed = hold;
+            return hold;
+        }
+        async function untilHeld(hold, rotation, unheld = "rotate settled without awaiting barriers.afterClaim; wire " +
+            "the barrier into rotate between its claim and its insert, or, " +
+            "only if rotate never awaits between them, set " +
+            "rotateAwaitsBarrier: false") {
+            const outcome = await Promise.race([
+                hold.reached.promise.then(() => "held"),
+                rotation.then(() => "settled", () => "settled"),
+            ]);
+            assert(outcome === "held", unheld);
+        }
+        /**
+         * Runs `during` while `rotate(current, next)` is held after its claim,
+         * or, for a store that cannot be held, while the rotation is in flight.
+         */
+        async function whileRotating(current, next, during) {
+            if (!pausable) {
+                const rotation = rotate(current, next);
+                const other = during();
+                return await Promise.all([
+                    Promise.allSettled([rotation]).then(([r]) => r),
+                    Promise.allSettled([other]).then(([o]) => o),
+                ]);
+            }
+            const hold = arm();
+            const rotation = rotate(current, next);
+            await untilHeld(hold, rotation);
+            const other = during();
+            await settledWithin(other, blockedAfterMs);
+            hold.release.resolve();
+            return await Promise.all([
+                Promise.allSettled([rotation]).then(([r]) => r),
+                Promise.allSettled([other]).then(([o]) => o),
+            ]);
+        }
+        /**
+         * Wraps the token service to record every refresh token the grant
+         * generates, and to run `beforeRotate` before each `rotate` reaches the
+         * store.
+         */
+        function observe(beforeRotate) {
+            const issued = [];
+            const observed = new Proxy(tokenService, {
+                get(target, prop) {
+                    if (prop === "generateRefreshToken") {
+                        return async (...args) => {
+                            const value = await target.generateRefreshToken(...args);
+                            if (value)
+                                issued.push(value);
+                            return value;
+                        };
+                    }
+                    if (prop === "rotate" && beforeRotate) {
+                        return async (current, next) => {
+                            await beforeRotate();
+                            return await rotate(current, next);
+                        };
+                    }
+                    const value = Reflect.get(target, prop, target);
+                    return typeof value === "function" ? value.bind(target) : value;
+                },
+            });
+            return { observed, issued };
+        }
+        function refreshGrant(service, reuseEvents) {
+            return new RefreshTokenGrant({
+                resolve: () => ({ clientService, tokenService: service }),
+                onTokenReuse: (event) => {
+                    reuseEvents.push(event);
+                },
+            });
+        }
+        function refresh(grant, refreshToken) {
+            const body = new FormData();
+            body.set("grant_type", "refresh_token");
+            body.set("refresh_token", refreshToken);
+            return grant.token(new Request("https://as.test/token", { method: "POST" }), client, body);
+        }
+        it("implements rotate, revokeFamily and getRevokedRefreshToken", () => {
+            assert(typeof tokenService.rotate === "function" &&
+                typeof tokenService.revokeFamily === "function" &&
+                typeof tokenService.getRevokedRefreshToken === "function", "the rotation contract covers rotate together with reuse detection");
+        });
+        it("refuses to rotate a member of a family revoked before it began", async () => {
+            const parent = await savedMember(family);
+            const next = await member(family);
+            await tokenService.revokeFamily(family);
+            expect(await rotate(parent, next)).toBe(undefined);
+            expect(await live([parent, next]), "a rotation that starts after its family was revoked must not " +
+                "give the family a live member again").toStrictEqual([]);
+        });
+        it("leaves no live member when the family is revoked while a rotation is in flight", async () => {
+            const parent = await savedMember(family);
+            const next = await member(family);
+            const [rotated, revoked] = await whileRotating(parent, next, () => tokenService.revokeFamily(family));
+            assert(revoked.status === "fulfilled");
+            assert(rotated.status === "fulfilled");
+            expect([undefined, next.refreshToken]).toContain(rotated.value?.refreshToken);
+            expect(await live([parent, next]), "revokeFamily must wait for a rotation holding the family, or the " +
+                "successor that rotation commits afterwards stays live in a " +
+                "family the server revoked").toStrictEqual([]);
+        });
+        it("revokes the successor of a rotation that committed before the family was revoked", async () => {
+            const parent = await savedMember(family);
+            const next = await member(family);
+            expect((await rotate(parent, next))?.refreshToken).toBe(next.refreshToken);
+            expect(await tokenService.revokeFamily(family)).toBe(true);
+            expect(await live([parent, next])).toStrictEqual([]);
+        });
+        it("gives concurrent rotations of one refresh token exactly one successor", async () => {
+            const parent = await savedMember(family);
+            const successors = await race(() => member(family));
+            const results = await race((caller) => rotate(parent, successors[caller]));
+            expect(results.filter((result) => result !== undefined).length, "rotate must claim its parent once, however many callers race").toBe(1);
+            expect(await live([parent, ...successors])).toHaveLength(1);
+        });
+        it("refuses a second rotation that starts while the first is held after its claim", async ({ skip, }) => {
+            skip(!pausable, "rotate cannot be held (rotateAwaitsBarrier: false)");
+            const parent = await savedMember(family);
+            const first = await member(family);
+            const second = await member(family);
+            const [held, racing] = await whileRotating(parent, first, () => rotate(parent, second));
+            assert(held.status === "fulfilled" && racing.status === "fulfilled");
+            expect(held.value?.refreshToken).toBe(first.refreshToken);
+            expect(racing.value).toBe(undefined);
+            expect(await live([parent, first, second])).toStrictEqual([first]);
+        });
+        it("answers a refresh that loses the claim to a concurrent one with invalid_grant, keeping the winner's successor", async () => {
+            const parent = await savedMember(family);
+            const held = Promise.withResolvers();
+            const release = Promise.withResolvers();
+            let rotations = 0;
+            const { observed, issued } = observe(async () => {
+                if (rotations++ === 0) {
+                    held.resolve();
+                    await release.promise;
+                }
+            });
+            const reuseEvents = [];
+            const grant = refreshGrant(observed, reuseEvents);
+            const first = refresh(grant, parent.refreshToken);
+            await untilHeld({ reached: held }, first, "the refresh grant settled without calling rotate");
+            const second = await refresh(grant, parent.refreshToken);
+            release.resolve();
+            const firstOutcome = await Promise.allSettled([first]);
+            assert(firstOutcome[0].status === "rejected");
+            expect(firstOutcome[0].reason).toBeInstanceOf(InvalidGrantError);
+            expect(reuseEvents, "losing the claim is a race, not a replay of a rotated-out token").toStrictEqual([]);
+            const liveRefreshTokens = await liveOf([
+                parent.refreshToken,
+                ...issued,
+            ]);
+            expect(liveRefreshTokens).toStrictEqual([second.refreshToken]);
+        });
+        it("answers a replay that arrives while a rotation is held after its claim with invalid_grant, without revoking the family", async ({ skip, }) => {
+            skip(!pausable, "rotate cannot be held (rotateAwaitsBarrier: false)");
+            const parent = await savedMember(family);
+            const { observed, issued } = observe();
+            const reuseEvents = [];
+            const grant = refreshGrant(observed, reuseEvents);
+            const hold = arm();
+            const first = refresh(grant, parent.refreshToken);
+            await untilHeld(hold, first);
+            const replay = refresh(grant, parent.refreshToken);
+            await settledWithin(replay, blockedAfterMs);
+            hold.release.resolve();
+            const [firstOutcome, replayOutcome] = await Promise.allSettled([
+                first,
+                replay,
+            ]);
+            assert(firstOutcome.status === "fulfilled");
+            assert(replayOutcome.status === "rejected");
+            expect(replayOutcome.reason).toBeInstanceOf(InvalidGrantError);
+            expect(reuseEvents, "a replay inside the claim-to-insert gap found no live successor " +
+                "and was taken for theft").toStrictEqual([]);
+            const liveRefreshTokens = await liveOf([
+                parent.refreshToken,
+                ...issued,
+            ]);
+            expect(liveRefreshTokens).toStrictEqual([
+                firstOutcome.value.refreshToken,
+            ]);
+        });
+        it("does not hold a rotation in another family behind a held one", async () => {
+            const parent = await savedMember(family);
+            const next = await member(family);
+            const otherParent = await savedMember(otherFamily);
+            const otherNext = await member(otherFamily);
+            if (!pausable) {
+                const [rotated, other] = await Promise.all([
+                    rotate(parent, next),
+                    rotate(otherParent, otherNext),
+                ]);
+                expect(rotated?.refreshToken).toBe(next.refreshToken);
+                expect(other?.refreshToken).toBe(otherNext.refreshToken);
+                return;
+            }
+            const hold = arm();
+            const rotation = rotate(parent, next);
+            await untilHeld(hold, rotation);
+            const other = rotate(otherParent, otherNext);
+            const settled = await settledWithin(other, 5_000);
+            hold.release.resolve();
+            expect(settled, "the family lock must be keyed by family, so one login's " +
+                "rotation never waits on another's").toBe(true);
+            expect((await other)?.refreshToken).toBe(otherNext.refreshToken);
+            expect((await rotation)?.refreshToken).toBe(next.refreshToken);
+        });
+        it("leaves the parent live and persists nothing when the successor cannot be persisted", async () => {
+            const parent = await savedMember(family);
+            const unpersistable = await member(family);
+            Object.defineProperty(unpersistable, "refreshToken", {
+                enumerable: true,
+                get() {
+                    throw new Error("forced persistence failure");
+                },
+            });
+            const outcome = await Promise.allSettled([
+                rotate(parent, unpersistable),
+            ]);
+            if (outcome[0].status === "fulfilled") {
+                expect(outcome[0].value).toBe(undefined);
+            }
+            expect(await tokenService.getRefreshToken(parent.refreshToken), "a failed rotation must not spend its parent").not.toBe(undefined);
+            expect(await tokenService.getToken(unpersistable.accessToken)).toBe(undefined);
+            const retry = await member(family);
+            expect((await rotate(parent, retry))?.refreshToken).toBe(retry.refreshToken);
+        });
+        it("rolls the claim back when the insert fails after it", async ({ skip, }) => {
+            skip(!pausable, "rotate cannot be held (rotateAwaitsBarrier: false)");
+            const parent = await savedMember(family);
+            const next = await member(family);
+            const hold = arm();
+            const rotation = rotate(parent, next);
+            await untilHeld(hold, rotation);
+            hold.release.reject(new Error("forced insert failure"));
+            const outcome = await Promise.allSettled([rotation]);
+            if (outcome[0].status === "fulfilled") {
+                expect(outcome[0].value).toBe(undefined);
+            }
+            expect(await tokenService.getRefreshToken(parent.refreshToken), "the claim and the insert are one step: a failed insert must " +
+                "leave the parent live").not.toBe(undefined);
+            expect(await live([next])).toStrictEqual([]);
+            expect(await tokenService.getRevokedRefreshToken(next.refreshToken)).toBe(undefined);
+            const retry = await member(family);
+            expect((await rotate(parent, retry))?.refreshToken, "a failed rotation must release the family").toBe(retry.refreshToken);
+        });
+    });
+}

package/dist/testing/contract/token.d.ts

@@ -12,6 +12,9 @@
  * with `user: undefined` and persists a token whose `user` is unset — a store
  * that requires a user cannot hold a machine token.
  *
+ * When the service implements `rotate`, its single-caller contract is checked
+ * here too; `runTokenRotationContractTests` checks it under concurrent callers.
+ *
  * @module
  */
 import type { ClientInterface } from "../../models/client.ts";

package/dist/testing/contract/token.js

@@ -12,6 +12,9 @@
  * with `user: undefined` and persists a token whose `user` is unset — a store
  * that requires a user cannot hold a machine token.
  *
+ * When the service implements `rotate`, its single-caller contract is checked
+ * here too; `runTokenRotationContractTests` checks it under concurrent callers.
+ *
  * @module
  */
 import { assert, beforeEach, describe, expect, it } from "vitest";
@@ -212,10 +215,10 @@ export function runTokenServiceContractTests(options) {
             describe("refresh-token rotation family", () => {
                 const FAMILY = "family-1";
                 const OTHER_FAMILY = "family-2";
-                async function saveFamilyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
+                async function familyMember(familyId, refreshTokenExpiresAt = new Date(Date.now() + 600_000)) {
                     const accessToken = await tokenService.generateAccessToken(client, user);
                     const refreshToken = (await tokenService.generateRefreshToken(client, user));
-                    const token = {
+                    return {
                         accessToken,
                         accessTokenExpiresAt: new Date(Date.now() + 60_000),
                         refreshToken,
@@ -225,6 +228,9 @@ export function runTokenServiceContractTests(options) {
                         client,
                         user,
                     };
+                }
+                async function saveFamilyMember(familyId, refreshTokenExpiresAt) {
+                    const token = await familyMember(familyId, refreshTokenExpiresAt);
                     await tokenService.save(token);
                     return token;
                 }
@@ -285,6 +291,42 @@ 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("rotates in one call: the parent is spent and stamped, the successor live", async ({ skip, }) => {
+                    skip(typeof tokenService.rotate !== "function", "the service does not implement rotate");
+                    const parent = await saveFamilyMember(FAMILY);
+                    const next = await familyMember(FAMILY);
+                    const before = Date.now();
+                    const rotated = await tokenService.rotate(parent, next);
+                    expect(rotated?.refreshToken).toBe(next.refreshToken);
+                    expect((await tokenService.getRefreshToken(next.refreshToken))?.familyId).toBe(FAMILY);
+                    expect(await tokenService.getToken(next.accessToken)).not.toBe(undefined);
+                    expect(await tokenService.getRefreshToken(parent.refreshToken)).toBe(undefined);
+                    expect(await tokenService.getToken(parent.accessToken), "rotation ends the parent's access token, as revokeRotated does").toBe(undefined);
+                    const tombstone = await tokenService.getRevokedRefreshToken(parent.refreshToken);
+                    expect(tombstone?.familyId).toBe(FAMILY);
+                    assert(tombstone?.rotatedAt instanceof Date &&
+                        tombstone.rotatedAt.getTime() >= before - 1000 &&
+                        tombstone.rotatedAt.getTime() <= Date.now() + 1000, "rotate must stamp rotatedAt as revokeRotated does, or the " +
+                        "refresh grant's replayGraceSeconds and the revocation " +
+                        "endpoint's family revocation stop applying");
+                });
+                it("refuses to rotate a refresh token that is no longer live, persisting nothing", async ({ skip, }) => {
+                    skip(typeof tokenService.rotate !== "function", "the service does not implement rotate");
+                    const parent = await saveFamilyMember(FAMILY);
+                    const first = await familyMember(FAMILY);
+                    const second = await familyMember(FAMILY);
+                    const revokedParent = await saveFamilyMember(FAMILY);
+                    const third = await familyMember(FAMILY);
+                    await tokenService.revoke(revokedParent.refreshToken, "refresh_token");
+                    expect(await tokenService.rotate(parent, first)).not.toBe(undefined);
+                    expect(await tokenService.rotate(parent, second), "a refresh token is claimed once").toBe(undefined);
+                    expect(await tokenService.rotate(revokedParent, third)).toBe(undefined);
+                    for (const refused of [second, third]) {
+                        expect(await tokenService.getRefreshToken(refused.refreshToken)).toBe(undefined);
+                        expect(await tokenService.getToken(refused.accessToken)).toBe(undefined);
+                        expect(await tokenService.getRevokedRefreshToken(refused.refreshToken)).toBe(undefined);
+                    }
+                });
                 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);

package/dist/testing/services.d.ts

@@ -247,6 +247,13 @@ export declare class MemoryTokenService<C extends ClientInterface, U extends Mem
      * token was already claimed.
      */
     revokeRotated(token: RefreshToken<C, U, S>): Promise<boolean>;
+    /**
+     * Claims `current` and saves `next` in one step, stamping the rotated-out
+     * tombstone with `rotatedAt` as {@linkcode revokeRotated} does. Resolves
+     * `undefined`, saving nothing, when `current` is no longer live or either
+     * token's family has been revoked.
+     */
+    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>;
     /**

package/dist/testing/services.js

@@ -317,38 +317,46 @@ export class MemoryTokenService {
         return this.#hydrate(stored, "", refreshToken);
     }
     async save(token) {
-        const accessTokenHash = await sha256Hash(token.accessToken);
+        this.#store(await this.#prepare(token));
+        return token;
+    }
+    async #prepare(token) {
         const stored = {
-            accessTokenHash,
+            accessTokenHash: await sha256Hash(token.accessToken),
             accessTokenExpiresAt: token.accessTokenExpiresAt,
             clientId: token.client.id,
             userId: token.user?.id,
             scope: token.scope,
             authenticationContext: snapshotAuthenticationContext(token.authenticationContext),
         };
-        if (token.code) {
+        if (token.code)
             stored.codeHash = await sha256Hash(token.code);
-            let bucket = this.#tokensByCodeHash.get(stored.codeHash);
-            if (!bucket) {
-                bucket = new Set();
-                this.#tokensByCodeHash.set(stored.codeHash, bucket);
-            }
-            bucket.add(accessTokenHash);
-        }
         if ("refreshToken" in token) {
             const rt = token;
             stored.refreshTokenHash = await sha256Hash(rt.refreshToken);
             stored.refreshTokenExpiresAt = rt.refreshTokenExpiresAt;
             stored.familyId = rt.familyId;
             stored.familyCreatedAt = rt.familyCreatedAt;
-            if (rt.familyId && this.#revokedFamilies.has(rt.familyId)) {
+        }
+        return stored;
+    }
+    #store(stored) {
+        if (stored.codeHash) {
+            let bucket = this.#tokensByCodeHash.get(stored.codeHash);
+            if (!bucket) {
+                bucket = new Set();
+                this.#tokensByCodeHash.set(stored.codeHash, bucket);
+            }
+            bucket.add(stored.accessTokenHash);
+        }
+        if (stored.refreshTokenHash) {
+            if (stored.familyId && this.#revokedFamilies.has(stored.familyId)) {
                 this.#tombstone(stored.refreshTokenHash, stored);
-                return token;
+                return;
             }
             this.#tokensByRefreshHash.set(stored.refreshTokenHash, stored);
         }
-        this.#tokensByAccessHash.set(accessTokenHash, stored);
-        return token;
+        this.#tokensByAccessHash.set(stored.accessTokenHash, stored);
     }
     async revoke(token, hint) {
         if (typeof token !== "string") {
@@ -386,6 +394,27 @@ export class MemoryTokenService {
         stored.rotatedAt = new Date();
         return await this.revoke(token);
     }
+    /**
+     * Claims `current` and saves `next` in one step, stamping the rotated-out
+     * tombstone with `rotatedAt` as {@linkcode revokeRotated} does. Resolves
+     * `undefined`, saving nothing, when `current` is no longer live or either
+     * token's family has been revoked.
+     */
+    async rotate(current, next) {
+        const currentHash = await sha256Hash(current.refreshToken);
+        const successor = await this.#prepare(next);
+        const stored = this.#tokensByRefreshHash.get(currentHash);
+        if (!stored ||
+            [stored.familyId, successor.familyId].some((familyId) => familyId && this.#revokedFamilies.has(familyId))) {
+            return undefined;
+        }
+        stored.rotatedAt = new Date();
+        this.#tokensByAccessHash.delete(stored.accessTokenHash);
+        this.#tokensByRefreshHash.delete(currentHash);
+        this.#tombstone(currentHash, stored);
+        this.#store(successor);
+        return next;
+    }
     /** Whether the family has a live refresh token that has not expired. */
     hasLiveRefreshToken(familyId) {
         const now = Date.now();

package/package.json

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