@oxyhq/core 5.5.0 → 7.0.0

package/dist/types/AuthManager.d.ts

@@ -1,380 +0,0 @@
-/**
- * AuthManager - Centralized Authentication Manager
- *
- * Provides a unified authentication interface for all platforms.
- * Handles token storage, session management, and auth state changes.
- *
- * @module core/AuthManager
- */
-import type { OxyServices } from './OxyServices';
-import type { SessionLoginResponse, MinimalUserData } from './models/session';
-import type { AuthManagerAccount, RestoreFromCookiesResult, RestoreFromCookiesOptions, SwitchAuthuserResult } from './AuthManagerTypes';
-/**
- * Storage adapter interface for platform-agnostic storage.
- */
-export interface StorageAdapter {
-    getItem: (key: string) => Promise<string | null> | string | null;
-    setItem: (key: string, value: string) => Promise<void> | void;
-    removeItem: (key: string) => Promise<void> | void;
-}
-/**
- * Auth state change callback type.
- */
-export type AuthStateChangeCallback = (user: MinimalUserData | null) => void;
-/**
- * Auth method types.
- */
-export type AuthMethod = 'fedcm' | 'redirect' | 'credentials' | 'identity';
-/**
- * Auth manager configuration.
- */
-export interface AuthManagerConfig {
-    /** Storage adapter (localStorage, AsyncStorage, etc.) */
-    storage?: StorageAdapter;
-    /** Whether to auto-refresh tokens */
-    autoRefresh?: boolean;
-    /** Token refresh interval in milliseconds (default: 5 minutes before expiry) */
-    refreshBuffer?: number;
-    /** Enable cross-tab coordination via BroadcastChannel (default: true in browsers) */
-    crossTabSync?: boolean;
-}
-/**
- * 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();
- * ```
- */
-export declare class AuthManager {
-    private oxyServices;
-    private storage;
-    private listeners;
-    private currentUser;
-    private currentAuthMethod;
-    private refreshTimer;
-    private refreshPromise;
-    private config;
-    /** Tracks the access token this instance last knew about, for cross-tab adoption. */
-    private _lastKnownAccessToken;
-    /** BroadcastChannel for coordinating token refreshes across browser tabs. */
-    private _broadcastChannel;
-    /**
-     * Identifier for this AuthManager instance (≈ "this tab"). Random hex
-     * generated at construction; advertised in every outgoing broadcast and
-     * used as the lookup key in `_knownPeerNonces`.
-     */
-    private readonly _tabId;
-    /**
-     * Per-tab nonce, advertised in every outgoing broadcast. Receivers record
-     * the first (tabId, nonce) pair they see from a given peer; subsequent
-     * messages from the same tabId MUST carry the same nonce or they're
-     * ignored.
-     *
-     * Threat model: a same-origin XSS payload can post to the channel but can
-     * NOT read this instance's private `_broadcastNonce` field (it lives in
-     * closure, not on `window`). Forged broadcasts from XSS therefore can't
-     * impersonate this tab. A new attacker-controlled tabId trips the
-     * "first message from a new peer" branch, which is by definition trusted
-     * — so the gate raises the bar but is not a complete defence (a perfect
-     * mitigation would require message signing with a server-issued key).
-     */
-    private readonly _broadcastNonce;
-    /**
-     * Bounded LRU of `(tabId → nonce)` pairs seen on inbound broadcasts. First
-     * sighting of a new tabId records its nonce; later messages from that
-     * tabId are rejected if the nonce doesn't match.
-     */
-    private readonly _knownPeerNonces;
-    private static readonly _MAX_KNOWN_PEERS;
-    /**
-     * In-flight `switchAuthuser` promise. Deduplicates concurrent calls so two
-     * near-simultaneous switches don't both fire refresh requests and rotate
-     * the slot twice. Mirrors the `refreshPromise` pattern used by
-     * `refreshToken`.
-     */
-    private _switchPromise;
-    /**
-     * Last `restoreFromCookies()` completion timestamp, keyed by the
-     * AuthManager's active authuser at the time of completion. Used to gate
-     * cross-tab cascade: a flurry of BroadcastChannel events from sibling
-     * tabs can otherwise trigger N back-to-back snapshots and rotate every
-     * slot's access token N times.
-     */
-    private readonly _lastRestoreAt;
-    private static readonly _RESTORE_DEBOUNCE_MS;
-    /**
-     * In-memory registry of every device-local account the AuthManager knows
-     * about, keyed by `authuser` slot index. Populated by:
-     *   - `restoreFromCookies()` (cold boot)
-     *   - `switchAuthuser()` (per-account rotation)
-     *   - `handleAuthSuccess()` (fresh login when the server response carries
-     *     an `authuser` field)
-     * Access tokens live ONLY here in the cookie path — they are never
-     * persisted to localStorage.
-     */
-    private accounts;
-    /**
-     * Currently-active `authuser` slot in the cookie path. `null` means either
-     * the cookie path hasn't been initialised yet, or no slots are signed in.
-     */
-    private activeAuthuser;
-    constructor(oxyServices: OxyServices, config?: AuthManagerConfig);
-    /**
-     * Initialize BroadcastChannel for cross-tab token refresh coordination.
-     * Only called in browser environments where BroadcastChannel is available.
-     */
-    private _initBroadcastChannel;
-    /**
-     * Handle messages from other tabs about token refresh activity.
-     */
-    private _handleCrossTabMessage;
-    /**
-     * Broadcast a message to other tabs. Always stamps this tab's `tabId` and
-     * `nonce` onto the message so receivers can run the cross-tab nonce gate.
-     */
-    private _broadcast;
-    /**
-     * Generate `bytes` bytes of cryptographic randomness encoded as lowercase
-     * hex. Prefers Web Crypto's `getRandomValues` when available (browser /
-     * modern Node); falls back to `Math.random` ONLY in environments without
-     * Web Crypto (the resulting nonce is still unguessable to a same-origin
-     * XSS payload — the goal is unforgeability across tabs, not cryptographic
-     * secrecy across the network).
-     */
-    private static _randomHex;
-    /**
-     * Validate an inbound broadcast against the cross-tab nonce gate.
-     *
-     * Returns `true` when the message should be honoured, `false` when it
-     * MUST be ignored:
-     *   - Message is missing `tabId` or `nonce` → ignore (forged or
-     *     mismatched-version sibling tab).
-     *   - First sighting of `tabId` → record the nonce and honour the message
-     *     (trust-on-first-use, the best we can do without a shared secret).
-     *   - Subsequent message from the same `tabId` with the SAME nonce →
-     *     honour.
-     *   - Subsequent message from the same `tabId` with a DIFFERENT nonce →
-     *     ignore (the canonical "forged broadcast" case — a same-origin XSS
-     *     payload can't read the real tab's `_broadcastNonce`).
-     *
-     * Echoes of this tab's own broadcasts (same `tabId`) are also dropped so
-     * we don't react to our own messages.
-     */
-    private _acceptBroadcast;
-    /**
-     * Get default storage based on environment.
-     */
-    private getDefaultStorage;
-    /**
-     * Subscribe to auth state changes.
-     *
-     * @param callback - Function called when auth state changes
-     * @returns Unsubscribe function
-     */
-    onAuthStateChange(callback: AuthStateChangeCallback): () => void;
-    /**
-     * Notify all listeners of auth state change.
-     */
-    private notifyListeners;
-    /**
-     * Handle successful authentication.
-     *
-     * @param session - Session response from auth
-     * @param method - Auth method used
-     */
-    handleAuthSuccess(session: SessionLoginResponse, method?: AuthMethod): Promise<void>;
-    /**
-     * Refresh the access token. Deduplicates concurrent calls so only one
-     * refresh request is in-flight at a time. The only refresh authority is the
-     * active httpOnly refresh-cookie slot; this method never reads access tokens
-     * from storage.
-     */
-    refreshToken(): Promise<boolean>;
-    private _doRefreshToken;
-    /**
-     * Sign out and clear all auth data.
-     */
-    signOut(): Promise<void>;
-    /**
-     * Clear local cookie-path state. The only persisted AuthManager value is the
-     * active numeric slot; tokens and user objects are intentionally memory-only.
-     */
-    private clearSession;
-    /**
-     * Get current user.
-     */
-    getCurrentUser(): MinimalUserData | null;
-    /**
-     * Check if user is authenticated.
-     */
-    isAuthenticated(): boolean;
-    /**
-     * Get a valid access token, refreshing automatically if expired or expiring
-     * soon. The token is read from memory only.
-     */
-    getAccessToken(): Promise<string | null>;
-    /**
-     * Get the auth method used for current session.
-     */
-    getAuthMethod(): Promise<AuthMethod | null>;
-    /**
-     * Initialize auth state on app startup.
-     *
-     * Only the cookie path is authoritative. `restoreFromCookies()` refreshes
-     * the httpOnly `oxy_rt_${authuser}` slots through `/auth/refresh-all`,
-     * plants the active access token in memory, and returns the active user.
-     * No access token, refresh token, or session JSON is read from localStorage.
-     *
-     * Returns the active user on success, or `null` when no cookie-backed
-     * account was restored.
-     */
-    initialize(options?: RestoreFromCookiesOptions): Promise<MinimalUserData | null>;
-    /**
-     * Read the persisted active `authuser` slot index. Returns `null` when
-     * none is persisted, the value is corrupt, or the storage adapter has no
-     * record. Storage failures are non-fatal: the cookie path falls back to
-     * "lowest authuser" deterministic selection.
-     */
-    private readActiveAuthuser;
-    /**
-     * Persist the active `authuser` slot index. No-ops on storage failure
-     * (e.g. Safari private mode, native SecureStore unavailable) — this is
-     * best-effort UX persistence, not authoritative state.
-     */
-    private writeActiveAuthuser;
-    /**
-     * Clear the persisted active `authuser` so the next cold boot starts from
-     * a clean slate (used on full sign-out).
-     */
-    private clearActiveAuthuser;
-    /**
-     * Build a `MinimalUserData` from a `RefreshAllAccount`. Returns `null` when
-     * the wire entry has no user shape; the AuthManager's caller is expected to
-     * hydrate via `/users/me` in that case.
-     */
-    private static toMinimalUser;
-    /**
-     * Hydrate the user shape for a slot whose AuthManagerAccount currently has
-     * `user: null` (for example, a switch onto a previously unknown slot). Calls
-     * `/users/me` with the slot's freshly-planted access
-     * token already on the HTTP client; merges the result back into the
-     * registry entry. Network failures are non-fatal — the slot remains with
-     * `user: null` and the UI is expected to render the public-key fallback
-     * handle until a later restore picks the real user shape up.
-     */
-    private _hydrateUnknownUser;
-    /**
-     * Snapshot of the registered cookie-path accounts, sorted by `authuser`
-     * ascending (canonical order). Mutating the returned array does not
-     * affect AuthManager state.
-     */
-    getAccounts(): AuthManagerAccount[];
-    /**
-     * The slot index that is currently active in the cookie path, or `null`
-     * if the cookie path hasn't been initialised or no slots are signed in.
-     */
-    getActiveAuthuser(): number | null;
-    /**
-     * Convenience: the AuthManagerAccount currently flagged active.
-     */
-    getActiveAccount(): AuthManagerAccount | null;
-    /**
-     * Restore every device-local account from the httpOnly refresh cookies.
-     *
-     * Calls `oxyServices.refreshAllSessions()` (`POST /auth/refresh-all` with
-     * `credentials: 'include'`). The server rotates every presented
-     * `oxy_rt_${authuser}` cookie in parallel and returns one entry per
-     * valid slot.
-     *
-     * Plants the active account's access token on the shared HTTP client;
-     * sibling slots' tokens stay in the in-memory registry so a later
-     * `switchAuthuser()` can hot-swap them without a network round-trip.
-     *
-     * The persisted `oxy_active_authuser` slot wins when it matches a
-     * returned account; otherwise the lowest returned `authuser` is chosen
-     * deterministically.
-     *
-     * Returns `{ accounts: [], activeAuthuser: null }` on any failure or
-     * empty snapshot — callers treat that as "no signed-in accounts" and
-     * proceed unauthenticated. State is NOT cleared on failure; existing
-     * accounts (if any) remain intact.
-     */
-    restoreFromCookies(options?: RestoreFromCookiesOptions): Promise<RestoreFromCookiesResult>;
-    /**
-     * Switch the active account to a different device-local slot.
-     *
-     * Calls `oxyServices.refreshTokenViaCookie({ authuser })` to mint a fresh
-     * access token from the slot's httpOnly cookie, updates the in-memory
-     * registry entry, plants the token on the HTTP client, persists the new
-     * active slot, and broadcasts cross-tab.
-     *
-     * Throws when the slot's refresh cookie is missing / expired / reused
-     * (the SDK returns `null` from `refreshTokenViaCookie` in that case, and
-     * we surface it as an `Error` so callers can clean up the slot from
-     * their UI).
-     */
-    switchAuthuser(authuser: number): Promise<SwitchAuthuserResult>;
-    private _doSwitchAuthuser;
-    /**
-     * Sign out a single device-local slot.
-     *
-     * Calls `oxyServices.logoutSessionByAuthuser(authuser)`: server-side
-     * revokes the slot's refresh-token family and clears the
-     * `oxy_rt_${authuser}` cookie via `Set-Cookie`. The slot is removed from
-     * the in-memory registry. If the slot was active, the next lowest
-     * remaining authuser becomes active (or `null` when none remain).
-     */
-    signOutAuthuser(authuser: number): Promise<void>;
-    /**
-     * Sign out EVERY device-local account on this device.
-     *
-     * Calls `oxyServices.logoutAllSessionsViaCookie()`: server-side revokes
-     * every presented family and `Set-Cookie`s an immediate expiry for every
-     * recognised `oxy_rt_${n}` slot. The in-memory registry is wiped, the active
-     * slot is cleared, and the persisted `oxy_active_authuser` is removed so the
-     * next cold boot starts fresh.
-     */
-    signOutAllViaCookies(): Promise<void>;
-    /**
-     * Schedule an auto-refresh for the cookie path on the active slot. The
-     * AuthManager has exactly one active slot at a time, so one timer suffices.
-     */
-    private setupCookieRefresh;
-    /**
-     * Decode the session id from an unverified JWT access token. Decode-only
-     * (no signature verification) — the server already verified the
-     * signature when minting the token. Returns `null` on malformed input.
-     */
-    private static decodeSessionIdFromAccessToken;
-    private static decodeAuthuserFromAccessToken;
-    /**
-     * Destroy the auth manager and clean up resources.
-     */
-    destroy(): void;
-}
-/**
- * Create an AuthManager instance.
- *
- * @param oxyServices - OxyServices instance
- * @param config - Optional configuration
- * @returns AuthManager instance
- */
-export declare function createAuthManager(oxyServices: OxyServices, config?: AuthManagerConfig): AuthManager;

package/dist/types/AuthManagerTypes.d.ts

@@ -1,81 +0,0 @@
-/**
- * AuthManager — public types for the multi-account cookie path.
- *
- * Lives in its own module (rather than the 670-line `models/interfaces.ts`)
- * so consumers can `import type` exactly the multi-account surface without
- * pulling in the full interfaces graph, and so `AuthManager.ts` stays
- * decoupled from the wire shapes — these types re-state the wire as the
- * AuthManager's in-memory representation.
- *
- * @module core/AuthManagerTypes
- */
-import type { RefreshAllAccountUser } from './models/interfaces';
-/**
- * One device-local account known to `AuthManager` in the cookie path.
- *
- * Built from a `POST /auth/refresh-all` entry, OR from a single
- * `POST /auth/refresh?authuser=N` rotation after a switch, OR from a
- * `handleAuthSuccess` call after a fresh login. The `accessToken` is held in
- * memory only — the refresh token never enters JS (it lives in the httpOnly
- * `oxy_rt_${authuser}` cookie).
- */
-export interface AuthManagerAccount {
-    /** Device-local cookie slot index (0..N-1). */
-    authuser: number;
-    /** Server-side session id this slot is bound to. */
-    sessionId: string;
-    /**
-     * Projected user shape from the wire (username/avatar/color/email).
-     *
-     * `null` when a refresh-via-cookie planted a fresh access token for a slot
-     * that the AuthManager has no prior in-memory user metadata for. Callers (or
-     * the AuthManager itself) are expected to hydrate the user shape via
-     * `getCurrentUser()` after the token is planted; the chooser UI must render
-     * the public-key fallback handle until the hydration completes.
-     */
-    user: RefreshAllAccountUser | null;
-    /** Currently-valid access token for this slot (in-memory only). */
-    accessToken: string;
-    /** ISO-8601 expiry of the access token. */
-    expiresAt: string;
-}
-/**
- * Outcome of `AuthManager.restoreFromCookies()`.
- *
- * `accounts` is sorted by `authuser` ascending (matching the server's
- * canonical ordering). `activeAuthuser` is whichever slot the AuthManager
- * picked as active — usually the persisted `oxy_active_authuser` if it
- * matched a returned slot, otherwise the lowest returned `authuser`, or
- * `null` if no accounts were restored.
- */
-export interface RestoreFromCookiesResult {
-    accounts: AuthManagerAccount[];
-    activeAuthuser: number | null;
-}
-/**
- * Options for `AuthManager.restoreFromCookies()` / `AuthManager.initialize()`.
- */
-export interface RestoreFromCookiesOptions {
-    /**
-     * Abort the underlying `POST /auth/refresh-all` after this many milliseconds
-     * and treat it as "no signed-in accounts" instead of hanging. Forwarded
-     * verbatim to `OxyServices.refreshAllSessions({ timeout })`.
-     *
-     * Intended for the cold-boot cookie-restore step on a cross-domain RP, where
-     * the `Domain=oxy.so` refresh cookie never reaches `api.<apex>` and the
-     * request can stall with no useful answer. Omit (the default) to wait
-     * indefinitely — the warm cross-tab cascade path passes nothing, preserving
-     * its existing behaviour.
-     */
-    timeout?: number;
-}
-/**
- * Outcome of `AuthManager.switchAuthuser()`.
- *
- * Mirrors the wire `RefreshCookieResponse`.
- */
-export interface SwitchAuthuserResult {
-    accessToken: string;
-    expiresAt: string;
-    authuser: number;
-}

package/dist/types/CrossDomainAuth.d.ts

@@ -1,164 +0,0 @@
-/**
- * Cross-Domain Authentication Helper
- *
- * Provides a simplified API for cross-domain SSO authentication. The
- * automatic sign-in path uses a full-page redirect through the central IdP
- * (`auth.oxy.so`) — a tokenless, universal mechanism that works in every
- * browser.
- *
- * FedCM (`signInWithFedCM`) is intentionally NOT part of the automatic
- * (`'auto'`) path: it is a Chrome-only browser API, and a misconfigured or
- * unreachable FedCM endpoint fails fast and silently, which — combined with a
- * caller's auth-guard effect re-invoking `signIn()` whenever the user is still
- * unauthenticated — produced a real production incident (an accelerating
- * `autoSignIn` → FedCM-fails → redirect retry loop). `signInWithFedCM` remains
- * available for callers that want to opt into it EXPLICITLY
- * (`signIn({ method: 'fedcm' })`).
- *
- * Usage:
- * ```typescript
- * import { CrossDomainAuth } from '@oxyhq/core';
- *
- * const auth = new CrossDomainAuth(oxyServices);
- *
- * // Automatic method selection (always redirect)
- * const session = await auth.signIn();
- *
- * // Or use a specific method
- * auth.signInWithRedirect();
- * ```
- */
-import type { OxyServices } from './OxyServices';
-import type { SessionLoginResponse } from './models/session';
-export interface CrossDomainAuthOptions {
-    /**
-     * Preferred authentication method
-     * - 'auto': Automatically select best method (default)
-     * - 'fedcm': Use FedCM (browser-native)
-     * - 'redirect': Use full-page redirect
-     */
-    method?: 'auto' | 'fedcm' | 'redirect';
-    /**
-     * Custom redirect URI (for redirect method)
-     */
-    redirectUri?: string;
-    /**
-     * Whether to open signup page instead of login
-     */
-    isSignup?: boolean;
-    /**
-     * Callback when auth method is selected
-     */
-    onMethodSelected?: (method: 'fedcm' | 'redirect') => void;
-}
-export declare class CrossDomainAuth {
-    private oxyServices;
-    constructor(oxyServices: OxyServices);
-    /**
-     * Sign in with automatic method selection.
-     *
-     * Auto mode always uses the full-page redirect (see the class doc comment
-     * for why FedCM was removed from this path). Pass `{ method: 'fedcm' }` to
-     * opt into FedCM explicitly.
-     *
-     * @param options - Authentication options
-     * @returns Session with user data and access token
-     */
-    signIn(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse | null>;
-    /**
-     * Automatic sign-in.
-     *
-     * Goes straight to the full-page redirect — the sole automatic method.
-     * FedCM is deliberately NOT attempted here (see the class doc comment):
-     * it is Chrome-only, and its fast/silent failure mode combined with a
-     * caller's auth-guard effect re-invoking `signIn()` produced a real
-     * production sign-in loop. Use `signIn({ method: 'fedcm' })` to opt in
-     * explicitly.
-     *
-     * @private
-     */
-    private autoSignIn;
-    /**
-     * Sign in using FedCM (Federated Credential Management)
-     *
-     * Best method - browser-native, Google-like experience
-     */
-    signInWithFedCM(options?: CrossDomainAuthOptions): Promise<SessionLoginResponse>;
-    /**
-     * Sign in using full-page redirect
-     *
-     * Fallback method - works everywhere but loses app state
-     */
-    signInWithRedirect(options?: CrossDomainAuthOptions): void;
-    /**
-     * Handle redirect callback
-     *
-     * Call this on app startup to check if we're returning from auth redirect
-     */
-    handleRedirectCallback(): SessionLoginResponse | null;
-    /**
-     * Silent sign-in (check for existing session)
-     *
-     * Tries to automatically sign in without user interaction, via the
-     * iframe-based silent auth against the per-apex `/auth/silent` IdP host.
-     * FedCM is deliberately NOT attempted here (see the class doc comment).
-     *
-     * @returns Session if user is already signed in, null otherwise
-     */
-    silentSignIn(): Promise<SessionLoginResponse | null>;
-    /**
-     * Restore session from storage.
-     *
-     * Access tokens are no longer persisted in browser storage; providers restore
-     * through refresh cookies / SSO code exchange instead.
-     */
-    restoreSession(): boolean;
-    /**
-     * Check if FedCM is supported in current browser
-     */
-    isFedCMSupported(): boolean;
-    /**
-     * Get recommended authentication method for current environment
-     *
-     * Redirect is the sole recommended automatic method — it works in every
-     * browser, unlike FedCM (Chrome-only). Callers that want FedCM must opt in
-     * explicitly via `signIn({ method: 'fedcm' })`.
-     *
-     * @returns Recommended method name and reason
-     */
-    getRecommendedMethod(): {
-        method: 'redirect';
-        reason: string;
-    };
-    /**
-     * Initialize cross-domain auth on app startup
-     *
-     * This handles:
-     * 1. Redirect callback (if returning from auth.oxy.so)
-     * 2. Silent sign-in (check for existing SSO session)
-     *
-     * @returns Session if user is authenticated, null otherwise
-     */
-    initialize(): Promise<SessionLoginResponse | null>;
-}
-/**
- * Helper function to create CrossDomainAuth instance
- *
- * @example
- * ```typescript
- * import { createCrossDomainAuth } from '@oxyhq/core';
- *
- * 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();
- * ```
- */
-export declare function createCrossDomainAuth(oxyServices: OxyServices): CrossDomainAuth;