@oxyhq/core 2.2.1 → 2.3.0

package/dist/types/index.d.ts

@@ -72,11 +72,12 @@ export type { LogContext } from './utils/loggerUtils';
 export { updateAvatarVisibility } from './utils/avatarUtils';
 export { buildAccountsArray, createQuickAccount, getAccountDisplayName, getAccountFallbackHandle, formatPublicKeyHandle, mergeAccountsFromRefreshAll, getAccountColor, } from './utils/accountUtils';
 export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
-export { autoDetectAuthWebUrl } from './utils/fapiAutoDetect';
-export { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './utils/authWebUrl';
-export { parseSsoReturnFragment } from './utils/ssoReturn';
-export type { SsoReturnKind, SsoReturnResult } from './utils/ssoReturn';
+export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
+export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';
+export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
+export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
+export { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoNavigate, buildSsoBounceUrl, isCentralIdPOrigin, guardActive, } from './utils/ssoBounce';
 export { runColdBoot } from './utils/coldBoot';
 export type { ColdBootStep, ColdBootStepResult, ColdBootSession, ColdBootSkip, ColdBootOutcome, RunColdBootOptions, } from './utils/coldBoot';
 export { packageInfo } from './constants/version';

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

@@ -51,6 +51,12 @@ interface ServiceTokenCacheEntry {
     secretBuf: Buffer;
     /** In-flight refresh promise (deduplicates concurrent callers) */
     pending: Promise<string> | null;
+    /**
+     * The raw apiKey that produced this entry. Retained so a targeted, fully
+     * synchronous `invalidateServiceToken(apiKey)` can locate the entry without
+     * re-deriving the async `SHA-256(apiKey)` Map key. Never logged or returned.
+     */
+    apiKey: string;
 }
 /**
  * Sentinel error raised when getServiceToken() is called with a known apiKey
@@ -132,6 +138,35 @@ export declare function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(B
          * @internal
          */
         _doFetchServiceToken(key: string, secret: string, cacheKey: string, secretBuf: Buffer): Promise<string>;
+        /**
+         * Invalidate cached service token(s), forcing the next `getServiceToken()`
+         * call to mint a fresh token from `/auth/service-token`.
+         *
+         * `getServiceToken()` only refreshes on expiry (with a 60s clock-drift
+         * buffer), so a credential that is revoked or rotated mid-run — surfaced as
+         * a 401 on a downstream service request — cannot otherwise be recovered
+         * within the same process: the still-unexpired cached token keeps being
+         * returned. Call this after such a 401 to clear the stale entry; the very
+         * next `getServiceToken()` for that credential re-mints.
+         *
+         * Fully synchronous and deterministic: the call completes before it
+         * returns, so a `getServiceToken()` issued immediately afterwards is
+         * guaranteed to see the cleared cache and mint anew.
+         *
+         * @param apiKey - When provided, clears only the cache entry for that
+         *   specific apiKey. When omitted, clears the entry for the credential set
+         *   via `configureServiceAuth()`; if neither is available (no key to
+         *   target), clears the entire cache. Passing no argument is the common
+         *   case for hosts that configured a single service credential at startup.
+         *
+         * The cache Map is keyed by an asynchronously-computed `SHA-256(apiKey)`
+         * that cannot be reproduced synchronously, so a targeted clear scans the
+         * entries and removes the one whose stored raw `apiKey` matches — keeping
+         * this method synchronous. The fully-untargeted call (no argument and no
+         * configured key) clears every entry, which is safe because each credential
+         * pair is independently re-minted on its next request.
+         */
+        invalidateServiceToken(apiKey?: string): void;
         /**
          * Make an authenticated request on behalf of a user using a service token.
          * Automatically obtains/refreshes the service token.

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

@@ -49,6 +49,13 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         }): Promise<User>;
         /**
          * Get profile recommendations, optionally filtering out specific user types.
+         *
+         * Public discovery read — works WITHOUT authentication. The SDK attaches the
+         * access token automatically when one is available (personalized via
+         * mutual-connection overlap), and falls back to popular public profiles when
+         * the caller is logged out. This deliberately does NOT use `withAuthRetry`,
+         * which would throw an authentication timeout for logged-out callers before
+         * the request is ever sent.
          */
         getProfileRecommendations(options?: {
             excludeTypes?: Array<"federated" | "agent" | "automated">;

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

@@ -16,9 +16,20 @@
  * derivation). The central-SSO path deliberately does NOT auto-detect per-apex
  * IdPs — it is central only. An explicitly-configured `authWebUrl` still wins.
  */
+/**
+ * The registrable apex (eTLD+1) of the Oxy ecosystem's central Identity
+ * Provider. The central IdP is reachable at `auth.${CENTRAL_IDP_APEX}` and the
+ * ID-token assertion issuer is always `https://auth.${CENTRAL_IDP_APEX}`
+ * regardless of which per-apex `auth.<rp>` host served a given request.
+ *
+ * Kept as a standalone constant so the IdP worker and the SDK derive the same
+ * literal from one source of truth (the worker imports it to brand assertions).
+ */
+export declare const CENTRAL_IDP_APEX = "oxy.so";
 /**
  * The canonical central Identity Provider origin for the Oxy ecosystem.
- * No trailing slash.
+ * No trailing slash. Derived from {@link CENTRAL_IDP_APEX} so the apex and the
+ * full origin never drift apart.
  */
 export declare const CENTRAL_AUTH_URL = "https://auth.oxy.so";
 /**

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

@@ -34,4 +34,40 @@
  * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
  * is required for end-to-end FedCM correctness — no per-RP config.
  */
+/**
+ * Known multi-part public suffixes where the registrable domain is the LAST
+ * THREE labels, not two. Deriving an apex from `labels.slice(-2)` against any
+ * of these would yield an attacker-registrable suffix (e.g. `auth.co.uk`),
+ * so we bail out instead.
+ *
+ * This is intentionally a small, explicit allow-list rather than the full
+ * Public Suffix List — it covers the suffixes the Oxy ecosystem's RPs use.
+ * Any multi-part-TLD RP MUST extend this set (or wire in a proper PSL check)
+ * before relying on this helper, otherwise auto-detection silently bails to
+ * `undefined` and the consumer must pass `authWebUrl` explicitly.
+ */
+export declare const MULTIPART_TLDS: ReadonlySet<string>;
+/**
+ * Compute the bare registrable apex (eTLD+1) of a hostname, guarding against
+ * multi-part public suffixes.
+ *
+ * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
+ * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
+ * and builds NO URL. It only answers "what is the registrable domain of this
+ * host, or is that undefinable?".
+ *
+ * Returns `null` (apex undefinable) for:
+ *   - empty input;
+ *   - IPv4 literals (`192.168.1.10`);
+ *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
+ *   - single-label hosts (`intranet`, `localhost`);
+ *   - hosts whose trailing two labels form a known multi-part public suffix
+ *     (e.g. `foo.co.uk`), where `labels.slice(-2)` would yield an
+ *     attacker-registrable suffix (`co.uk`) rather than a real registrable
+ *     domain. Such hosts MUST configure `authWebUrl` explicitly.
+ *
+ * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
+ * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
+ */
+export declare function registrableApex(hostname: string): string | null;
 export declare function autoDetectAuthWebUrl(location?: Pick<Location, 'hostname' | 'protocol'> | undefined): string | undefined;

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

@@ -0,0 +1,124 @@
+/**
+ * Central cross-domain SSO bounce — per-origin sessionStorage keys, the bounce
+ * URL builder, and the small pure predicates shared by every consumer's
+ * cold-boot `sso-return` / `sso-bounce` steps and bfcache `pageshow`
+ * re-evaluation.
+ *
+ * This is the single source of truth for the SSO bounce wire/storage contract.
+ * `@oxyhq/auth` (`WebOxyProvider`) and `@oxyhq/services` (`OxyContext`) both
+ * consume these helpers so the two providers behave identically.
+ *
+ * TRUE central SSO (Google/Meta/Clerk style) works like this for a Relying
+ * Party (mention.earth, homiio.com, alia.onl, …) with no local session:
+ *
+ *   1. `sso-bounce` (terminal, once): a TOP-LEVEL navigation to
+ *      `auth.oxy.so/sso?prompt=none&client_id=<origin>&return_to=<origin>{@link SSO_CALLBACK_PATH}&state=<s>`.
+ *      Before navigating it records, in this origin's `sessionStorage`, the
+ *      CSRF `state` ({@link ssoStateKey}), a guard timestamp ({@link ssoGuardKey},
+ *      the loop breaker), and the real destination URL ({@link ssoDestKey}) to
+ *      restore after the callback.
+ *   2. The central IdP worker reads its first-party `fedcm_session`, mints a
+ *      session, stores it under an opaque single-use `code`, and 303-redirects
+ *      back to `<origin>{@link SSO_CALLBACK_PATH}#oxy_sso=ok&code=<code>&state=<s>`
+ *      (or `#oxy_sso=none` / `#oxy_sso=error`).
+ *   3. `sso-return` parses the fragment (`parseSsoReturnFragment`), validates
+ *      `state`, exchanges the `code` via `oxyServices.exchangeSsoCode`, commits
+ *      the session, then restores the original destination.
+ *
+ * Loop proof (logged-out): first load all steps skip → `sso-bounce` sets
+ * guard/state/dest and navigates; the IdP (no central session) returns
+ * `#oxy_sso=none`; the callback load's `sso-return` sees `none`, sets the
+ * NO_SESSION flag ({@link ssoNoSessionKey}), and `sso-bounce` is then disabled.
+ * Exactly ONE bounce, no loop. An interrupted bounce (user hit back
+ * mid-redirect) self-heals once the {@link SSO_GUARD_TTL_MS} guard TTL lapses.
+ *
+ * All state lives in `sessionStorage` (per tab, cleared on tab close) and is
+ * keyed per-origin so two RPs hosted in the same browser never collide. The
+ * key strings and the 30s TTL are a wire/storage contract — they MUST match
+ * the values the IdP and every consumer expect and must not change lightly.
+ */
+/**
+ * The RP callback path the central IdP redirects back to after a bounce. The
+ * SSO result is delivered in the fragment of this URL; the `sso-return` step
+ * consumes it and then restores the user's real destination (stored under
+ * {@link ssoDestKey}), so the user never lingers on this internal path.
+ */
+export declare const SSO_CALLBACK_PATH = "/__oxy/sso-callback";
+/**
+ * Self-healing TTL (ms) for the bounce guard. An in-flight bounce sets a
+ * timestamp guard; if the bounce is interrupted before the callback lands
+ * (e.g. the user navigates back mid-redirect), the guard would otherwise pin
+ * the RP signed-out forever. After this window the guard is treated as stale
+ * and a fresh single bounce is permitted. 30s comfortably exceeds a real
+ * redirect round-trip while keeping a crash short-lived.
+ */
+export declare const SSO_GUARD_TTL_MS = 30000;
+/** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
+export declare function ssoStateKey(origin: string): string;
+/** Per-origin bounce guard key (a timestamp; loop breaker + self-heal TTL). */
+export declare function ssoGuardKey(origin: string): string;
+/** Per-origin destination key (the real URL to restore after the callback). */
+export declare function ssoDestKey(origin: string): string;
+/**
+ * Per-origin "the central IdP has no session for me" key. Set after a
+ * `none`/`error` return (or a failed/forged exchange) so `sso-bounce` does not
+ * fire again this tab — the definitive loop breaker.
+ */
+export declare function ssoNoSessionKey(origin: string): string;
+/**
+ * Perform the terminal top-level SSO bounce navigation.
+ *
+ * A thin wrapper over `window.location.assign(url)` so the single navigation
+ * seam lives in one place (and stays mockable in tests, where jsdom's
+ * `Location.assign` is a non-configurable native method). In production this is
+ * exactly `window.location.assign` — the document is torn down and replaced by
+ * the central IdP page. Off-browser (SSR / native) it is a no-op: native never
+ * bounces.
+ */
+export declare function ssoNavigate(url: string): void;
+/**
+ * Build the central IdP `/sso` bounce URL for an RP.
+ *
+ * Pure (no DOM access) so it is unit-testable and shared by every consumer's
+ * terminal `sso-bounce` step. The IdP reads `client_id` (the RP origin) and
+ * `return_to` to mint an origin-bound opaque code and 303-redirect back.
+ *
+ * The IdP base is resolved via {@link resolveCentralAuthUrl} so an explicit
+ * `authWebUrl` override (e.g. a staging IdP) drives the SSO bounce exactly the
+ * way it drives FedCM. When omitted, the central default {@link CENTRAL_AUTH_URL}
+ * is used.
+ *
+ * @param origin - The RP origin (`window.location.origin`).
+ * @param state - The CSRF state minted for this bounce.
+ * @param authWebUrl - Optional explicit IdP base URL override. Falls back to
+ *   the central default when `undefined`/empty.
+ * @returns The absolute `<idp-origin>/sso?...` URL string.
+ */
+export declare function buildSsoBounceUrl(origin: string, state: string, authWebUrl?: string): string;
+/**
+ * Whether `origin` IS the central IdP origin. The RP must NEVER bounce while
+ * sitting on `auth.oxy.so` itself — doing so would loop the IdP against itself.
+ *
+ * Both sides are normalised via `new URL(...).origin` so a trailing-slash or
+ * path difference never defeats the guard. Returns `false` on any parse
+ * failure (an unparseable candidate is, by definition, not the central IdP).
+ */
+export declare function isCentralIdPOrigin(origin: string): boolean;
+/**
+ * Read the bounce guard and decide whether it is still ACTIVE.
+ *
+ * Active means: a guard value is present AND it parses to a finite timestamp
+ * AND less than {@link SSO_GUARD_TTL_MS} has elapsed since it was set. An active
+ * guard disables `sso-bounce` (a bounce is already in flight this tab). A
+ * missing, malformed, or expired guard is NOT active, so a fresh bounce may
+ * proceed (this is the 30s self-heal for an interrupted bounce).
+ *
+ * Defensive: a `getItem` that throws (e.g. a locked/disabled storage) is
+ * treated as "not active" so the guard never wedges the flow.
+ *
+ * @param storage - The session storage to read (injected for testability).
+ * @param origin - The page origin whose guard to evaluate.
+ * @param now - Current epoch ms (injected for deterministic tests). Defaults to
+ *   `Date.now()`.
+ */
+export declare function guardActive(storage: Pick<Storage, 'getItem'>, origin: string, now?: number): boolean;

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

@@ -20,6 +20,7 @@
  * an oxy_sso fragment at all (i.e. `oxy_sso` is absent or an unrecognised
  * value), so the caller can ignore unrelated fragments without special-casing.
  */
+import type { SessionLoginResponse } from '../models/session';
 /**
  * The recognised outcomes of an SSO bounce.
  */
@@ -44,3 +45,67 @@ export interface SsoReturnResult {
  *   otherwise `null`. Never throws.
  */
 export declare function parseSsoReturnFragment(hash: string | undefined | null): SsoReturnResult | null;
+/**
+ * Injectable dependencies for {@link consumeSsoReturn}.
+ *
+ * Every web seam (storage, location, history, web-detection) is injectable so
+ * the function is fully unit-testable with fakes and so SSR / native callers
+ * can supply their own (or rely on the defaults, which resolve to `window.*`
+ * only when a browser is present). Defaults are evaluated lazily inside
+ * `consumeSsoReturn` so importing this module never touches `window`.
+ */
+export interface ConsumeSsoReturnDeps {
+    /** Per-tab SSO state store. Default: `window.sessionStorage`. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /** The current location. Default: `window.location`. */
+    location?: Pick<Location, 'hash' | 'origin' | 'pathname' | 'search'>;
+    /** History API for fragment stripping / dest restore. Default: `window.history`. */
+    history?: Pick<History, 'replaceState'>;
+    /**
+     * Whether the current environment is a web browser with usable
+     * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
+     * window.sessionStorage !== 'undefined'`.
+     */
+    isWeb?: () => boolean;
+    /**
+     * Optional debug hook invoked with the thrown error when the code exchange
+     * fails. NEVER rethrown — `consumeSsoReturn` is total. Default: no-op.
+     */
+    onExchangeError?: (error: unknown) => void;
+}
+/**
+ * Consume an SSO return: the commit-free, security-critical kernel of the
+ * cross-domain SSO `sso-return` cold-boot step.
+ *
+ * This performs the CSRF/fragment/exchange/dest-restore/loop-breaker sequence
+ * and RETURNS the exchanged session (or `null`). It deliberately does NOT
+ * commit any UI/auth state — each provider commits its own way AROUND this
+ * (e.g. `@oxyhq/services` `OxyContext` calls its `handleWebSSOSession`,
+ * `@oxyhq/auth` `WebOxyProvider` updates its React state). Hoisting the kernel
+ * here keeps the two providers byte-for-byte identical on the parts that matter
+ * for security (state validation, fragment stripping order, loop prevention).
+ *
+ * Security/loop invariants (preserved exactly from both former copies):
+ *   - The fragment is stripped via `history.replaceState` FIRST — before the
+ *     exchange — so the opaque code never lingers in the URL, browser history,
+ *     or a `Referer` header even if a later step throws.
+ *   - `state` must match (CSRF). A mismatch or a missing code sets the
+ *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
+ *   - `none`/`error` outcomes set the NO_SESSION flag (the load2 half of the
+ *     loop proof).
+ *   - A throwing exchange is caught, reported via `onExchangeError`, and
+ *     treated exactly like "no session" (never loops, never rethrows).
+ *   - After a successful exchange landing on {@link SSO_CALLBACK_PATH}, the real
+ *     destination is restored from the DEST key — same-origin only (an
+ *     attacker-planted cross-origin or relative-evil dest is rejected). The
+ *     DEST key is removed unconditionally.
+ *
+ * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
+ *
+ * @param oxy - The exchange surface (`oxyServices.exchangeSsoCode`).
+ * @param deps - Injectable web seams; see {@link ConsumeSsoReturnDeps}.
+ * @returns The exchanged session on success, otherwise `null`.
+ */
+export declare function consumeSsoReturn(oxy: {
+    exchangeSsoCode: (code: string) => Promise<SessionLoginResponse>;
+}, deps?: ConsumeSsoReturnDeps): Promise<SessionLoginResponse | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -368,14 +368,28 @@ export type { QuickAccount, DisplayNameUserShape } from './utils/accountUtils';
 // ---------------------------------------------------------------------------
 // Cross-domain SSO infrastructure
 // ---------------------------------------------------------------------------
-export { autoDetectAuthWebUrl } from './utils/fapiAutoDetect';
+export { autoDetectAuthWebUrl, registrableApex, MULTIPART_TLDS } from './utils/fapiAutoDetect';
 
 // Central cross-domain SSO (opaque single-use code bounce via auth.oxy.so)
-export { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from './utils/authWebUrl';
-export { parseSsoReturnFragment } from './utils/ssoReturn';
-export type { SsoReturnKind, SsoReturnResult } from './utils/ssoReturn';
+export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './utils/authWebUrl';
+export { parseSsoReturnFragment, consumeSsoReturn } from './utils/ssoReturn';
+export type { SsoReturnKind, SsoReturnResult, ConsumeSsoReturnDeps } from './utils/ssoReturn';
 export { generateSsoState } from './mixins/OxyServices.sso';
 
+// SSO bounce — per-origin sessionStorage keys, bounce URL builder, predicates
+export {
+    SSO_CALLBACK_PATH,
+    SSO_GUARD_TTL_MS,
+    ssoStateKey,
+    ssoGuardKey,
+    ssoDestKey,
+    ssoNoSessionKey,
+    ssoNavigate,
+    buildSsoBounceUrl,
+    isCentralIdPOrigin,
+    guardActive,
+} from './utils/ssoBounce';
+
 export { runColdBoot } from './utils/coldBoot';
 export type {
     ColdBootStep,

package/src/mixins/OxyServices.auth.ts

@@ -65,6 +65,12 @@ interface ServiceTokenCacheEntry {
   secretBuf: Buffer;
   /** In-flight refresh promise (deduplicates concurrent callers) */
   pending: Promise<string> | null;
+  /**
+   * The raw apiKey that produced this entry. Retained so a targeted, fully
+   * synchronous `invalidateServiceToken(apiKey)` can locate the entry without
+   * re-deriving the async `SHA-256(apiKey)` Map key. Never logged or returned.
+   */
+  apiKey: string;
 }
 
 /**
@@ -210,6 +216,7 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           expiresAt: 0,
           secretBuf: providedSecretBuf,
           pending: null,
+          apiKey: key,
         };
         this._serviceTokenCache.set(cacheKey, entry);
       }
@@ -260,12 +267,59 @@ export function OxyServicesAuthMixin<T extends typeof OxyServicesBase>(Base: T)
           expiresAt,
           secretBuf,
           pending: null,
+          apiKey: key,
         });
       }
 
       return response.token;
     }
 
+    /**
+     * Invalidate cached service token(s), forcing the next `getServiceToken()`
+     * call to mint a fresh token from `/auth/service-token`.
+     *
+     * `getServiceToken()` only refreshes on expiry (with a 60s clock-drift
+     * buffer), so a credential that is revoked or rotated mid-run — surfaced as
+     * a 401 on a downstream service request — cannot otherwise be recovered
+     * within the same process: the still-unexpired cached token keeps being
+     * returned. Call this after such a 401 to clear the stale entry; the very
+     * next `getServiceToken()` for that credential re-mints.
+     *
+     * Fully synchronous and deterministic: the call completes before it
+     * returns, so a `getServiceToken()` issued immediately afterwards is
+     * guaranteed to see the cleared cache and mint anew.
+     *
+     * @param apiKey - When provided, clears only the cache entry for that
+     *   specific apiKey. When omitted, clears the entry for the credential set
+     *   via `configureServiceAuth()`; if neither is available (no key to
+     *   target), clears the entire cache. Passing no argument is the common
+     *   case for hosts that configured a single service credential at startup.
+     *
+     * The cache Map is keyed by an asynchronously-computed `SHA-256(apiKey)`
+     * that cannot be reproduced synchronously, so a targeted clear scans the
+     * entries and removes the one whose stored raw `apiKey` matches — keeping
+     * this method synchronous. The fully-untargeted call (no argument and no
+     * configured key) clears every entry, which is safe because each credential
+     * pair is independently re-minted on its next request.
+     */
+    invalidateServiceToken(apiKey?: string): void {
+      const targetKey = apiKey ?? this._serviceApiKey;
+
+      // No specific credential to target — clear everything. The next
+      // getServiceToken() for any credential re-mints from scratch.
+      if (!targetKey) {
+        this._serviceTokenCache.clear();
+        return;
+      }
+
+      for (const [cacheKey, entry] of this._serviceTokenCache) {
+        if (entry.apiKey === targetKey) {
+          this._serviceTokenCache.delete(cacheKey);
+          return;
+        }
+      }
+    }
+
     /**
      * Make an authenticated request on behalf of a user using a service token.
      * Automatically obtains/refreshes the service token.

package/src/mixins/OxyServices.user.ts

@@ -135,6 +135,13 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
     /**
      * Get profile recommendations, optionally filtering out specific user types.
+     *
+     * Public discovery read — works WITHOUT authentication. The SDK attaches the
+     * access token automatically when one is available (personalized via
+     * mutual-connection overlap), and falls back to popular public profiles when
+     * the caller is logged out. This deliberately does NOT use `withAuthRetry`,
+     * which would throw an authentication timeout for logged-out callers before
+     * the request is ever sent.
      */
     async getProfileRecommendations(options?: {
       excludeTypes?: Array<'federated' | 'agent' | 'automated'>;
@@ -152,12 +159,14 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       _count?: { followers: number; following: number };
       [key: string]: unknown;
     }>> {
-      const params = options?.excludeTypes?.length
-        ? { excludeTypes: options.excludeTypes.join(',') }
-        : undefined;
-      return this.withAuthRetry(async () => {
+      try {
+        const params = options?.excludeTypes?.length
+          ? { excludeTypes: options.excludeTypes.join(',') }
+          : undefined;
         return await this.makeRequest('GET', '/profiles/recommendations', params, { cache: true });
-      }, 'getProfileRecommendations');
+      } catch (error) {
+        throw this.handleError(error);
+      }
     }
 
     /**

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

@@ -332,6 +332,98 @@ describe('H1: getServiceToken per-credential cache + secret verification', () =>
   });
 });
 
+// ---------------------------------------------------------------------------
+// invalidateServiceToken — clears the cached service token so the next
+// getServiceToken() mints anew, enabling recovery from a mid-run 401 (e.g.
+// credential revocation) without waiting for natural token expiry.
+// ---------------------------------------------------------------------------
+
+describe('invalidateServiceToken: forces a fresh mint after a same-run 401', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy as unknown as { makeRequest: jest.Mock }, 'makeRequest');
+  });
+
+  afterEach(() => {
+    makeRequestSpy.mockRestore();
+  });
+
+  it('re-mints on the next getServiceToken() after invalidation (configured credential)', async () => {
+    makeRequestSpy
+      .mockResolvedValueOnce({ token: 'token-first', expiresIn: 3600, appName: 'tenant-A' })
+      .mockResolvedValueOnce({ token: 'token-second', expiresIn: 3600, appName: 'tenant-A' });
+
+    oxy.configureServiceAuth('key-A', 'secret-A');
+
+    const first = await oxy.getServiceToken();
+    // Cached — would normally be returned again without re-minting.
+    const cached = await oxy.getServiceToken();
+    expect(first).toBe('token-first');
+    expect(cached).toBe('token-first');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+
+    // Simulate a 401: invalidate, then the very next call must mint anew.
+    oxy.invalidateServiceToken();
+
+    const fresh = await oxy.getServiceToken();
+    expect(fresh).toBe('token-second');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('clears only the targeted apiKey entry, leaving other tenants cached', async () => {
+    makeRequestSpy
+      .mockResolvedValueOnce({ token: 'token-A1', expiresIn: 3600, appName: 'tenant-A' })
+      .mockResolvedValueOnce({ token: 'token-B1', expiresIn: 3600, appName: 'tenant-B' })
+      .mockResolvedValueOnce({ token: 'token-A2', expiresIn: 3600, appName: 'tenant-A' });
+
+    await oxy.getServiceToken('key-A', 'secret-A');
+    await oxy.getServiceToken('key-B', 'secret-B');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+
+    // Invalidate only tenant A.
+    oxy.invalidateServiceToken('key-A');
+
+    // Tenant A re-mints...
+    const a2 = await oxy.getServiceToken('key-A', 'secret-A');
+    expect(a2).toBe('token-A2');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+
+    // ...tenant B is still cached (no extra mint).
+    const b1 = await oxy.getServiceToken('key-B', 'secret-B');
+    expect(b1).toBe('token-B1');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+  });
+
+  it('clears every entry when no key is configured and none is passed', async () => {
+    makeRequestSpy
+      .mockResolvedValueOnce({ token: 'token-A1', expiresIn: 3600, appName: 'tenant-A' })
+      .mockResolvedValueOnce({ token: 'token-B1', expiresIn: 3600, appName: 'tenant-B' })
+      .mockResolvedValueOnce({ token: 'token-A2', expiresIn: 3600, appName: 'tenant-A' })
+      .mockResolvedValueOnce({ token: 'token-B2', expiresIn: 3600, appName: 'tenant-B' });
+
+    await oxy.getServiceToken('key-A', 'secret-A');
+    await oxy.getServiceToken('key-B', 'secret-B');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+
+    // No configureServiceAuth() and no argument → clear all.
+    oxy.invalidateServiceToken();
+
+    const a2 = await oxy.getServiceToken('key-A', 'secret-A');
+    const b2 = await oxy.getServiceToken('key-B', 'secret-B');
+    expect(a2).toBe('token-A2');
+    expect(b2).toBe('token-B2');
+    expect(makeRequestSpy).toHaveBeenCalledTimes(4);
+  });
+
+  it('is a no-op safe to call when nothing is cached', () => {
+    expect(() => oxy.invalidateServiceToken()).not.toThrow();
+    expect(() => oxy.invalidateServiceToken('key-unknown')).not.toThrow();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // H2 — malformed tokens must yield 401, not 500. Uses class-based error
 // detection so future failure modes can't silently fall through.

package/src/utils/__tests__/authWebUrl.test.ts

@@ -5,13 +5,23 @@
  * `auth.oxy.so` origin is returned. No DOM, no side effects.
  */
 
-import { CENTRAL_AUTH_URL, resolveCentralAuthUrl } from '../authWebUrl';
+import { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from '../authWebUrl';
+
+describe('CENTRAL_IDP_APEX', () => {
+  it('is the central IdP registrable apex', () => {
+    expect(CENTRAL_IDP_APEX).toBe('oxy.so');
+  });
+});
 
 describe('CENTRAL_AUTH_URL', () => {
   it('is the central IdP origin with no trailing slash', () => {
     expect(CENTRAL_AUTH_URL).toBe('https://auth.oxy.so');
     expect(CENTRAL_AUTH_URL.endsWith('/')).toBe(false);
   });
+
+  it('is derived from CENTRAL_IDP_APEX (apex and origin never drift)', () => {
+    expect(CENTRAL_AUTH_URL).toBe(`https://auth.${CENTRAL_IDP_APEX}`);
+  });
 });
 
 describe('resolveCentralAuthUrl', () => {