@oxyhq/core 12.11.0 → 13.0.0

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/index.d.ts

@@ -26,7 +26,7 @@ export { getCommonsApprovalBlockingReason, parseCommonsApprovalExpiresAt, } from
 export { selectCommonsDelivery, pushTargetsFromDelivery, commonsDeliveryPlatform } from './utils/commonsDelivery';
 export type { CommonsDeliveryFacts, CommonsDeliveryPlatform, CommonsDeliveryRoute, } from './utils/commonsDelivery';
 export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
-export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsDenyReason, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
+export type { CommonsSignInHandle, CommonsSignInStatus, CommonsSignInPurpose, CommonsOAuthContext, CommonsApprovalInfo, CommonsApprovalSubjectAccount, CommonsSignInActionResult, CommonsOAuthFinalizeResult, CommonsDeliveryResult, } from './mixins/OxyServices.auth';
 export type { PushTokenPlatform, RegisterPushTokenInput, } from './mixins/OxyServices.notifications';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
@@ -96,11 +96,9 @@ export { CENTRAL_IDP_APEX } from './utils/authWebUrl';
 export { isOxyRpOrigin } from './utils/webauthnOrigin';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
-export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_SILENT_OAUTH_ATTEMPTED_KEY, OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
+export { buildOAuthAuthorizeUrl, computeCodeChallenge, generateOAuthState, generatePkcePair, DEFAULT_OAUTH_SCOPE, OXY_AUTHORIZE_URL, OXY_OAUTH_STATE_STORAGE_KEY, OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, OXY_OAUTH_REDIRECT_URI_STORAGE_KEY, OXY_OAUTH_RETURN_PATH_STORAGE_KEY, normalizeOAuthRedirectUri, canonicalizeOAuthRedirectUri, persistOAuthHandshake, readOAuthHandshake, clearOAuthHandshake, persistOAuthReturnPath, consumeOAuthReturnPath, } from './utils/oauthPkce';
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from './utils/officialOrigins';
-export { syncHubAfterSignIn, redeemHubTicketOnHub, } from './session/hubSync';
-export type { SyncHubAfterSignInOptions } from './session/hubSync';
+export { isLoopbackOrigin, isOfficialWebOrigin, isAllowedDeviceJoinOrigin, } from './utils/officialOrigins';
 export { SessionClient } from './session/SessionClient';
 export type { TokenTransport, SessionClientHost, SessionClientOptions, DeviceCredential, SessionStateOrigin } from './session/SessionClient';
 export type { SocketIOFactory, MinimalSocket } from './session/socketLoader';

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

@@ -4,7 +4,7 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import type { LoginResult, LoginSessionResult, CommonsDenyReason } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import type { PublicApplication } from './OxyServices.connectedApps';
@@ -226,17 +226,6 @@ export interface CommonsApprovalInfo {
 export interface CommonsSignInActionResult {
     success: boolean;
 }
-/**
- * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
- * endpoint is unauthenticated, so it accepts no free-form text:
- *
- *  - `'declined'` the approver rejected a request they recognised ("Not now").
- *  - `'not_me'`   the approver did not start the request ("This wasn't me").
- *                 The only value that records the denial as suspicious rather
- *                 than an ordinary cancel, so a UI may only offer it where the
- *                 user genuinely said so.
- */
-export type CommonsDenyReason = 'declined' | 'not_me';
 /**
  * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
  *

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

@@ -13,7 +13,7 @@
  * the cold boot / re-mint handler own persistence and `setTokens`, so the same
  * primitive can be reused from either without double-planting.
  */
-import { type DeviceTokenMintResponse, type DeviceHubTicketIssueResponse, type DeviceHubTicketRedeemResponse } from '@oxyhq/contracts';
+import { type DeviceTokenMintResponse } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 /**
  * The server's `401 account_not_on_device` for a PINNED mint: the requested
@@ -71,10 +71,6 @@ export declare function OxyServicesDeviceBootMixin<T extends typeof OxyServicesB
         mintFromDeviceSecret(deviceId: string, deviceSecret: string, options?: {
             accountId?: string;
         }): Promise<DeviceTokenMintResponse>;
-        /** Mint a one-time hub sync ticket (bearer required). */
-        issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse>;
-        /** Redeem a hub sync ticket for a fresh device secret (public). */
-        redeemHubTicket(ticket: string, returnOrigin: string): Promise<DeviceHubTicketRedeemResponse>;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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/dist/types/server/index.d.ts

@@ -24,4 +24,4 @@ export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
 export { verifySecret } from './verifySecret';
 export { registrableApex } from '../utils/registrableApex';
-export { buildIdpHubOrigin, buildHubSyncUrl, isIdpHubOrigin, isOfficialWebOrigin, normalizeOfficialReturnOrigin, parseHubSyncReturnUrl, } from '../utils/officialOrigins';
+export { isOfficialWebOrigin } from '../utils/officialOrigins';

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

@@ -231,21 +231,17 @@ export interface AccountDialogControllerOptions {
      * `SessionClient.registerAndActivate` (registration + activation only — no
      * provider-side durable persist/hydration).
      *
-     * This is the SIGN-IN commit: on an official web origin it may run the
-     * cross-origin hub-sync (a full-page redirect to `auth.oxy.so/sync`) that
-     * bootstraps silent OAuth restore on OTHER origins. A first sign-in on a web
-     * origin legitimately needs that. An account SWITCH does NOT — see
-     * {@link commitSwitchedSession}.
+     * This is the SIGN-IN commit: registers the session into the host's device
+     * set with durable persist + profile hydration. An account SWITCH uses
+     * {@link commitSwitchedSession} instead — see below.
      */
     commitSession?: (session: SessionLoginResponse) => Promise<void>;
     /**
      * Commit a minted graph SWITCH session into the host's session set — same
      * device-first registration + durable persist + profile hydration as
-     * {@link commitSession}, but IN-PLACE: it must NOT trigger the cross-origin
-     * hub-sync redirect. Switching into an account you already operate reuses the
-     * device credential that was already hub-synced at the original sign-in, so
-     * re-syncing is redundant and a full-page redirect on switch is the exact
-     * regression this separation prevents. Cross-tab/app propagation of the switch
+     * {@link commitSession}, but IN-PLACE: it must NOT re-run sign-in side effects
+     * that belong only to a fresh authorization (for example, a redundant full
+     * device-set reconcile on switch). Cross-tab/app propagation of the switch
      * still happens instantly via the server's device-scoped `session_state` /
      * `session_accounts_changed` socket broadcast — no navigation required.
      *
@@ -600,11 +596,9 @@ export declare class AccountDialogController {
      * consumer's commit funnel (durable persist + hydration); falls back to
      * `SessionClient.registerAndActivate` (registration + activation only).
      *
-     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel
-     * so it never runs the cross-origin hub-sync redirect; a SIGN-IN uses
-     * `commitSession` (which may hub-sync on an official web origin). When the
-     * switch funnel is not wired it falls back to the sign-in funnel, then to
-     * `registerAndActivate`.
+     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel;
+     * a SIGN-IN uses `commitSession`. When the switch funnel is not wired it falls
+     * back to the sign-in funnel, then to `registerAndActivate`.
      */
     private commitAuthorizedSession;
     private failSignIn;

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

@@ -43,10 +43,18 @@ export interface BuildOAuthAuthorizeUrlParams {
     /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
     codeChallenge: string;
     /**
-     * OAuth `prompt` parameter. Use `none` for silent cross-origin session restore
-     * (no UI when the IdP hub already has a session + grant).
+     * OAuth `prompt` parameter — `login` forces a fresh authentication even when
+     * the IdP already has a session, `consent` forces the consent screen even for
+     * an already-granted scope. Both are ordinary OAuth/OIDC and are here for
+     * third-party relying parties building their own authorize link.
+     *
+     * `'none'` is deliberately NOT in this union. It is the silent-SSO value, and
+     * it was the only value this SDK ever sent — from the cold-boot cross-origin
+     * restore deleted in #691 phase 7b. Accepting it again would hand consumers a
+     * one-line rebuild of the automatic, gesture-less full-page bounce to the IdP
+     * that the popup transport exists to eliminate.
      */
-    prompt?: 'none' | 'login' | 'consent';
+    prompt?: 'login' | 'consent';
     /**
      * How the IdP should deliver the authorization response. Omitted (the
      * default) means the ordinary top-level redirect back to `redirectUri`.
@@ -95,10 +103,6 @@ export declare const OXY_OAUTH_STATE_STORAGE_KEY = "oxy_oauth_state";
 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. */
-export declare const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = "oxy.cross_origin_restore_attempted";
 /**
  * `sessionStorage` key for the in-app path to return to after an authorize
  * round trip. See {@link persistOAuthReturnPath}.

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

@@ -1,23 +1,13 @@
 /**
- * Official first-party web origin allowlist — shared by hub-ticket issuance,
- * OAuth redirect validation, and cross-origin session restore.
+ * Official first-party web origin allowlist — shared by OAuth redirect
+ * validation and the server-side trusted-origin checks.
  */
-export declare function buildIdpHubOrigin(): string;
-/** Whether the current web origin is the central IdP hub (`auth.oxy.so`). */
-export declare function isIdpHubOrigin(): boolean;
 /**
  * Whether an origin is a loopback / local-dev origin (`localhost`, `127.0.0.1`,
- * or `[::1]` on any port, http or https). Local dev must never be bounced to a
- * hosted IdP for cross-origin session restore.
+ * or `[::1]` on any port, http or https).
  */
 export declare function isLoopbackOrigin(origin: string): boolean;
 /** Whether an origin belongs to the official Oxy web ecosystem. */
 export declare function isOfficialWebOrigin(origin: string): boolean;
-/** Normalize and validate a return URL against official origins. Returns origin only. */
-export declare function normalizeOfficialReturnOrigin(raw: string): string | null;
-/** Validate a hub-sync return URL; returns the full normalized URL string. */
-export declare function parseHubSyncReturnUrl(raw: string | null): string | null;
-/** Build auth.oxy.so/sync redirect URL with a one-time hub ticket. */
-export declare function buildHubSyncUrl(ticket: string, returnUrl?: string): string;
 /** @deprecated Use {@link isOfficialWebOrigin}. */
 export declare const isAllowedDeviceJoinOrigin: typeof isOfficialWebOrigin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "12.11.0",
+  "version": "13.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -115,8 +115,8 @@
   "dependencies": {
     "@noble/ciphers": "^1.3.0",
     "@noble/hashes": "^1.8.0",
-    "@oxyhq/contracts": "^0.18.0",
-    "@oxyhq/protocol": "^0.1.5",
+    "@oxyhq/contracts": "^0.19.0",
+    "@oxyhq/protocol": "^0.1.6",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",
     "elliptic": "^6.6.1",
@@ -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/index.ts

@@ -59,10 +59,15 @@ export type {
     CommonsApprovalInfo,
     CommonsApprovalSubjectAccount,
     CommonsSignInActionResult,
-    CommonsDenyReason,
     CommonsOAuthFinalizeResult,
     CommonsDeliveryResult,
 } from './mixins/OxyServices.auth';
+// `denyCommonsSignIn`'s reason parameter is typed by `CommonsDenyReason`, which
+// is a WIRE contract shared with the API (the request schema of
+// `POST /auth/session/deny/:authorizeCode` and the persisted
+// `AuthSession.deniedReason` enum read the same declaration). It lives in
+// `@oxyhq/contracts` and is NOT re-exported here: consumers import API contract
+// types directly from `@oxyhq/contracts`, per the package boundary rule.
 // Push-token registration (Expo push tokens — never raw APNs/FCM device tokens).
 export type {
     PushTokenPlatform,
@@ -601,8 +606,6 @@ export {
     OXY_OAUTH_STATE_STORAGE_KEY,
     OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY,
     OXY_OAUTH_REDIRECT_URI_STORAGE_KEY,
-    OXY_SILENT_OAUTH_ATTEMPTED_KEY,
-    OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY,
     OXY_OAUTH_RETURN_PATH_STORAGE_KEY,
     normalizeOAuthRedirectUri,
     canonicalizeOAuthRedirectUri,
@@ -615,22 +618,11 @@ export {
 export type { PkcePair, BuildOAuthAuthorizeUrlParams } from './utils/oauthPkce';
 
 export {
-    buildIdpHubOrigin,
-    buildHubSyncUrl,
-    isIdpHubOrigin,
     isLoopbackOrigin,
     isOfficialWebOrigin,
     isAllowedDeviceJoinOrigin,
-    normalizeOfficialReturnOrigin,
-    parseHubSyncReturnUrl,
 } from './utils/officialOrigins';
 
-export {
-    syncHubAfterSignIn,
-    redeemHubTicketOnHub,
-} from './session/hubSync';
-export type { SyncHubAfterSignInOptions } from './session/hubSync';
-
 // ---------------------------------------------------------------------------
 // Session sync (device-scoped multi-account session client)
 // ---------------------------------------------------------------------------

package/src/mixins/OxyServices.auth.ts

@@ -4,7 +4,12 @@
  * Supports password-based login (email/username) and public key challenge-response.
  */
 import type { User } from '../models/interfaces';
-import type { UserNameResponse, LoginResult, LoginSessionResult } from '@oxyhq/contracts';
+import type {
+  UserNameResponse,
+  LoginResult,
+  LoginSessionResult,
+  CommonsDenyReason,
+} from '@oxyhq/contracts';
 import { loginResultSchema, safeParseContract } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
@@ -336,18 +341,6 @@ export interface CommonsSignInActionResult {
   success: boolean;
 }
 
-/**
- * Why the approver denied a "Sign in with Oxy" request. A CLOSED set — the deny
- * endpoint is unauthenticated, so it accepts no free-form text:
- *
- *  - `'declined'` the approver rejected a request they recognised ("Not now").
- *  - `'not_me'`   the approver did not start the request ("This wasn't me").
- *                 The only value that records the denial as suspicious rather
- *                 than an ordinary cancel, so a UI may only offer it where the
- *                 user genuinely said so.
- */
-export type CommonsDenyReason = 'declined' | 'not_me';
-
 /**
  * Result of finalizing an approved, OAuth-bound "Sign in with Oxy" request.
  *

package/src/mixins/OxyServices.deviceBoot.ts

@@ -15,12 +15,8 @@
  */
 import {
   deviceTokenMintResponseSchema,
-  deviceHubTicketIssueResponseSchema,
-  deviceHubTicketRedeemResponseSchema,
   safeParseContract,
   type DeviceTokenMintResponse,
-  type DeviceHubTicketIssueResponse,
-  type DeviceHubTicketRedeemResponse,
 } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 
@@ -124,48 +120,5 @@ export function OxyServicesDeviceBootMixin<T extends typeof OxyServicesBase>(Bas
         throw normalized;
       }
     }
-
-    /** Mint a one-time hub sync ticket (bearer required). */
-    async issueHubTicket(returnOrigin: string): Promise<DeviceHubTicketIssueResponse> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/session/device/hub-ticket',
-          { returnOrigin },
-          { cache: false },
-        );
-        const parsed = safeParseContract(deviceHubTicketIssueResponseSchema, res);
-        if (!parsed) {
-          throw new Error('session/device/hub-ticket returned an unexpected response shape');
-        }
-        return parsed;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
-
-    /** Redeem a hub sync ticket for a fresh device secret (public). */
-    async redeemHubTicket(
-      ticket: string,
-      returnOrigin: string,
-    ): Promise<DeviceHubTicketRedeemResponse> {
-      try {
-        const res = await this.makeRequest<unknown>(
-          'POST',
-          '/session/device/redeem-ticket',
-          { ticket, returnOrigin },
-          // Public device-hub sync mint (bearer-less). Same control-plane class as
-          // the device-secret mint — bypassQueue so it never waits for a slot.
-          { cache: false, skipAuth: true, bypassQueue: true },
-        );
-        const parsed = safeParseContract(deviceHubTicketRedeemResponseSchema, res);
-        if (!parsed) {
-          throw new Error('session/device/redeem-ticket returned an unexpected response shape');
-        }
-        return parsed;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-    }
   };
 }

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);