@oxyhq/core 2.2.2 → 2.3.1

package/dist/types/index.d.ts

@@ -77,7 +77,7 @@ export { CENTRAL_AUTH_URL, CENTRAL_IDP_APEX, resolveCentralAuthUrl } from './uti
 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 { SSO_CALLBACK_PATH, SSO_GUARD_TTL_MS, ssoStateKey, ssoGuardKey, ssoDestKey, ssoNoSessionKey, ssoAttemptedKey, 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/utils/ssoBounce.d.ts

@@ -26,11 +26,15 @@
  *      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
+ * guard/state/dest + the outcome-independent attempted-flag
+ * ({@link ssoAttemptedKey}) 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.
+ * The attempted-flag is the definitive, outcome-INDEPENDENT loop breaker: it is
+ * set pre-bounce so even if the return-side NO_SESSION write never lands, the
+ * bounce can never re-fire this tab after the self-heal 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
@@ -65,6 +69,16 @@ export declare function ssoDestKey(origin: string): string;
  * fire again this tab — the definitive loop breaker.
  */
 export declare function ssoNoSessionKey(origin: string): string;
+/**
+ * Per-origin, OUTCOME-INDEPENDENT once-guard. Set in `sessionStorage` BEFORE
+ * the terminal SSO bounce navigates. Gates the bounce so the silent
+ * cross-domain probe fires AT MOST ONCE per tab session — independent of
+ * whether the return-side NO_SESSION flag ever lands. The definitive loop
+ * breaker; survives the 30s self-heal `ssoGuardKey` TTL. Cleared only on an
+ * explicit sign-out/clear so a later cold boot (after the user signs in
+ * centrally) can probe again.
+ */
+export declare function ssoAttemptedKey(origin: string): string;
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

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

@@ -91,8 +91,8 @@ export interface ConsumeSsoReturnDeps {
  *     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).
+ *   - `none`/`error` outcomes set BOTH the NO_SESSION flag and the
+ *     outcome-independent attempted-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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "2.2.2",
+  "version": "2.3.1",
   "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

@@ -384,6 +384,7 @@ export {
     ssoGuardKey,
     ssoDestKey,
     ssoNoSessionKey,
+    ssoAttemptedKey,
     ssoNavigate,
     buildSsoBounceUrl,
     isCentralIdPOrigin,

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

@@ -14,6 +14,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
 } from '../ssoBounce';
 import type { SessionLoginResponse } from '../../models/session';
 
@@ -116,10 +117,31 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
     expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
   });
 
+  it('sets BOTH ssoNoSessionKey AND ssoAttemptedKey on a none outcome', async () => {
+    const oxy = okExchange();
+    const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
+    const history = makeHistory();
+    const result = await consumeSsoReturn(oxy, {
+      isWeb: () => true,
+      storage,
+      location: makeLocation({ hash: '#oxy_sso=none&state=s' }),
+      history,
+    });
+
+    expect(result).toBeNull();
+    expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
+    expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
+    // Fragment stripped FIRST (history.replaceState called).
+    expect(history.calls.length).toBeGreaterThanOrEqual(1);
+    expect(history.calls[0]?.[2]).toBe(SSO_CALLBACK_PATH);
+  });
+
   it('sets NO_SESSION and returns null on an "error" outcome', async () => {
     const oxy = okExchange();
     const storage = makeStorage({ [ssoStateKey(ORIGIN)]: 's' });
@@ -132,6 +154,7 @@ describe('consumeSsoReturn', () => {
 
     expect(result).toBeNull();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('sets NO_SESSION and returns null on a state mismatch (CSRF)', async () => {
@@ -147,6 +170,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('sets NO_SESSION and returns null when ok carries no code', async () => {
@@ -162,6 +186,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(oxy.exchangeSsoCode).not.toHaveBeenCalled();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('exchanges, returns the session, strips the fragment, and removes state/guard keys on ok', async () => {
@@ -187,6 +212,9 @@ describe('consumeSsoReturn', () => {
     expect(storage.map.has(ssoStateKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoGuardKey(ORIGIN))).toBe(false);
     expect(storage.map.has(ssoNoSessionKey(ORIGIN))).toBe(false);
+    // The ok happy-path must NOT set the attempted-flag — a future sign-out
+    // should be able to re-probe the central IdP.
+    expect(storage.map.has(ssoAttemptedKey(ORIGIN))).toBe(false);
     // Fragment stripped to pathname+search (the first replaceState).
     expect(history.calls[0]?.[2]).toBe('/feed?tab=home');
   });
@@ -242,6 +270,7 @@ describe('consumeSsoReturn', () => {
     expect(result).toBeNull();
     expect(onExchangeError).toHaveBeenCalledWith(boom);
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   it('does not throw when the exchange throws and no onExchangeError hook is given', async () => {
@@ -277,6 +306,7 @@ describe('consumeSsoReturn', () => {
 
     expect(result).toBeNull();
     expect(storage.map.get(ssoNoSessionKey(ORIGIN))).toBe('1');
+    expect(storage.map.get(ssoAttemptedKey(ORIGIN))).toBe('1');
   });
 
   describe('dest restore', () => {

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

@@ -14,6 +14,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
   buildSsoBounceUrl,
   isCentralIdPOrigin,
   guardActive,
@@ -35,6 +36,7 @@ describe('per-origin key builders', () => {
     expect(ssoGuardKey(origin)).toBe('oxy_sso_guard:https://mention.earth');
     expect(ssoDestKey(origin)).toBe('oxy_sso_dest:https://mention.earth');
     expect(ssoNoSessionKey(origin)).toBe('oxy_sso_no_session:https://mention.earth');
+    expect(ssoAttemptedKey(origin)).toBe('oxy_sso_attempted:https://mention.earth');
   });
 
   it('namespaces keys per origin so two RPs never collide', () => {

package/src/utils/ssoBounce.ts

@@ -26,11 +26,15 @@
  *      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
+ * guard/state/dest + the outcome-independent attempted-flag
+ * ({@link ssoAttemptedKey}) 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.
+ * The attempted-flag is the definitive, outcome-INDEPENDENT loop breaker: it is
+ * set pre-bounce so even if the return-side NO_SESSION write never lands, the
+ * bounce can never re-fire this tab after the self-heal 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
@@ -62,6 +66,7 @@ const STATE_KEY_PREFIX = 'oxy_sso_state:';
 const GUARD_KEY_PREFIX = 'oxy_sso_guard:';
 const DEST_KEY_PREFIX = 'oxy_sso_dest:';
 const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
+const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -87,6 +92,19 @@ export function ssoNoSessionKey(origin: string): string {
   return `${NO_SESSION_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin, OUTCOME-INDEPENDENT once-guard. Set in `sessionStorage` BEFORE
+ * the terminal SSO bounce navigates. Gates the bounce so the silent
+ * cross-domain probe fires AT MOST ONCE per tab session — independent of
+ * whether the return-side NO_SESSION flag ever lands. The definitive loop
+ * breaker; survives the 30s self-heal `ssoGuardKey` TTL. Cleared only on an
+ * explicit sign-out/clear so a later cold boot (after the user signs in
+ * centrally) can probe again.
+ */
+export function ssoAttemptedKey(origin: string): string {
+  return `${ATTEMPTED_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Perform the terminal top-level SSO bounce navigation.
  *

package/src/utils/ssoReturn.ts

@@ -28,6 +28,7 @@ import {
   ssoGuardKey,
   ssoDestKey,
   ssoNoSessionKey,
+  ssoAttemptedKey,
 } from './ssoBounce';
 
 /**
@@ -149,8 +150,8 @@ export interface ConsumeSsoReturnDeps {
  *     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).
+ *   - `none`/`error` outcomes set BOTH the NO_SESSION flag and the
+ *     outcome-independent attempted-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
@@ -204,6 +205,10 @@ export async function consumeSsoReturn(
 
   const markNoSession = () => {
     storage.setItem(ssoNoSessionKey(origin), '1');
+    // A return was consumed, so the probe definitively happened. Set the
+    // outcome-independent attempted-flag too so the bounce can never re-fire
+    // even if some consumer path skipped setting it pre-bounce.
+    storage.setItem(ssoAttemptedKey(origin), '1');
   };
 
   if (ret.kind === 'none' || ret.kind === 'error') {