@starci/auth 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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).

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/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.2.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",