@mentra/cloud-client 3.2.0-dev.137 → 3.2.0-dev.154

package/src/modules/auth/auth.ts

@@ -25,18 +25,14 @@
  * See docs/issues/004-cloud-client/spec.md ("cloud.auth"), design.md, and
  * docs/issues/001-cloud-core/auth/spec.md (endpoints + token shapes).
  */
-import type {
-  AuthConfig,
-  CoreAuthConfig,
-  RuntimeAuthConfig,
-  SubjectTokenType,
-} from "../../config";
-import type { HttpClient } from "../../http";
-import type { Logger } from "../../logger";
-import type { HttpTransport } from "../../transports";
-import { AuthExpiredError } from "../../errors";
-import { decodeClaims } from "./jwt";
-import { TokenStore } from "./token-store";
+import type {AuthConfig, CoreAuthConfig, RuntimeAuthConfig, SubjectTokenType} from "../../config"
+import type {HttpClient} from "../../http"
+import type {Logger} from "../../logger"
+import type {HttpTransport} from "../../transports"
+import {AuthExpiredError, HttpError, SessionRevocationError} from "../../errors"
+import {systemTimers, type CloudClientTimers} from "../../timers"
+import {decodeClaims} from "./jwt"
+import {TokenStore} from "./token-store"
 
 /**
  * The public auth surface a host uses, from spec.md.
@@ -51,85 +47,105 @@ export interface AuthModule {
   // `{ forceRefresh: true }` to bypass the in-memory cache and refresh now, for
   // the case where the cloud rejected a token the client still thinks is fresh
   // (clock skew or a mid-session revoke surfaced as AUTH_EXPIRED).
-  getRuntimeToken(opts?: { forceRefresh?: boolean }): Promise<string>;
+  getRuntimeToken(opts?: {forceRefresh?: boolean}): Promise<string>
   // current Core token, refreshing as needed (Core-backed mode only).
-  getCoreToken(opts?: { forceRefresh?: boolean }): Promise<string>;
+  getCoreToken(opts?: {forceRefresh?: boolean}): Promise<string>
   // a miniapp-scoped token, cached per packageName and re-minted before expiry
   getMiniappToken(
     packageName: string,
-    opts?: { minTtlMs?: number; devAttestation?: string },
-  ): Promise<{ token: string; expiresAt: number }>;
+    opts?: {minTtlMs?: number; devAttestation?: string},
+  ): Promise<{token: string; expiresAt: number}>
   // Core-owned user/oem identity, read from the Core access token.
   // Runtime-only deployments do not expose this surface.
-  readonly identity: { mentraUserId: string; tenantId: string };
+  readonly identity: {mentraUserId: string; tenantId: string}
+  // clear access, refresh, runtime, and miniapp credentials for logout. Local
+  // credentials are always cleared; rejects with `SessionRevocationError` when
+  // Core did not confirm revocation of the server-side session.
+  clearSession(): Promise<void>
   // refresh failed; the host must send the user back through login
-  onExpired(handler: () => void): () => void;
+  onExpired(handler: () => void): () => void
 }
 
 /** RFC 8693 token-exchange grant type for the `/exchange` call. */
-const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
+const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
 
 /**
  * Map a config `SubjectTokenType` to the RFC 8693 `subject_token_type` URN the
  * cloud expects.
  *
- * All three supported subject tokens (an OEM-signed JWT, a Mentra core token, a
- * Supabase session) are presented as a JWT and verified by their own `iss` /
+ * All supported subject tokens (OIDC, an OEM-signed JWT, a Mentra core token,
+ * or a Supabase session) are presented as a JWT and verified by their own `iss` /
  * verification path on the cloud, so they share the one JWT token-type URN. The
  * mapping is kept explicit (rather than hard-coding one URN) so that if the
  * cloud later wants distinct URNs per source, this is the single place to widen.
  */
 const SUBJECT_TOKEN_TYPE_URN: Record<SubjectTokenType, string> = {
+  "oidc": "urn:ietf:params:oauth:token-type:jwt",
   "oem-jwt": "urn:ietf:params:oauth:token-type:jwt",
   "mentra-core": "urn:ietf:params:oauth:token-type:jwt",
-  supabase: "urn:ietf:params:oauth:token-type:jwt",
-};
+  "supabase": "urn:ietf:params:oauth:token-type:jwt",
+}
 
 /** Seconds of headroom before `exp` at which we proactively refresh/re-mint. */
-const EXPIRY_MARGIN_SECONDS = 60;
+const EXPIRY_MARGIN_SECONDS = 60
+
+/** Total attempts at the idempotent `/revoke` during logout on network/5xx failures. */
+const REVOKE_ATTEMPTS = 3
+/** Base backoff between revoke attempts in milliseconds; doubles per attempt. */
+const REVOKE_RETRY_BASE_MS = 250
 
 /** The cloud's token endpoints, relative to the core base URL. */
-const EXCHANGE_PATH = "/api/client/auth/exchange";
-const REFRESH_PATH = "/api/client/auth/refresh";
-const RUNTIME_TOKEN_PATH = "/api/client/auth/runtime-token";
-const MINIAPP_TOKEN_PATH = "/api/client/auth/miniapp-token";
+const EXCHANGE_PATH = "/api/client/auth/exchange"
+const REFRESH_PATH = "/api/client/auth/refresh"
+const RUNTIME_TOKEN_PATH = "/api/client/auth/runtime-token"
+const MINIAPP_TOKEN_PATH = "/api/client/auth/miniapp-token"
+const REVOKE_PATH = "/api/client/auth/revoke"
 
 /** Single-flight keys. The miniapp key is suffixed per packageName below. */
-const FLIGHT_ACCESS = "access-token";
-const FLIGHT_RUNTIME = "runtime-token";
-const MINIAPP_FLIGHT_PREFIX = "miniapp-token:";
+const FLIGHT_ACCESS = "access-token"
+const FLIGHT_RUNTIME = "runtime-token"
+const MINIAPP_FLIGHT_PREFIX = "miniapp-token:"
 
 /** The cloud's RFC-shaped token response from `/exchange` and `/refresh`. */
 interface TokenResponse {
-  access_token: string;
-  refresh_token: string;
-  token_type: string;
-  expires_in: number;
+  access_token: string
+  refresh_token: string
+  token_type: string
+  expires_in: number
 }
 
 /** A cached miniapp token plus its absolute expiry (Unix seconds). */
 interface MiniappTokenEntry {
-  token: string;
-  expiresAt: number;
+  token: string
+  expiresAt: number
 }
 
 interface RuntimeTokenResponse {
-  access_token: string;
-  token_type: string;
-  expires_in: number;
+  access_token: string
+  token_type: string
+  expires_in: number
 }
 
 interface RuntimeTokenEntry {
-  token: string;
-  expiresAt: number;
+  token: string
+  expiresAt: number
+}
+
+/**
+ * A revoke is worth retrying only when Core gave no definite answer: the
+ * transport failed (`status` 0) or the server errored (5xx). A 4xx means Core
+ * rejected the request and repeating it would not change the outcome.
+ */
+function isRetryableRevokeError(err: unknown): boolean {
+  return err instanceof HttpError && (err.status === 0 || err.status >= 500)
 }
 
 export class Auth implements AuthModule {
-  private readonly http?: HttpClient;
-  private readonly store: TokenStore;
-  private readonly coreConfig?: CoreAuthConfig;
-  private readonly runtimeConfig: RuntimeAuthConfig;
-  private readonly logger: Logger;
+  private readonly http?: HttpClient
+  private readonly store: TokenStore
+  private readonly coreConfig?: CoreAuthConfig
+  private readonly runtimeConfig: RuntimeAuthConfig
+  private readonly logger: Logger
   /**
    * Core base URL for the form-encoded `/exchange` and `/refresh` calls.
    *
@@ -140,38 +156,45 @@ export class Auth implements AuthModule {
    * design: Core identity, miniapp token minting, and miniapp auto-auth are
    * Core-backed features.
    */
-  private readonly baseUrl?: string;
-  private readonly httpTransport: HttpTransport;
+  private readonly baseUrl?: string
+  private readonly httpTransport: HttpTransport
+  private readonly timers: CloudClientTimers
 
   /** Miniapp tokens cached per packageName until near expiry. */
-  private readonly miniappCache = new Map<string, MiniappTokenEntry>();
+  private readonly miniappCache = new Map<string, MiniappTokenEntry>()
   /** Core-brokered runtime token cache. */
-  private runtimeToken: RuntimeTokenEntry | null = null;
+  private runtimeToken: RuntimeTokenEntry | null = null
 
   /** Registered `onExpired` handlers. */
-  private readonly expiredHandlers = new Set<() => void>();
+  private readonly expiredHandlers = new Set<() => void>()
 
   /**
    * Latches once `onExpired` has fired, so a dead refresh token notifies the
    * host exactly once instead of on every subsequent call.
    */
-  private expiredFired = false;
+  private expiredFired = false
+  /** Incremented on logout so late async results cannot repopulate credentials. */
+  private sessionGeneration = 0
+  /** A logged-out client stays inert until the host constructs a fresh client. */
+  private sessionCleared = false
 
   constructor(deps: {
-    http?: HttpClient;
-    store: TokenStore;
-    config: AuthConfig;
-    logger: Logger;
-    baseUrl?: string;
-    fetch?: HttpTransport;
+    http?: HttpClient
+    store: TokenStore
+    config: AuthConfig
+    logger: Logger
+    baseUrl?: string
+    fetch?: HttpTransport
+    timers?: CloudClientTimers
   }) {
-    this.http = deps.http;
-    this.store = deps.store;
-    this.coreConfig = deps.config.core;
-    this.runtimeConfig = deps.config.runtime;
-    this.logger = deps.logger;
-    this.baseUrl = deps.baseUrl;
-    this.httpTransport = deps.fetch ?? globalThis.fetch;
+    this.http = deps.http
+    this.store = deps.store
+    this.coreConfig = deps.config.core
+    this.runtimeConfig = deps.config.runtime
+    this.logger = deps.logger
+    this.baseUrl = deps.baseUrl
+    this.httpTransport = deps.fetch ?? globalThis.fetch
+    this.timers = deps.timers ?? systemTimers
   }
 
   /**
@@ -181,39 +204,46 @@ export class Auth implements AuthModule {
    * margin is returned with no network call. Otherwise we obtain one through a
    * single-flight so concurrent callers share the same request.
    */
-  async getRuntimeToken(opts?: { forceRefresh?: boolean }): Promise<string> {
+  async getRuntimeToken(opts?: {forceRefresh?: boolean}): Promise<string> {
+    this.assertSessionActive()
     if ("getToken" in this.runtimeConfig) {
-      return this.runtimeConfig.getToken(opts);
+      const generation = this.sessionGeneration
+      const token = await this.runtimeConfig.getToken(opts)
+      this.assertSessionActive(generation)
+      return token
     }
 
     if (opts?.forceRefresh) {
-      this.runtimeToken = null;
+      this.runtimeToken = null
     } else if (this.runtimeToken && !this.isExpiring(this.runtimeToken.expiresAt)) {
-      return this.runtimeToken.token;
+      return this.runtimeToken.token
     }
 
-    return this.store.singleFlight(FLIGHT_RUNTIME, () =>
-      this.obtainCoreBrokeredRuntimeToken(),
-    );
+    const generation = this.sessionGeneration
+    return this.store.singleFlight(`${FLIGHT_RUNTIME}:${generation}`, () =>
+      this.obtainCoreBrokeredRuntimeToken(generation),
+    )
   }
 
-  async getCoreToken(opts?: { forceRefresh?: boolean }): Promise<string> {
-    this.requireCoreConfig();
+  async getCoreToken(opts?: {forceRefresh?: boolean}): Promise<string> {
+    this.assertSessionActive()
+    this.requireCoreConfig()
     // A forced refresh drops the cached access token first, so the cache check
     // below misses and we go straight to the single-flight refresh. The
     // single-flight still de-dupes, so a burst of forced refreshes (one per
     // reconnect attempt) collapses to one request.
     if (opts?.forceRefresh) {
-      this.store.invalidateAccess();
+      this.store.invalidateAccess()
     } else {
-      const cached = this.store.current();
+      const cached = this.store.current()
       if (cached && !this.isExpiring(cached.exp)) {
-        return cached.accessToken;
+        return cached.accessToken
       }
     }
 
     // De-dupe: if a refresh/exchange is already running, await that one result.
-    return this.store.singleFlight(FLIGHT_ACCESS, () => this.obtainAccessToken());
+    const generation = this.sessionGeneration
+    return this.store.singleFlight(`${FLIGHT_ACCESS}:${generation}`, () => this.obtainAccessToken(generation))
   }
 
   /**
@@ -227,38 +257,41 @@ export class Auth implements AuthModule {
    */
   async getMiniappToken(
     packageName: string,
-    opts?: { minTtlMs?: number; devAttestation?: string },
-  ): Promise<{ token: string; expiresAt: number }> {
-    const marginSeconds = this.tokenMarginSeconds(opts?.minTtlMs);
-    const cached = this.miniappCache.get(packageName);
+    opts?: {minTtlMs?: number; devAttestation?: string},
+  ): Promise<{token: string; expiresAt: number}> {
+    this.assertSessionActive()
+    const generation = this.sessionGeneration
+    const marginSeconds = this.tokenMarginSeconds(opts?.minTtlMs)
+    const cached = this.miniappCache.get(packageName)
     if (cached && !this.isExpiring(cached.expiresAt, marginSeconds)) {
-      return { token: cached.token, expiresAt: cached.expiresAt };
+      return {token: cached.token, expiresAt: cached.expiresAt}
     }
 
-    return this.store.singleFlight(MINIAPP_FLIGHT_PREFIX + packageName, async () => {
+    return this.store.singleFlight(`${MINIAPP_FLIGHT_PREFIX}${packageName}:${generation}`, async () => {
       // Re-check the cache inside the flight: a concurrent mint that resolved
       // while we were queued may have already filled it.
-      const fresh = this.miniappCache.get(packageName);
+      const fresh = this.miniappCache.get(packageName)
       if (fresh && !this.isExpiring(fresh.expiresAt, marginSeconds)) {
-        return { token: fresh.token, expiresAt: fresh.expiresAt };
+        return {token: fresh.token, expiresAt: fresh.expiresAt}
       }
 
-      const accessToken = await this.getCoreToken();
-      const http = this.requireCoreHttp();
+      const accessToken = await this.getCoreToken()
+      const http = this.requireCoreHttp()
       const res = await http.post<MiniappTokenEntry>(
         MINIAPP_TOKEN_PATH,
         {
           packageName,
-          ...(opts?.devAttestation ? { devAttestation: opts.devAttestation } : {}),
+          ...(opts?.devAttestation ? {devAttestation: opts.devAttestation} : {}),
         },
-        { bearer: accessToken },
-      );
-
-      const entry: MiniappTokenEntry = { token: res.token, expiresAt: res.expiresAt };
-      this.miniappCache.set(packageName, entry);
-      this.logger.debug("minted miniapp token", { packageName });
-      return { token: entry.token, expiresAt: entry.expiresAt };
-    });
+        {bearer: accessToken},
+      )
+
+      this.assertSessionActive(generation)
+      const entry: MiniappTokenEntry = {token: res.token, expiresAt: res.expiresAt}
+      this.miniappCache.set(packageName, entry)
+      this.logger.debug("minted miniapp token", {packageName})
+      return {token: entry.token, expiresAt: entry.expiresAt}
+    })
   }
 
   /**
@@ -273,14 +306,74 @@ export class Auth implements AuthModule {
    * every call, so the client need not). Throws if no Core access token has been
    * obtained yet, since Core identity is meaningless before the first exchange.
    */
-  get identity(): { mentraUserId: string; tenantId: string } {
-    this.requireCoreConfig();
-    const current = this.store.current();
+  get identity(): {mentraUserId: string; tenantId: string} {
+    this.requireCoreConfig()
+    const current = this.store.current()
     if (!current) {
-      throw new AuthExpiredError("Core identity is unavailable before first Core sign-in");
+      throw new AuthExpiredError("Core identity is unavailable before first Core sign-in")
+    }
+    const claims = decodeClaims(current.accessToken)
+    return {mentraUserId: claims.sub, tenantId: claims.tenant_id}
+  }
+
+  async clearSession(): Promise<void> {
+    this.sessionGeneration += 1
+    this.sessionCleared = true
+    let revokeError: unknown
+    try {
+      await this.revokeCoreSession()
+    } catch (err) {
+      revokeError = err
+      this.logger.warn("Core session revocation failed during local logout", {
+        error: (err as Error)?.message,
+      })
+    } finally {
+      await this.store.clear()
+      this.runtimeToken = null
+      this.miniappCache.clear()
+      this.expiredFired = false
+    }
+    if (revokeError) {
+      throw new SessionRevocationError("Core session revocation failed; local credentials were cleared", {
+        cause: revokeError,
+      })
+    }
+  }
+
+  /**
+   * Revoke the Core session server-side before local credentials are dropped.
+   *
+   * Core verifies the presented access token with no clock tolerance, so a
+   * cached token inside the usual expiry margin is refreshed first rather than
+   * risking a rejected revoke. `/revoke` is idempotent, so a network error or a
+   * 5xx is retried a bounded number of times with backoff; a definite 4xx is
+   * not. Any failure propagates so the caller can tell revocation did not
+   * complete.
+   */
+  private async revokeCoreSession(): Promise<void> {
+    if (!this.coreConfig || !this.http) return
+    const current = this.store.current()
+    const refreshToken = await this.store.refreshToken()
+    let accessToken: string | null = null
+    if (current && !this.isExpiring(current.exp)) {
+      accessToken = current.accessToken
+    } else if (refreshToken) {
+      const body = new URLSearchParams({grant_type: "refresh_token", refresh_token: refreshToken})
+      const tokens = await this.postForm(REFRESH_PATH, body, "logout refresh")
+      accessToken = tokens.access_token
+    }
+    if (!accessToken) return
+
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await this.http.post(REVOKE_PATH, {}, {bearer: accessToken})
+        return
+      } catch (err) {
+        if (attempt + 1 >= REVOKE_ATTEMPTS || !isRetryableRevokeError(err)) throw err
+        this.logger.warn("Core session revocation failed; retrying", {attempt: attempt + 1})
+        await new Promise<void>((resolve) => this.timers.setTimeout(resolve, REVOKE_RETRY_BASE_MS * 2 ** attempt))
+      }
     }
-    const claims = decodeClaims(current.accessToken);
-    return { mentraUserId: claims.sub, tenantId: claims.tenant_id };
   }
 
   /**
@@ -291,10 +384,10 @@ export class Auth implements AuthModule {
    * `fireExpired`).
    */
   onExpired(handler: () => void): () => void {
-    this.expiredHandlers.add(handler);
+    this.expiredHandlers.add(handler)
     return () => {
-      this.expiredHandlers.delete(handler);
-    };
+      this.expiredHandlers.delete(handler)
+    }
   }
 
   // === internals ===
@@ -307,15 +400,15 @@ export class Auth implements AuthModule {
    * in seconds and subtract the margin.
    */
   private isExpiring(expSeconds: number, marginSeconds = EXPIRY_MARGIN_SECONDS): boolean {
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    return expSeconds - marginSeconds <= nowSeconds;
+    const nowSeconds = Math.floor(Date.now() / 1000)
+    return expSeconds - marginSeconds <= nowSeconds
   }
 
   private tokenMarginSeconds(minTtlMs?: number): number {
     if (!Number.isFinite(minTtlMs) || !minTtlMs || minTtlMs <= 0) {
-      return EXPIRY_MARGIN_SECONDS;
+      return EXPIRY_MARGIN_SECONDS
     }
-    return Math.max(EXPIRY_MARGIN_SECONDS, Math.ceil(minTtlMs / 1000));
+    return Math.max(EXPIRY_MARGIN_SECONDS, Math.ceil(minTtlMs / 1000))
   }
 
   /**
@@ -323,24 +416,24 @@ export class Auth implements AuthModule {
    * do the first-use exchange. Runs inside the single-flight from
    * `getCoreToken`, so only one of these is ever in flight.
    */
-  private async obtainAccessToken(): Promise<string> {
-    const refreshToken = await this.store.refreshToken();
+  private async obtainAccessToken(generation: number): Promise<string> {
+    const refreshToken = await this.store.refreshToken()
     if (refreshToken) {
       try {
-        return await this.refresh(refreshToken, { deferExpired: this.canExchangeFreshSubject() });
+        return await this.refresh(refreshToken, {deferExpired: this.canExchangeFreshSubject(), generation})
       } catch (err) {
         if (this.canExchangeFreshSubject()) {
-          this.logger.info("refresh failed; exchanging fresh subject token");
+          this.logger.info("refresh failed; exchanging fresh subject token")
           try {
-            return await this.exchange();
+            return await this.exchange(generation)
           } catch {
-            this.fireExpired();
+            this.fireExpired()
           }
         }
-        throw err;
+        throw err
       }
     }
-    return this.exchange();
+    return this.exchange(generation)
   }
 
   /**
@@ -353,36 +446,42 @@ export class Auth implements AuthModule {
    * no subject token at all: we persist its refresh token and refresh, since we
    * only reach `exchange` when no refresh token is stored.
    */
-  private async exchange(): Promise<string> {
-    const config = this.requireCoreConfig();
+  private async exchange(generation = this.sessionGeneration): Promise<string> {
+    const config = this.requireCoreConfig()
     // Pre-exchanged credentials: seed the store and refresh, no /exchange call.
     if ("refreshToken" in config) {
-      await this.store.save({
-        accessToken: config.accessToken,
-        refreshToken: config.refreshToken,
-      });
+      await this.saveTokenPair(
+        {
+          accessToken: config.accessToken,
+          refreshToken: config.refreshToken,
+        },
+        generation,
+      )
       // The seeded access token may already be near expiry, so refresh through
       // the normal path to guarantee a fresh one.
-      return this.refresh(config.refreshToken);
+      return this.refresh(config.refreshToken, {generation})
     }
 
-    const subject = await this.resolveSubjectToken(config);
+    const subject = await this.resolveSubjectToken(config)
     const body = new URLSearchParams({
       grant_type: TOKEN_EXCHANGE_GRANT,
       subject_token: subject.token,
       subject_token_type: SUBJECT_TOKEN_TYPE_URN[subject.type],
-    });
-
-    const tokens = await this.postForm(EXCHANGE_PATH, body, "exchange");
-    await this.store.save({
-      accessToken: tokens.access_token,
-      refreshToken: tokens.refresh_token,
-    });
+    })
+
+    const tokens = await this.postForm(EXCHANGE_PATH, body, "exchange")
+    await this.saveTokenPair(
+      {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+      },
+      generation,
+    )
     // A successful exchange means credentials are live again; clear the latch so
     // a future failure can notify the host once more.
-    this.expiredFired = false;
-    this.logger.info("exchanged subject token for access token");
-    return tokens.access_token;
+    this.expiredFired = false
+    this.logger.info("exchanged subject token for access token")
+    return tokens.access_token
   }
 
   /**
@@ -395,36 +494,39 @@ export class Auth implements AuthModule {
    * `AuthExpiredError`. We do not retry refresh forever: a dead refresh token
    * will not heal on its own, and retrying would loop.
    */
-  private async refresh(refreshToken: string, opts?: { deferExpired?: boolean }): Promise<string> {
+  private async refresh(refreshToken: string, opts?: {deferExpired?: boolean; generation?: number}): Promise<string> {
     const body = new URLSearchParams({
       grant_type: "refresh_token",
       refresh_token: refreshToken,
-    });
+    })
 
-    let tokens: TokenResponse;
+    let tokens: TokenResponse
     try {
-      tokens = await this.postForm(REFRESH_PATH, body, "refresh");
+      tokens = await this.postForm(REFRESH_PATH, body, "refresh")
     } catch {
       // The refresh token is unusable: drop it so we do not keep presenting a
       // known-bad token.
-      await this.store.clear();
+      await this.store.clear()
       if (!opts?.deferExpired) {
-        this.fireExpired();
+        this.fireExpired()
       }
-      throw new AuthExpiredError("token refresh failed; re-auth required");
+      throw new AuthExpiredError("token refresh failed; re-auth required")
     }
 
-    await this.store.save({
-      accessToken: tokens.access_token,
-      refreshToken: tokens.refresh_token,
-    });
-    this.expiredFired = false;
-    this.logger.debug("refreshed access token");
-    return tokens.access_token;
+    await this.saveTokenPair(
+      {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+      },
+      opts?.generation ?? this.sessionGeneration,
+    )
+    this.expiredFired = false
+    this.logger.debug("refreshed access token")
+    return tokens.access_token
   }
 
   private canExchangeFreshSubject(): boolean {
-    return !!this.coreConfig && "getSubjectToken" in this.coreConfig;
+    return !!this.coreConfig && "getSubjectToken" in this.coreConfig
   }
 
   /**
@@ -434,52 +536,61 @@ export class Auth implements AuthModule {
    * Only reached for the two non-pre-exchanged config shapes; the caller handles
    * the pre-exchanged shape before us, so the final throw is just exhaustiveness.
    */
-  private async resolveSubjectToken(
-    config: CoreAuthConfig,
-  ): Promise<{ token: string; type: SubjectTokenType }> {
+  private async resolveSubjectToken(config: CoreAuthConfig): Promise<{token: string; type: SubjectTokenType}> {
     if ("subjectToken" in config) {
-      return { token: config.subjectToken, type: config.subjectTokenType };
+      return {token: config.subjectToken, type: config.subjectTokenType}
     }
     if ("getSubjectToken" in config) {
-      return config.getSubjectToken();
+      return config.getSubjectToken()
     }
-    throw new AuthExpiredError("no subject token available to exchange");
+    throw new AuthExpiredError("no subject token available to exchange")
   }
 
   private requireCoreConfig(): CoreAuthConfig {
     if (!this.coreConfig) {
-      throw new AuthExpiredError("core auth is not configured; this API is unavailable in runtime-only mode");
+      throw new AuthExpiredError("core auth is not configured; this API is unavailable in runtime-only mode")
     }
-    return this.coreConfig;
+    return this.coreConfig
   }
 
   private requireCoreHttp(): HttpClient {
     if (!this.http) {
-      throw new AuthExpiredError("core endpoint is not configured; this API is unavailable in runtime-only mode");
+      throw new AuthExpiredError("core endpoint is not configured; this API is unavailable in runtime-only mode")
     }
-    return this.http;
+    return this.http
   }
 
-  private async obtainCoreBrokeredRuntimeToken(): Promise<string> {
-    const fresh = this.runtimeToken;
+  private async obtainCoreBrokeredRuntimeToken(generation: number): Promise<string> {
+    const fresh = this.runtimeToken
     if (fresh && !this.isExpiring(fresh.expiresAt)) {
-      return fresh.token;
+      return fresh.token
     }
 
-    const coreToken = await this.getCoreToken();
-    const http = this.requireCoreHttp();
-    const res = await http.post<RuntimeTokenResponse>(
-      RUNTIME_TOKEN_PATH,
-      {},
-      { bearer: coreToken },
-    );
+    const coreToken = await this.getCoreToken()
+    const http = this.requireCoreHttp()
+    const res = await http.post<RuntimeTokenResponse>(RUNTIME_TOKEN_PATH, {}, {bearer: coreToken})
     if (res.token_type !== "Bearer" || !res.access_token) {
-      throw new AuthExpiredError("core returned an invalid runtime token response");
+      throw new AuthExpiredError("core returned an invalid runtime token response")
     }
 
-    const expiresAt = Math.floor(Date.now() / 1000) + res.expires_in;
-    this.runtimeToken = { token: res.access_token, expiresAt };
-    return res.access_token;
+    this.assertSessionActive(generation)
+    const expiresAt = Math.floor(Date.now() / 1000) + res.expires_in
+    this.runtimeToken = {token: res.access_token, expiresAt}
+    return res.access_token
+  }
+
+  /** Persist a token pair without allowing a concurrent logout to restore it. */
+  private async saveTokenPair(tokens: {accessToken: string; refreshToken: string}, generation: number): Promise<void> {
+    this.assertSessionActive(generation)
+    await this.store.save(tokens)
+    try {
+      this.assertSessionActive(generation)
+    } catch (error) {
+      // A storage adapter may have completed its write after logout cleared the
+      // key. Clear once more so the late write cannot resurrect the session.
+      await this.store.clear()
+      throw error
+    }
   }
 
   /**
@@ -491,27 +602,23 @@ export class Auth implements AuthModule {
    * subject/refresh token in the body, not as a Bearer header. We never log the
    * body: it carries a token.
    */
-  private async postForm(
-    path: string,
-    body: URLSearchParams,
-    label: string,
-  ): Promise<TokenResponse> {
-    const url = this.joinUrl(path);
+  private async postForm(path: string, body: URLSearchParams, label: string): Promise<TokenResponse> {
+    const url = this.joinUrl(path)
     const res = await this.httpTransport(url, {
       method: "POST",
-      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      headers: {"Content-Type": "application/x-www-form-urlencoded"},
       body: body.toString(),
-    });
+    })
 
     if (!res.ok) {
       // The body may carry an RFC `{ error, error_description }`, but we keep the
       // thrown detail to the status + label so no token field can leak into a
       // message a host might surface. The caller maps this to re-auth.
-      this.logger.warn("auth token request failed", { label, status: res.status });
-      throw new AuthExpiredError(`${label} request failed with status ${res.status}`);
+      this.logger.warn("auth token request failed", {label, status: res.status})
+      throw new AuthExpiredError(`${label} request failed with status ${res.status}`)
     }
 
-    return (await res.json()) as TokenResponse;
+    return (await res.json()) as TokenResponse
   }
 
   /**
@@ -522,11 +629,11 @@ export class Auth implements AuthModule {
    */
   private joinUrl(path: string): string {
     if (!this.baseUrl) {
-      throw new AuthExpiredError("core endpoint is not configured; this API is unavailable in runtime-only mode");
+      throw new AuthExpiredError("core endpoint is not configured; this API is unavailable in runtime-only mode")
     }
-    const base = this.baseUrl.replace(/\/+$/, "");
-    const suffix = path.replace(/^\/+/, "");
-    return `${base}/${suffix}`;
+    const base = this.baseUrl.replace(/\/+$/, "")
+    const suffix = path.replace(/^\/+/, "")
+    return `${base}/${suffix}`
   }
 
   /**
@@ -537,17 +644,23 @@ export class Auth implements AuthModule {
    * exchange/refresh so a later failure can notify again.
    */
   private fireExpired(): void {
-    if (this.expiredFired) return;
-    this.expiredFired = true;
+    if (this.expiredFired) return
+    this.expiredFired = true
     for (const handler of this.expiredHandlers) {
       try {
-        handler();
+        handler()
       } catch (err) {
         // A host handler throwing must not stop the others from running.
         this.logger.error("onExpired handler threw", {
           error: err instanceof Error ? err.message : String(err),
-        });
+        })
       }
     }
   }
+
+  private assertSessionActive(generation = this.sessionGeneration): void {
+    if (this.sessionCleared || generation !== this.sessionGeneration) {
+      throw new AuthExpiredError("auth session was cleared")
+    }
+  }
 }