@starci/auth 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 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`, `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/auth",
-  "version": "0.1.0",
+  "version": "0.2.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",