@oxyhq/core 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @oxyhq/core
+
+OxyHQ SDK Foundation. Platform-agnostic core library that works in Node.js, browser, and React Native environments. No React dependency.
+
+## Installation
+
+```bash
+npm install @oxyhq/core
+```
+
+## Contents
+
+- **OxyServices API client** — all API methods for interacting with OxyHQ services
+- **AuthManager, CrossDomainAuth** — authentication and cross-domain session handling
+- **Crypto** — KeyManager, SignatureService, RecoveryPhraseService
+- **Models and types** — User, ApiError, ClientSession, and more
+- **i18n** — translate function and locale files
+- **Shared utilities** — color, theme, error, network, debug helpers
+- **Platform detection utilities**
+- **Device management**
+
+## Exports
+
+The package exposes three entry points:
+
+- `@oxyhq/core` — main entry (API client, auth, models, i18n, platform, device)
+- `@oxyhq/core/crypto` — cryptographic utilities (KeyManager, SignatureService, RecoveryPhraseService)
+- `@oxyhq/core/shared` — shared utilities (color, theme, error, network, debug)
+
+## Usage
+
+```ts
+import { OxyServices, oxyClient } from '@oxyhq/core';
+import type { User, ApiError } from '@oxyhq/core';
+
+// Get user
+const user = await oxyClient.getUserById('123');
+
+// Crypto
+import { KeyManager, SignatureService } from '@oxyhq/core/crypto';
+const keyManager = new KeyManager();
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+Compiles with TypeScript, producing CJS, ESM, and type declaration outputs.

package/dist/cjs/AuthManager.js

@@ -0,0 +1,361 @@
+"use strict";
+/**
+ * AuthManager - Centralized Authentication Manager
+ *
+ * Provides a unified authentication interface for all platforms.
+ * Handles token storage, session management, and auth state changes.
+ *
+ * @module core/AuthManager
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthManager = void 0;
+exports.createAuthManager = createAuthManager;
+/**
+ * Storage keys used by AuthManager.
+ */
+const STORAGE_KEYS = {
+    ACCESS_TOKEN: 'oxy_access_token',
+    REFRESH_TOKEN: 'oxy_refresh_token',
+    SESSION: 'oxy_session',
+    USER: 'oxy_user',
+    AUTH_METHOD: 'oxy_auth_method',
+};
+/**
+ * Default in-memory storage for non-browser environments.
+ */
+class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    getItem(key) {
+        return this.store.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+    removeItem(key) {
+        this.store.delete(key);
+    }
+}
+/**
+ * Browser localStorage adapter.
+ */
+class LocalStorageAdapter {
+    getItem(key) {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            return localStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    }
+    setItem(key, value) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            localStorage.setItem(key, value);
+        }
+        catch {
+            // Storage full or blocked
+        }
+    }
+    removeItem(key) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            localStorage.removeItem(key);
+        }
+        catch {
+            // Ignore errors
+        }
+    }
+}
+/**
+ * AuthManager - Centralized authentication management.
+ *
+ * Provides a single point of control for:
+ * - Token storage and retrieval
+ * - Session management
+ * - Auth state change notifications
+ * - Multiple auth method support
+ *
+ * @example
+ * ```typescript
+ * const authManager = new AuthManager(oxyServices);
+ *
+ * // Listen for auth changes
+ * authManager.onAuthStateChange((user) => {
+ *   console.log('Auth state changed:', user);
+ * });
+ *
+ * // Handle successful auth
+ * await authManager.handleAuthSuccess(session);
+ *
+ * // Sign out
+ * await authManager.signOut();
+ * ```
+ */
+class AuthManager {
+    constructor(oxyServices, config = {}) {
+        this.listeners = new Set();
+        this.currentUser = null;
+        this.refreshTimer = null;
+        this.oxyServices = oxyServices;
+        this.config = {
+            storage: config.storage ?? this.getDefaultStorage(),
+            autoRefresh: config.autoRefresh ?? true,
+            refreshBuffer: config.refreshBuffer ?? 5 * 60 * 1000, // 5 minutes
+        };
+        this.storage = this.config.storage;
+    }
+    /**
+     * Get default storage based on environment.
+     */
+    getDefaultStorage() {
+        if (typeof window !== 'undefined' && window.localStorage) {
+            return new LocalStorageAdapter();
+        }
+        return new MemoryStorage();
+    }
+    /**
+     * Subscribe to auth state changes.
+     *
+     * @param callback - Function called when auth state changes
+     * @returns Unsubscribe function
+     */
+    onAuthStateChange(callback) {
+        this.listeners.add(callback);
+        // Call immediately with current state
+        callback(this.currentUser);
+        return () => {
+            this.listeners.delete(callback);
+        };
+    }
+    /**
+     * Notify all listeners of auth state change.
+     */
+    notifyListeners() {
+        for (const listener of this.listeners) {
+            try {
+                listener(this.currentUser);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+    /**
+     * Handle successful authentication.
+     *
+     * @param session - Session response from auth
+     * @param method - Auth method used
+     */
+    async handleAuthSuccess(session, method = 'credentials') {
+        // Store tokens
+        if (session.accessToken) {
+            await this.storage.setItem(STORAGE_KEYS.ACCESS_TOKEN, session.accessToken);
+            this.oxyServices.httpService.setTokens(session.accessToken);
+        }
+        // Store refresh token if available
+        if (session.refreshToken) {
+            await this.storage.setItem(STORAGE_KEYS.REFRESH_TOKEN, session.refreshToken);
+        }
+        // Store session info
+        await this.storage.setItem(STORAGE_KEYS.SESSION, JSON.stringify({
+            sessionId: session.sessionId,
+            deviceId: session.deviceId,
+            expiresAt: session.expiresAt,
+        }));
+        // Store user only if it has valid required fields (not an empty placeholder)
+        if (session.user && typeof session.user.id === 'string' && session.user.id.length > 0) {
+            await this.storage.setItem(STORAGE_KEYS.USER, JSON.stringify(session.user));
+            this.currentUser = session.user;
+        }
+        // Store auth method
+        await this.storage.setItem(STORAGE_KEYS.AUTH_METHOD, method);
+        // Setup auto-refresh if enabled
+        if (this.config.autoRefresh && session.expiresAt) {
+            this.setupTokenRefresh(session.expiresAt);
+        }
+        // Notify listeners
+        this.notifyListeners();
+    }
+    /**
+     * Setup automatic token refresh.
+     */
+    setupTokenRefresh(expiresAt) {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+        }
+        const expiresAtMs = new Date(expiresAt).getTime();
+        const now = Date.now();
+        const refreshAt = expiresAtMs - this.config.refreshBuffer;
+        const delay = Math.max(0, refreshAt - now);
+        if (delay > 0) {
+            this.refreshTimer = setTimeout(() => {
+                this.refreshToken().catch(() => {
+                    // Refresh failed, user will need to re-auth
+                });
+            }, delay);
+        }
+    }
+    /**
+     * Refresh the access token.
+     */
+    async refreshToken() {
+        const refreshToken = await this.storage.getItem(STORAGE_KEYS.REFRESH_TOKEN);
+        if (!refreshToken) {
+            return false;
+        }
+        try {
+            // Cast httpService to proper type (needed due to mixin composition)
+            const httpService = this.oxyServices.httpService;
+            const response = await httpService.request({
+                method: 'POST',
+                url: '/api/auth/refresh',
+                data: { refreshToken },
+                cache: false,
+            });
+            await this.handleAuthSuccess(response, 'credentials');
+            return true;
+        }
+        catch {
+            // Refresh failed, clear session and update state
+            await this.clearSession();
+            this.currentUser = null;
+            this.notifyListeners();
+            return false;
+        }
+    }
+    /**
+     * Sign out and clear all auth data.
+     */
+    async signOut() {
+        // Clear refresh timer
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        // Revoke FedCM credential if supported
+        try {
+            const services = this.oxyServices;
+            if (services.revokeFedCMCredential) {
+                await services.revokeFedCMCredential();
+            }
+        }
+        catch {
+            // Ignore FedCM errors
+        }
+        // Clear HTTP client tokens
+        this.oxyServices.httpService.setTokens('');
+        // Clear storage
+        await this.clearSession();
+        // Update state and notify
+        this.currentUser = null;
+        this.notifyListeners();
+    }
+    /**
+     * Clear session data from storage.
+     */
+    async clearSession() {
+        await this.storage.removeItem(STORAGE_KEYS.ACCESS_TOKEN);
+        await this.storage.removeItem(STORAGE_KEYS.REFRESH_TOKEN);
+        await this.storage.removeItem(STORAGE_KEYS.SESSION);
+        await this.storage.removeItem(STORAGE_KEYS.USER);
+        await this.storage.removeItem(STORAGE_KEYS.AUTH_METHOD);
+    }
+    /**
+     * Get current user.
+     */
+    getCurrentUser() {
+        return this.currentUser;
+    }
+    /**
+     * Check if user is authenticated.
+     */
+    isAuthenticated() {
+        return this.currentUser !== null;
+    }
+    /**
+     * Get stored access token.
+     */
+    async getAccessToken() {
+        return this.storage.getItem(STORAGE_KEYS.ACCESS_TOKEN);
+    }
+    /**
+     * Get the auth method used for current session.
+     */
+    async getAuthMethod() {
+        const method = await this.storage.getItem(STORAGE_KEYS.AUTH_METHOD);
+        return method;
+    }
+    /**
+     * Initialize auth state from storage.
+     *
+     * Call this on app startup to restore previous session.
+     */
+    async initialize() {
+        try {
+            // Try to restore user from storage
+            const userJson = await this.storage.getItem(STORAGE_KEYS.USER);
+            if (userJson) {
+                this.currentUser = JSON.parse(userJson);
+            }
+            // Restore token to HTTP client
+            const token = await this.storage.getItem(STORAGE_KEYS.ACCESS_TOKEN);
+            if (token) {
+                this.oxyServices.httpService.setTokens(token);
+            }
+            // Check session expiry
+            const sessionJson = await this.storage.getItem(STORAGE_KEYS.SESSION);
+            if (sessionJson) {
+                const session = JSON.parse(sessionJson);
+                if (session.expiresAt) {
+                    const expiresAt = new Date(session.expiresAt).getTime();
+                    if (expiresAt <= Date.now()) {
+                        // Session expired, try refresh
+                        const refreshed = await this.refreshToken();
+                        if (!refreshed) {
+                            await this.clearSession();
+                            this.currentUser = null;
+                        }
+                    }
+                    else if (this.config.autoRefresh) {
+                        // Setup refresh timer
+                        this.setupTokenRefresh(session.expiresAt);
+                    }
+                }
+            }
+            return this.currentUser;
+        }
+        catch {
+            // Failed to restore, start fresh
+            await this.clearSession();
+            this.currentUser = null;
+            return null;
+        }
+    }
+    /**
+     * Destroy the auth manager and clean up resources.
+     */
+    destroy() {
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.listeners.clear();
+    }
+}
+exports.AuthManager = AuthManager;
+/**
+ * Create an AuthManager instance.
+ *
+ * @param oxyServices - OxyServices instance
+ * @param config - Optional configuration
+ * @returns AuthManager instance
+ */
+function createAuthManager(oxyServices, config) {
+    return new AuthManager(oxyServices, config);
+}

package/dist/cjs/CrossDomainAuth.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * Cross-Domain Authentication Helper
+ *
+ * Provides a simplified API for cross-domain SSO authentication that automatically
+ * selects the best authentication method based on browser capabilities:
+ *
+ * 1. FedCM (if supported) - Modern, Google-style browser-native auth
+ * 2. Popup (fallback) - OAuth2-style popup window
+ * 3. Redirect (final fallback) - Traditional full-page redirect
+ *
+ * Usage:
+ * ```typescript
+ * import { CrossDomainAuth } from '@oxyhq/services';
+ *
+ * const auth = new CrossDomainAuth(oxyServices);
+ *
+ * // Automatic method selection
+ * const session = await auth.signIn();
+ *
+ * // Or use specific method
+ * const session = await auth.signInWithPopup();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossDomainAuth = void 0;
+exports.createCrossDomainAuth = createCrossDomainAuth;
+class CrossDomainAuth {
+    constructor(oxyServices) {
+        this.oxyServices = oxyServices;
+    }
+    /**
+     * Sign in with automatic method selection
+     *
+     * Tries methods in this order:
+     * 1. FedCM (if supported and not in private browsing)
+     * 2. Popup (if not blocked)
+     * 3. Redirect (always works)
+     *
+     * @param options - Authentication options
+     * @returns Session with user data and access token
+     */
+    async signIn(options = {}) {
+        const method = options.method || 'auto';
+        // If specific method requested, use it directly
+        if (method === 'fedcm') {
+            return this.signInWithFedCM(options);
+        }
+        if (method === 'popup') {
+            return this.signInWithPopup(options);
+        }
+        if (method === 'redirect') {
+            this.signInWithRedirect(options);
+            return null; // Redirect doesn't return immediately
+        }
+        // Auto mode: Try methods in order of preference
+        return this.autoSignIn(options);
+    }
+    /**
+     * Automatic sign-in with progressive enhancement
+     *
+     * @private
+     */
+    async autoSignIn(options) {
+        // 1. Try FedCM first (best UX, most modern)
+        if (this.isFedCMSupported()) {
+            try {
+                options.onMethodSelected?.('fedcm');
+                return await this.signInWithFedCM(options);
+            }
+            catch (error) {
+                console.warn('[CrossDomainAuth] FedCM failed, trying popup...', error);
+            }
+        }
+        // 2. Try popup (good UX, widely supported)
+        try {
+            options.onMethodSelected?.('popup');
+            return await this.signInWithPopup(options);
+        }
+        catch (error) {
+            console.warn('[CrossDomainAuth] Popup failed, falling back to redirect...', error);
+        }
+        // 3. Fallback to redirect (always works)
+        options.onMethodSelected?.('redirect');
+        this.signInWithRedirect(options);
+        return null;
+    }
+    /**
+     * Sign in using FedCM (Federated Credential Management)
+     *
+     * Best method - browser-native, no popups, Google-like experience
+     */
+    async signInWithFedCM(options = {}) {
+        return this.oxyServices.signInWithFedCM({
+            context: options.isSignup ? 'signup' : 'signin',
+        });
+    }
+    /**
+     * Sign in using popup window
+     *
+     * Good method - preserves app state, no full page reload
+     */
+    async signInWithPopup(options = {}) {
+        return this.oxyServices.signInWithPopup({
+            mode: options.isSignup ? 'signup' : 'login',
+            width: options.popupDimensions?.width,
+            height: options.popupDimensions?.height,
+        });
+    }
+    /**
+     * Sign in using full-page redirect
+     *
+     * Fallback method - works everywhere but loses app state
+     */
+    signInWithRedirect(options = {}) {
+        this.oxyServices.signInWithRedirect({
+            redirectUri: options.redirectUri,
+            mode: options.isSignup ? 'signup' : 'login',
+        });
+    }
+    /**
+     * Handle redirect callback
+     *
+     * Call this on app startup to check if we're returning from auth redirect
+     */
+    handleRedirectCallback() {
+        return this.oxyServices.handleAuthCallback();
+    }
+    /**
+     * Silent sign-in (check for existing session)
+     *
+     * Tries to automatically sign in without user interaction.
+     * Works with both FedCM and popup/iframe methods.
+     *
+     * @returns Session if user is already signed in, null otherwise
+     */
+    async silentSignIn() {
+        // Try FedCM silent sign-in first (if supported)
+        if (this.isFedCMSupported()) {
+            try {
+                const session = await this.oxyServices.silentSignInWithFedCM();
+                if (session) {
+                    return session;
+                }
+            }
+            catch (error) {
+                console.warn('[CrossDomainAuth] FedCM silent sign-in failed:', error);
+            }
+        }
+        // Fallback to iframe-based silent auth
+        try {
+            return await this.oxyServices.silentSignIn();
+        }
+        catch (error) {
+            console.warn('[CrossDomainAuth] Silent sign-in failed:', error);
+            return null;
+        }
+    }
+    /**
+     * Restore session from storage
+     *
+     * For redirect method - restores previously authenticated session from localStorage
+     */
+    restoreSession() {
+        return this.oxyServices.restoreSession?.() || false;
+    }
+    /**
+     * Check if FedCM is supported in current browser
+     */
+    isFedCMSupported() {
+        return this.oxyServices.constructor.isFedCMSupported?.() || false;
+    }
+    /**
+     * Get recommended authentication method for current environment
+     *
+     * @returns Recommended method name and reason
+     */
+    getRecommendedMethod() {
+        if (this.isFedCMSupported()) {
+            return {
+                method: 'fedcm',
+                reason: 'FedCM is supported - provides best UX with browser-native auth',
+            };
+        }
+        if (typeof window !== 'undefined') {
+            return {
+                method: 'popup',
+                reason: 'Browser environment - popup preserves app state',
+            };
+        }
+        return {
+            method: 'redirect',
+            reason: 'Fallback method - works in all environments',
+        };
+    }
+    /**
+     * Initialize cross-domain auth on app startup
+     *
+     * This handles:
+     * 1. Redirect callback (if returning from auth.oxy.so)
+     * 2. Session restoration (from localStorage)
+     * 3. Silent sign-in (check for existing SSO session)
+     *
+     * @returns Session if user is authenticated, null otherwise
+     */
+    async initialize() {
+        // 1. Check if this is a redirect callback
+        const callbackSession = this.handleRedirectCallback();
+        if (callbackSession) {
+            return callbackSession;
+        }
+        // 2. Try to restore existing session from storage
+        const restored = this.restoreSession();
+        if (restored) {
+            // Verify session is still valid by fetching user
+            try {
+                const user = await this.oxyServices.getCurrentUser();
+                if (user) {
+                    return {
+                        sessionId: this.oxyServices.getStoredSessionId?.() || '',
+                        deviceId: '',
+                        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+                        user,
+                    };
+                }
+            }
+            catch (error) {
+                console.warn('[CrossDomainAuth] Stored session invalid:', error);
+            }
+        }
+        // 3. Try silent sign-in (check for SSO session at auth.oxy.so)
+        return await this.silentSignIn();
+    }
+}
+exports.CrossDomainAuth = CrossDomainAuth;
+/**
+ * Helper function to create CrossDomainAuth instance
+ *
+ * @example
+ * ```typescript
+ * import { createCrossDomainAuth } from '@oxyhq/services';
+ *
+ * const oxyServices = new OxyServices({ baseURL: 'https://api.oxy.so' });
+ * const auth = createCrossDomainAuth(oxyServices);
+ *
+ * // On app startup
+ * const session = await auth.initialize();
+ * if (session) {
+ *   console.log('User is signed in:', session.user);
+ * }
+ *
+ * // Sign in button click
+ * const session = await auth.signIn();
+ * ```
+ */
+function createCrossDomainAuth(oxyServices) {
+    return new CrossDomainAuth(oxyServices);
+}