@oxyhq/services 5.17.17 → 5.18.0

package/src/core/mixins/OxyServices.fedcm.ts

@@ -0,0 +1,315 @@
+import type { OxyServicesBase } from '../OxyServices.base';
+import { OxyAuthenticationError } from '../OxyServices.errors';
+import type { SessionLoginResponse } from '../../models/session';
+
+export interface FedCMAuthOptions {
+  nonce?: string;
+  context?: 'signin' | 'signup' | 'continue' | 'use';
+}
+
+export interface FedCMConfig {
+  enabled: boolean;
+  configURL: string;
+  clientId?: string;
+}
+
+/**
+ * Federated Credential Management (FedCM) Authentication Mixin
+ *
+ * Implements the modern browser-native identity federation API that enables
+ * Google-style cross-domain authentication without third-party cookies.
+ *
+ * Browser Support:
+ * - Chrome 108+
+ * - Safari 16.4+
+ * - Edge 108+
+ * - Firefox: Not yet supported (fallback required)
+ *
+ * Key Features:
+ * - No redirects or popups required
+ * - Browser-native UI prompts
+ * - Privacy-preserving (IdP can't track users)
+ * - Automatic SSO across domains
+ * - Silent re-authentication support
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/FedCM_API
+ */
+export function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+  public static readonly DEFAULT_CONFIG_URL = 'https://auth.oxy.so/fedcm.json';
+  public static readonly FEDCM_TIMEOUT = 60000; // 1 minute
+
+  /**
+   * Check if FedCM is supported in the current browser
+   */
+  static isFedCMSupported(): boolean {
+    if (typeof window === 'undefined') return false;
+    return 'IdentityCredential' in window && 'navigator' in window && 'credentials' in navigator;
+  }
+
+  /**
+   * Instance method to check FedCM support
+   */
+  isFedCMSupported(): boolean {
+    return (this.constructor as typeof OxyServicesBase & { isFedCMSupported: () => boolean }).isFedCMSupported();
+  }
+
+  /**
+   * Sign in using FedCM (Federated Credential Management API)
+   *
+   * This provides a Google-style authentication experience:
+   * - Browser shows native "Sign in with Oxy" prompt
+   * - No redirect or popup required
+   * - User approves → credential exchange happens in browser
+   * - All apps automatically get SSO after first sign-in
+   *
+   * @param options - Authentication options
+   * @returns Session with access token and user data
+   * @throws {OxyAuthenticationError} If FedCM not supported or user cancels
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const session = await oxyServices.signInWithFedCM();
+   *   console.log('Signed in:', session.user);
+   * } catch (error) {
+   *   // Fallback to popup or redirect auth
+   *   await oxyServices.signInWithPopup();
+   * }
+   * ```
+   */
+  async signInWithFedCM(options: FedCMAuthOptions = {}): Promise<SessionLoginResponse> {
+    if (!this.isFedCMSupported()) {
+      throw new OxyAuthenticationError(
+        'FedCM not supported in this browser. Please update your browser or use an alternative sign-in method.'
+      );
+    }
+
+    try {
+      const nonce = options.nonce || this.generateNonce();
+      const clientId = this.getClientId();
+
+      // Request credential from browser's native identity flow
+      const credential = await this.requestIdentityCredential({
+        configURL: (this.constructor as any).DEFAULT_CONFIG_URL,
+        clientId,
+        nonce,
+        context: options.context,
+      });
+
+      if (!credential || !credential.token) {
+        throw new OxyAuthenticationError('No credential received from browser');
+      }
+
+      // Exchange FedCM ID token for Oxy session
+      const session = await this.exchangeIdTokenForSession(credential.token);
+
+      // Store access token in HttpService (extract from response or get from session)
+      if (session && (session as any).accessToken) {
+        this.httpService.setTokens((session as any).accessToken);
+      }
+
+      return session;
+    } catch (error) {
+      if ((error as any).name === 'AbortError') {
+        throw new OxyAuthenticationError('Sign-in was cancelled by user');
+      }
+      if ((error as any).name === 'NetworkError') {
+        throw new OxyAuthenticationError('Network error during sign-in. Please check your connection.');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Silent sign-in using FedCM
+   *
+   * Attempts to automatically re-authenticate the user without any UI.
+   * This is what enables "instant sign-in" across all Oxy domains after
+   * the user has signed in once.
+   *
+   * The browser will:
+   * 1. Check if user has previously signed in to Oxy
+   * 2. Check if user is still signed in at auth.oxy.so
+   * 3. If yes, automatically provide credential without prompting
+   *
+   * @returns Session if user is already signed in, null otherwise
+   *
+   * @example
+   * ```typescript
+   * // On app startup
+   * useEffect(() => {
+   *   const checkAuth = async () => {
+   *     const session = await oxyServices.silentSignInWithFedCM();
+   *     if (session) {
+   *       setUser(session.user);
+   *     } else {
+   *       // Show sign-in button
+   *     }
+   *   };
+   *   checkAuth();
+   * }, []);
+   * ```
+   */
+  async silentSignInWithFedCM(): Promise<SessionLoginResponse | null> {
+    if (!this.isFedCMSupported()) {
+      return null;
+    }
+
+    try {
+      const nonce = this.generateNonce();
+      const clientId = this.getClientId();
+
+      // Request credential with silent mediation (no UI)
+      const credential = await this.requestIdentityCredential({
+        configURL: (this.constructor as any).DEFAULT_CONFIG_URL,
+        clientId,
+        nonce,
+        mediation: 'silent',
+      });
+
+      if (!credential || !credential.token) {
+        return null;
+      }
+
+      const session = await this.exchangeIdTokenForSession(credential.token);
+      if (session && (session as any).accessToken) {
+        this.httpService.setTokens((session as any).accessToken);
+      }
+
+      return session;
+    } catch (error) {
+      // Silent failures are expected and should not throw
+      return null;
+    }
+  }
+
+  /**
+   * Request identity credential from browser using FedCM API
+   *
+   * @private
+   */
+  public async requestIdentityCredential(options: {
+    configURL: string;
+    clientId: string;
+    nonce: string;
+    context?: string;
+    mediation?: 'silent' | 'optional' | 'required';
+  }): Promise<{ token: string } | null> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), (this.constructor as any).FEDCM_TIMEOUT);
+
+    try {
+      // Type assertion needed as FedCM types may not be in all TypeScript versions
+      const credential = (await (navigator.credentials as any).get({
+        identity: {
+          providers: [
+            {
+              configURL: options.configURL,
+              clientId: options.clientId,
+              nonce: options.nonce,
+              ...(options.context && { loginHint: options.context }),
+            },
+          ],
+        },
+        mediation: options.mediation || 'optional',
+        signal: controller.signal,
+      })) as any;
+
+      if (!credential || credential.type !== 'identity') {
+        return null;
+      }
+
+      return { token: credential.token };
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /**
+   * Exchange FedCM ID token for Oxy session
+   *
+   * The ID token is a JWT issued by auth.oxy.so that proves the user's
+   * identity. We exchange it for a full Oxy session with access token.
+   *
+   * @private
+   */
+  public async exchangeIdTokenForSession(idToken: string): Promise<SessionLoginResponse> {
+    return this.makeRequest<SessionLoginResponse>(
+      'POST',
+      '/api/auth/fedcm/exchange',
+      { id_token: idToken },
+      { cache: false }
+    );
+  }
+
+  /**
+   * Revoke FedCM credential (sign out)
+   *
+   * This tells the browser to forget the FedCM credential for this app.
+   * The user will need to re-authenticate next time.
+   */
+  async revokeFedCMCredential(): Promise<void> {
+    if (!this.isFedCMSupported()) {
+      return;
+    }
+
+    try {
+      // FedCM logout API (if available)
+      if ('IdentityCredential' in window && 'logout' in (window as any).IdentityCredential) {
+        const clientId = this.getClientId();
+        await (window as any).IdentityCredential.logout({
+          configURL: (this.constructor as any).DEFAULT_CONFIG_URL,
+          clientId,
+        });
+      }
+    } catch (error) {
+      // Silent failure
+    }
+  }
+
+  /**
+   * Get configuration for FedCM
+   *
+   * @returns FedCM configuration with browser support info
+   */
+  getFedCMConfig(): FedCMConfig {
+    return {
+      enabled: this.isFedCMSupported(),
+      configURL: (this.constructor as any).DEFAULT_CONFIG_URL,
+      clientId: this.getClientId(),
+    };
+  }
+
+  /**
+   * Generate a cryptographically secure nonce for FedCM
+   *
+   * @private
+   */
+  public generateNonce(): string {
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.randomUUID) {
+      return window.crypto.randomUUID();
+    }
+    // Fallback for older browsers
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+
+  /**
+   * Get the client ID for this origin
+   *
+   * @private
+   */
+  public getClientId(): string {
+    if (typeof window === 'undefined') {
+      return 'unknown';
+    }
+    return window.location.origin;
+  }
+  };
+}
+
+// Export the mixin function as both named and default
+export { OxyServicesFedCMMixin as FedCMMixin };

package/src/core/mixins/OxyServices.popup.ts

@@ -0,0 +1,402 @@
+import type { OxyServicesBase } from '../OxyServices.base';
+import { OxyAuthenticationError } from '../OxyServices.errors';
+import type { SessionLoginResponse } from '../../models/session';
+
+export interface PopupAuthOptions {
+  width?: number;
+  height?: number;
+  timeout?: number;
+  mode?: 'login' | 'signup';
+}
+
+export interface SilentAuthOptions {
+  timeout?: number;
+}
+
+/**
+ * Popup-based Cross-Domain Authentication Mixin
+ *
+ * Implements OAuth2-style authentication using popup windows and postMessage.
+ * This is the primary authentication method for modern browsers, providing a
+ * Google-like experience without full page redirects.
+ *
+ * Flow:
+ * 1. Opens small popup window to auth.oxy.so
+ * 2. User signs in (auth.oxy.so sets its own first-party cookie)
+ * 3. auth.oxy.so sends token back via postMessage
+ * 4. Popup closes, parent app has the session
+ *
+ * Features:
+ * - No full page redirect (preserves app state)
+ * - Works across different domains (homiio.com, mention.earth, etc.)
+ * - Silent refresh using hidden iframe for seamless SSO
+ * - CSRF protection via state parameter
+ * - XSS protection via origin validation
+ *
+ * Browser Support: All modern browsers (IE11+)
+ */
+export function OxyServicesPopupAuthMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+  public static readonly AUTH_URL = 'https://auth.oxy.so';
+  public static readonly POPUP_WIDTH = 500;
+  public static readonly POPUP_HEIGHT = 700;
+  public static readonly POPUP_TIMEOUT = 60000; // 1 minute
+  public static readonly SILENT_TIMEOUT = 5000; // 5 seconds
+
+  /**
+   * Sign in using popup window
+   *
+   * Opens a centered popup window to auth.oxy.so where the user can sign in.
+   * The popup automatically closes after successful authentication and the
+   * session is returned to the parent window.
+   *
+   * @param options - Popup configuration options
+   * @returns Session with access token and user data
+   * @throws {OxyAuthenticationError} If popup is blocked or auth fails
+   *
+   * @example
+   * ```typescript
+   * const handleSignIn = async () => {
+   *   try {
+   *     const session = await oxyServices.signInWithPopup();
+   *     console.log('Signed in:', session.user);
+   *   } catch (error) {
+   *     if (error.message.includes('blocked')) {
+   *       alert('Please allow popups for this site');
+   *     }
+   *   }
+   * };
+   * ```
+   */
+  async signInWithPopup(options: PopupAuthOptions = {}): Promise<SessionLoginResponse> {
+    if (typeof window === 'undefined') {
+      throw new OxyAuthenticationError('Popup authentication requires browser environment');
+    }
+
+    const state = this.generateState();
+    const nonce = this.generateNonce();
+
+    // Store state for CSRF protection
+    this.storeAuthState(state, nonce);
+
+    const width = options.width || (this.constructor as any).POPUP_WIDTH;
+    const height = options.height || (this.constructor as any).POPUP_HEIGHT;
+    const timeout = options.timeout || (this.constructor as any).POPUP_TIMEOUT;
+    const mode = options.mode || 'login';
+
+    const authUrl = this.buildAuthUrl({
+      mode,
+      state,
+      nonce,
+      clientId: window.location.origin,
+      redirectUri: `${(this.constructor as any).AUTH_URL}/auth/callback`,
+    });
+
+    const popup = this.openCenteredPopup(authUrl, 'Oxy Sign In', width, height);
+
+    if (!popup) {
+      throw new OxyAuthenticationError(
+        'Popup blocked. Please allow popups for this site and try again.'
+      );
+    }
+
+    try {
+      const session = await this.waitForPopupAuth(popup, state, timeout);
+
+      // Store access token if present
+      if (session && (session as any).accessToken) {
+        this.httpService.setTokens((session as any).accessToken);
+      }
+
+      return session;
+    } catch (error) {
+      throw error;
+    } finally {
+      this.clearAuthState(state);
+    }
+  }
+
+  /**
+   * Sign up using popup window
+   *
+   * Same as signInWithPopup but opens the signup page by default.
+   *
+   * @param options - Popup configuration options
+   * @returns Session with access token and user data
+   */
+  async signUpWithPopup(options: PopupAuthOptions = {}): Promise<SessionLoginResponse> {
+    return this.signInWithPopup({ ...options, mode: 'signup' });
+  }
+
+  /**
+   * 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 sends token via postMessage
+   * 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;
+
+    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 = `${(this.constructor as any).AUTH_URL}/auth/silent?` + `client_id=${encodeURIComponent(clientId)}&` + `nonce=${nonce}`;
+
+    iframe.src = silentUrl;
+    document.body.appendChild(iframe);
+
+    try {
+      const session = await this.waitForIframeAuth(iframe, timeout, clientId);
+
+      if (session && (session as any).accessToken) {
+        this.httpService.setTokens((session as any).accessToken);
+      }
+
+      return session;
+    } catch (error) {
+      return null;
+    } finally {
+      document.body.removeChild(iframe);
+    }
+  }
+
+  /**
+   * Open a centered popup window
+   *
+   * @private
+   */
+  public openCenteredPopup(url: string, title: string, width: number, height: number): Window | null {
+    const left = window.screenX + (window.outerWidth - width) / 2;
+    const top = window.screenY + (window.outerHeight - height) / 2;
+
+    const features = [
+      `width=${width}`,
+      `height=${height}`,
+      `left=${left}`,
+      `top=${top}`,
+      'toolbar=no',
+      'menubar=no',
+      'scrollbars=yes',
+      'resizable=yes',
+      'status=no',
+      'location=no',
+    ].join(',');
+
+    return window.open(url, title, features);
+  }
+
+  /**
+   * Wait for authentication response from popup
+   *
+   * @private
+   */
+  public async waitForPopupAuth(
+    popup: Window,
+    expectedState: string,
+    timeout: number
+  ): Promise<SessionLoginResponse> {
+    return new Promise((resolve, reject) => {
+      const timeoutId = setTimeout(() => {
+        cleanup();
+        reject(new OxyAuthenticationError('Authentication timeout'));
+      }, timeout);
+
+      const messageHandler = (event: MessageEvent) => {
+        // CRITICAL: Verify origin to prevent XSS attacks
+        if (event.origin !== (this.constructor as any).AUTH_URL) {
+          return;
+        }
+
+        const { type, state, session, error } = event.data;
+
+        if (type !== 'oxy_auth_response') {
+          return;
+        }
+
+        // Verify state parameter to prevent CSRF attacks
+        if (state !== expectedState) {
+          cleanup();
+          reject(new OxyAuthenticationError('Invalid state parameter. Possible CSRF attack.'));
+          return;
+        }
+
+        cleanup();
+
+        if (error) {
+          reject(new OxyAuthenticationError(error));
+        } else if (session) {
+          resolve(session);
+        } else {
+          reject(new OxyAuthenticationError('No session received from authentication server'));
+        }
+      };
+
+      // Poll to detect if user closed the popup
+      const pollInterval = setInterval(() => {
+        if (popup.closed) {
+          cleanup();
+          reject(new OxyAuthenticationError('Authentication cancelled by user'));
+        }
+      }, 500);
+
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        clearInterval(pollInterval);
+        window.removeEventListener('message', messageHandler);
+        if (!popup.closed) {
+          popup.close();
+        }
+      };
+
+      window.addEventListener('message', messageHandler);
+    });
+  }
+
+  /**
+   * 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
+        if (event.origin !== (this.constructor as any).AUTH_URL) {
+          return;
+        }
+
+        const { type, session } = event.data;
+
+        if (type !== 'oxy_silent_auth') {
+          return;
+        }
+
+        cleanup();
+        resolve(session || null);
+      };
+
+      const cleanup = () => {
+        clearTimeout(timeoutId);
+        window.removeEventListener('message', messageHandler);
+      };
+
+      window.addEventListener('message', messageHandler);
+    });
+  }
+
+  /**
+   * Build authentication URL with query parameters
+   *
+   * @private
+   */
+  public buildAuthUrl(params: {
+    mode: string;
+    state: string;
+    nonce: string;
+    clientId: string;
+    redirectUri: string;
+  }): string {
+    const url = new URL(`${(this.constructor as any).AUTH_URL}/${params.mode}`);
+    url.searchParams.set('response_type', 'token');
+    url.searchParams.set('client_id', params.clientId);
+    url.searchParams.set('redirect_uri', params.redirectUri);
+    url.searchParams.set('state', params.state);
+    url.searchParams.set('nonce', params.nonce);
+    return url.toString();
+  }
+
+  /**
+   * Generate cryptographically secure state for CSRF protection
+   *
+   * @private
+   */
+  public generateState(): string {
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.randomUUID) {
+      return window.crypto.randomUUID();
+    }
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+
+  /**
+   * Generate nonce for replay attack prevention
+   *
+   * @private
+   */
+  public generateNonce(): string {
+    if (typeof window !== 'undefined' && window.crypto && window.crypto.randomUUID) {
+      return window.crypto.randomUUID();
+    }
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 15)}`;
+  }
+
+  /**
+   * Store auth state in session storage
+   *
+   * @private
+   */
+  public storeAuthState(state: string, nonce: string): void {
+    if (typeof window !== 'undefined' && window.sessionStorage) {
+      sessionStorage.setItem(`oxy_auth_state_${state}`, JSON.stringify({ nonce, timestamp: Date.now() }));
+    }
+  }
+
+  /**
+   * Clear auth state from session storage
+   *
+   * @private
+   */
+  public clearAuthState(state: string): void {
+    if (typeof window !== 'undefined' && window.sessionStorage) {
+      sessionStorage.removeItem(`oxy_auth_state_${state}`);
+    }
+  }
+  };
+}
+
+// Export the mixin function as both named and default
+export { OxyServicesPopupAuthMixin as PopupAuthMixin };