@oxyhq/core 12.11.0 → 12.11.1

package/dist/types/HttpService.d.ts

@@ -89,7 +89,15 @@ export declare class HttpService {
     private logger;
     private config;
     private tokenRefreshPromise;
-    private tokenRefreshCooldownUntil;
+    /**
+     * 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;
     private authRefreshHandler;
     private accessTokenProvider;
     private deviceSecretMintInFlight;
@@ -224,6 +232,15 @@ export declare class HttpService {
      */
     private getAuthHeader;
     refreshAccessToken(reason: AuthRefreshReason): Promise<string | null>;
+    /**
+     * 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;
     /**
      * PROCESS-WIDE single-flight for the rotating device-secret mint
      * (`POST /session/device/token`).

package/dist/types/mixins/OxyServices.user.d.ts

@@ -55,6 +55,8 @@ export interface ViewerGraph {
     mutualIds: string[];
     /** Accounts the viewer has blocked (bounded). */
     blockedIds: string[];
+    /** Accounts the viewer has restricted (bounded). */
+    restrictedIds: string[];
 }
 /** Per-user outcome returned by `POST /users/unfollow/bulk`. */
 export interface BulkUnfollowEntry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.11.0",
+  "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",
@@ -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', () => {

package/src/mixins/OxyServices.privacy.ts

@@ -167,6 +167,9 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
           cache: false,
         });
         this.clearCacheEntry('GET:/privacy/restricted');
+        // The restriction changed the viewer's graph (`restrictedIds`) — bust the
+        // cached consolidated `GET /users/me/graph` so the next read reflects it.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -190,6 +193,9 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
           cache: false,
         });
         this.clearCacheEntry('GET:/privacy/restricted');
+        // Symmetric to restrictUser: the unrestrict changed the viewer's
+        // `restrictedIds`, so bust the consolidated `GET /users/me/graph` cache.
+        this.clearCacheEntry('GET:/users/me/graph');
         return result;
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/OxyServices.user.ts

@@ -92,6 +92,8 @@ export interface ViewerGraph {
   mutualIds: string[];
   /** Accounts the viewer has blocked (bounded). */
   blockedIds: string[];
+  /** Accounts the viewer has restricted (bounded). */
+  restrictedIds: string[];
 }
 
 /** Per-user outcome returned by `POST /users/unfollow/bulk`. */
@@ -1044,6 +1046,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           followingIds: graph?.followingIds || [],
           mutualIds: graph?.mutualIds || [],
           blockedIds: graph?.blockedIds || [],
+          restrictedIds: graph?.restrictedIds || [],
         };
       } catch (error) {
         throw this.handleError(error);

package/src/mixins/__tests__/privacyCacheInvalidation.test.ts

@@ -134,10 +134,12 @@ describe('privacy cache invalidation', () => {
     fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
     await oxy.blockUser('u1');
     expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/blocked');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/me/graph');
 
     fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
     await oxy.restrictUser('u2');
     expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/restricted');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/me/graph');
 
     fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: true }));
     await oxy.updatePrivacySettings({ isPrivateAccount: true }, 'me');