@oxyhq/core 3.13.1 → 3.15.0

package/src/mixins/__tests__/OxyServices.nodes.test.ts

@@ -0,0 +1,341 @@
+/**
+ * User-Node Mixin tests (self-sovereign identity layer — Fase 5 user nodes).
+ *
+ * Stubs `makeRequest` so the tests run with no network, then asserts:
+ *  - `registerNode` fetches the caller's chain head (uncached), signs a
+ *    self-issued v2 `type:'node'` envelope (record `{ endpoint, nodePublicKey,
+ *    mode }`, seq=head+1, prev=head id, collection `app.oxy.node`, rkey `self`),
+ *    POSTs it to the EXISTING `/identity/records` path, sweeps the node +
+ *    `/users/me` GET caches, then returns the freshly-read status. `mode`
+ *    defaults to `pull`; an explicit `mode` is forwarded; genesis coords apply
+ *    when there is no head. It is NATIVE-ONLY: a signing failure (no on-device
+ *    identity) propagates, and no-auth throws before any network. It does NOT
+ *    sweep when the POST fails, and throws when the node fails to materialize.
+ *  - `getMyNode` shapes the cached GET `/nodes/me` and unwraps `.node` (or null).
+ *  - `removeMyNode` DELETEs `/nodes/me`, maps `{success}`→`{revoked}`, and sweeps.
+ *  - `provisionManagedVault` POSTs `/nodes/managed`, returns `.node`, and sweeps.
+ *  - `notifyNodeIngest` POSTs the URL-encoded hint path and resolves void.
+ *
+ * The write tests mock `SignatureService.signRecordV2` (asserting the exact
+ * record + chain coords) so they isolate the SDK's request shaping from native
+ * key storage — mirroring the civic mixin tests.
+ */
+
+import type { SignedRecordEnvelope } from '@oxyhq/contracts';
+import { OxyServices } from '../../OxyServices';
+import { SignatureService } from '../../crypto/signatureService';
+import type { UserNodeStatus } from '../OxyServices.nodes';
+
+const NODE_PUBLIC_KEY = `04${'ab'.repeat(63)}`; // 128 hex chars (uncompressed secp256k1)
+
+const sampleNode: UserNodeStatus = {
+  endpoint: 'https://node.example.com',
+  nodePublicKey: NODE_PUBLIC_KEY,
+  mode: 'pull',
+  managed: false,
+  controller: 'self',
+  status: 'active',
+  createdAt: '2026-06-27T00:00:00.000Z',
+  updatedAt: '2026-06-27T00:00:00.000Z',
+};
+
+describe('OxyServices.nodes', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue('user-123');
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  describe('registerNode', () => {
+    const signedEnvelope: SignedRecordEnvelope = {
+      version: 2,
+      type: 'node',
+      subject: 'did:web:oxy.so:u:user-123',
+      issuer: 'did:web:oxy.so:u:user-123',
+      record: { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+      issuedAt: 1700000000000,
+      seq: 4,
+      prev: 'rec-3',
+      collection: 'app.oxy.node',
+      rkey: 'self',
+      publicKey: 'pub',
+      alg: 'ES256K-DER-SHA256',
+      signature: 'sig',
+    };
+
+    it('signs a v2 node record on the caller chain, POSTs /identity/records, sweeps, and returns the status', async () => {
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      // 1st makeRequest = chain head; 2nd = POST /identity/records; 3rd = GET /nodes/me.
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      const result = await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'pull',
+      });
+
+      // Fetched the caller's chain head first (uncached).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        1,
+        'GET',
+        '/identity/records/user-123/chain/head',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      // Signed a self-issued v2 `node` record: subject=caller DID, exact record,
+      // seq=head+1, prev=head id, collection app.oxy.node, rkey self.
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+      // Published via the EXISTING /identity/records path (NOT a bespoke endpoint).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        2,
+        'POST',
+        '/identity/records',
+        signedEnvelope,
+        expect.objectContaining({ cache: false }),
+      );
+      // Re-read the freshly-materialized status (cached GET /nodes/me).
+      expect(makeRequestSpy).toHaveBeenNthCalledWith(
+        3,
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+      // Swept the node + /users/me GET caches after the publish.
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+      expect(result).toEqual(sampleNode);
+    });
+
+    it('forwards an explicit push mode in the signed record', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+        mode: 'push',
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'push' },
+        { seq: 4, prev: 'rec-3', collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('defaults mode to pull and uses genesis coords when there is no chain head', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: null, seq: -1, recordCount: 0 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: sampleNode });
+
+      await oxy.registerNode({
+        endpoint: 'https://node.example.com',
+        nodePublicKey: NODE_PUBLIC_KEY,
+      });
+
+      expect(signV2Spy).toHaveBeenCalledWith(
+        'node',
+        'did:web:oxy.so:u:user-123',
+        { endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY, mode: 'pull' },
+        { seq: 0, prev: null, collection: 'app.oxy.node', rkey: 'self' },
+      );
+    });
+
+    it('throws when no user is authenticated (before any network)', async () => {
+      jest.spyOn(oxy, 'getCurrentUserId').mockReturnValue(null);
+      const signV2Spy = jest.spyOn(SignatureService, 'signRecordV2');
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No authenticated user/);
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+      expect(signV2Spy).not.toHaveBeenCalled();
+    });
+
+    it('propagates a signing failure (native-only: no on-device identity)', async () => {
+      const signV2Spy = jest
+        .spyOn(SignatureService, 'signRecordV2')
+        .mockRejectedValue(new Error('No identity found. Please create or import an identity first.'));
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/No identity found/);
+      // Only the chain-head read happened; no publish, no sweep.
+      expect(signV2Spy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('does NOT sweep caches when the publish POST fails', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockRejectedValueOnce(new Error('Signed record rejected: chain_fork'));
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+
+    it('throws when the node was stored on the chain but not materialized', async () => {
+      jest.spyOn(SignatureService, 'signRecordV2').mockResolvedValue(signedEnvelope);
+      jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy
+        .mockResolvedValueOnce({ headRecordId: 'rec-3', seq: 3, recordCount: 4 })
+        .mockResolvedValueOnce({ envelope: signedEnvelope, verified: true })
+        .mockResolvedValueOnce({ node: null });
+
+      await expect(
+        oxy.registerNode({ endpoint: 'https://node.example.com', nodePublicKey: NODE_PUBLIC_KEY }),
+      ).rejects.toThrow(/could not be materialized/);
+    });
+  });
+
+  describe('getMyNode', () => {
+    it('GETs /nodes/me (cached) and unwraps the node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: sampleNode });
+
+      const result = await oxy.getMyNode();
+
+      expect(result).toEqual(sampleNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'GET',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: true }),
+      );
+    });
+
+    it('returns null when the caller has no node', async () => {
+      makeRequestSpy.mockResolvedValue({ node: null });
+      await expect(oxy.getMyNode()).resolves.toBeNull();
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.getMyNode()).rejects.toThrow();
+    });
+  });
+
+  describe('removeMyNode', () => {
+    it('DELETEs /nodes/me, maps success→revoked, and sweeps caches', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ success: true });
+
+      const result = await oxy.removeMyNode();
+
+      expect(result).toEqual({ revoked: true });
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'DELETE',
+        '/nodes/me',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when the DELETE fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('No active node registration to revoke'));
+
+      await expect(oxy.removeMyNode()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('provisionManagedVault', () => {
+    it('POSTs /nodes/managed, returns the node, and sweeps caches', async () => {
+      const managedNode: UserNodeStatus = {
+        ...sampleNode,
+        managed: true,
+        controller: 'oxy',
+      };
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockResolvedValue({ node: managedNode });
+
+      const result = await oxy.provisionManagedVault();
+
+      expect(result).toEqual(managedNode);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/managed',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/nodes/');
+      expect(sweepSpy).toHaveBeenCalledWith('GET:/users/me');
+    });
+
+    it('does NOT sweep caches when provisioning fails', async () => {
+      const sweepSpy = jest.spyOn(oxy, 'clearCacheByPrefix').mockReturnValue(0);
+      makeRequestSpy.mockRejectedValue(new Error('Managed vaults are not available right now'));
+
+      await expect(oxy.provisionManagedVault()).rejects.toThrow();
+      expect(sweepSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('notifyNodeIngest', () => {
+    it('POSTs the ingest-notify hint and resolves void', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+
+      await expect(oxy.notifyNodeIngest('user-9')).resolves.toBeUndefined();
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/user-9',
+        undefined,
+        expect.objectContaining({ cache: false }),
+      );
+    });
+
+    it('URL-encodes the userId path segment', async () => {
+      makeRequestSpy.mockResolvedValue({ accepted: true });
+      await oxy.notifyNodeIngest('a/b');
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/nodes/ingest/notify/a%2Fb',
+        undefined,
+        expect.anything(),
+      );
+    });
+
+    it('rejects on a transport failure', async () => {
+      makeRequestSpy.mockRejectedValue(new Error('network down'));
+      await expect(oxy.notifyNodeIngest('user-9')).rejects.toThrow();
+    });
+  });
+});

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

@@ -0,0 +1,123 @@
+/**
+ * Connected-apps (OAuth grants) SDK tests.
+ *
+ * `listConnectedApps()` reads the user's authorized applications from
+ * `GET /auth/grants` and caches the response (identity-scoped). `revokeAppGrant`
+ * deletes a grant via `DELETE /auth/grants/:applicationId` and MUST invalidate
+ * the cached `GET:/auth/grants` so a re-read observes the removal instead of the
+ * STALE pre-revoke list (mirrors the privacy/follow invalidation contract).
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { ConnectedApp } from '../OxyServices.applications';
+
+/** Build a non-verified JWT whose payload decodes to the given claims. */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const APP_A: ConnectedApp = {
+  applicationId: 'app-a',
+  name: 'App A',
+  logoUrl: 'https://cdn.example/a.png',
+  scopes: ['profile', 'email'],
+  firstGrantedAt: '2026-01-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-01T00:00:00.000Z',
+};
+
+const APP_B: ConnectedApp = {
+  applicationId: 'app-b',
+  name: 'App B',
+  scopes: ['profile'],
+  firstGrantedAt: '2026-02-01T00:00:00.000Z',
+  lastUsedAt: '2026-06-02T00:00:00.000Z',
+};
+
+describe('connected apps (OAuth grants)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('lists connected apps, unwrapping the { data } envelope', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    const apps = await oxy.listConnectedApps();
+    expect(apps).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants');
+    expect(init?.method).toBe('GET');
+  });
+
+  it('caches the list within the TTL (second read is a cache hit)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Second read within the TTL must not hit the network.
+    expect(await oxy.listConnectedApps()).toEqual([APP_A]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it('revokes a grant via DELETE /auth/grants/:applicationId', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await expect(oxy.revokeAppGrant('app-a')).resolves.toBeUndefined();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(String(url)).toBe('http://test.invalid/auth/grants/app-a');
+    expect(init?.method).toBe('DELETE');
+  });
+
+  it('busts the cached list after revokeAppGrant', async () => {
+    // 1) Warm the cache.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_A, APP_B]));
+    expect(await oxy.listConnectedApps()).toEqual([APP_A, APP_B]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read is a cache hit (no extra network call).
+    await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Revoke — must invalidate the cached list.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Re-read MUST re-fetch and observe the revoked app gone.
+    fetchMock.mockResolvedValueOnce(jsonResponse([APP_B]));
+    const after = await oxy.listConnectedApps();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after).toEqual([APP_B]);
+  });
+
+  it('invalidates the exact GET:/auth/grants key on revoke', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ revoked: true }));
+    await oxy.revokeAppGrant('app-a');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/auth/grants');
+    clearSpy.mockRestore();
+  });
+});

package/src/mixins/index.ts

@@ -31,6 +31,7 @@ import { OxyServicesManagedAccountsMixin } from './OxyServices.managedAccounts';
 import { OxyServicesContactsMixin } from './OxyServices.contacts';
 import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
+import { OxyServicesNodesMixin } from './OxyServices.nodes';
 
 /**
  * Instance shape of every mixin in the pipeline, intersected. The runtime
@@ -66,6 +67,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesContactsMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesAppDataMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
 
 /**
@@ -134,6 +136,9 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     OxyServicesAppDataMixin,
     // Civic / Commons "Oxy ID" (public signed cards, Oxy ID QR payload)
     OxyServicesCivicMixin,
+    // User nodes / decentralization (Fase 5): register/read/revoke/manage the
+    // caller's personal data node + ingest hint.
+    OxyServicesNodesMixin,
 
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,

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;
+}