@oxyhq/core 3.14.0 → 3.16.0

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

@@ -15,9 +15,11 @@ import {
   ssoDestKey,
   ssoNoSessionKey,
   ssoAttemptedKey,
+  ssoPriorSessionKey,
   buildSsoBounceUrl,
   isCentralIdPOrigin,
   guardActive,
+  allowSsoBounce,
 } from '../ssoBounce';
 import { CENTRAL_AUTH_URL } from '../authWebUrl';
 
@@ -37,10 +39,36 @@ describe('per-origin key builders', () => {
     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');
+    expect(ssoPriorSessionKey(origin)).toBe('oxy_sso_prior_session:https://mention.earth');
   });
 
   it('namespaces keys per origin so two RPs never collide', () => {
     expect(ssoStateKey('https://a.test')).not.toBe(ssoStateKey('https://b.test'));
+    expect(ssoPriorSessionKey('https://a.test')).not.toBe(ssoPriorSessionKey('https://b.test'));
+  });
+});
+
+describe('allowSsoBounce (smart returning-visitor gate)', () => {
+  it('ALLOWS a returning visitor (prior-session hint) with no local session', () => {
+    // The core of fix B: a returning user whose local session has expired still
+    // gets ONE establish bounce so a central-only cross-domain session recovers.
+    expect(
+      allowSsoBounce({ hasPriorSession: true, hasLocalSession: false }),
+    ).toBe(true);
+  });
+
+  it('SUPPRESSES a truly first-time anonymous visitor (no hint, no local session)', () => {
+    // The smart default (the ONLY behaviour): a first-time visitor browses
+    // anonymously instead of being force-redirected to the central IdP.
+    expect(
+      allowSsoBounce({ hasPriorSession: false, hasLocalSession: false }),
+    ).toBe(false);
+  });
+
+  it('ALLOWS when a local session was recovered this boot (spec fidelity)', () => {
+    expect(
+      allowSsoBounce({ hasPriorSession: false, hasLocalSession: true }),
+    ).toBe(true);
   });
 });
 

package/src/utils/ssoBounce.ts

@@ -68,6 +68,7 @@ const DEST_KEY_PREFIX = 'oxy_sso_dest:';
 const NO_SESSION_KEY_PREFIX = 'oxy_sso_no_session:';
 const ATTEMPTED_KEY_PREFIX = 'oxy_sso_attempted:';
 const CALLBACK_BOOTSTRAP_KEY_PREFIX = 'oxy_sso_callback_bootstrap:';
+const PRIOR_SESSION_KEY_PREFIX = 'oxy_sso_prior_session:';
 
 /** Per-origin CSRF state key (matched on return to defeat fragment forgery). */
 export function ssoStateKey(origin: string): string {
@@ -106,6 +107,24 @@ export function ssoAttemptedKey(origin: string): string {
   return `${ATTEMPTED_KEY_PREFIX}${origin}`;
 }
 
+/**
+ * Per-origin DURABLE "this device/origin has had a signed-in Oxy session
+ * before" hint.
+ *
+ * Unlike every other key in this module — which lives in per-tab
+ * `sessionStorage` — this hint is written to DURABLE storage (web
+ * `localStorage`; the services provider uses its own `storageKeyPrefix`-scoped
+ * key in `@oxyhq/services`). It is set whenever a session is established or
+ * restored and survives a session expiring; it is cleared ONLY on an explicit
+ * full sign-out. It exists purely to drive {@link allowSsoBounce}: a returning
+ * visitor (hint present) whose local session has lapsed still gets ONE terminal
+ * `/sso` establish bounce to recover a session that lives only at the central
+ * IdP, while a truly first-time anonymous visitor is never force-bounced.
+ */
+export function ssoPriorSessionKey(origin: string): string {
+  return `${PRIOR_SESSION_KEY_PREFIX}${origin}`;
+}
+
 /**
  * Per-origin marker written by the pre-hydration callback bootstrap.
  *
@@ -247,3 +266,53 @@ export function guardActive(
   }
   return now - ts < SSO_GUARD_TTL_MS;
 }
+
+/**
+ * Inputs to the smart {@link allowSsoBounce} gate.
+ */
+export interface SsoBounceGate {
+  /**
+   * Whether this device/origin has had a signed-in Oxy session before (the
+   * durable {@link ssoPriorSessionKey} hint). Set whenever a session is
+   * established or restored; survives session expiry; cleared only on explicit
+   * full sign-out. `true` ⇒ a returning visitor.
+   */
+  readonly hasPriorSession: boolean;
+  /**
+   * Whether a local/stored session was recovered earlier this cold boot. At the
+   * terminal bounce gate this is effectively always `false` (an earlier step
+   * would have won and short-circuited), but it is part of the contract — "no
+   * prior hint AND no local session" — so it is passed explicitly for fidelity
+   * and robustness.
+   */
+  readonly hasLocalSession: boolean;
+}
+
+/**
+ * Decide whether the terminal `/sso` establish-bounce is ALLOWED for this
+ * visitor (the smart `enabled` gate for the `sso-bounce` cold-boot step).
+ *
+ * The terminal bounce is the ONLY cold-boot step that can recover a session
+ * that lives SOLELY at the central IdP — the cross-apex Relying-Party case
+ * (e.g. `mention.earth`, a different apex from `oxy.so`) whose device-local
+ * session has expired and whose `Domain=oxy.so` refresh cookie never reaches
+ * `api.<apex>`. It is also what plants the first-party per-apex `fedcm_session`
+ * cookie that the EARLIER `silent-iframe` step later relies on. So it must fire
+ * for a RETURNING user, yet it must NOT force a truly first-time anonymous
+ * visitor off to the IdP.
+ *
+ *   - ALLOW when there is a prior-signed-in hint OR a local session was
+ *     recovered this boot (a returning user) — so a central-only cross-domain
+ *     session recovers via ONE bounce, after which the per-apex cookie is
+ *     planted and subsequent loads restore silently with no bounce.
+ *   - else (no hint, no local session) SUPPRESS — a first-time anonymous
+ *     visitor browses without a forced redirect.
+ *
+ * This is the smart DEFAULT and the ONLY behaviour: apps never configure it.
+ * It is also the GATE DECISION ONLY — callers still apply the per-tab loop
+ * guards (`ssoAttemptedKey`, `ssoNoSessionKey`, {@link guardActive}) so an
+ * allowed bounce still fires at most once per cold boot.
+ */
+export function allowSsoBounce(gate: SsoBounceGate): boolean {
+  return gate.hasPriorSession || gate.hasLocalSession;
+}