@passflow/core 0.20.1 → 0.21.0

package/dist/index.d.ts

@@ -42,6 +42,8 @@ type Token = {
   iss: string;
   jti: string;
   sub: string;
+  /** Auth session the refresh lineage is anchored to; kept by every rotation of one sign-in. */
+  sid?: string;
   type: string;
   email?: string;
   phonenumber?: string;
@@ -345,6 +347,12 @@ declare class StorageManager {
    * Clear the CSRF token from storage
    */
   clearCsrfToken(): void;
+  /**
+   * Every storage key the token session lives in (JSON tokens, scopes, the cookie-mode ID token,
+   * CSRF token and delivery mode). The refresh coordinator filters `storage` events by it, so
+   * writes to unrelated keys never wake the refresh path.
+   */
+  tokenKeys(): string[];
   private getKeyForTokenType;
 }
 declare class DeviceService {
@@ -586,6 +594,13 @@ interface PlatformAdapter {
    * Must be synchronous. Use localStorage on web, MMKV on React Native.
    */
   readonly storage: PlatformStorage;
+  /**
+   * True when `storage` is shared by every tab of the origin (the browser's localStorage, or a
+   * wrapper over it). Token refresh coordinates tabs only over shared storage
+   * (`refreshCoordination: 'web-locks'`); a per-tab storage (sessionStorage, memory) shares no
+   * session. Optional: an adapter that leaves it unset is treated as per-tab. WebAdapter sets it.
+   */
+  readonly storageSharedAcrossTabs?: boolean;
   /**
    * Returns the current URL of the application.
    * On web: wraps window.location.
@@ -696,6 +711,11 @@ interface PlatformAdapter {
 }
 export declare class WebAdapter implements PlatformAdapter {
   get storage(): PlatformStorage;
+  /**
+   * `storage` is the browser's localStorage, which every tab of the origin shares. False in
+   * SSR/Node (the no-op storage) and where reading localStorage throws (storage blocked).
+   */
+  get storageSharedAcrossTabs(): boolean;
   /**
    * Replaces:
    *   window.location.origin  (passflow.ts:95, axios-client.ts:49)
@@ -796,6 +816,97 @@ export declare class WebAdapter implements PlatformAdapter {
  * Exported so consuming code can reference it without allocating a new instance.
  */
 export declare const webAdapter: WebAdapter;
+/**
+ * Public types of multi-tab-safe token refresh (PFL-792, architecture §2.2-2.5).
+ *
+ * @module refresh/types
+ */
+/** Options of one lock request: exclusive mode only, as the SDK uses `navigator.locks`. */
+interface RefreshLockOptions {
+  ifAvailable?: boolean;
+  steal?: boolean;
+  signal?: AbortSignal;
+}
+/** The part of `navigator.locks` (LockManager) the SDK uses: exclusive mode only. */
+interface RefreshLockManager {
+  request(name: string, options: RefreshLockOptions, callback: (lock: unknown) => unknown): Promise<unknown>;
+}
+/** The part of BroadcastChannel the SDK uses. Must not deliver an instance's own posts to itself. */
+interface RefreshChannel {
+  postMessage(message: unknown): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  removeEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+  close(): void;
+}
+/** Time source for every refresh timer of one instance (heartbeat, silence, retry, waits). */
+interface RefreshClock {
+  /** Epoch ms. */
+  now(): number;
+  /** Runs `fn` after `ms`; returns the cancel. */
+  setTimeout(fn: () => void, ms: number): () => void;
+  /** `[0, 1)` for backoff jitter. Default `Math.random`. */
+  random?(): number;
+}
+/** Transports for the cross-tab protocol, supplied by tests, Electron or custom hosts. */
+interface RefreshCoordinator {
+  locks: RefreshLockManager;
+  /** One per Passflow instance; closed by `dispose()`. */
+  channel: RefreshChannel;
+  /** Default: `crypto.randomUUID()` or a random string. */
+  tabId?: string;
+  /** Another tab wrote the shared token storage. Called once at construction; returns unsubscribe. */
+  onStorageChange?: (listener: () => void) => () => void;
+  /** Default: `Date.now` / `setTimeout` / `Math.random`. */
+  clock?: RefreshClock;
+}
+/** How tabs of this origin coordinate token refresh (`PassflowConfig.refreshCoordination`). */
+type RefreshCoordination = 'web-locks' | 'none' | RefreshCoordinator;
+/** What asked for a refresh (`ErrorPayload.source`). */
+type RefreshTrigger =
+/** `Passflow.refreshToken()` / `AuthService.refreshToken()` */
+'refresh-token' |
+/** `TokenCacheService.getTokensWithRefresh()` */
+'token-check' |
+/** `getTokens(true)` / `session({ doRefresh: true })` */
+'session' |
+/** An SDK API call whose access token expires within 30 s */
+'pre-request' |
+/** Step-up commit */
+'upgrade' |
+/** The scheduled retry, with no new caller */
+'retry' |
+/** The held-tab send */
+'held';
+/** How a failed `/auth/refresh` is read (architecture §2.6). */
+type RefreshFailureKind = 'transient' | 'blocked' | 'auth';
+/** Refresh details on `ErrorPayload` for operations `refresh` and `upgrade.commit`. */
+interface RefreshErrorInfo {
+  classification: RefreshFailureKind;
+  /** A retry is scheduled (transient, or auth with strikes left). */
+  willRetry: boolean;
+  /** Epoch ms of the retry, when `willRetry`. */
+  nextRetryAt?: number;
+  /** Auth failures since the last success, after this one. */
+  strikes: number;
+  /** Resolved `refreshStrikes`. */
+  maxStrikes: number;
+}
+/** Whether an event was caused by this tab's own action or learnt from another tab. */
+type EventOrigin = 'this-tab' | 'other-tab';
+/** Why a session ended (`SessionExpired.reason`). */
+type SessionExpiredReason =
+/** `refreshStrikes` auth failures (this tab, or another tab of the lineage). */
+'refresh_failed' |
+/** `error.token.blocked` and no successor within 20 s; this tab only. */
+'successor_timeout' |
+/** Storage now holds another user's tokens. */
+'identity_changed' |
+/** Legacy members, never emitted. */
+'token_invalid' | 'logged_out';
 /** Factor types the upgrade protocol understands, named as `upgrade.type` on the wire. */
 type UpgradeFactorType = 'totp' | 'recovery_codes' | 'passkey' | 'email_otp' | 'sms_otp';
 /** The prepare round's result — `POST /auth/upgrade/begin`, normalised to camelCase. */
@@ -1010,6 +1121,26 @@ export type PassflowConfig = {
    * resource that has to be torn down, which configuration cannot express.
    */
   upgrade?: PassflowUpgradeConfig;
+  /**
+   * How tabs of this origin coordinate token refresh.
+   * - `'web-locks'` (default): a Web Lock plus a BroadcastChannel, on a browser page whose
+   *   `platform.storage` is shared by every tab (the default web adapter's localStorage) and that
+   *   has `navigator.locks` and `BroadcastChannel`. Elsewhere it falls back to `'none'`; on a
+   *   browser page with shared storage the fallback writes one `[passflow]` warning, at the first
+   *   refresh.
+   * - `'none'`: no cross-tab coordination. Single flight within this instance, compare-and-set
+   *   save, per-instance retries.
+   * - a `RefreshCoordinator` object: the same protocol as `'web-locks'` over the transports
+   *   you supply (tests, Electron, custom hosts). Never falls back.
+   */
+  refreshCoordination?: RefreshCoordination;
+  /**
+   * Authentication failures of `/auth/refresh` counted since the last successful refresh or
+   * adoption, after which the session ends. Transient failures in between neither add a strike nor
+   * reset the count. Default 3. A non-integer is floored; a value below 1 or not a finite number
+   * uses the default.
+   */
+  refreshStrikes?: number;
 };
 export type PassflowUpgradeConfig = {
   /** Relying-party id forwarded verbatim to `POST /auth/upgrade/start` for passkey upgrades. */
@@ -1725,13 +1856,24 @@ export interface CLIAuthCompleteRequest {
  * config, so anything registered afterwards is structurally too late.
  */
 type AxiosUpgradeHandler = (error: AxiosError, challenge: UpgradeChallenge) => Promise<AxiosResponse>;
+/**
+ * The pre-request refresh (PFL-792). Installed by `Passflow` on every client it owns; it asks the
+ * instance's refresh controller, which coordinates with the other tabs and owns retries, strikes
+ * and the session end. Resolves with the tokens to send (`undefined` once the session ended).
+ *
+ * `allowStale` is true when the access token is inside the 30 s window but not yet expired: during
+ * a pending retry the controller then resolves at once and the call goes out with the current
+ * bearer instead of waiting for the retry.
+ */
+type AxiosRefreshHandler = (request: {
+  trigger: 'pre-request';
+  allowStale: boolean;
+}) => Promise<Tokens | undefined>;
 declare class AxiosClient {
   private instance;
   protected storageManager: StorageManager;
   protected deviceService: DeviceService;
   protected tokenDeliveryManager: TokenDeliveryManager;
-  private refreshPromise;
-  private isRefreshing;
   private _platform;
   tokenService: TokenService;
   get origin(): string;
@@ -1751,6 +1893,8 @@ declare class AxiosClient {
   private readonly protectedEndpoints;
   /** Set when a consumer wires the upgrade feature. Absent by default. */
   private upgradeHandler?;
+  /** Set by `Passflow` (its refresh controller). Absent on a client built standalone. */
+  private refreshHandler?;
   /**
    * Passflow's own API as an interception scope, resolved ONCE here from
    * `PassflowConfig.url` so no wrapper or adapter ever derives it. `null` when
@@ -1769,6 +1913,17 @@ declare class AxiosClient {
    * upgrade challenge. Passing `undefined` detaches it.
    */
   setUpgradeInterceptor(handler: AxiosUpgradeHandler | undefined): void;
+  /**
+   * Installs (or clears) the pre-request refresh. JSON mode only: before a request that needs an
+   * access token (not `/auth/refresh`, not logout) whose access token expires within 30 s while a
+   * refresh token is stored, the handler is awaited and its access token becomes the bearer. On
+   * rejection the call still goes out with the current bearer when that token has not expired yet;
+   * otherwise the call rejects with the handler's error. Nothing is ever deleted here.
+   *
+   * Without a handler (an API client built standalone, outside `Passflow`) no refresh runs: every
+   * call sends the stored bearer as it is, and an expired one gets the server's 401.
+   */
+  setRefreshHandler(handler: AxiosRefreshHandler | undefined): void;
   /**
    * Re-issues a request after an elevation. Exposed for the upgrade handler,
    * which owns the replay-once decision; the marker preventing a second
@@ -1787,11 +1942,6 @@ declare class AxiosClient {
    * configure cookie mode for platforms where cookiesSupported() returns false.
    */
   private detectCookieSupport;
-  /**
-   * Refresh tokens using single-flight pattern to prevent race conditions
-   * Supports both cookie mode and JSON mode
-   */
-  private refreshTokens;
   private handleRateLimitError;
   private handleAxiosError;
   private send;
@@ -2929,6 +3079,117 @@ export declare class M2MTokenParseError extends M2MError {
 export declare class M2MConfigError extends M2MError {
   constructor(message: string);
 }
+/**
+ * Logger interface for Passflow services
+ */
+interface Logger {
+  error(message: string, ...args: unknown[]): void;
+  warn(message: string, ...args: unknown[]): void;
+  info(message: string, ...args: unknown[]): void;
+  debug(message: string, ...args: unknown[]): void;
+}
+/**
+ * Session and user identity pinning for an upgrade flight (§13.4 revision 6).
+ *
+ * ## The rule
+ *
+ * An upgrade flight is bound to the **session and user identity it began
+ * under**, and that identity is verified **at the moment tokens are applied** —
+ * not only around `prepare` and `commit`. On mismatch the rotated tokens are
+ * discarded, never applied, and the flight settles as `session changed
+ * mid-flight`.
+ *
+ * ## Why the epoch counter was not enough
+ *
+ * The round-1 epoch check wraps the two rounds that talk to the server. It does
+ * not wrap token APPLICATION, which happens inside `AuthService.refreshToken`
+ * after the commit returns. A logout and re-login during an in-flight upgrade
+ * therefore let user A's flight write its rotated tokens over user B's live
+ * session: the request was authorized as A, the storage belongs to B, and
+ * nothing in between compared the two principals.
+ *
+ * An epoch tells you something changed. An identity check tells you **whether
+ * it is still the same principal**, which is the property actually required.
+ * Both run, and they are complementary rather than redundant.
+ *
+ * ## Why this module is pure
+ *
+ * It imports nothing and reads no storage, so the token-applying path can be
+ * given a pin by value and the comparison can be tested with literals. Reading
+ * the identity is the host's job — it is the only code that knows where the
+ * session lives in each delivery mode.
+ */
+/**
+ * The principal an upgrade flight is pinned to.
+ *
+ * `sub` is the user. `sid` is the session when the server issues one; it is
+ * absent in tokens that carry no session claim, and the field is then simply
+ * not part of the comparison — a missing claim cannot be made to prove
+ * anything, and inventing a value would make two different sessions compare
+ * equal or unequal arbitrarily.
+ */
+type UpgradeSessionPin = {
+  readonly sub: string;
+  readonly sid?: string;
+};
+/** Lock and channel names for a storage prefix. Empty prefix: the portal's names. */
+interface RefreshNames {
+  lock: string;
+  takeoverLock: string;
+  channel: string;
+}
+/** The transports of the cross-tab protocol for one instance. */
+interface CrossTabTransports {
+  locks: RefreshLockManager;
+  channel: RefreshChannel;
+  tabId: string;
+}
+/** What `refreshCoordination` resolved to for one instance. */
+interface ResolvedCoordination {
+  /** Cross-tab transports, or null: local (single-instance) coordination. */
+  transports: CrossTabTransports | null;
+  /** Lock and channel names for the storage prefix. */
+  names: RefreshNames;
+  /** The time source of every refresh timer of the instance. */
+  clock: Required<RefreshClock>;
+  /** Another tab wrote the shared token storage. Returns unsubscribe. */
+  onStorageChange?: (listener: () => void) => () => void;
+  /** Write the fallback warning once, when the instance first starts a refresh. */
+  warnOnFirstCycle: boolean;
+}
+interface RefreshRequest {
+  trigger: RefreshTrigger;
+  /** `refreshToken()`: satisfied only by a pair from a request sent at or after the call (§2.8). */
+  fresh?: boolean;
+}
+interface RefreshController {
+  refresh(request: RefreshRequest): Promise<PassflowAuthorizationResponse>;
+  /** The pre-request refresh (§2.8): the tokens to send the API call with. */
+  ensureFresh(request: {
+    trigger: 'pre-request';
+    allowStale: boolean;
+  }): Promise<Tokens | undefined>;
+  commitUpgrade(upgrade: UpgradeRefreshField, pin?: UpgradeSessionPin): Promise<PassflowAuthorizationResponse>;
+  /**
+   * logOut (§2.8): rejects plain callers, stops the timers, waits for this tab's request in
+   * flight, takes the lock (≤ 5 s), posts signed-out naming the newest stored token, runs
+   * `cleanup(newestRefreshToken)`, ends the session here and releases. Emits nothing: the caller
+   * emits its one SignOut.
+   */
+  signOut(cleanup: (newest?: string) => Promise<void>): Promise<void>;
+  /** reset() (A2): the same without the lock or an API call, synchronously. */
+  signOutNow(cleanup: (newest?: string) => void): void;
+  /** A new session in this tab (sign-in, register, setTokens): new generation, counters reset. */
+  sessionStarted(): void;
+  /** The `sub` this tab's session belongs to. */
+  identity(): string | undefined;
+  readonly coordinated: boolean;
+  /** This instance has a cycle: waiting for the lock, a request in flight, a retry or a successor pending. */
+  readonly busy: boolean;
+  /** The session ended here (or the instance was disposed): `refresh()` rejects with a PassflowRefreshError. */
+  readonly ended: boolean;
+  dispose(): void;
+}
 /**
  * Passflow event types
  */
@@ -2956,8 +3217,17 @@ export declare enum PassflowEvent {
   TwoFactorSetupMagicLinkFailed = "2fa:magic_link_failed",
   TwoFactorChallengeReceived = "two_factor_challenge_received",
   TwoFactorMethodSwitched = "two_factor_method_switched",
-  TwoFactorDeviceTrusted = "two_factor_device_trusted"
+  TwoFactorDeviceTrusted = "two_factor_device_trusted",
+  /** Token refresh entered a transient-failure episode (once per episode, per tab). */
+  RefreshFailing = "refresh:failing",
+  /** The transient-failure episode ended with a successful refresh or adoption. */
+  RefreshRecovered = "refresh:recovered"
 }
+/**
+ * The SDK operation that failed (`ErrorPayload.operation`). The SDK sets it on every `Error` it
+ * emits, so a subscriber can tell a failed sign-in from a failed refresh without parsing messages.
+ */
+type PassflowOperation = 'sign-in' | 'sign-up' | 'passwordless.start' | 'passwordless.complete' | 'password-reset.send' | 'password-reset.complete' | 'passkey.register' | 'passkey.authenticate' | 'federated.popup' | 'auth-redirect.url' | 'auth-redirect' | 'auth.is-authenticated' | 'session.check' | 'tokens.get' | 'tokens.load' | 'tokens.from-url' | 'refresh' | 'upgrade.commit' | 'log-out' | 'reset' | 'settings.app' | 'settings.all' | 'settings.password-policy' | 'settings.passkey' | 'passkey.list' | 'passkey.rename' | 'passkey.delete' | 'passkey.add' | 'tenant.create' | 'invitation.join' | 'invitation.request-link' | 'invitation.list' | 'invitation.delete' | 'invitation.resend' | 'invitation.get-link' | '2fa.status' | '2fa.setup.begin' | '2fa.setup.confirm' | '2fa.verify' | '2fa.recovery.use' | '2fa.disable' | '2fa.recovery.regenerate' | '2fa.methods.available' | '2fa.methods.registered' | '2fa.method.setup.start' | '2fa.method.setup.complete' | '2fa.method.remove' | '2fa.challenge.request' | '2fa.challenge.verify' | '2fa.method.switch' | '2fa.trusted-devices.list' | '2fa.trusted-devices.revoke';
 /**
  * Error payload interface for structured error information
  */
@@ -2966,7 +3236,17 @@ interface ErrorPayload {
   code?: string | number;
   details?: unknown;
   originalError?: unknown;
+  /** The operation that failed. Always set by the SDK. */
+  operation?: PassflowOperation;
+  /** For operation `refresh` | `upgrade.commit`: what asked for the refresh. */
+  source?: RefreshTrigger;
+  /** For operation `refresh` | `upgrade.commit`: how the failure was classified and what follows. */
+  refresh?: RefreshErrorInfo;
 }
+/** An `Error` payload as the SDK reports it: `operation` is required. */
+type OperationErrorPayload = ErrorPayload & {
+  operation: PassflowOperation;
+};
 /**
  * Event-specific payload types
  */
@@ -2974,6 +3254,8 @@ type PassflowEventPayload = {
   [PassflowEvent.SignIn]: {
     tokens?: Tokens;
     parsedTokens?: ParsedTokens;
+    /** `'other-tab'` only when an ended tab revives on a new session found in storage. Absent on this tab's own sign-in. */
+    origin?: EventOrigin;
   };
   [PassflowEvent.SignInStart]: {
     email?: string;
@@ -2987,7 +3269,10 @@ type PassflowEventPayload = {
     email?: string;
   };
   [PassflowEvent.SignOut]: {
+    /** `sub` of the session that ended, when known. */
     userId?: string;
+    /** Always set by the SDK. `'other-tab'`: another tab signed out, or shared storage was emptied. */
+    origin?: EventOrigin;
   };
   [PassflowEvent.SessionRestored]: {
     id: string;
@@ -2996,12 +3281,19 @@ type PassflowEventPayload = {
     [key: string]: unknown;
   };
   [PassflowEvent.SessionExpired]: {
-    reason: 'refresh_failed' | 'token_invalid' | 'logged_out';
+    reason: SessionExpiredReason;
+    /** Always set by the SDK. */
+    origin?: EventOrigin;
   };
   [PassflowEvent.Error]: ErrorPayload;
   [PassflowEvent.Refresh]: {
     tokens?: Tokens;
     parsedTokens?: ParsedTokens;
+    /**
+     * Always set by the SDK. `'refresh'`: this tab's request; `'upgrade'`: this tab's step-up
+     * commit; `'adopted'`: tokens this tab did not request (another tab's, or found in storage).
+     */
+    source?: 'refresh' | 'upgrade' | 'adopted';
   };
   [PassflowEvent.RefreshStart]: {
     tokenId?: string;
@@ -3061,6 +3353,20 @@ type PassflowEventPayload = {
     alternativeMethods: TwoFactorMethod[];
   };
   [PassflowEvent.TwoFactorDeviceTrusted]: Record<string, never>;
+  [PassflowEvent.RefreshFailing]: {
+    /** Epoch ms of the episode's first transient failure. */
+    since: number;
+    /** Epoch ms of the shared pending retry, when known. */
+    nextRetryAt?: number;
+    /** `'this-tab'` when this tab's own request failed. */
+    origin: EventOrigin;
+  };
+  [PassflowEvent.RefreshRecovered]: {
+    /** Same value as the `RefreshFailing` that opened the episode. */
+    since: number;
+    /** `'this-tab'`: own request succeeded; `'other-tab'`: adopted another tab's tokens. */
+    origin: EventOrigin;
+  };
 };
 /**
  * Passflow subscriber interface
@@ -3091,54 +3397,14 @@ declare class PassflowStore {
    * @param payload Event-specific payload data
    */
   notify<E extends PassflowEvent>(eventType: E, payload?: PassflowEventPayload[E]): void;
+  /**
+   * Notify subscribers of an error, at most once per error object (`notifyError` in `error-report.ts`).
+   * @returns whether the event was emitted
+   */
+  notifyError(payload: OperationErrorPayload): boolean;
 }
-/**
- * Session and user identity pinning for an upgrade flight (§13.4 revision 6).
- *
- * ## The rule
- *
- * An upgrade flight is bound to the **session and user identity it began
- * under**, and that identity is verified **at the moment tokens are applied** —
- * not only around `prepare` and `commit`. On mismatch the rotated tokens are
- * discarded, never applied, and the flight settles as `session changed
- * mid-flight`.
- *
- * ## Why the epoch counter was not enough
- *
- * The round-1 epoch check wraps the two rounds that talk to the server. It does
- * not wrap token APPLICATION, which happens inside `AuthService.refreshToken`
- * after the commit returns. A logout and re-login during an in-flight upgrade
- * therefore let user A's flight write its rotated tokens over user B's live
- * session: the request was authorized as A, the storage belongs to B, and
- * nothing in between compared the two principals.
- *
- * An epoch tells you something changed. An identity check tells you **whether
- * it is still the same principal**, which is the property actually required.
- * Both run, and they are complementary rather than redundant.
- *
- * ## Why this module is pure
- *
- * It imports nothing and reads no storage, so the token-applying path can be
- * given a pin by value and the comparison can be tested with literals. Reading
- * the identity is the host's job — it is the only code that knows where the
- * session lives in each delivery mode.
- */
-/**
- * The principal an upgrade flight is pinned to.
- *
- * `sub` is the user. `sid` is the session when the server issues one; it is
- * absent in tokens that carry no session claim, and the field is then simply
- * not part of the comparison — a missing claim cannot be made to prove
- * anything, and inventing a value would make two different sessions compare
- * equal or unequal arbitrarily.
- */
-type UpgradeSessionPin = {
-  readonly sub: string;
-  readonly sid?: string;
-};
 export declare class TokenCacheService {
   private storageManager;
-  private authApi;
   private subscribeStore;
   private platform;
   tokensCache: Tokens | undefined;
@@ -3147,14 +3413,33 @@ export declare class TokenCacheService {
   private readonly CHECK_INTERVAL;
   private unsubscribeForeground;
   private unsubscribeUnload;
-  isRefreshing: boolean;
+  private refreshController;
+  /**
+   * Set when the expiry check (`initialize()`, the 60 s check, foreground) finds the access token
+   * expired, with `TokenCacheExpired{isExpired:true}`. Output only: it never gates a refresh. The
+   * refresh controller clears it on every `Refresh`.
+   */
   tokenExpiredFlag: boolean;
-  constructor(storageManager: StorageManager, authApi: AuthAPI, subscribeStore: PassflowStore, platform?: PlatformAdapter);
+  /**
+   * `authApi` is no longer used here (the refresh controller sends every refresh); the parameter
+   * stays so the constructor's signature does not change.
+   */
+  constructor(storageManager: StorageManager, _authApi: AuthAPI, subscribeStore: PassflowStore, platform?: PlatformAdapter);
+  /** Whether this instance has a refresh cycle (waiting, in flight, a retry or a successor pending). */
+  get isRefreshing(): boolean;
+  /**
+   * Connects `getTokensWithRefresh()` to the instance's refresh controller. `Passflow` calls it at
+   * construction. Without it, `getTokensWithRefresh()` returns the cache and sends nothing.
+   */
+  attachRefreshController(controller: Pick<RefreshController, 'refresh' | 'busy'> | undefined): void;
   initialize(): void;
-  private refreshTokensCache;
   startTokenCheck(): void;
   private setupLifecycleListeners;
-  private stopTokenCheck;
+  /**
+   * Stops the expiry check and its foreground listener. Public so the refresh controller can stop
+   * it when a session ends in this tab (it is called optionally: test fakes may lack it).
+   */
+  stopTokenCheck(): void;
   /**
    * Cleanup method to stop all intervals and remove event listeners.
    * Should be called when the service is no longer needed.
@@ -3162,10 +3447,23 @@ export declare class TokenCacheService {
   destroy(): void;
   setTokensCache(tokens: Tokens | undefined): void;
   getTokens(): Tokens | undefined;
+  /**
+   * The cached tokens, refreshed first when the access token has expired (trigger `token-check`).
+   *
+   * It asks the refresh controller, which starts a refresh or joins the one pending, and returns
+   * the cache whatever the outcome: the new tokens, the kept ones after a failure that did not end
+   * the session, `undefined` once it ended. It never rejects; the controller reports the failure.
+   */
   getTokensWithRefresh(): Promise<Tokens | undefined>;
   getParsedTokens(): ParsedTokens | undefined;
   isExpired(): boolean;
 }
+/** How this instance's refresh controller coordinates (architecture §3.3, §3.4). */
+export type AuthServiceRefreshOptions = {
+  coordination: ResolvedCoordination;
+  /** `PassflowConfig.refreshStrikes`; the controller resolves the default. */
+  strikes?: number;
+};
 /**
  * Service for handling authentication related functionality
  */
@@ -3185,13 +3483,19 @@ export declare class AuthService {
   private tokenDeliveryManager;
   private tokenExchangeConfig?;
   private pendingPkce?;
+  /**
+   * The one place this instance sends `/auth/refresh` (PFL-792). Every refresh path asks it: the
+   * explicit `refreshToken()`, the upgrade commit, `getTokens(true)`/`session()` and, once
+   * `Passflow` attaches it, `TokenCacheService.getTokensWithRefresh()`.
+   */
+  readonly refresh: RefreshController;
   constructor(authApi: AuthAPI, deviceService: DeviceService, storageManager: StorageManager, subscribeStore: PassflowStore, tokenCacheService: TokenCacheService, scopes: string[], createTenantForNewUser: boolean, url: string, sessionCallbacks: {
     createSession?: ({ tokens, parsedTokens }: {
       tokens?: Tokens;
       parsedTokens?: ParsedTokens;
     }) => Promise<void>;
     expiredSession?: () => Promise<void>;
-  }, appId?: string | undefined, tokenExchangeConfig?: TokenExchangeConfig, platform?: PlatformAdapter, readPkceEnabled?: (() => Promise<boolean>) | undefined);
+  }, appId?: string | undefined, tokenExchangeConfig?: TokenExchangeConfig, platform?: PlatformAdapter, readPkceEnabled?: (() => Promise<boolean>) | undefined, refreshOptions?: AuthServiceRefreshOptions);
   /**
    * Initialize session state on page load for cookie/BFF mode
    */
@@ -3203,11 +3507,20 @@ export declare class AuthService {
    */
   restoreSession(): Promise<boolean>;
   /**
-   * Process successful authentication response
-   * Handles token storage, session state, CSRF tokens
-   * In BFF mode, forwards tokens to BFF server
+   * Applies a sign-in's tokens and starts a new session in the refresh controller.
+   *
+   * Every sign-in reaches the tokens through here: password, passwordless, passkey, federated,
+   * the 2FA code and recovery-code completion, PKCE completion, `joinInvitation` and tokens from a
+   * redirect (`applyTokens`). So this is where the controller learns of a new session (amendment
+   * A1): a tab that signed out, or whose session ended, refreshes again on the new one.
    */
   private processAuthResponse;
+  /**
+   * Stores an authentication response: token storage, session state, CSRF token. In BFF mode it
+   * forwards the tokens to the BFF server first. Starts no session: a cookie-mode refresh applies
+   * its answer through here too.
+   */
+  private applyAuthResponse;
   /**
    * Reports whether a sign-in response is still waiting on its second factor,
    * and when it is, hands the 2FA token on.
@@ -3269,7 +3582,28 @@ export declare class AuthService {
   signUp(payload: PassflowSignUpPayload): Promise<PassflowAuthorizationResponse>;
   passwordlessSignIn(payload: PassflowPasswordlessSignInPayload): Promise<PassflowPasswordlessResponse>;
   passwordlessSignInComplete(payload: PassflowPasswordlessSignInCompletePayload): Promise<PassflowValidationResponse>;
-  logOut(): Promise<void>;
+  /**
+   * Signs this tab out under the refresh lock (PFL-792 §2.8): stops this tab's refresh callers and
+   * retry timer, waits at most 5 s for the lock (a request already in flight lands first), posts
+   * `signed-out` to the other tabs, calls the logout API with the NEWEST stored refresh token (best
+   * effort), then deletes the stored tokens, id token and CSRF token and clears the token cache.
+   *
+   * Emits no `SignOut`: `Passflow.logOut()` emits exactly one, after this resolves.
+   *
+   * @returns the `sub` of the session that ended, when known
+   */
+  logOut(): Promise<string | undefined>;
+  /**
+   * `Passflow.reset()` (PFL-792 amendment A2): the same local sign-out, synchronously, with no
+   * API call and no lock. Emits no `SignOut`; the caller emits one.
+   *
+   * @returns the `sub` of the session that ended, when known
+   */
+  resetSession(): string | undefined;
+  /** The logout API call. Server-side cleanup is best effort: every failure is ignored. */
+  private callLogoutApi;
+  /** Deletes every local trace of the session (both delivery modes) and clears the token cache. */
+  private clearLocalSession;
   /**
    * The session and user identity this client currently holds, or `undefined`
    * when none is readable.
@@ -3302,21 +3636,38 @@ export declare class AuthService {
    * state — two different axes.
    */
   private assertSessionPin;
+  /** The delivery mode the refresh transport sends in. BFF without a refresh URL has no endpoint: JSON, as before. */
+  private refreshMode;
+  /**
+   * The controller's events, onto the store. Only `notify` is used (plus the error dedupe), so a
+   * store double with `notify` alone works.
+   */
+  private createRefreshEmit;
+  /**
+   * One refresh request in the current delivery mode, with no events and no saving (architecture
+   * §3.2): the controller decides what an answer or a failure means.
+   *
+   * - JSON: `AuthAPI.refreshToken(stored refresh token, stored scopes, stored access token[, upgrade])`.
+   * - Cookie: `AuthAPI.refreshToken('', scopes[, undefined, upgrade])`; the server reads the HttpOnly cookie.
+   * - BFF: `POST tokenExchange.refreshUrl`. A non-OK answer becomes a `PassflowError` (status, and
+   *   the body's `error.id` or `error.http.<status>`), so it is classified like any other answer.
+   */
+  private createRefreshTransport;
+  /** The BFF refresh endpoint. A non-OK answer becomes a `PassflowError`; a network failure rejects as is. */
+  private sendBffRefresh;
   /**
    * Refreshes the session, optionally committing an assurance upgrade.
    *
-   * This is the ONLY token-storing path for all four delivery modes, which is
-   * why the upgrade commit goes through here rather than posting to
-   * `/auth/refresh` directly: it saves the rotated tokens, updates the cache and
-   * emits `Refresh`. Bypassing it would elevate the session on the server and
-   * leave the client holding stale tokens — everything looks fine until the next
-   * request 401s.
+   * Both go through the refresh controller, the one place this instance sends `/auth/refresh`: it
+   * coordinates with other tabs, saves with a compare-and-set, classifies failures and emits the
+   * events (PFL-792). A plain refresh is "fresh": it is satisfied only by tokens from a request
+   * sent at or after the call. A failure keeps the tokens unless it really ends the session.
    *
-   * An upgrade commit changes the error handling in one specific way: a 4xx is
-   * NOT treated as a dead session. The server answers a wrong code with a 401,
-   * and tearing the session down there is the logout-at-step-up defect. The
-   * upgrade transport classifies those failures and invalidates the session
-   * itself when the 401 turns out to be a genuine expiry.
+   * The upgrade commit is the one path that is never classified: any failure rejects with the
+   * error unchanged and keeps the tokens, because a 4xx there is the server rejecting the PROOF,
+   * not the session (logging the user out for mistyping six digits is the defect this flow exists
+   * to fix). The upgrade transport classifies those failures itself. The session pin is checked
+   * when the answer arrives, before anything is applied: see `assertSessionPin`.
    */
   refreshToken(upgrade?: UpgradeRefreshField, pin?: UpgradeSessionPin): Promise<PassflowAuthorizationResponse>;
   sendPasswordResetEmail(payload: PassflowSendPasswordResetEmailPayload): Promise<PassflowSuccessResponse>;
@@ -3347,6 +3698,13 @@ export declare class AuthService {
    * Handle session check and callbacks
    */
   submitSessionCheck(doRefresh?: boolean): Promise<Tokens | undefined>;
+  /**
+   * `getTokens(true)` / `session({ doRefresh: true })` (architecture §2.8): starts or joins a
+   * refresh, then resolves with the cached tokens whatever the outcome: the kept tokens after a
+   * transient, blocked or auth-with-strikes-left failure, `undefined` once the session ended. The
+   * failure itself was reported by the controller, so it is not reported again here.
+   */
+  private refreshForSession;
   /**
    * Get tokens and refresh if needed
    * Cookie/BFF mode: Returns ID token only (access/refresh in HttpOnly cookies)
@@ -3396,15 +3754,6 @@ export declare class InvitationService {
    */
   getInvitationLink(invitationID: string): Promise<InviteLinkResponse>;
 }
-/**
- * Logger interface for Passflow services
- */
-interface Logger {
-  error(message: string, ...args: unknown[]): void;
-  warn(message: string, ...args: unknown[]): void;
-  info(message: string, ...args: unknown[]): void;
-  debug(message: string, ...args: unknown[]): void;
-}
 /**
  * Flat user representation
  */
@@ -5116,8 +5465,12 @@ export declare class Passflow {
    * Creates proper ErrorPayload, distinguishes PassflowError from generic Error,
    * notifies error event, and re-throws the error.
    *
+   * Reports at most once per error object: when a service already reported it (a 2FA wrapper,
+   * a sign-in), the service's more specific report stands and nothing is added here.
+   *
    * @param error - The error to handle
-   * @param context - Context description for the error
+   * @param operation - The operation that failed (`ErrorPayload.operation`)
+   * @param context - Context description for the fallback message
    * @throws The original error after handling
    */
   private handleError;
@@ -5200,11 +5553,31 @@ export declare class Passflow {
    * ```
    */
   reset(error?: string): void;
+  /** The one `SignOut` of `logOut()`/`reset()` in this tab (PFL-792 §2.4). */
+  private notifySignedOut;
+  /**
+   * Releases what this instance holds for token refresh: leaves the refresh lock queue, cancels
+   * every refresh timer and the token check, removes its storage and foreground listeners, closes
+   * its BroadcastChannel, and rejects pending refresh callers with `PassflowRefreshError`
+   * (`error.refresh.disposed`). Afterwards the instance must not be used.
+   *
+   * The SDK never calls it by itself, not on `beforeunload` (it fires before a cancellable
+   * "Leave site?" prompt and before a page enters the back/forward cache) nor on `pagehide`:
+   * document teardown already releases the page's locks and channels. Call it when an SPA tears
+   * the instance down, and in tests.
+   *
+   * @example
+   * ```typescript
+   * passflow.dispose();
+   * ```
+   */
+  dispose(): void;
   /**
    * Refresh the access token using the refresh token.
    *
    * @returns Promise with new authorization response containing refreshed tokens
-   * @throws {Error} If no refresh token is found
+   * @throws {Error} JSON mode with no stored refresh token (`No tokens found` / `No refresh token found`)
+   * @throws {PassflowRefreshError} `error.refresh.session_ended` and the other ends, once the session ended
    * @throws {PassflowError} If refresh request fails
    *
    * @example
@@ -5904,6 +6277,51 @@ export declare class Passflow {
    */
   clearMagicLinkSession(): void;
 }
+/** §2.6 row 2: the session cannot be refreshed, whatever the status. */
+export declare const REFRESH_AUTH_FAILURE_IDS: readonly string[];
+/** Ids of {@link PassflowRefreshError}. */
+export declare const RefreshErrorId: {
+  /** Joined another tab's cycle whose attempt failed transiently (status 503). */
+  readonly unavailable: 'error.refresh.unavailable';
+  /** Joined another tab's cycle whose attempt failed on auth with strikes left (status 401). */
+  readonly authRetry: 'error.refresh.auth_retry';
+  /** The session ended (strikes exhausted here or elsewhere). */
+  readonly sessionEnded: 'error.refresh.session_ended';
+  /** A sign-out (this tab or another tab of the user). */
+  readonly signedOut: 'error.refresh.signed_out';
+  /** `error.token.blocked` and no successor within 20 s. */
+  readonly successorTimeout: 'error.refresh.successor_timeout';
+  /** Storage now holds another user's tokens. */
+  readonly identityChanged: 'error.refresh.identity_changed';
+  /** `Passflow.dispose()` was called. */
+  readonly disposed: 'error.refresh.disposed';
+};
+export type RefreshErrorId = (typeof RefreshErrorId)[keyof typeof RefreshErrorId];
+interface PassflowRefreshErrorOptions {
+  message?: string;
+  /** Epoch ms of the shared pending retry, for `unavailable` / `auth_retry`. */
+  nextRetryAt?: number;
+  /** The failure this error stands for (another tab's attempt, the request's own error). */
+  cause?: unknown;
+}
+/** A refresh outcome the SDK decided, not the server: joined a failed cycle, or the session ended. */
+export declare class PassflowRefreshError extends PassflowError {
+  readonly id: RefreshErrorId;
+  readonly nextRetryAt?: number;
+  readonly cause?: unknown;
+  constructor(id: RefreshErrorId, options?: PassflowRefreshErrorOptions);
+}
+/** Why an upgrade commit was not sent, or its answer not applied. */
+type UpgradeCommitInterruptedReason = 'lock-timeout' | 'superseded';
+/**
+ * Upgrade commit only: the commit could not be sent (lock wait over 10 s) or its answer arrived
+ * after storage moved to another token. A plain Error with no `status` and no `response`: the
+ * upgrade transport's classifier reads it as `network` (retryable, no invalidation).
+ */
+export declare class UpgradeCommitInterruptedError extends Error {
+  readonly reason: UpgradeCommitInterruptedReason;
+  constructor(reason: UpgradeCommitInterruptedReason, message?: string);
+}
 /**
  * Validates JWT token format (not signature, just structure)
  * Checks that the token has 3 parts separated by dots and each part is valid base64url
@@ -5941,4 +6359,4 @@ export declare function isValidPhoneNumber(phone: string): boolean;
  * @returns true if valid username format, false otherwise
  */
 export declare function isValidUsername(username: string): boolean;
-export type { AssuranceBar, AuthCallbackResult, BodyKind, ChallengeChannel, CreateClientConfig, CurrentUrlInfo, ErrorPayload, FetchLike, FetchMiddleware, GroupMembership, InvitationToken, M2MClientConfig, M2MErrorCode, M2MErrorResponse, M2MRateLimitInfo, M2MTokenCache, M2MTokenClaims, M2MTokenRequestInfo, M2MTokenRequestOptions, M2MTokenResponse, OpenAuthUrlOptions, PassflowEventPayload, PassflowSubscriber, PasskeySupport, PlatformAdapter, PlatformStorage, RawUserMembership, RegisterOptions, ReplayPolicy, RequestSnapshot, ResponseInterceptorHost, RetryStrategy, SnapshotHeader, Tenant, TenantMembership, Token, UpgradeAssertContext, UpgradeAssertion, UpgradeChallenge, UpgradeControllerOptions, UpgradeDiagnostic, UpgradeDiagnosticReason, UpgradeDiagnosticSink, UpgradeElevation, UpgradeEnableOptions, UpgradeEndpoint, UpgradeErrorKind, UpgradeFacade, UpgradeFactor, UpgradeFactorInput, UpgradeFactorType, UpgradeFlightState, UpgradeFlightSummary, UpgradeOptions, UpgradePrepared, UpgradePromptHandler, UpgradePromptRequest, UpgradePromptResult, UpgradeProof, UpgradeReplayInfo, UpgradeResult, UpgradeSessionPin, UpgradeTransport, UpgradeTransportErrorInit, UpgradeWaiterSummary, UserMembership, Waiter, WaiterEntry, WaiterOutcome, WaiterReport };
+export type { AssuranceBar, AuthCallbackResult, BodyKind, ChallengeChannel, CreateClientConfig, CurrentUrlInfo, ErrorPayload, EventOrigin, FetchLike, FetchMiddleware, GroupMembership, InvitationToken, M2MClientConfig, M2MErrorCode, M2MErrorResponse, M2MRateLimitInfo, M2MTokenCache, M2MTokenClaims, M2MTokenRequestInfo, M2MTokenRequestOptions, M2MTokenResponse, OpenAuthUrlOptions, OperationErrorPayload, PassflowEventPayload, PassflowOperation, PassflowRefreshErrorOptions, PassflowSubscriber, PasskeySupport, PlatformAdapter, PlatformStorage, RawUserMembership, RefreshChannel, RefreshClock, RefreshCoordination, RefreshCoordinator, RefreshErrorInfo, RefreshFailureKind, RefreshLockManager, RefreshLockOptions, RefreshTrigger, RegisterOptions, ReplayPolicy, RequestSnapshot, ResponseInterceptorHost, RetryStrategy, SessionExpiredReason, SnapshotHeader, Tenant, TenantMembership, Token, UpgradeAssertContext, UpgradeAssertion, UpgradeChallenge, UpgradeCommitInterruptedReason, UpgradeControllerOptions, UpgradeDiagnostic, UpgradeDiagnosticReason, UpgradeDiagnosticSink, UpgradeElevation, UpgradeEnableOptions, UpgradeEndpoint, UpgradeErrorKind, UpgradeFacade, UpgradeFactor, UpgradeFactorInput, UpgradeFactorType, UpgradeFlightState, UpgradeFlightSummary, UpgradeOptions, UpgradePrepared, UpgradePromptHandler, UpgradePromptRequest, UpgradePromptResult, UpgradeProof, UpgradeReplayInfo, UpgradeResult, UpgradeSessionPin, UpgradeTransport, UpgradeTransportErrorInit, UpgradeWaiterSummary, UserMembership, Waiter, WaiterEntry, WaiterOutcome, WaiterReport };