@oxyhq/core 3.14.0 → 3.15.0

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