@oxyhq/core 9.1.0 → 9.2.1

package/src/session/authStateStore.ts

@@ -5,7 +5,7 @@
  * a reload restores the session locally without a redirect: `deviceId` +
  * `deviceSecret` mint a fresh access token via `POST /session/device/token`.
  * This module is the storage seam: a tiny `load / save / clear` interface plus
- * platform factories, so the cold boot (`coldBootV2`) and the unified re-mint
+ * platform factories, so the cold boot (`sessionColdBoot`) and the unified re-mint
  * handler (`refresh.ts`) never touch a platform storage API directly.
  *
  * Platform-agnostic — the native factory takes an INJECTED key/value store
@@ -106,17 +106,26 @@ function deserialize(raw: string | null): PersistedAuthState | null {
     return null;
   }
   const candidate = parsed as Record<string, unknown>;
-  if (
-    typeof candidate.sessionId !== 'string' ||
-    typeof candidate.userId !== 'string' ||
-    candidate.sessionId.length === 0 ||
-    candidate.userId.length === 0
-  ) {
+  const hasDeviceCredential =
+    typeof candidate.deviceId === 'string' &&
+    candidate.deviceId.length > 0 &&
+    typeof candidate.deviceSecret === 'string' &&
+    candidate.deviceSecret.length > 0;
+
+  const hasSessionIdentity =
+    typeof candidate.sessionId === 'string' &&
+    typeof candidate.userId === 'string' &&
+    candidate.sessionId.length > 0 &&
+    candidate.userId.length > 0;
+
+  // Device-only bootstrap (post join, pre-sign-in): durable credential without session.
+  if (!hasSessionIdentity && !hasDeviceCredential) {
     return null;
   }
+
   const state: PersistedAuthState = {
-    sessionId: candidate.sessionId,
-    userId: candidate.userId,
+    sessionId: hasSessionIdentity ? (candidate.sessionId as string) : '',
+    userId: hasSessionIdentity ? (candidate.userId as string) : '',
   };
   if (typeof candidate.deviceId === 'string' && candidate.deviceId.length > 0) {
     state.deviceId = candidate.deviceId;

package/src/session/hubSync.ts

@@ -0,0 +1,79 @@
+/**
+ * Post-sign-in hub sync — plant device credentials on auth.oxy.so via a
+ * one-time server ticket (no secrets in URL fragments).
+ */
+
+import type { OxyServices } from '../OxyServices';
+import type { AuthStateStore } from './authStateStore';
+import {
+  buildHubSyncUrl,
+  buildIdpHubOrigin,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+} from '../utils/officialOrigins';
+
+export interface SyncHubAfterSignInOptions {
+  /** Skip sync when false (OxyProvider hubSync prop). @default true */
+  enabled?: boolean;
+}
+
+/**
+ * After a successful sign-in on an official web app, mint a hub ticket and
+ * redirect to auth.oxy.so/sync so the IdP hub can redeem it and persist the
+ * shared device credential for silent OAuth restore on other origins.
+ *
+ * No-op on native, non-official origins, and when already on the IdP hub.
+ */
+export async function syncHubAfterSignIn(
+  oxy: Pick<OxyServices, 'issueHubTicket'>,
+  opts?: SyncHubAfterSignInOptions,
+): Promise<boolean> {
+  if (opts?.enabled === false) {
+    return false;
+  }
+
+  if (typeof globalThis === 'undefined') {
+    return false;
+  }
+
+  const location = (globalThis as { location?: Location }).location;
+  if (!location) {
+    return false;
+  }
+
+  if (isIdpHubOrigin()) {
+    return false;
+  }
+
+  if (!isOfficialWebOrigin(location.origin)) {
+    return false;
+  }
+
+  const hubOrigin = buildIdpHubOrigin();
+  const issued = await oxy.issueHubTicket(hubOrigin);
+  const returnUrl = `${location.origin}${location.pathname}${location.search}`;
+  const syncUrl = buildHubSyncUrl(issued.ticket, returnUrl);
+
+  window.location.assign(syncUrl);
+  return true;
+}
+
+/** Redeem a hub ticket on auth.oxy.so and persist credentials locally. */
+export async function redeemHubTicketOnHub(
+  oxy: Pick<OxyServices, 'redeemHubTicket'>,
+  store: AuthStateStore,
+  ticket: string,
+): Promise<boolean> {
+  const hubOrigin = buildIdpHubOrigin();
+  const creds = await oxy.redeemHubTicket(ticket, hubOrigin);
+  const prior = await store.load();
+  await store.save({
+    sessionId: prior?.sessionId ?? '',
+    userId: prior?.userId ?? '',
+    deviceId: creds.deviceId,
+    deviceSecret: creds.deviceSecret,
+    ...(prior?.accessToken ? { accessToken: prior.accessToken } : {}),
+    ...(prior?.expiresAt ? { expiresAt: prior.expiresAt } : {}),
+  });
+  return true;
+}

package/src/session/sessionClientHost.ts

@@ -1,5 +1,5 @@
 import type { OxyServices } from '../OxyServices';
-import type { SessionClientHost } from './SessionClient';
+import type { DeviceCredential, SessionClientHost } from './SessionClient';
 
 /**
  * Thin `SessionClientHost` adapter over an `OxyServices` instance.
@@ -15,17 +15,25 @@ import type { SessionClientHost } from './SessionClient';
  */
 export function createSessionClientHost(
   oxyServices: OxyServices,
-): SessionClientHost & { setCurrentAccountId(id: string | null): void } {
+): SessionClientHost & {
+  setCurrentAccountId(id: string | null): void;
+  setDeviceCredential(credential: DeviceCredential | null): void;
+} {
   let currentAccountId: string | null = null;
+  let deviceCredential: DeviceCredential | null = null;
   return {
     makeRequest: (method, url, data, options) => oxyServices.makeRequest(method, url, data, options),
     getBaseURL: () => oxyServices.getBaseURL(),
     getAccessToken: () => oxyServices.getAccessToken(),
+    getDeviceCredential: () => deviceCredential,
     onTokensChanged: (listener) => oxyServices.onTokensChanged(listener),
     setTokens: (accessToken) => oxyServices.setTokens(accessToken),
     getCurrentAccountId: () => currentAccountId,
     setCurrentAccountId: (id) => {
       currentAccountId = id;
     },
+    setDeviceCredential: (credential) => {
+      deviceCredential = credential;
+    },
   };
 }

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

@@ -0,0 +1,74 @@
+import {
+  buildHubSyncUrl,
+  buildIdpHubOrigin,
+  isAllowedDeviceJoinOrigin,
+  isIdpHubOrigin,
+  isOfficialWebOrigin,
+  normalizeOfficialReturnOrigin,
+  parseHubSyncReturnUrl,
+} from '../officialOrigins';
+
+describe('officialOrigins', () => {
+  it('builds the IdP hub origin', () => {
+    expect(buildIdpHubOrigin()).toBe('https://auth.oxy.so');
+  });
+
+  it('allows official first-party origins', () => {
+    expect(isOfficialWebOrigin('https://inbox.oxy.so')).toBe(true);
+    expect(isOfficialWebOrigin('https://mention.earth')).toBe(true);
+    expect(isOfficialWebOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('keeps the deprecated alias in sync with isOfficialWebOrigin', () => {
+    expect(isAllowedDeviceJoinOrigin('https://accounts.oxy.so')).toBe(true);
+    expect(isAllowedDeviceJoinOrigin('https://evil.example')).toBe(false);
+  });
+
+  it('normalizes return origins to origin only', () => {
+    expect(normalizeOfficialReturnOrigin('https://accounts.oxy.so/settings')).toBe(
+      'https://accounts.oxy.so',
+    );
+    expect(normalizeOfficialReturnOrigin('https://evil.example/')).toBeNull();
+  });
+
+  it('parses hub-sync return URLs', () => {
+    expect(parseHubSyncReturnUrl('https://inbox.oxy.so/messages')).toBe(
+      'https://inbox.oxy.so/messages',
+    );
+    expect(parseHubSyncReturnUrl('https://evil.example/')).toBeNull();
+  });
+
+  it('builds hub sync URLs with ticket and optional return', () => {
+    const url = new URL(buildHubSyncUrl('tk-abc', 'https://accounts.oxy.so/'));
+    expect(url.pathname).toBe('/sync');
+    expect(url.searchParams.get('ticket')).toBe('tk-abc');
+    expect(url.searchParams.get('return')).toBe('https://accounts.oxy.so/');
+  });
+
+  describe('isIdpHubOrigin', () => {
+    const originalLocation = globalThis.location;
+
+    afterEach(() => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: originalLocation,
+      });
+    });
+
+    it('returns true on auth.oxy.so', () => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: { href: 'https://auth.oxy.so/sync' },
+      });
+      expect(isIdpHubOrigin()).toBe(true);
+    });
+
+    it('returns false on satellite origins', () => {
+      Object.defineProperty(globalThis, 'location', {
+        configurable: true,
+        value: { href: 'https://inbox.oxy.so/' },
+      });
+      expect(isIdpHubOrigin()).toBe(false);
+    });
+  });
+});

package/src/utils/coldBoot.ts

@@ -16,7 +16,7 @@
  *     web bundle — the reason any run-once guard for a step must live in the
  *     calling consumer, never in a core module-level singleton).
  *   - Architecture-agnostic: it knows nothing about HOW a step resolves a
- *     session; `runSessionColdBoot` (`boot/coldBootV2.ts`) is the current
+ *     session; `runSessionColdBoot` (`boot/sessionColdBoot.ts`) is the current
  *     device-first consumer.
  *
  * A step is skipped (without running) when its `enabled` predicate returns
@@ -106,7 +106,7 @@ export interface RunColdBootOptions<S> {
    * fails to settle before the deadline, the runner abandons the await for that
    * step (reporting it via `onStepDeadline`) and CONTINUES to the next step,
    * each now racing against an already-expired deadline. This is deliberate:
-   * the runner keeps iterating so the TERMINAL step (e.g. `coldBootV2`'s
+   * the runner keeps iterating so the TERMINAL step (e.g. `sessionColdBoot`'s
    * `bootstrap-hop`, whose `run()` performs its navigation side effect
    * synchronously before its first `await`) still gets to fire. A step that
    * has nothing to contribute after the deadline simply doesn't settle and is

package/src/utils/oauthPkce.ts

@@ -61,6 +61,11 @@ export interface BuildOAuthAuthorizeUrlParams {
   state: string;
   /** The PKCE `codeChallenge` from {@link generatePkcePair}. */
   codeChallenge: string;
+  /**
+   * OAuth `prompt` parameter. Use `none` for silent cross-origin session restore
+   * (no UI when the IdP hub already has a session + grant).
+   */
+  prompt?: 'none' | 'login' | 'consent';
 }
 
 /**
@@ -184,6 +189,72 @@ export function buildOAuthAuthorizeUrl(params: BuildOAuthAuthorizeUrlParams): st
   url.searchParams.set('scope', scope);
   url.searchParams.set('code_challenge', codeChallenge);
   url.searchParams.set('code_challenge_method', 'S256');
+  if (params.prompt) {
+    url.searchParams.set('prompt', params.prompt);
+  }
 
   return url.toString();
 }
+
+/** `sessionStorage` key for the OAuth CSRF `state` across an authorize redirect. */
+export const OXY_OAUTH_STATE_STORAGE_KEY = 'oxy_oauth_state';
+
+/** `sessionStorage` key for the PKCE `code_verifier` across an authorize redirect. */
+export const OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY = 'oxy_oauth_code_verifier';
+
+/** `sessionStorage` key — at most one silent OAuth attempt per navigation. */
+export const OXY_SILENT_OAUTH_ATTEMPTED_KEY = 'oxy.silent_oauth_attempted';
+
+/** `sessionStorage` key — blocks further cross-origin auto-restore in this tab. */
+export const OXY_CROSS_ORIGIN_RESTORE_ATTEMPTED_KEY = 'oxy.cross_origin_restore_attempted';
+
+/**
+ * Normalize a redirect URI to its origin. Official Oxy apps register apex
+ * origins (`https://inbox.oxy.so`) — never path-qualified URLs.
+ */
+export function normalizeOAuthRedirectUri(input: string): string {
+  try {
+    return new URL(input).origin;
+  } catch {
+    return input;
+  }
+}
+
+/** Persist the OAuth handshake for a full-page redirect return (web only). */
+export function persistOAuthHandshake(state: string, codeVerifier: string): boolean {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  try {
+    if (!store) throw new Error('sessionStorage is unavailable');
+    store.setItem(OXY_OAUTH_STATE_STORAGE_KEY, state);
+    store.setItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY, codeVerifier);
+    return true;
+  } catch (error) {
+    logger.warn(
+      'Could not persist OAuth handshake to sessionStorage',
+      { component: 'oauthPkce' },
+      error,
+    );
+    return false;
+  }
+}
+
+/** Read the persisted OAuth handshake, or `null` when absent. */
+export function readOAuthHandshake(): { state: string; codeVerifier: string } | null {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  if (!store) return null;
+  const state = store.getItem(OXY_OAUTH_STATE_STORAGE_KEY);
+  const codeVerifier = store.getItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+  if (!state || !codeVerifier) return null;
+  return { state, codeVerifier };
+}
+
+/** Drop persisted OAuth handshake keys after a successful or aborted return. */
+export function clearOAuthHandshake(): void {
+  const store = (globalThis as { sessionStorage?: Storage }).sessionStorage;
+  try {
+    store?.removeItem(OXY_OAUTH_STATE_STORAGE_KEY);
+    store?.removeItem(OXY_OAUTH_CODE_VERIFIER_STORAGE_KEY);
+  } catch {
+    // Best-effort cleanup only.
+  }
+}

package/src/utils/officialOrigins.ts

@@ -0,0 +1,124 @@
+/**
+ * Official first-party web origin allowlist — shared by hub-ticket issuance,
+ * OAuth redirect validation, and cross-origin session restore.
+ */
+
+import { CENTRAL_IDP_APEX } from './authWebUrl';
+import { registrableApex } from './registrableApex';
+
+/** Official first-party registrable apexes (mirrors API trusted origins). */
+const OFFICIAL_APEXES = new Set([
+  'oxy.so',
+  'fairco.in',
+  'mention.earth',
+  'homiio.com',
+  'alia.onl',
+  'syra.fm',
+  'allo.you',
+  'tnp.network',
+  'moovo.now',
+  'mercaria.co',
+]);
+
+export function buildIdpHubOrigin(): string {
+  return `https://auth.${CENTRAL_IDP_APEX}`;
+}
+
+/** Whether the current web origin is the central IdP hub (`auth.oxy.so`). */
+export function isIdpHubOrigin(): boolean {
+  if (typeof globalThis === 'undefined') {
+    return false;
+  }
+  const location = (globalThis as { location?: Location }).location;
+  if (!location) {
+    return false;
+  }
+  try {
+    const { hostname } = new URL(location.href);
+    return hostname === `auth.${CENTRAL_IDP_APEX}`;
+  } catch {
+    return false;
+  }
+}
+
+function isLoopbackOrigin(origin: string): boolean {
+  try {
+    const parsed = new URL(origin);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return false;
+    }
+    const host = parsed.hostname.toLowerCase();
+    return host === 'localhost' || host === '127.0.0.1' || host === '[::1]';
+  } catch {
+    return false;
+  }
+}
+
+/** Whether an origin belongs to the official Oxy web ecosystem. */
+export function isOfficialWebOrigin(origin: string): boolean {
+  if (isLoopbackOrigin(origin)) {
+    return true;
+  }
+  try {
+    const parsed = new URL(origin);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return false;
+    }
+    const host = parsed.hostname.toLowerCase();
+    if (host === CENTRAL_IDP_APEX || host.endsWith(`.${CENTRAL_IDP_APEX}`)) {
+      return true;
+    }
+    const apex = registrableApex(host);
+    return apex != null && OFFICIAL_APEXES.has(apex);
+  } catch {
+    return false;
+  }
+}
+
+/** Normalize and validate a return URL against official origins. Returns origin only. */
+export function normalizeOfficialReturnOrigin(raw: string): string | null {
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return null;
+    }
+    if (!isOfficialWebOrigin(parsed.origin)) {
+      return null;
+    }
+    return parsed.origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Validate a hub-sync return URL; returns the full normalized URL string. */
+export function parseHubSyncReturnUrl(raw: string | null): string | null {
+  if (!raw) {
+    return null;
+  }
+  try {
+    const parsed = new URL(raw);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+      return null;
+    }
+    if (!isOfficialWebOrigin(parsed.origin)) {
+      return null;
+    }
+    return parsed.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** Build auth.oxy.so/sync redirect URL with a one-time hub ticket. */
+export function buildHubSyncUrl(ticket: string, returnUrl?: string): string {
+  const url = new URL('/sync', buildIdpHubOrigin());
+  url.searchParams.set('ticket', ticket);
+  if (returnUrl) {
+    url.searchParams.set('return', returnUrl);
+  }
+  return url.toString();
+}
+
+/** @deprecated Use {@link isOfficialWebOrigin}. */
+export const isAllowedDeviceJoinOrigin = isOfficialWebOrigin;