@starci/auth 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.3.0 - 2026-11-03
+
+- Added: a session carries the person's full name when the account directory knows it: `AccountStanding.name` and `AuthSubject.name` in; `SessionUser.name`, the `name` access-token claim (`AUTH_CLAIMS.name`), `AccessClaims.name` and `AuthPrincipal.name` out. The client keeps it (from the grant, or from the token when the grant carries no user) and announces a change of it. An account without a name answers as before.
+
+## 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).

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 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.
+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

@@ -45,7 +45,7 @@ export interface AuthClient {
     accessToken(): Promise<string | undefined>;
     /** The held access token without any request. */
     peek(): string | undefined;
-    /** The signed-in person (id and email), or null when signed out. */
+    /** The signed-in person (id, email and the full name when the account has one), or null when signed out. */
     user(): Promise<SessionUser | null>;
     /** The `Authorization` header of the current session (an empty object when signed out). */
     headers(): Promise<Record<string, string>>;

package/dist/client/auth-client.js

@@ -20,11 +20,14 @@ const claimsOf = (token) => {
         return {};
     }
 };
+/** The full name of a person, when a grant or a token names one. */
+const nameOf = (name) => (typeof name === "string" ? { name } : {});
 const userOf = (grant) => {
-    if (typeof grant.user === "object" && typeof grant.user.id === "string")
-        return { id: grant.user.id, email: typeof grant.user.email === "string" ? grant.user.email : "" };
-    const { sub, email } = claimsOf(grant.accessToken);
-    return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "" } : null;
+    if (typeof grant.user === "object" && typeof grant.user.id === "string") {
+        return { id: grant.user.id, email: typeof grant.user.email === "string" ? grant.user.email : "", ...nameOf(fieldOf(grant.user, "name")) };
+    }
+    const { sub, email, name } = claimsOf(grant.accessToken);
+    return typeof sub === "string" ? { id: sub, email: typeof email === "string" ? email : "", ...nameOf(name) } : null;
 };
 const MILLISECONDS = 1000;
 const timerPause = (ms) => new Promise((resolve) => {

package/dist/client/session.d.ts

@@ -4,6 +4,7 @@ export type SessionEvent = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT" | "TOK
 export interface SessionPerson {
     readonly id: string;
     readonly email: string;
+    readonly name?: 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> {
@@ -33,7 +34,7 @@ export interface SessionStore<User extends SessionPerson> {
     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. */
+    /** Publishes the snapshot of a signed-in person; watchers hear it only when status, id, email or name changed. */
     signedIn: (user: User | null) => void;
     /** Publishes the signed-out snapshot. */
     signedOut: () => void;

package/dist/client/session.js

@@ -5,7 +5,7 @@ export const createSessionStore = (source) => {
     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)
+        if (snapshot.status === next.status && snapshot.user?.id === next.user?.id && snapshot.user?.email === next.user?.email && snapshot.user?.name === next.user?.name)
             return;
         snapshot = next;
         for (const watcher of watchers)

package/dist/contracts/index.d.ts

@@ -30,6 +30,7 @@ export declare const AUTH_CLAIMS: {
     readonly role: "role";
     readonly sessionId: "session_id";
     readonly email: "email";
+    readonly name: "name";
 };
 /** The signature algorithm of every access token: pinned, never negotiated. */
 export declare const AUTH_ALGORITHM = "EdDSA";
@@ -63,6 +64,8 @@ export interface SessionUser {
     readonly id: string;
     /** The account email. */
     readonly email: string;
+    /** The person's full name, when the account has one. */
+    readonly name?: string;
 }
 /** What a sign-in, refresh or session door answers in the body. */
 export interface AccessGrant {

package/dist/contracts/index.js

@@ -28,6 +28,7 @@ export const AUTH_CLAIMS = {
     role: "role",
     sessionId: "session_id",
     email: "email",
+    name: "name",
 };
 /** The signature algorithm of every access token: pinned, never negotiated. */
 export const AUTH_ALGORITHM = "EdDSA";

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

@@ -5,6 +5,8 @@ export interface AuthSubject {
     readonly userId: string;
     /** The account email. */
     readonly email: string;
+    /** The person's full name, when the account has one. */
+    readonly name?: string | undefined;
 }
 /** What Google told us about the person who consented. */
 export interface GoogleProfile {
@@ -34,6 +36,8 @@ export interface AccountStanding {
     readonly email: string | null;
     /** Whether the account is disabled or gone. */
     readonly disabled: boolean;
+    /** The person's full name, when the account has one (the session answers and the access token carry it). */
+    readonly name?: string | undefined;
 }
 /** The app's user table, seen only as far as sessions need it. */
 export interface AccountDirectory {
@@ -49,6 +53,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 +69,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 +87,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 +123,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;
 }
@@ -128,6 +134,8 @@ export interface AccessClaims {
     readonly email?: string | undefined;
     /** The device session the token belongs to. */
     readonly sessionId: string;
+    /** The person's full name at issue time, when the account has one. */
+    readonly name?: string | undefined;
 }
 /** The principal domain code builds from a verified access token. */
 export interface AuthPrincipal {
@@ -135,6 +143,7 @@ export interface AuthPrincipal {
     readonly role: "authenticated";
     readonly sessionId: string;
     readonly email?: string;
+    readonly name?: string;
 }
 /** A freshly signed access token. */
 export interface IssuedAccessToken {

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,23 @@
 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;
+/** The subject of a standing account: its id, its address and its full name when the directory knows one. */
+const subjectOf = (user, email) => ({ userId: user.id, email, ...(user.name === undefined ? {} : { name: user.name }) });
 /**
  * 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 +49,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 +62,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,15 +88,13 @@ 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);
             throw new AuthError(AUTH_ERROR_CODES.AccountDisabled);
         }
         await this.#store.touchSession(rotation.row.sessionId, now);
-        return this.#tokensFor({ userId: user.id, email: user.email }, rotation.row.sessionId, rotation.next, now);
+        return this.#tokensFor(subjectOf(user, user.email), rotation.row.sessionId, rotation.next, now);
     }
     /**
      * Answers a fresh access token for the session of a refresh token WITHOUT rotating it, so parallel gated requests of one browser
@@ -130,18 +140,18 @@ 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(subjectOf(user, 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);
+        const name = subject.name === undefined ? {} : { name: subject.name };
+        const access = await this.#deps.tokens.sign({ sub: subject.userId, email: subject.email, sessionId, ...name }, now);
         return {
             accessToken: access.token,
             accessExpiresAt: access.expiresAt.toISOString(),
             accessExpiresIn: Math.round((access.expiresAt.getTime() - now.getTime()) / MILLISECONDS),
             cookieToken: refreshToken,
             refreshMaxAgeSeconds: this.#deps.options.refreshTtlSeconds,
-            user: { id: subject.userId, email: subject.email },
+            user: { id: subject.userId, email: subject.email, ...name },
         };
     }
     #refreshExpiry(now) {

package/dist/server/tokens.js

@@ -25,6 +25,7 @@ export class AuthTokens {
             [AUTH_CLAIMS.role]: AUTH_ROLE,
             [AUTH_CLAIMS.sessionId]: claims.sessionId,
             ...(claims.email === undefined ? {} : { [AUTH_CLAIMS.email]: claims.email }),
+            ...(claims.name === undefined ? {} : { [AUTH_CLAIMS.name]: claims.name }),
         })
             .setProtectedHeader({ alg: AUTH_ALGORITHM, kid: signer.keyId, typ: "JWT" })
             .setSubject(claims.sub)
@@ -50,7 +51,8 @@ export class AuthTokens {
                 return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
             }
             const email = payload[AUTH_CLAIMS.email];
-            return ok({ sub: payload.sub, sessionId, ...(typeof email === "string" ? { email } : {}) });
+            const name = payload[AUTH_CLAIMS.name];
+            return ok({ sub: payload.sub, sessionId, ...(typeof email === "string" ? { email } : {}), ...(typeof name === "string" ? { name } : {}) });
         }
         catch (cause) {
             return refused(AUTH_ERROR_CODES.AccessTokenInvalid, { cause: String(cause) });

package/dist/server/verifier.js

@@ -13,8 +13,8 @@ export class AuthPrincipalVerifier {
         const verified = await this.#tokens.verify(token, now);
         if (verified.kind === "refused")
             return refused(AUTH_ERROR_CODES.AccessTokenInvalid);
-        const { sub, email, sessionId } = verified.value;
-        return ok({ id: sub, role: AUTH_ROLE, sessionId, ...(email === undefined ? {} : { email }) });
+        const { sub, email, name, sessionId } = verified.value;
+        return ok({ id: sub, role: AUTH_ROLE, sessionId, ...(email === undefined ? {} : { email }), ...(name === undefined ? {} : { name }) });
     }
 }
 /** The verifier of an app that serves no user session: every access token is refused, so the default-deny guard admits only its public and credential doors. */

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.2.0",
+  "version": "0.3.0",
   "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",