@oxyhq/core 5.5.0 → 7.0.0

package/src/mixins/OxyServices.redirect.ts

@@ -1,122 +0,0 @@
-import type { OxyServicesBase } from '../OxyServices.base';
-import { OxyAuthenticationError } from '../OxyServices.errors';
-import type { SessionLoginResponse } from '../models/session';
-import {
-  buildSsoBounceUrl,
-  ssoAttemptedKey,
-  ssoDestKey,
-  ssoGuardKey,
-  ssoStateKey,
-} from '../utils/ssoBounce';
-
-export interface RedirectAuthOptions {
-  redirectUri?: string;
-  mode?: 'login' | 'signup';
-  preserveUrl?: boolean;
-}
-
-/**
- * Redirect-based authentication without bearer tokens in URLs.
- *
- * The redirect fallback now uses the same central SSO code-return contract as
- * cold boot: the RP stores CSRF/destination state in sessionStorage, navigates
- * to the central IdP, receives only an opaque one-time code in the URL fragment,
- * and the provider's `sso-return` step exchanges that code for the real session.
- */
-export function OxyServicesRedirectAuthMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Start a full-page redirect through the central SSO flow.
-     *
-     * No access token, refresh token, or session id is ever put in the URL or
-     * localStorage. The caller's provider must run `consumeSsoReturn` on startup
-     * to complete the code exchange and commit the session.
-     */
-    signInWithRedirect(options: RedirectAuthOptions = {}): void {
-      if (typeof window === 'undefined' || typeof window.sessionStorage === 'undefined') {
-        throw new OxyAuthenticationError('Redirect authentication requires browser sessionStorage');
-      }
-
-      const origin = window.location.origin;
-      const state = this.generateState();
-      const destination = options.preserveUrl === false
-        ? (options.redirectUri || origin)
-        : (options.redirectUri || window.location.href);
-
-      window.sessionStorage.setItem(ssoStateKey(origin), state);
-      window.sessionStorage.setItem(ssoGuardKey(origin), String(Date.now()));
-      window.sessionStorage.setItem(ssoDestKey(origin), destination);
-      window.sessionStorage.setItem(ssoAttemptedKey(origin), '1');
-
-      window.location.assign(buildSsoBounceUrl(origin, state, this.config.authWebUrl));
-    }
-
-    signUpWithRedirect(options: RedirectAuthOptions = {}): void {
-      this.signInWithRedirect({ ...options, mode: 'signup' });
-    }
-
-    /**
-     * Legacy token-query callbacks are intentionally rejected. Modern providers
-     * complete redirect auth through `consumeSsoReturn`, which accepts only
-     * `#oxy_sso=ok&code=...`.
-     */
-    handleAuthCallback(): SessionLoginResponse | null {
-      if (typeof window === 'undefined') {
-        return null;
-      }
-
-      const url = new URL(window.location.href);
-      if (url.searchParams.has('access_token') || url.searchParams.has('session_id')) {
-        this.cleanAuthCallbackUrl(url);
-        throw new OxyAuthenticationError('Legacy access-token redirect callbacks are no longer accepted.');
-      }
-
-      return null;
-    }
-
-    restoreSession(): boolean {
-      return false;
-    }
-
-    clearStoredSession(): void {
-      this.httpService.clearTokens();
-    }
-
-    getStoredSessionId(): string | null {
-      return null;
-    }
-
-    public generateState(): string {
-      if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-        return crypto.randomUUID();
-      }
-      if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-        const bytes = new Uint8Array(16);
-        crypto.getRandomValues(bytes);
-        return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-      }
-      throw new Error('No secure random source available for state generation');
-    }
-
-    public generateNonce(): string {
-      return this.generateState();
-    }
-
-    public cleanAuthCallbackUrl(url: URL): void {
-      url.searchParams.delete('access_token');
-      url.searchParams.delete('session_id');
-      url.searchParams.delete('expires_at');
-      url.searchParams.delete('state');
-      url.searchParams.delete('nonce');
-      url.searchParams.delete('error');
-      url.searchParams.delete('error_description');
-      window.history.replaceState({}, '', url.toString());
-    }
-  };
-}
-
-export { OxyServicesRedirectAuthMixin as RedirectAuthMixin };

package/src/mixins/OxyServices.silent.ts

@@ -1,272 +0,0 @@
-import type { OxyServicesBase } from "../OxyServices.base";
-import type { SessionLoginResponse } from "../models/session";
-import { createDebugLogger } from "../shared/utils/debugUtils";
-
-const debug = createDebugLogger("SilentAuth");
-
-export interface SilentAuthOptions {
-	timeout?: number;
-	/**
-	 * Override the auth-web (IdP) origin used for the silent iframe, instead of
-	 * the instance's configured `resolveAuthUrl()`.
-	 *
-	 * Why this exists: an instance configured with the CENTRAL IdP
-	 * (`authWebUrl=https://auth.oxy.so`, for the opaque-code `/sso` bounce and
-	 * FedCM) cannot read the DURABLE per-apex `fedcm_session` cookie via the
-	 * central host — that cookie is first-party only on `auth.<rp-apex>` (e.g.
-	 * `auth.mention.earth`). The cross-domain reload-restore path must point the
-	 * `/auth/silent` iframe at the PER-APEX host so the cookie is same-site to
-	 * the RP page (first-party under Safari ITP / Firefox TCP) and the restore
-	 * is NOT a top-level navigation (no flash, works in a backgrounded tab).
-	 *
-	 * When provided this value is used BOTH for the iframe `src` AND for the
-	 * `postMessage` origin validation in {@link waitForIframeAuth}, so the
-	 * security check still matches the exact origin the iframe was loaded from.
-	 * Must be an absolute origin (`https://auth.<apex>`); ignored if empty.
-	 */
-	authWebUrlOverride?: string;
-}
-
-/**
- * Cross-domain silent browser auth helpers.
- *
- * The clean session model supports FedCM, tokenless redirect SSO, and silent
- * iframe SSO. Bearer-token callback URLs are not part of this surface.
- */
-export function OxyServicesSilentAuthMixin<T extends typeof OxyServicesBase>(
-	Base: T,
-) {
-	return class extends Base {
-		constructor(...args: any[]) {
-			super(...(args as [any]));
-		}
-		public static readonly DEFAULT_AUTH_URL = "https://auth.oxy.so";
-
-		/** Resolve auth URL from config or static default (method, not getter — getters break in TS mixins) */
-		public resolveAuthUrl(): string {
-			return (
-				this.config.authWebUrl || (this.constructor as any).DEFAULT_AUTH_URL
-			);
-		}
-
-		public static readonly SILENT_TIMEOUT = 5000; // 5 seconds
-
-		/**
-		 * Silent sign-in using hidden iframe
-		 *
-		 * Attempts to automatically re-authenticate the user without any UI.
-		 * This is what enables seamless SSO across all Oxy domains.
-		 *
-		 * How it works:
-		 * 1. Creates hidden iframe pointing to auth.oxy.so/silent-auth
-		 * 2. If user has valid session at auth.oxy.so, it exchanges an opaque SSO code
-		 * 3. If not, iframe responds with null (no error thrown)
-		 *
-		 * This should be called on app startup to check for existing sessions.
-		 *
-		 * @param options - Silent auth options
-		 * @returns Session if user is signed in, null otherwise
-		 *
-		 * @example
-		 * ```typescript
-		 * useEffect(() => {
-		 *   const checkAuth = async () => {
-		 *     const session = await oxyServices.silentSignIn();
-		 *     if (session) {
-		 *       setUser(session.user);
-		 *     }
-		 *   };
-		 *   checkAuth();
-		 * }, []);
-		 * ```
-		 */
-		async silentSignIn(
-			options: SilentAuthOptions = {},
-		): Promise<SessionLoginResponse | null> {
-			if (typeof window === "undefined") {
-				return null;
-			}
-
-			const timeout =
-				options.timeout || (this.constructor as any).SILENT_TIMEOUT;
-			const nonce = this.generateNonce();
-			const clientId = window.location.origin;
-
-			// Resolve the IdP origin for the iframe. An explicit per-apex override (the
-			// durable cross-domain reload path — see `SilentAuthOptions.authWebUrlOverride`)
-			// wins over the instance's configured central auth URL. The SAME origin is
-			// handed to `waitForIframeAuth` so the postMessage origin check matches the
-			// exact host the iframe was loaded from.
-			const authOrigin =
-				options.authWebUrlOverride && options.authWebUrlOverride.length > 0
-					? options.authWebUrlOverride
-					: this.resolveAuthUrl();
-
-			const iframe = document.createElement("iframe");
-			iframe.style.display = "none";
-			iframe.style.position = "absolute";
-			iframe.style.width = "0";
-			iframe.style.height = "0";
-			iframe.style.border = "none";
-
-			const silentUrl =
-				`${authOrigin}/auth/silent?` +
-				`client_id=${encodeURIComponent(clientId)}&` +
-				`nonce=${nonce}`;
-
-			iframe.src = silentUrl;
-			document.body.appendChild(iframe);
-
-			try {
-				const session = await this.waitForIframeAuth(
-					iframe,
-					timeout,
-					authOrigin,
-				);
-
-				// Bail early on incomplete responses. The iframe contract requires
-				// both an access token and a session id; anything less is unusable.
-				// Returning `null` here (without installing the token) prevents a
-				// stale credential from being committed to HttpService when the
-				// user is actually signed out — that pattern caused a `getCurrentUser`
-				// -> 401 -> token-clear loop in consumer apps because callers gated
-				// on `session?.user` and never installed the user via
-				// `handleAuthSuccess`, while HttpService quietly held the token.
-				const accessToken = session
-					? (session as { accessToken?: string }).accessToken
-					: undefined;
-				if (!session || !accessToken || !session.sessionId) {
-					return null;
-				}
-
-				// Snapshot the previous token so we can roll back if the user
-				// lookup below fails — this avoids leaving a half-committed session
-				// (token installed, user missing) which would let the next
-				// authenticated request 401 with no way to recover.
-				const previousAccessToken = this.httpService.getAccessToken();
-				this.httpService.setTokens(accessToken);
-
-				// The iframe typically returns `{ sessionId, accessToken }` without
-				// user data. Fetch the user explicitly so callers receive a
-				// fully-formed session and never need a second `/users/me` round
-				// trip. If this fails the session is unusable — revert the token
-				// and return null so the caller treats this exactly like a
-				// missing-session response.
-				if (!session.user) {
-					try {
-						const userData = await this.makeRequest<unknown>(
-							"GET",
-							`/session/user/${session.sessionId}`,
-							undefined,
-							{ cache: false, retry: false },
-						);
-						if (!userData) {
-							throw new Error("Empty user response");
-						}
-						(session as { user?: unknown }).user = userData;
-					} catch (userError) {
-						debug.warn(
-							"silentSignIn: failed to fetch user data, rolling back token",
-							userError,
-						);
-						if (previousAccessToken) {
-							this.httpService.setTokens(previousAccessToken);
-						} else {
-							this.httpService.clearTokens();
-						}
-						return null;
-					}
-				}
-
-				return session;
-			} catch (error) {
-				return null;
-			} finally {
-				document.body.removeChild(iframe);
-			}
-		}
-
-		/**
-		 * Wait for authentication response from iframe
-		 *
-		 * @private
-		 */
-		public async waitForIframeAuth(
-			iframe: HTMLIFrameElement,
-			timeout: number,
-			expectedOrigin: string,
-		): Promise<SessionLoginResponse | null> {
-			return new Promise((resolve) => {
-				const timeoutId = setTimeout(() => {
-					cleanup();
-					resolve(null); // Silent failure - don't throw
-				}, timeout);
-
-				const messageHandler = (event: MessageEvent) => {
-					// Verify origin against the EXACT host the iframe was loaded from
-					// (`expectedOrigin`). For the per-apex durable-restore path this is
-					// `auth.<rp-apex>`, not the instance's central `resolveAuthUrl()` — so
-					// we must honour the caller-supplied origin, never re-derive it here.
-					if (event.origin !== expectedOrigin) {
-						return;
-					}
-
-					const { type, session } = event.data;
-
-					if (type !== "oxy_silent_auth") {
-						return;
-					}
-
-					cleanup();
-					resolve(session || null);
-				};
-
-				// Fail-fast on a load failure. When the per-apex `/auth/silent` host is
-				// unreachable, blocked by CSP `frame-ancestors`/`X-Frame-Options`, or the
-				// network drops, the iframe never posts a message — without this handler
-				// the silent restore would block for the FULL `timeout` (dead latency in
-				// the cold-boot critical path). `onerror`/`onabort` fire on a failed load,
-				// so resolve `null` immediately and let the next cold-boot step run. The
-				// success path posts a message and is handled above; these only catch the
-				// no-message failure modes.
-				const failFast = () => {
-					cleanup();
-					resolve(null);
-				};
-				iframe.onerror = failFast;
-				iframe.onabort = failFast;
-
-				const cleanup = () => {
-					clearTimeout(timeoutId);
-					iframe.onerror = null;
-					iframe.onabort = null;
-					window.removeEventListener("message", messageHandler);
-				};
-
-				window.addEventListener("message", messageHandler);
-			});
-		}
-
-		/**
-		 * Generate nonce for replay attack prevention
-		 *
-		 * @private
-		 */
-		public generateNonce(): string {
-			if (typeof crypto !== "undefined" && crypto.randomUUID) {
-				return crypto.randomUUID();
-			}
-			if (typeof crypto !== "undefined" && crypto.getRandomValues) {
-				const bytes = new Uint8Array(16);
-				crypto.getRandomValues(bytes);
-				return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join(
-					"",
-				);
-			}
-			throw new Error("No secure random source available for nonce generation");
-		}
-	};
-}
-
-// Export the mixin function as both named and default
-export { OxyServicesSilentAuthMixin as SilentAuthMixin };

package/src/mixins/OxyServices.sso.ts

@@ -1,261 +0,0 @@
-/**
- * Central Cross-Domain SSO (opaque-code) Mixin
- *
- * Implements the Relying-Party half of TRUE central cross-domain SSO
- * (Google/Meta/Clerk style). The central IdP at `auth.oxy.so` owns the session;
- * an RP bounces a top-level redirect (prompt=none) to `auth.oxy.so/sso`, which
- * returns an OPAQUE single-use code in the redirect fragment. The RP then
- * exchanges that code here for the real session.
- *
- * Security properties:
- *   - NO token/JWT ever travels in a URL — only the opaque code does. The real
- *     `accessToken` is delivered exclusively in this exchange response body.
- *   - The exchange is a CORS POST with NO credentials/cookies — the opaque code
- *     is the only bearer of authority, and the central store burns it atomically
- *     (single-use). Sending no cookies keeps the request a clean, ambient-
- *     authority-free bearer exchange that the central `POST /sso/exchange`
- *     endpoint validates by `Origin` against the code's bound `clientOrigin`.
- *   - The code is minted server-side bound to the RP origin and expires in
- *     seconds, so a leaked code is useless cross-origin and short-lived.
- *
- * On success the mixin plants the returned access token via
- * `httpService.setTokens(...)` — mirroring `exchangeIdTokenForSession` /
- * `verifyChallenge` — so callers do NOT need to plant tokens manually.
- */
-
-import type { OxyServicesBase } from '../OxyServices.base';
-import type { SessionLoginResponse, MinimalUserData } from '../models/session';
-import type { UserNameResponse } from '@oxyhq/contracts';
-import { createDebugLogger } from '../shared/utils/debugUtils';
-import { ssoStateKey } from '../utils/ssoBounce';
-
-const debug = createDebugLogger('SSO');
-
-/**
- * Wire shape of `POST /sso/exchange`. `expiresAt` and `authuser` are optional
- * because the central SSO store may omit them.
- */
-interface SsoExchangeWireResponse {
-  accessToken: string;
-  sessionId: string;
-  user: {
-    id?: string;
-    _id?: string;
-    username?: string;
-    name?: UserNameResponse;
-    avatar?: string;
-  };
-  expiresAt?: string;
-  authuser?: number;
-}
-
-/** Wire shape of `POST /sso/establish-token`. */
-interface SsoEstablishTokenWireResponse {
-  establishUrl: string;
-}
-
-/**
- * Generate a cryptographically secure state value for the SSO bounce.
- *
- * Exposed as a module-level helper (in addition to the instance method below)
- * so consumers that do not yet hold an `OxyServices` instance can still mint a
- * bounce state. Uses `crypto.randomUUID` with a `getRandomValues` fallback.
- */
-export function generateSsoState(): string {
-  if (typeof crypto !== 'undefined' && crypto.randomUUID) {
-    return crypto.randomUUID();
-  }
-  if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
-    const bytes = new Uint8Array(16);
-    crypto.getRandomValues(bytes);
-    return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
-  }
-  throw new Error('No secure random source available for SSO state generation');
-}
-
-/**
- * Read the SSO bounce state stored for the current browser origin, if any.
- *
- * Returns `null` outside a browser (no `window`/`sessionStorage`) or when no
- * state is stored — in which case the caller cannot (and must not) enforce a
- * state match, e.g. native flows or pre-hydration callbacks that already
- * validated the state before this exchange.
- */
-function getStoredSsoStateForCurrentOrigin(): string | null {
-  if (typeof window === 'undefined' || !window.location || !window.sessionStorage) {
-    return null;
-  }
-
-  try {
-    return window.sessionStorage.getItem(ssoStateKey(window.location.origin));
-  } catch {
-    return null;
-  }
-}
-
-export function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T) {
-  return class extends Base {
-    constructor(...args: any[]) {
-      super(...(args as [any]));
-    }
-
-    /**
-     * Generate cryptographically secure state for the SSO bounce (CSRF
-     * protection). Delegates to the module-level {@link generateSsoState}
-     * helper, which uses `crypto.randomUUID` when available and falls back to
-     * `crypto.getRandomValues`.
-     */
-    public generateSsoState(): string {
-      return generateSsoState();
-    }
-
-    /**
-     * Exchange an opaque single-use SSO code for the real Oxy session.
-     *
-     * POSTs `{ code }` to `${getSessionBaseUrl()}/sso/exchange` as a CORS
-     * request with NO credentials/cookies. On success the returned access token
-     * is planted via `httpService.setTokens(...)` (matching
-     * `exchangeIdTokenForSession` / `verifyChallenge`), so callers do not need
-     * to plant tokens manually.
-     *
-     * @param code - The opaque single-use code delivered in the SSO return
-     *   fragment (see {@link parseSsoReturnFragment}). The central store burns
-     *   it atomically on exchange.
-     * @param state - The state value returned alongside the code. In browsers,
-     *   when an SSO bounce state is still stored for the current origin, this
-     *   must match before any token-committing exchange is attempted.
-     * @returns The resolved {@link SessionLoginResponse}.
-     */
-    public async exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse> {
-      if (typeof code !== 'string' || code.length === 0) {
-        throw this.handleError(new Error('exchangeSsoCode requires a non-empty code'));
-      }
-
-      const expectedState = getStoredSsoStateForCurrentOrigin();
-      if (expectedState !== null && (typeof state !== 'string' || state.length === 0 || state !== expectedState)) {
-        throw this.handleError(new Error('SSO exchange state mismatch'));
-      }
-
-      const url = `${this.getSessionBaseUrl().replace(/\/$/, '')}/sso/exchange`;
-      debug.log('Exchanging SSO code for session...');
-
-      let response: Response;
-      try {
-        response = await fetch(url, {
-          method: 'POST',
-          // No cookies: the opaque code is the sole bearer of authority and the
-          // server validates by Origin against the code's bound clientOrigin.
-          credentials: 'omit',
-          headers: {
-            'Content-Type': 'application/json',
-            Accept: 'application/json',
-          },
-          body: JSON.stringify({ code }),
-        });
-      } catch (error) {
-        debug.error('SSO exchange request failed:', error instanceof Error ? error.message : String(error));
-        throw this.handleError(error);
-      }
-
-      if (!response.ok) {
-        throw this.handleError(new Error(`SSO exchange failed with HTTP ${response.status}`));
-      }
-
-      let payload: SsoExchangeWireResponse;
-      try {
-        payload = (await response.json()) as SsoExchangeWireResponse;
-      } catch (error) {
-        throw this.handleError(error);
-      }
-
-      if (!payload || typeof payload.accessToken !== 'string' || payload.accessToken.length === 0) {
-        throw this.handleError(new Error('SSO exchange returned no access token'));
-      }
-      if (typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
-        throw this.handleError(new Error('SSO exchange returned no sessionId'));
-      }
-
-      const userId = payload.user?.id ?? payload.user?._id;
-      if (!userId || typeof payload.user?.username !== 'string') {
-        throw this.handleError(new Error('SSO exchange returned an invalid user'));
-      }
-
-      const user: MinimalUserData = {
-        id: userId,
-        username: payload.user.username,
-        // `name.displayName` is optional on the contract. A no-name user is
-        // valid; carry whatever structured name the server sent (possibly an
-        // empty object) and let consumers fall back to a handle.
-        name: payload.user.name ?? {},
-        avatar: payload.user.avatar,
-      };
-
-      // Plant the access token exactly like exchangeIdTokenForSession does.
-      // The SSO exchange does not return a refresh token (the central store
-      // holds the refresh credential), so default it to an empty string.
-      this.httpService.setTokens(payload.accessToken);
-
-      debug.log('SSO exchange complete:', { hasSession: !!payload.sessionId });
-
-      const session: SessionLoginResponse = {
-        sessionId: payload.sessionId,
-        deviceId: '',
-        expiresAt: payload.expiresAt ?? '',
-        user,
-        accessToken: payload.accessToken,
-      };
-
-      return session;
-    }
-
-    /**
-     * Mint a server-formed `/sso/establish` URL for the caller's OWN session,
-     * bound to an approved RP `origin`.
-     *
-     * Bearer-authenticated (the session id is taken from the caller's own
-     * bearer, server-side — never from any argument). The server validates that
-     * `origin` is an approved client origin (and matches the request `Origin`),
-     * derives the per-apex IdP host (`auth.<apex>`), mints a short-lived HS256
-     * establish-token, and returns a fully-formed
-     * `https://<auth-host>/sso/establish?et=…&return_to=<origin>/__oxy/sso-callback&state=<state>`.
-     *
-     * Used AFTER a web device-flow claim to plant the durable first-party
-     * `fedcm_session` cookie so a reload can re-mint a token (see
-     * {@link establishIdpSessionAfterClaim}). Cache-free (a POST is never
-     * cached, but `cache: false` is explicit).
-     *
-     * @param origin - The RP origin (`window.location.origin`) to establish for.
-     * @param state - The CSRF state echoed back in the callback fragment; the
-     *   caller persists the SAME value under `ssoStateKey(origin)` so the
-     *   post-bounce `sso-return` step validates it.
-     */
-    public async requestSsoEstablishUrl(
-      origin: string,
-      state: string,
-    ): Promise<{ establishUrl: string }> {
-      if (typeof origin !== 'string' || origin.length === 0) {
-        throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty origin'));
-      }
-      if (typeof state !== 'string' || state.length === 0) {
-        throw this.handleError(new Error('requestSsoEstablishUrl requires a non-empty state'));
-      }
-
-      const response = await this.makeRequest<SsoEstablishTokenWireResponse>(
-        'POST',
-        '/sso/establish-token',
-        { origin, state },
-        { cache: false },
-      );
-
-      if (
-        !response ||
-        typeof response.establishUrl !== 'string' ||
-        response.establishUrl.length === 0
-      ) {
-        throw this.handleError(new Error('SSO establish-token returned no establishUrl'));
-      }
-
-      return { establishUrl: response.establishUrl };
-    }
-  };
-}