@oxyhq/core 12.10.6 → 12.11.1

package/dist/types/session/identitySession.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Identity-bound session — pin reconciliation + establishment.
+ *
+ * This is the SDK half of "an identity vault's authenticated user is whoever
+ * owns the local primary key". Two operations, both consumed by the cold boot
+ * (`boot/sessionColdBoot.ts`) and the re-mint lane (`session/refresh.ts`):
+ *
+ *  - {@link resolveIdentityPin} — read the persisted `{publicKey, accountId}`
+ *    pin and reconcile it against the identity currently on this device. A
+ *    definitive mismatch (the key was replaced, or is gone) CLEARS the pin; an
+ *    INDETERMINATE read (keychain locked / storage threw) leaves it untouched.
+ *  - {@link establishIdentitySession} — mint a session from the PRIMARY local
+ *    key (`getPublicKey` → `requestChallenge` → `signChallenge` →
+ *    `verifyChallenge`), persist the resulting device credential, and write the
+ *    pin. This is the identity-mode replacement for the shared-keychain lane,
+ *    which reads the CROSS-APP shared slot and may therefore hold a different
+ *    identity than this device's primary.
+ *
+ * Both take their key/signature functions from an injectable {@link IdentityBinding}
+ * (defaulting to `KeyManager` / `SignatureService`) so the lanes above stay
+ * testable without a keychain.
+ *
+ * ESM-safe (no `require()`); no react/react-native/expo imports.
+ */
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import type { SessionLoginResponse } from '../models/session';
+import { type AuthChallenge } from '../crypto/signatureService';
+import { type IdentityPin, type IdentityPinStore } from './identityPin';
+/** Per-call transport overrides forwarded to the challenge/verify round-trips. */
+export interface IdentityRequestOptions {
+    retry?: boolean;
+    timeout?: number;
+}
+/**
+ * Everything an identity-bound client needs to resolve and re-establish its
+ * session. `@oxyhq/services` builds one of these (platform-appropriate pin
+ * store) and passes it to the cold boot and the refresh handler.
+ */
+export interface IdentityBinding {
+    /** Where the `{publicKey, accountId}` pin is persisted. */
+    pinStore: IdentityPinStore;
+    /**
+     * Reads this device's PRIMARY identity public key. Defaults to
+     * `KeyManager.getPublicKey()`. NEVER the shared-slot key.
+     */
+    readPublicKey?: () => Promise<string | null>;
+    /**
+     * Signs a server challenge with the PRIMARY local private key. Defaults to
+     * `SignatureService.signChallenge`.
+     */
+    signChallenge?: (challenge: string) => Promise<AuthChallenge>;
+    /** Optional device labels forwarded to `verifyChallenge`. */
+    deviceName?: string;
+    deviceFingerprint?: string;
+}
+/** The result of a successful {@link establishIdentitySession}. */
+export interface EstablishedIdentitySession {
+    session: SessionLoginResponse;
+    /** The pin as written: the local key plus the account the server resolved for it. */
+    pin: IdentityPin;
+}
+/**
+ * Read the persisted pin and reconcile it against the identity on this device.
+ *
+ * Returns the pin ONLY when the local primary public key still matches it — that
+ * is the single condition under which a client may bind its token and its
+ * rendered user to that account.
+ *
+ * Outcomes:
+ *  - no pin stored → `null` (nothing to clear).
+ *  - local key MATCHES → the pin (trusted).
+ *  - local key read succeeded and differs / is absent → the identity was
+ *    replaced or lost: CLEAR the pin and return `null`. Keeping it would pin the
+ *    client to an account it can no longer prove control of.
+ *  - the local key read THREW (keychain locked, storage unavailable) → return
+ *    `null` WITHOUT clearing. A read that produced no verdict is never evidence
+ *    of an identity change (the same rule `KeyManager` applies to its own
+ *    transient errors); the caller falls through to the identity sign-in lane,
+ *    which fails closed on a locked keychain rather than adopting a foreign
+ *    account.
+ */
+export declare function resolveIdentityPin(binding: IdentityBinding): Promise<IdentityPin | null>;
+/**
+ * Establish a session for the device's PRIMARY identity key and pin it.
+ *
+ * `requestChallenge` → `signChallenge` → `verifyChallenge`; `verifyChallenge`
+ * plants the access token itself. The server resolves the account from the
+ * VERIFIED SIGNER, so the returned session is identity-authoritative — it
+ * ignores the device's `activeAccountId` entirely.
+ *
+ * Side effects on success: the durable device credential is persisted (so the
+ * next boot can take the fast pinned-mint lane) and the pin is written.
+ *
+ * Returns `null` — never throws — for the two "nothing to do" cases: no local
+ * identity (including every web caller, where `KeyManager` has no key), and a
+ * verify that produced no access token. Network/crypto failures propagate so the
+ * caller can classify them.
+ */
+export declare function establishIdentitySession(args: {
+    oxy: OxyServices;
+    store: AuthStateStore;
+    binding: IdentityBinding;
+    requestOptions?: IdentityRequestOptions;
+}): Promise<EstablishedIdentitySession | null>;

package/dist/types/session/projectSessionState.d.ts

@@ -1,17 +1,6 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
-/**
- * Pure projection helpers: `DeviceSessionState` (the device-scoped
- * multi-account session-sync state produced by `SessionClient`) -> the
- * shapes `@oxyhq/services` consumers render today
- * (`ClientSession[]`, an active session id, an active `User`).
- *
- * No I/O. The caller fetches profiles via
- * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
- * from the result before calling `deviceStateToClientSessions` /
- * `activeUserOf`.
- */
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
  *
@@ -23,19 +12,32 @@ import type { User } from '../models/interfaces';
  * though `ClientSession` only stores `userId` — a session is still
  * projected for an account whose id is absent from `usersById` (no
  * placeholder user is fabricated).
+ *
+ * `isCurrent` marks the PINNED account when one is supplied, so it can never
+ * disagree with {@link activeSessionIdOf} / {@link activeUserOf} for the same
+ * pin.
  */
-export declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>): ClientSession[];
+export declare function deviceStateToClientSessions(state: DeviceSessionState, usersById: Map<string, User>, pinnedAccountId?: string | null): ClientSession[];
 /**
- * The active account's `sessionId`, or `null` when there is no state or no
- * active account is set.
+ * The bound account's `sessionId`, or `null` when there is no state, no bound
+ * account, or that account has no session on this device.
+ *
+ * A pinned account that is ABSENT from `state.accounts` yields `null` — the
+ * honest signal that this device no longer carries a session for the pinned
+ * identity, which the caller answers by re-establishing the identity session
+ * (never by adopting the device's active account).
  */
-export declare function activeSessionIdOf(state: DeviceSessionState | null): string | null;
+export declare function activeSessionIdOf(state: DeviceSessionState | null, pinnedAccountId?: string | null): string | null;
 /**
- * The active account's `User`, resolved from `usersById`. `null` when there
- * is no state, no active account is set, or the active account id is absent
- * from `usersById`.
+ * The bound account's `User`, resolved from `usersById`. `null` when there is no
+ * state, no bound account, or the bound account id is absent from `usersById`.
+ *
+ * A pinned user is resolved from `usersById` alone — deliberately NOT gated on
+ * device membership — so a transient device-state gap cannot flicker the
+ * identity vault's rendered user. Whether the pinned session still exists on the
+ * device is answered by {@link activeSessionIdOf}.
  */
-export declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>): User | null;
+export declare function activeUserOf(state: DeviceSessionState | null, usersById: Map<string, User>, pinnedAccountId?: string | null): User | null;
 /**
  * All account ids in `state`, suitable for an `oxyServices.getUsersByIds(...)`
  * fetch. `[]` for `null` state.

package/dist/types/session/refresh.d.ts

@@ -1,6 +1,8 @@
 import type { OxyServices } from '../OxyServices';
 import type { AuthRefreshHandler } from '../HttpService';
 import type { AuthStateStore } from './authStateStore';
+import type { IdentityPin } from './identityPin';
+import { type IdentityBinding } from './identitySession';
 /**
  * Lead time (ms) before access-token expiry at which the proactive scheduler
  * re-mints. Mirrors `HttpService`'s per-request `TOKEN_REFRESH_LEAD_SECONDS`
@@ -14,9 +16,19 @@ export interface RefreshDeps {
     /**
      * Whether to fall back to the native shared-keychain re-mint (arm 2) when the
      * persisted secret is absent / rejected. Defaults to `isNative()` — web has no
-     * shared keychain. Exposed for tests.
+     * shared keychain. Exposed for tests. IGNORED when {@link identity} is set: an
+     * identity-bound client must never adopt the CROSS-APP shared slot, which may
+     * hold a different identity than this device's primary key.
      */
     allowSharedKeyFallback?: boolean;
+    /**
+     * Identity-bound (pinned) mode. When present, every re-mint targets the
+     * PINNED account — resolved fresh from the pin store on each call, since a
+     * re-established session can move it — instead of the device's active
+     * account, and arm 2 becomes the PRIMARY-key identity sign-in rather than the
+     * shared-keychain one.
+     */
+    identity?: IdentityBinding;
 }
 /**
  * The outcome of ONE device-secret mint attempt (arm 1). Discriminated so both
@@ -28,6 +40,10 @@ export interface RefreshDeps {
  *    diverged (another tab/device rotated it past the grace window).
  *  - `no-session` — 401 `no_active_session`: the device is known but has no live
  *    session (authoritative signed-out).
+ *  - `account-not-on-device` — 401 `account_not_on_device` for a PINNED mint: the
+ *    pinned account is not (or no longer) a live account of this device session.
+ *    The device secret is FINE — it is the identity binding that went stale, so
+ *    the caller must re-establish from the local key, never drop the credential.
  *  - `transient` — network / 5xx; keep the secret, a later attempt can succeed.
  *  - `persist-failed` — the mint succeeded (the SERVER rotated the secret) but
  *    the rotated `nextDeviceSecret` could NOT be durably persisted. The token is
@@ -45,6 +61,8 @@ export type DeviceSecretMintOutcome = {
     status: 'invalid-secret';
 } | {
     status: 'no-session';
+} | {
+    status: 'account-not-on-device';
 } | {
     status: 'transient';
 } | {
@@ -70,10 +88,18 @@ export type DeviceSecretMintOutcome = {
  * planting. This function performs NO store mutation on failure — the caller
  * applies the drop/clear policy (which differs web vs native) from the returned
  * status.
+ *
+ * `pin` makes the mint IDENTITY-BOUND: the request carries the pinned
+ * `accountId` (so the server mints that account's token without touching
+ * `activeAccountId`), and the persisted `sessionId`/`userId` are resolved from
+ * the PINNED account entry — never from `state.activeAccountId`, whose drift is
+ * exactly what the pin exists to stop.
  */
 export declare function refreshDeviceSecretArm(deps: {
     oxy: OxyServices;
     store: AuthStateStore;
+    /** The identity pin, when this client is identity-bound. */
+    pin?: IdentityPin | null;
 }): Promise<DeviceSecretMintOutcome>;
 /**
  * Re-mint the persisted session and return the fresh access token, or `null`
@@ -91,6 +117,11 @@ export declare function refreshDeviceSecretArm(deps: {
  * recovered `{deviceId, deviceSecret, …}` is PERSISTED so the fast device-secret
  * lane is repopulated (mirrors the cold boot's `shared-key-signin` step) — an
  * in-session shared-key recovery must not leave the fast-lane credential empty.
+ *
+ * IDENTITY-BOUND clients (`deps.identity`) run a different arm 2: the
+ * shared-keychain lane is DISABLED (its cross-app slot may hold a different
+ * identity) and replaced by {@link establishIdentitySession}, which re-signs a
+ * challenge with the PRIMARY local key and rewrites the pin. Arm 1 is pinned.
  */
 export declare function refreshPersistedSession(deps: RefreshDeps): Promise<string | null>;
 /**

package/dist/types/utils/commonsDelivery.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Automatic "Sign in with Oxy" delivery selection (issue #691, Phase 4).
+ *
+ * The user performs ONE action ("Continue with Oxy"); Oxy — not the user —
+ * decides how the approval request reaches their Commons identity. This module
+ * is that decision, and nothing else: a single pure function mapping the facts
+ * the caller has gathered onto exactly ONE primary route.
+ *
+ * Deliberate design constraints:
+ *
+ *  - **Pure.** No I/O, no platform sniffing, no clock, no globals. Every input
+ *    is passed in by the caller, which is what makes the decision exhaustively
+ *    unit-testable and identical on web, native, and server.
+ *  - **One route, never a chain.** The result is the PRIMARY route only.
+ *    Alternatives stay hidden behind a "Having trouble?" affordance and are
+ *    revealed by the UI only once the primary route fails or is unavailable —
+ *    the SDK never silently cascades from one delivery surface to the next.
+ *  - **Fail-safe to QR.** QR is the route that works with no prior knowledge of
+ *    the device, so every ambiguous or malformed input degrades to it rather
+ *    than to a route that could leave the user staring at a dead end.
+ *
+ * Every route drives the SAME `AuthSession`, resolved from the same public
+ * `authorizeCode`; the route only decides how that code travels.
+ */
+/**
+ * The kind of surface the sign-in was initiated from.
+ *
+ * `'unknown'` is a first-class value, not an error: a caller that cannot
+ * confidently classify the surface must say so rather than guess, and an
+ * unknown surface never opts into the deep-link route (a custom-scheme
+ * navigation that does not resolve is a dead end with no automatic way back).
+ */
+export type CommonsDeliveryPlatform = 'mobile' | 'desktop' | 'unknown';
+/**
+ * The single primary route chosen for this request.
+ *
+ *  - `'open-commons'` — navigate to the verified Commons app/universal link on
+ *    THIS device and let the user confirm there.
+ *  - `'await-push'` — the request was pushed to a known Commons installation;
+ *    show "Check Commons on your phone" and wait for the authorization.
+ *  - `'qr'` — render the QR carrying the public `authorizeCode` for the user to
+ *    scan with Commons on another device.
+ */
+export type CommonsDeliveryRoute = 'open-commons' | 'await-push' | 'qr';
+/**
+ * The facts the caller must gather before asking for a route. All of them are
+ * observations, never decisions — the caller owns the platform detection, the
+ * app-link verification, and the delivery round-trip; this module owns only the
+ * choice between them.
+ */
+export interface CommonsDeliveryFacts {
+    /** Which surface the sign-in was initiated from (see {@link CommonsDeliveryPlatform}). */
+    platform: CommonsDeliveryPlatform;
+    /**
+     * `true` only when a VERIFIED Commons app/universal link can be opened on
+     * this very device (an installed, link-verified Commons). "The user probably
+     * has Commons somewhere" is not this fact — that is what `pushTargets`
+     * expresses.
+     */
+    commonsAvailable: boolean;
+    /**
+     * How many eligible Commons installations the server said it delivered the
+     * request to — the `targets` field of `deliverCommonsSignIn`. Zero is a
+     * NORMAL outcome (no capable Commons install is registered for this
+     * identity), never an error; it simply means push is not a usable route.
+     */
+    pushTargets: number;
+}
+/**
+ * Choose the ONE primary delivery route for a "Sign in with Oxy" request.
+ *
+ * Decision order (issue #691, "Automatic delivery selection"):
+ *
+ *  1. Mobile with a verified Commons link available → open Commons directly.
+ *     No push is needed when the identity is already reachable on this device.
+ *  2. At least one eligible Commons installation was pushed to → await the push.
+ *  3. Otherwise → QR.
+ *
+ * A caller that already knows it is on step 1 does not need to call
+ * `deliverCommonsSignIn` at all; every other caller runs the delivery
+ * round-trip first and passes its `targets` in here.
+ *
+ * `pushTargets` is server-derived, so it is validated rather than trusted: a
+ * negative, fractional, non-finite, or otherwise malformed count is treated as
+ * "no targets" and degrades to QR instead of parking the user on a "check your
+ * phone" screen that nothing will ever wake.
+ */
+export declare function selectCommonsDelivery(facts: CommonsDeliveryFacts): CommonsDeliveryRoute;
+/**
+ * Map a `deliverCommonsSignIn` result onto the `pushTargets` fact for
+ * {@link selectCommonsDelivery}. The server reports eligible install *count*
+ * separately from whether any push was accepted — a transport failure can leave
+ * `delivered: false` with `targets > 0`, which must NOT park the user on
+ * "check your phone".
+ */
+export declare function pushTargetsFromDelivery(result: {
+    delivered: boolean;
+    targets: number;
+}): number;
+/**
+ * Classify the current runtime surface for delivery selection. Callers that
+ * cannot confidently detect the platform should not use this — pass
+ * `'unknown'` explicitly instead.
+ */
+export declare function commonsDeliveryPlatform(): CommonsDeliveryPlatform;

package/dist/types/utils/oauthPkce.d.ts

@@ -47,6 +47,18 @@ export interface BuildOAuthAuthorizeUrlParams {
      * (no UI when the IdP hub already has a session + grant).
      */
     prompt?: 'none' | 'login' | 'consent';
+    /**
+     * How the IdP should deliver the authorization response. Omitted (the
+     * default) means the ordinary top-level redirect back to `redirectUri`.
+     *
+     * `web_message` asks the IdP to `postMessage` the result to its opener
+     * instead, so a popup sign-in never navigates the relying party's tab. It is
+     * a REQUEST, not a guarantee: an IdP with no opener still redirects, which is
+     * why the popup transport must handle both outcomes. Only the authorization
+     * code, the `state`, and a typed OAuth error ever cross that channel — never
+     * a token, device secret, or the PKCE verifier, which the opener keeps.
+     */
+    responseMode?: 'web_message';
 }
 /**
  * Compute the PKCE S256 `code_challenge` for a given verifier:
@@ -81,6 +93,8 @@ export declare function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlPar
 export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
 /** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
 export declare const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = "oxy_oauth_code_verifier";
+/** `sessionStorage` key — the exact `redirect_uri` sent on the authorize request. */
+export declare const OXY_OAUTH_REDIRECT_URI_STORAGE_KEY = "oxy.oauth_redirect_uri";
 /** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
 export declare const OXY_SILENT_OAUTH_ATTEMPTED_KEY = "oxy.silent_oauth_attempted";
 /** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
@@ -100,6 +114,11 @@ export declare const OXY_OAUTH_RETURN_PATH_STORAGE_KEY = "oxy.oauth_return_path"
  * out-of-band and restored on return.
  */
 export declare function normalizeOAuthRedirectUri(input: string): string;
+/**
+ * Collapse `https://app.example/` → `https://app.example` for OAuth binding.
+ * Path-qualified redirect URIs are preserved — matches the API token exchange.
+ */
+export declare function canonicalizeOAuthRedirectUri(redirectUri: string): string;
 /**
  * Remember the page the user was on before a full-page authorize redirect.
  *
@@ -123,11 +142,12 @@ export declare function persistOAuthReturnPath(path: string): void;
  */
 export declare function consumeOAuthReturnPath(): string | null;
 /** Persist the OAuth handshake for a full-page redirect return (web only). */
-export declare function persistOAuthHandshake(state: string, codeVerifier: string): boolean;
+export declare function persistOAuthHandshake(state: string, codeVerifier: string, redirectUri?: string): boolean;
 /** Read the persisted OAuth handshake, or `null` when absent. */
 export declare function readOAuthHandshake(): {
     state: string;
     codeVerifier: string;
+    redirectUri?: string;
 } | null;
 /** Drop persisted OAuth handshake keys after a successful or aborted return. */
 export declare function clearOAuthHandshake(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.10.6",
+  "version": "12.11.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,7 +115,7 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.17.0",
+    "@oxyhq/contracts": "^0.18.0",
     "@oxyhq/protocol": "^0.1.5",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
@@ -157,7 +157,7 @@
     "expo-crypto": "~56.0.3",
     "expo-secure-store": "~56.0.4",
     "express": "^4.22.2",
-    "express-rate-limit": "^7.5.0",
+    "express-rate-limit": "^8.6.0",
     "regexpu-core": "^6.4.0",
     "release-it": "^19.0.6",
     "typescript": "^5.9.2"

package/src/HttpService.ts

@@ -143,12 +143,32 @@ const CSRF_FETCH_RETRY_DELAY_MS = 500;
 
 /**
  * Cooldown (ms) applied after a failed access-token refresh before another
- * refresh is attempted. Prevents a refresh storm (and server hammering) when
+ * refresh is attempted while the CURRENT token is still valid (a proactive,
+ * near-expiry refresh). Prevents a refresh storm (and server hammering) when
  * the auth refresh handler is failing — every in-flight request that
- * hits a 401 would otherwise trigger its own refresh.
+ * hits a 401 would otherwise trigger its own refresh. A still-valid token can
+ * afford to wait this out; the request keeps carrying it in the meantime.
  */
 const TOKEN_REFRESH_COOLDOWN_MS = 15000;
 
+/**
+ * Cooldown (ms) applied after a failed refresh when the CURRENT access token is
+ * already past its `exp`. Much shorter than {@link TOKEN_REFRESH_COOLDOWN_MS}:
+ * an expired token is UNUSABLE, so the client must re-mint as soon as the mint
+ * endpoint is reachable again (e.g. a few seconds after an ECS rolling-deploy
+ * blip drains/restarts a task) instead of waiting out the full proactive
+ * cooldown while every request forwards or omits a stale bearer → server 401.
+ *
+ * Still NON-ZERO on purpose: it bounds the request-driven retry rate to at most
+ * one attempt per this interval so a PROLONGED outage cannot become a tight
+ * network storm. Combined with the process-wide single-flight below (concurrent
+ * requests coalesce to one in-flight mint) and the refresh handler's own
+ * terminal-state handling (a genuinely revoked session clears its device
+ * credential and stops issuing network mints), this recovers a transient blip
+ * ~15× faster without weakening the storm guard.
+ */
+const EXPIRED_TOKEN_REFRESH_COOLDOWN_MS = 1000;
+
 /**
  * Lead time (seconds) before access-token expiry at which a preflight refresh
  * is triggered. A token within this window of `exp` is treated as effectively
@@ -247,7 +267,15 @@ export class HttpService {
   private logger: SimpleLogger;
   private config: OxyConfig;
   private tokenRefreshPromise: Promise<string | null> | null = null;
-  private tokenRefreshCooldownUntil = 0;
+  /**
+   * Epoch ms of the last FAILED refresh (0 = none since the last success). The
+   * post-failure cooldown is measured from here; its length depends on whether
+   * the current token is still valid ({@link TOKEN_REFRESH_COOLDOWN_MS}) or
+   * already expired ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}), so an expired
+   * token recovers promptly the instant it crosses `exp` — without storing a
+   * fixed deadline that could not shrink once the token expired mid-cooldown.
+   */
+  private lastRefreshFailureAt = 0;
   private authRefreshHandler: AuthRefreshHandler | null = null;
   private accessTokenProvider: AccessTokenProvider | null = null;
   private deviceSecretMintInFlight: Promise<DeviceSecretMintOutcome> | null = null;
@@ -1058,7 +1086,16 @@ export class HttpService {
       return null;
     }
 
-    if (Date.now() < this.tokenRefreshCooldownUntil) {
+    // Post-failure cooldown. A genuinely EXPIRED current token uses a much
+    // shorter cooldown than a still-valid (proactive, near-expiry) one: an
+    // expired token is unusable, so re-mint as soon as the endpoint is reachable
+    // again rather than waiting out the full window while requests carry a stale
+    // bearer. Both cooldowns are measured from the last failure, so the moment a
+    // still-valid token crosses `exp` mid-cooldown the shorter window applies.
+    const cooldownMs = this.isAccessTokenExpired()
+      ? EXPIRED_TOKEN_REFRESH_COOLDOWN_MS
+      : TOKEN_REFRESH_COOLDOWN_MS;
+    if (Date.now() - this.lastRefreshFailureAt < cooldownMs) {
       return null;
     }
 
@@ -1066,19 +1103,22 @@ export class HttpService {
       this.tokenRefreshPromise = this.authRefreshHandler(reason)
         .then((newToken) => {
           if (!newToken) {
-            this.tokenRefreshCooldownUntil = Date.now() + TOKEN_REFRESH_COOLDOWN_MS;
+            this.lastRefreshFailureAt = Date.now();
             return null;
           }
           if (this.tokenStore.getAccessToken() !== newToken) {
             this.tokenStore.setTokens(newToken);
             this.notifyTokenChange();
           }
+          // A success clears the failure timestamp so the next refresh is never
+          // throttled by a stale cooldown.
+          this.lastRefreshFailureAt = 0;
           this.logger.debug('Token refreshed via the auth refresh handler');
           return newToken;
         })
         .catch((error) => {
           this.logger.warn('Token refresh failed:', error);
-          this.tokenRefreshCooldownUntil = Date.now() + TOKEN_REFRESH_COOLDOWN_MS;
+          this.lastRefreshFailureAt = Date.now();
           return null;
         })
         .finally(() => {
@@ -1089,6 +1129,27 @@ export class HttpService {
     return this.tokenRefreshPromise;
   }
 
+  /**
+   * Whether the CURRENT stored access token is already past its `exp`. Drives
+   * the shorter post-failure refresh cooldown ({@link EXPIRED_TOKEN_REFRESH_COOLDOWN_MS}):
+   * a still-valid (near-expiry) token can wait out the full cooldown, but an
+   * expired one must re-mint promptly. Returns `false` for an absent or
+   * opaque/no-`exp` token — no proof it is expired, so keep the conservative
+   * (longer) cooldown and avoid an unnecessary retry loop.
+   */
+  private isAccessTokenExpired(): boolean {
+    const token = this.tokenStore.getAccessToken();
+    if (!token) {
+      return false;
+    }
+    try {
+      const decoded = jwtDecode<JwtPayload>(token);
+      return typeof decoded.exp === 'number' && decoded.exp <= Math.floor(Date.now() / 1000);
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * PROCESS-WIDE single-flight for the rotating device-secret mint
    * (`POST /session/device/token`).

package/src/__tests__/inSessionRefresh.test.ts

@@ -164,6 +164,73 @@ describe('HttpService in-session refresh handler', () => {
     // The second call is inside the post-failure cooldown → handler not re-run.
     expect(handlerCalls).toBe(1);
   });
+
+  it('lets an EXPIRED token re-mint promptly instead of waiting out the long proactive cooldown', async () => {
+    // Regression: an ECS rolling-deploy blip briefly fails a mint; the 15s
+    // proactive cooldown then left the client forwarding/omitting a now-expired
+    // bearer for up to 15s after the endpoint recovered (Mention /privacy 401s).
+    // An already-expired token must recover on the short cooldown instead.
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const nowSpy = jest.spyOn(Date, 'now');
+    const T0 = 1_000_000_000_000;
+    nowSpy.mockReturnValue(T0);
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    // Current token is already 10s past exp (exp is in SECONDS).
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(T0 / 1000) - 10 }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    // First attempt fails → records the failure timestamp.
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 500ms later: still inside the SHORT expired cooldown → NOT re-run. This is
+    // the storm guard — an expired token does not fully bypass the cooldown.
+    nowSpy.mockReturnValue(T0 + 500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 1.5s later: past the short expired cooldown but WELL inside the 15s
+    // proactive cooldown → the expired token re-mints promptly.
+    nowSpy.mockReturnValue(T0 + 1500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(2);
+
+    nowSpy.mockRestore();
+  });
+
+  it('keeps the full 15s cooldown for a still-valid (proactive) near-expiry refresh', async () => {
+    globalThis.fetch = async () => jsonResponse({ ok: true });
+    const nowSpy = jest.spyOn(Date, 'now');
+    const T0 = 1_000_000_000_000;
+    nowSpy.mockReturnValue(T0);
+
+    const http = new HttpService({ baseURL: 'https://api.mention.earth', enableRetry: false });
+    // Token is still valid for another hour — a proactive refresh, not expired.
+    http.setTokens(createJwt({ userId: 'u', exp: Math.floor(T0 / 1000) + 3600 }));
+
+    let handlerCalls = 0;
+    http.setAuthRefreshHandler(async () => {
+      handlerCalls += 1;
+      return null;
+    });
+
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    // 1.5s later: past the short expired cooldown, but the token is NOT expired,
+    // so the full proactive cooldown still applies → no re-run (no storm).
+    nowSpy.mockReturnValue(T0 + 1500);
+    await http.refreshAccessToken('preflight');
+    expect(handlerCalls).toBe(1);
+
+    nowSpy.mockRestore();
+  });
 });
 
 describe('OxyServices.getAccessTokenExpiry', () => {