@starci/auth 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.1 - 2026-11-03
+
+- Fixed: a refresh replayed inside the grace window no longer signs the person out 30 seconds later. When a rotation's response never reached the browser (a navigation or an abort cut it), the next load presented the spent token, was answered an access token with no cookie (`cookieKept`) and the first load after the grace was reuse. Now `AuthSessions.refresh` gives such a replay a successor of its own in the same session and `AuthDoors.refresh` sets it as the cookie, at most `RACED_SUCCESSORS_MAX` (3) times per rotated token (`raced_count`); one more replay is reuse and ends the session, which revokes every token of it, as sign-out does. `SessionTokens.cookieKept` is removed; the session door never touched the cookie.
+- Changed: `RefreshTokenRecord` carries `racedCount`, `SessionTransaction` gains `markTokenRaced(tokenId, racedCount)`, and `insertToken` takes neither `usedAt` nor `racedCount`; `MemorySessionStore` implements them. `migrations/identity-sessions.sql` holds `raced_count integer not null default 0`, and `migrations/identity-refresh-raced-successors.sql` adds it to a baseline rendered from 0.2.0. Specs: the raced successor refreshes once, the sibling works, a replay after the grace ends the session, the cap, reuse revokes every sibling, and two parallel 401s renew with one refresh.
+
+## 0.2.0 - 2026-11-03
+
+- Added: `createSessionStore` and `createSingleFlight` in `@starci/auth/client`, the provider-agnostic session snapshot (snapshot, listeners, watchers, the first answer of a subscription) and the refresh-race guard (many requests answered 401 together refresh once, the others await it), each explicitly typed; `createAuthClient` is built on them and behaves as before. `@starci/auth-oidc/client` imports them instead of keeping a copy. Specs: `src/client/session.spec.ts` (one test per race case).
+
 ## 0.1.0 - 2026-11-03
 
 The sign-in of a lite StarCi app in one package, lifted from the product that ran it in production and generalised: no product names, every setting a typed option, no environment read.

package/README.md

@@ -23,7 +23,7 @@ AuthModule.registerAsync({
 })
 ```
 
-The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; secrets are passed as `{ reveal(): string }` holders or text. The app implements `SessionStore` over the tables of `migrations/identity-sessions.sql`, `AccountDirectory` over its user table, `RateCounter` over its shared counter, and `AuthAuthenticator` (the password and Google decisions) using `AuthPasswords` and `SignInBudget.counted` from the module.
+The package reads no environment. The app parses its settings (BE-CONFIG-2) and passes typed options; secrets are passed as `{ reveal(): string }` holders or text. The app implements `SessionStore` over the tables of `migrations/identity-sessions.sql` (an app whose baseline holds the 0.2.0 tables adds `migrations/identity-refresh-raced-successors.sql`), `AccountDirectory` over its account doors (in a StarCi lite app, the managed `persistence/account-doors.port.ts` over the SECURITY DEFINER `be_auth_*` functions of the baseline), `RateCounter` over its shared counter, and `AuthAuthenticator` (the password and Google decisions) using `AuthPasswords` and `SignInBudget.counted` from the module.
 
 Key rotation: list the new key first with its private key, keep the old key with its public key only, deploy, and drop the old key once its access tokens have expired. Every listed key verifies and is published by `AuthSessions.jwks()`.
 

package/dist/client/auth-client.d.ts

@@ -1,19 +1,17 @@
 import type { AccessGrant, AuthDoorName, AuthOutcome, SessionUser } from "../contracts/index.js";
 import type { StatusCodes } from "./outcome.js";
+import type { SessionEvent, SessionListener, SessionSnapshot } from "./session.js";
 /** What a door answered. A refusal is an answer, not a throw: the status says what happened. */
 export interface AuthDoorAnswer {
     readonly status: number;
     readonly body: unknown;
 }
 /** The event a listener hears. */
-export type AuthEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+export type AuthEvent = SessionEvent;
 /** Called on every sign-in, sign-out and token refresh with the id of the person the session belongs to (null when signed out). */
-export type AuthListener = (event: AuthEvent, userId: string | null) => void;
+export type AuthListener = SessionListener;
 /** What a view reads: loading until the first answer, then signed in or out. The object changes only when the session does. */
-export interface AuthSnapshot {
-    readonly status: "loading" | "signed-in" | "signed-out";
-    readonly user: SessionUser | null;
-}
+export type AuthSnapshot = SessionSnapshot<SessionUser>;
 /** The options of the client. */
 export interface AuthClientOptions {
     /** The API origin the doors live on. */

package/dist/client/auth-client.js

@@ -1,6 +1,6 @@
 import { AUTH_DOORS } from "../contracts/index.js";
 import { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientStatus } from "./outcome.js";
-const LOADING = { status: "loading", user: null };
+import { createSessionStore, createSingleFlight } from "./session.js";
 const isGrant = (value) => typeof value === "object" &&
     value !== null &&
     "accessToken" in value &&
@@ -46,28 +46,25 @@ export const createAuthClient = (options) => {
     let expiresAt = 0;
     let announced = false;
     let user = null;
-    let inFlight;
-    let snapshot = LOADING;
-    const listeners = new Set();
-    const watchers = new Set();
-    const setSnapshot = (next) => {
-        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email)
-            return;
-        snapshot = next;
-        for (const watcher of watchers)
-            watcher();
-    };
-    const notify = (event) => {
-        for (const listener of listeners)
-            listener(event, user?.id ?? null);
-    };
+    // The snapshot, the listeners and the watchers are the session store shared with every provider's client (./session.ts); the first
+    // answer of a subscription reads this client's facts at call time.
+    const store = createSessionStore({
+        announced: () => announced,
+        announce: () => {
+            announced = true;
+        },
+        held: () => token !== undefined,
+        userId: () => user?.id ?? null,
+        renew: () => renew(),
+        refreshing: () => flight.running(),
+    });
     const keep = (grant, event = "TOKEN_REFRESHED") => {
         token = grant.accessToken;
         expiresAt = now() + grant.expiresIn * MILLISECONDS;
         announced = true;
         user = userOf(grant);
-        setSnapshot({ status: "signed-in", user });
-        notify(event);
+        store.signedIn(user);
+        store.emit(event, user?.id ?? null);
     };
     const drop = () => {
         const had = token !== undefined;
@@ -75,9 +72,9 @@ export const createAuthClient = (options) => {
         expiresAt = 0;
         announced = true;
         user = null;
-        setSnapshot({ status: "signed-out", user: null });
+        store.signedOut();
         if (had)
-            notify("SIGNED_OUT");
+            store.emit("SIGNED_OUT", null);
     };
     const door = async (name, body, cookie) => {
         const get = name === "session" || name === "jwks";
@@ -121,12 +118,9 @@ export const createAuthClient = (options) => {
             return attempt < attemptsMax ? retry() : undefined;
         }
     };
-    const renew = () => {
-        inFlight ??= requestRefresh().finally(() => {
-            inFlight = undefined;
-        });
-        return inFlight;
-    };
+    // Many requests answered 401 together refresh once: the others await the one in flight.
+    const flight = createSingleFlight(() => requestRefresh());
+    const renew = () => flight.run();
     const accessToken = async () => token !== undefined && expiresAt - refreshAheadMs > now() ? token : renew();
     const outcomeOfAnswer = (answer, fallbacks) => {
         if (answer.status >= 200 && answer.status < 300)
@@ -161,33 +155,6 @@ export const createAuthClient = (options) => {
         }
         drop();
     };
-    const subscribe = (listener) => {
-        listeners.add(listener);
-        if (announced) {
-            listener("INITIAL_SESSION", user?.id ?? null);
-        }
-        else {
-            void renew().then(() => {
-                if (!announced)
-                    announced = true;
-                if (token === undefined) {
-                    setSnapshot({ status: "signed-out", user: null });
-                    listener("INITIAL_SESSION", null);
-                }
-            });
-        }
-        return () => {
-            listeners.delete(listener);
-        };
-    };
-    const watch = (onChange) => {
-        watchers.add(onChange);
-        if (!announced && inFlight === undefined)
-            void renew().then(() => undefined);
-        return () => {
-            watchers.delete(onChange);
-        };
-    };
     const checkSession = async (cookie) => {
         if (cookie === null || cookie === "")
             return authFailure("refused", "no-session");
@@ -216,10 +183,10 @@ export const createAuthClient = (options) => {
         },
         keep,
         drop,
-        subscribe,
-        getSnapshot: () => snapshot,
-        getServerSnapshot: () => LOADING,
-        watch,
+        subscribe: store.subscribe,
+        getSnapshot: store.getSnapshot,
+        getServerSnapshot: store.getServerSnapshot,
+        watch: store.watch,
         checkSession,
     };
 };

package/dist/client/index.d.ts

@@ -4,3 +4,5 @@ export { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientSta
 export type { StatusCodes } from "./outcome.js";
 export { EMAIL_PATTERN, NAME_MIN_LENGTH, PASSWORD_MIN_LENGTH, RESEND_COOLDOWN_SECONDS, authErrorKey, isLinkInvalid, passwordStrength, strengthKey, } from "./shared.js";
 export type { AuthErrorKey, Strength } from "./shared.js";
+export { createSessionStore, createSingleFlight } from "./session.js";
+export type { SessionEvent, SessionListener, SessionPerson, SessionSnapshot, SessionSource, SessionStore, SingleFlight } from "./session.js";

package/dist/client/index.js

@@ -1,3 +1,4 @@
 export { createAuthClient } from "./auth-client.js";
 export { authFailure, authOk, failureOfStatus, isSignedOutStatus, isTransientStatus, kindOfStatus } from "./outcome.js";
 export { EMAIL_PATTERN, NAME_MIN_LENGTH, PASSWORD_MIN_LENGTH, RESEND_COOLDOWN_SECONDS, authErrorKey, isLinkInvalid, passwordStrength, strengthKey, } from "./shared.js";
+export { createSessionStore, createSingleFlight } from "./session.js";

package/dist/client/session.d.ts

@@ -0,0 +1,57 @@
+/** The events a session listener hears. */
+export type SessionEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED";
+/** The person of a session as a view reads it. */
+export interface SessionPerson {
+    readonly id: string;
+    readonly email: string;
+}
+/** What a view reads: loading until the first answer, then signed in or out. The object changes only when the session does. */
+export interface SessionSnapshot<User extends SessionPerson> {
+    readonly status: "loading" | "signed-in" | "signed-out";
+    readonly user: User | null;
+}
+/** Called on every sign-in, sign-out and token refresh with the id of the person (null when signed out). */
+export type SessionListener = (event: SessionEvent, userId: string | null) => void;
+/** What the store asks of the client that owns it: the facts the first answer of a subscription depends on. */
+export interface SessionSource {
+    /** Whether the client has answered once (a refresh, a sign-in or a sign-out happened). */
+    announced(): boolean;
+    /** Records that the first answer was given. */
+    announce(): void;
+    /** Whether a token is held now. */
+    held(): boolean;
+    /** The id of the signed-in person, or null. */
+    userId(): string | null;
+    /** Starts (or joins) a refresh. */
+    renew(): Promise<unknown>;
+    /** Whether a refresh is running. */
+    refreshing(): boolean;
+}
+/** The snapshot, the listeners and the watchers of one client, shared by every provider's client. */
+export interface SessionStore<User extends SessionPerson> {
+    /** The current snapshot (stable between changes). */
+    getSnapshot: () => SessionSnapshot<User>;
+    /** The snapshot for server rendering: always loading. */
+    getServerSnapshot: () => SessionSnapshot<User>;
+    /** Publishes the snapshot of a signed-in person; watchers hear it only when status, id or email changed. */
+    signedIn: (user: User | null) => void;
+    /** Publishes the signed-out snapshot. */
+    signedOut: () => void;
+    /** Tells every listener an event with the id of the person it concerns. */
+    emit: (event: SessionEvent, userId: string | null) => void;
+    /** Listens to events; the first answer comes from a refresh when the client has not answered yet. Answers the function that stops listening. */
+    subscribe: (listener: SessionListener) => () => void;
+    /** Calls `onChange` when the snapshot changes (the shape `useSyncExternalStore` takes); starts the first refresh when none ran. */
+    watch: (onChange: () => void) => () => void;
+}
+/** Creates the session store of a client. `source` is read at call time, never captured. */
+export declare const createSessionStore: <User extends SessionPerson>(source: SessionSource) => SessionStore<User>;
+/** One refresh at a time: every caller that arrives while one runs awaits the same promise. */
+export interface SingleFlight<T> {
+    /** Starts `task` when none runs, else joins the running one; the slot frees itself when the run settles, success or failure. */
+    run(): Promise<T>;
+    /** Whether a run is in progress. */
+    running(): boolean;
+}
+/** Guards `task` so that overlapping calls (many requests answered 401 together) share one run. */
+export declare const createSingleFlight: <T>(task: () => Promise<T>) => SingleFlight<T>;

package/dist/client/session.js

@@ -0,0 +1,68 @@
+/** Creates the session store of a client. `source` is read at call time, never captured. */
+export const createSessionStore = (source) => {
+    const loading = { status: "loading", user: null };
+    let snapshot = loading;
+    const listeners = new Set();
+    const watchers = new Set();
+    const set = (next) => {
+        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email)
+            return;
+        snapshot = next;
+        for (const watcher of watchers)
+            watcher();
+    };
+    return {
+        getSnapshot: () => snapshot,
+        getServerSnapshot: () => loading,
+        signedIn: (user) => {
+            set({ status: "signed-in", user });
+        },
+        signedOut: () => {
+            set({ status: "signed-out", user: null });
+        },
+        emit: (event, userId) => {
+            for (const listener of listeners)
+                listener(event, userId);
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            if (source.announced()) {
+                listener("INITIAL_SESSION", source.userId());
+            }
+            else {
+                void source.renew().then(() => {
+                    if (!source.announced())
+                        source.announce();
+                    if (!source.held()) {
+                        set({ status: "signed-out", user: null });
+                        listener("INITIAL_SESSION", null);
+                    }
+                });
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        watch: (onChange) => {
+            watchers.add(onChange);
+            if (!source.announced() && !source.refreshing())
+                void source.renew().then(() => undefined);
+            return () => {
+                watchers.delete(onChange);
+            };
+        },
+    };
+};
+/** Guards `task` so that overlapping calls (many requests answered 401 together) share one run. */
+export const createSingleFlight = (task) => {
+    let inFlight;
+    return {
+        run: () => {
+            inFlight ??= task().finally(() => {
+                inFlight = undefined;
+            });
+            return inFlight;
+        },
+        running: () => inFlight !== undefined,
+    };
+};

package/dist/server/doors.d.ts

@@ -20,14 +20,14 @@ export interface DoorsDeps {
 }
 /**
  * The cookie doors of sign-in over the flows, the sessions and the cookie: what a controller calls. The refresh token only goes
- * into the cookie; a refresh that cannot be used clears it, one a sibling request just rotated leaves it as the sibling wrote it.
+ * into the cookie; every refresh rotates and sets its successor (a racing one included), and a refresh that cannot be used clears it.
  */
 export declare class AuthDoors {
     #private;
     constructor(deps: DoorsDeps);
     /** Email and password through the local strategy; the refresh token goes into the cookie. */
     login(exchange: HttpExchange): Promise<AccessGrant>;
-    /** Rotates the cookie token and answers a new access token; a cookie that cannot be used is cleared and the refusal rethrown. */
+    /** Rotates the cookie token and sets the successor (every refresh rotates, a racing one included); a cookie that cannot be used is cleared and the refusal rethrown. */
     refresh(exchange: HttpExchange): Promise<AccessGrant>;
     /** Answers a fresh access token for the cookie session without rotating the cookie. */
     session(exchange: HttpExchange): Promise<AccessGrant>;

package/dist/server/doors.js

@@ -11,7 +11,7 @@ export const accessOf = (tokens) => ({
 });
 /**
  * The cookie doors of sign-in over the flows, the sessions and the cookie: what a controller calls. The refresh token only goes
- * into the cookie; a refresh that cannot be used clears it, one a sibling request just rotated leaves it as the sibling wrote it.
+ * into the cookie; every refresh rotates and sets its successor (a racing one included), and a refresh that cannot be used clears it.
  */
 export class AuthDoors {
     #deps;
@@ -25,12 +25,11 @@ export class AuthDoors {
         this.#deps.cookie.issue(exchange.res, tokens);
         return accessOf(tokens);
     }
-    /** Rotates the cookie token and answers a new access token; a cookie that cannot be used is cleared and the refusal rethrown. */
+    /** Rotates the cookie token and sets the successor (every refresh rotates, a racing one included); a cookie that cannot be used is cleared and the refusal rethrown. */
     async refresh(exchange) {
         try {
             const tokens = await this.#deps.sessions.refresh(this.#deps.cookie.read(exchange.req));
-            if (tokens.cookieKept !== true)
-                this.#deps.cookie.issue(exchange.res, tokens);
+            this.#deps.cookie.issue(exchange.res, tokens);
             return accessOf(tokens);
         }
         catch (cause) {

package/dist/server/ports.d.ts

@@ -49,6 +49,8 @@ export interface RefreshTokenRecord {
     readonly expiresAt: Date;
     /** When the token was rotated away, or null while it is the live one. */
     readonly usedAt: Date | null;
+    /** How many successors replays of this token obtained within the grace window after its rotation (bounded). */
+    readonly racedCount: number;
 }
 /** A device session to open. */
 export interface NewSession {
@@ -63,11 +65,13 @@ export interface SessionTransaction {
     /** Opens a device session. */
     openSession(session: NewSession): Promise<void>;
     /** Stores a live refresh token. */
-    insertToken(token: Omit<RefreshTokenRecord, "usedAt">): Promise<void>;
+    insertToken(token: Omit<RefreshTokenRecord, "usedAt" | "racedCount">): Promise<void>;
     /** The token with this digest, locked for update (a pessimistic write lock), or null. */
     findTokenForUpdate(tokenHash: string): Promise<RefreshTokenRecord | null>;
     /** Marks a token as rotated away at `at`. */
     markTokenUsed(tokenId: string, at: Date): Promise<void>;
+    /** Records how many successors replays of a rotated token obtained within the grace window. */
+    markTokenRaced(tokenId: string, racedCount: number): Promise<void>;
     /** Deletes the tokens of an account that expired before `before`. */
     deleteExpiredTokens(userId: string, before: Date): Promise<void>;
 }
@@ -79,7 +83,7 @@ export interface SessionStore {
     findToken(tokenHash: string): Promise<RefreshTokenRecord | null>;
     /** Marks a session refreshed. */
     touchSession(sessionId: string, now: Date): Promise<void>;
-    /** Ends one session (and with it every token of it). */
+    /** Ends one session and revokes every token of it (logout, reuse, a gone or disabled account). */
     closeSession(sessionId: string): Promise<void>;
     /** Ends every session of an account but one. */
     closeOtherSessions(userId: string, keepSessionId: string): Promise<void>;
@@ -115,8 +119,6 @@ export interface SessionTokens {
     readonly accessExpiresIn: number;
     /** The opaque token the refresh cookie carries. */
     readonly cookieToken: string;
-    /** True when the answer did not rotate the token (a racing request, or the non-rotating session door): the caller leaves the cookie as it is. */
-    readonly cookieKept?: true;
     readonly refreshMaxAgeSeconds: number;
     readonly user: SessionUser;
 }

package/dist/server/sessions.d.ts

@@ -2,8 +2,14 @@ import type { JwksDocument } from "../contracts/index.js";
 import type { AuthOptions } from "./options.js";
 import type { AuthClock, AuthIds, AuthLogger, AuthSubject, DeviceMeta, SessionTokens } from "./ports.js";
 import type { AuthTokens } from "./tokens.js";
-/** A rotated token presented again this soon after its rotation is a racing tab, not a theft. */
+/**
+ * A rotated token presented again this soon after its rotation is a racing request or a browser that never received the successor (the
+ * response was cut by a navigation): it gets a successor of its own, set as the cookie, so the browser never keeps a spent token. Later,
+ * it is a replay and ends the session.
+ */
 export declare const DEFAULT_REUSE_GRACE_MS = 30000;
+/** How many successors one rotated token may obtain within the grace window; one more is a replay and ends the session. */
+export declare const RACED_SUCCESSORS_MAX = 3;
 /** The log event of a replayed refresh token. */
 export declare const REFRESH_REUSE_EVENT = "auth.refresh-reuse-detected";
 /** What the sessions need from the module. */
@@ -16,8 +22,8 @@ export interface SessionsDeps {
 }
 /**
  * Device sessions: opens one at sign-in, rotates its refresh token on every refresh (a replayed token ends the session) and ends it
- * at sign-out. A token rotated within the grace window is a racing request: it is answered with an access token only, the cookie
- * is left as the winner wrote it.
+ * at sign-out. A token rotated within the grace window gets a successor of its own in the same session, at most
+ * {@link RACED_SUCCESSORS_MAX} times.
  */
 export declare class AuthSessions {
     #private;
@@ -26,8 +32,9 @@ export declare class AuthSessions {
     start(subject: AuthSubject, device: DeviceMeta): Promise<SessionTokens>;
     /**
      * Exchanges a refresh token for a new pair; the presented token is spent. Throws when it is unknown, expired, or rotated long
-     * ago (reuse ends the session). A token a sibling request rotated within the grace window answers an access token marked
-     * `cookieKept`, so the caller leaves the cookie alone: the sibling already wrote the successor.
+     * ago (reuse ends the session). A token rotated within the grace window gets a successor of its own in the same session (its
+     * cookie is set: the response of the first rotation may never have reached the browser), at most {@link RACED_SUCCESSORS_MAX}
+     * times; one more replay is reuse.
      */
     refresh(presented: string): Promise<SessionTokens>;
     /**

package/dist/server/sessions.js

@@ -1,15 +1,21 @@
 import { AUTH_ERROR_CODES } from "../contracts/index.js";
 import { AuthError } from "./errors.js";
 import { digestOf } from "./primitives.js";
-/** A rotated token presented again this soon after its rotation is a racing tab, not a theft. */
+/**
+ * A rotated token presented again this soon after its rotation is a racing request or a browser that never received the successor (the
+ * response was cut by a navigation): it gets a successor of its own, set as the cookie, so the browser never keeps a spent token. Later,
+ * it is a replay and ends the session.
+ */
 export const DEFAULT_REUSE_GRACE_MS = 30_000;
+/** How many successors one rotated token may obtain within the grace window; one more is a replay and ends the session. */
+export const RACED_SUCCESSORS_MAX = 3;
 /** The log event of a replayed refresh token. */
 export const REFRESH_REUSE_EVENT = "auth.refresh-reuse-detected";
 const MILLISECONDS = 1000;
 /**
  * Device sessions: opens one at sign-in, rotates its refresh token on every refresh (a replayed token ends the session) and ends it
- * at sign-out. A token rotated within the grace window is a racing request: it is answered with an access token only, the cookie
- * is left as the winner wrote it.
+ * at sign-out. A token rotated within the grace window gets a successor of its own in the same session, at most
+ * {@link RACED_SUCCESSORS_MAX} times.
  */
 export class AuthSessions {
     #deps;
@@ -41,8 +47,9 @@ export class AuthSessions {
     }
     /**
      * Exchanges a refresh token for a new pair; the presented token is spent. Throws when it is unknown, expired, or rotated long
-     * ago (reuse ends the session). A token a sibling request rotated within the grace window answers an access token marked
-     * `cookieKept`, so the caller leaves the cookie alone: the sibling already wrote the successor.
+     * ago (reuse ends the session). A token rotated within the grace window gets a successor of its own in the same session (its
+     * cookie is set: the response of the first rotation may never have reached the browser), at most {@link RACED_SUCCESSORS_MAX}
+     * times; one more replay is reuse.
      */
     async refresh(presented) {
         if (presented === "")
@@ -53,12 +60,15 @@ export class AuthSessions {
             const row = await tx.findTokenForUpdate(digestOf(presented));
             if (row === null || row.expiresAt <= now)
                 return { kind: "invalid" };
-            if (row.usedAt !== null) {
-                return now.getTime() - row.usedAt.getTime() <= this.#graceMs
-                    ? { kind: "raced", row }
-                    : { kind: "reused", sessionId: row.sessionId };
+            if (row.usedAt === null) {
+                await tx.markTokenUsed(row.id, now);
+            }
+            else {
+                const raced = now.getTime() - row.usedAt.getTime() <= this.#graceMs;
+                if (!raced || row.racedCount >= RACED_SUCCESSORS_MAX)
+                    return { kind: "reused", sessionId: row.sessionId };
+                await tx.markTokenRaced(row.id, row.racedCount + 1);
             }
-            await tx.markTokenUsed(row.id, now);
             await tx.insertToken({
                 id: this.#deps.ids.next(),
                 sessionId: row.sessionId,
@@ -76,8 +86,6 @@ export class AuthSessions {
         }
         if (rotation.kind === "invalid")
             throw new AuthError(AUTH_ERROR_CODES.RefreshInvalid);
-        if (rotation.kind === "raced")
-            return this.#accessOf(rotation.row, presented, now);
         const user = await this.#deps.options.accounts.find(rotation.row.userId);
         if (user === undefined || user.disabled || user.email === null) {
             await this.#store.closeSession(rotation.row.sessionId);
@@ -130,8 +138,7 @@ export class AuthSessions {
             await this.#store.closeSession(row.sessionId);
             throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
         }
-        const tokens = await this.#tokensFor({ userId: user.id, email: user.email }, row.sessionId, presented, now);
-        return { ...tokens, cookieKept: true };
+        return this.#tokensFor({ userId: user.id, email: user.email }, row.sessionId, presented, now);
     }
     async #tokensFor(subject, sessionId, refreshToken, now) {
         const access = await this.#deps.tokens.sign({ sub: subject.userId, email: subject.email, sessionId }, now);

package/dist/testing/index.js

@@ -45,7 +45,7 @@ export class MemorySessionStore {
                 return Promise.resolve();
             },
             insertToken: (token) => {
-                this.tokens.set(token.id, { ...token, usedAt: null });
+                this.tokens.set(token.id, { ...token, usedAt: null, racedCount: 0 });
                 return Promise.resolve();
             },
             findTokenForUpdate: (tokenHash) => Promise.resolve(this.#byHash(tokenHash)),
@@ -55,6 +55,12 @@ export class MemorySessionStore {
                     this.tokens.set(tokenId, { ...row, usedAt: at });
                 return Promise.resolve();
             },
+            markTokenRaced: (tokenId, racedCount) => {
+                const row = this.tokens.get(tokenId);
+                if (row !== undefined)
+                    this.tokens.set(tokenId, { ...row, racedCount });
+                return Promise.resolve();
+            },
             deleteExpiredTokens: (userId, before) => {
                 for (const [id, row] of this.tokens)
                     if (row.userId === userId && row.expiresAt < before)

package/migrations/identity-refresh-raced-successors.sql

@@ -0,0 +1,7 @@
+-- identity-refresh-raced-successors: forward-only, for an app whose baseline holds identity-sessions.sql of @starci/auth 0.2.0.
+-- A refresh token presented again within the grace window after its rotation (a racing request, or a browser whose earlier Set-Cookie
+-- never arrived) gets a successor of its own, set as the cookie, instead of an access token that leaves the browser on a spent token.
+-- raced_count bounds how many such successors one rotated token may obtain; beyond it the replay is reuse and ends the session.
+-- Expand only: one column with a default, nothing existing altered. A baseline rendered from @starci/auth 0.2.1 already holds it.
+
+alter table public.identity_refresh_tokens add column raced_count integer not null default 0;

package/migrations/identity-sessions.sql

@@ -1,5 +1,6 @@
 -- The device sessions and rotating refresh tokens of @starci/auth. A token is stored by its sha256 only; a rotated token stays,
--- marked used, so a replay is detected (a replay inside the grace window is a racing tab, an older one ends the session).
+-- marked used, so a replay is detected: a replay inside the grace window gets a successor of its own (raced_count bounds how many),
+-- an older one ends the session and every token of it.
 -- identity_attempts counts the sign-in attempts of one address in a window every replica shares (the budget of failures).
 -- The app owns auth.users (db/bootstrap.sql) and the role app_be.
 
@@ -22,6 +23,7 @@ create table public.identity_refresh_tokens (
     created_at timestamptz not null default now(),
     expires_at timestamptz not null,
     used_at timestamptz,
+    raced_count integer not null default 0,
     constraint identity_refresh_tokens_hash_key unique (token_hash)
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/auth",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The sign-in of a StarCi lite app in one package: a NestJS module (EdDSA access tokens with a multi-key JWKS, bcrypt passwords, Google OAuth with state and PKCE, rotating refresh tokens with a reuse grace window and reuse detection, a failures-only sign-in limit, the refresh cookie), the door contracts, a front-end auth client (access token in memory, one shared refresh, signed out only on 401 or 403) with React bindings, and test doubles.",
   "keywords": [
     "auth",