@oxyhq/core 5.5.0 → 6.0.0

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;

package/dist/types/mixins/OxyServices.fedcm.d.ts

@@ -1,331 +0,0 @@
-import type { OxyServicesBase } from '../OxyServices.base';
-import type { SessionLoginResponse } from '../models/session';
-export interface FedCMAuthOptions {
-    nonce?: string;
-    context?: 'signin' | 'signup' | 'continue' | 'use';
-    loginHint?: string;
-}
-export interface FedCMConfig {
-    enabled: boolean;
-    configURL: string;
-    clientId?: string;
-}
-/**
- * FedCM request mode values.
- *
- * The W3C FedCM spec renamed the `IdentityCredentialRequestOptions.mode` enum:
- * `'widget'` → `'passive'` and `'button'` → `'active'`. Modern Chrome only
- * accepts `'active'`/`'passive'` and throws a synchronous `TypeError` for the
- * legacy values, while Chrome 125–131 only understands `'button'`/`'widget'`.
- * Callers should use the modern values; the legacy values are accepted for
- * convenience and normalised internally.
- */
-export type FedCMRequestMode = 'active' | 'passive' | 'button' | 'widget';
-/**
- * Normalised result of a FedCM credential request: the IdP-issued ID token plus
- * whether the browser auto-selected the account (no explicit user choice).
- */
-interface FedCMTokenResult {
-    token: string;
-    isAutoSelected: boolean;
-}
-/**
- * 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 secondary windows 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 declare function OxyServicesFedCMMixin<T extends typeof OxyServicesBase>(Base: T): {
-    new (...args: any[]): {
-        resolveFedcmConfigUrl(): string;
-        /**
-         * Instance method to check FedCM support
-         */
-        isFedCMSupported(): boolean;
-        /**
-         * 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 secondary window 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();
-       *   const user = session.user;
-       * } catch (error) {
-       *   // Fallback to redirect auth
-       *   oxyServices.signInWithRedirect();
-         * }
-         * ```
-         */
-        signInWithFedCM(options?: FedCMAuthOptions): Promise<SessionLoginResponse>;
-        /**
-         * Run a single interactive FedCM credential request + token exchange for the
-         * given (possibly undefined) loginHint. A successful exchange plants the
-         * access token and persists the user id as the future loginHint — the hint is
-         * therefore only ever stored after a GENUINELY successful sign-in, never
-         * speculatively.
-         *
-         * @private
-         */
-        attemptInteractiveSignIn(options: FedCMAuthOptions, loginHint: string | undefined): Promise<SessionLoginResponse>;
-        /**
-         * Map a raw FedCM/exchange failure to a user-facing {@link OxyAuthenticationError}
-         * (or pass it through). Extracted so the clear-and-retry path can reuse the
-         * exact same error normalisation as the first attempt.
-         *
-         * @private
-         */
-        normalizeInteractiveSignInError(error: unknown): unknown;
-        /**
-         * 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();
-         * }, []);
-         * ```
-         */
-        silentSignInWithFedCM(): Promise<SessionLoginResponse | null>;
-        /**
-         * Request identity credential from browser using FedCM API
-         *
-         * Uses a global lock to prevent concurrent requests, as FedCM only
-         * allows one navigator.credentials.get request at a time.
-         *
-         * Interactive requests (optional/required) wait for any silent request to finish first.
-         *
-         * @private
-         */
-        requestIdentityCredential(options: {
-            configURL: string;
-            clientId: string;
-            nonce: string;
-            context?: string;
-            loginHint?: string;
-            mediation?: "silent" | "optional" | "required";
-            /**
-             * FedCM request mode. The W3C spec values are `'active'` (user-gesture
-             * button flow) and `'passive'` (browser-initiated widget flow). Chrome
-             * 125–131 used the legacy names `'button'`/`'widget'`; those are accepted
-             * here and mapped to the modern values, with an automatic legacy retry if
-             * the running browser only understands the old enum.
-             */
-            mode?: FedCMRequestMode;
-        }): Promise<FedCMTokenResult | null>;
-        /**
-         * 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
-         */
-        exchangeIdTokenForSession(idToken: string): Promise<SessionLoginResponse>;
-        /**
-         * Revoke FedCM credential (sign out)
-         *
-         * Uses IdentityCredential.disconnect() to tell the browser to forget
-         * the RP-IdP-account association. This resets the "returning account"
-         * state, which is required for silent mediation to work again.
-         */
-        revokeFedCMCredential(): Promise<void>;
-        /**
-         * Get configuration for FedCM
-         *
-         * @returns FedCM configuration with browser support info
-         */
-        getFedCMConfig(): FedCMConfig;
-        /**
-         * Generate a cryptographically secure local nonce for FedCM.
-         *
-         * NOTE: this is a *local* fallback only. The server-side `/fedcm/exchange`
-         * endpoint requires the nonce embedded in the ID token to have been minted
-         * by `POST /fedcm/nonce` (see {@link mintServerNonce}) and bound to this
-         * origin. A purely local nonce will be rejected with `invalid_nonce`. Use
-         * {@link getFedcmNonce}, which prefers a server-minted nonce and only falls
-         * back to this generator when the mint endpoint is unreachable.
-         *
-         * @private
-         */
-        generateNonce(): string;
-        /**
-         * Mint a single-use, origin-bound nonce from the Oxy API.
-         *
-         * The FedCM ID token issued by the IdP embeds this nonce as the `nonce`
-         * claim. When the consuming app calls `POST /fedcm/exchange`, the API burns
-         * the nonce (atomic `usedAt` transition) and verifies it was minted for the
-         * same origin as the token `aud`. This is the anti-replay binding required
-         * by the API's H9 hardening — without a server-minted nonce the exchange
-         * always fails.
-         *
-         * The browser attaches the `Origin` header automatically on this
-         * cross-origin request, so the API binds the nonce to the calling app's
-         * origin (which also becomes the FedCM `clientId`/token `aud`).
-         *
-         * @private
-         */
-        mintServerNonce(): Promise<string>;
-        /**
-         * Resolve the nonce to use for a FedCM credential request.
-         *
-         * Prefers a server-minted, origin-bound nonce (required for the token
-         * exchange to succeed). If the mint endpoint is unreachable we fall back to
-         * a locally generated nonce so the browser flow can still proceed; the
-         * exchange may then fail server-side, but that is strictly better than
-         * throwing before the browser ever shows its UI.
-         *
-         * @private
-         */
-        getFedcmNonce(): Promise<string>;
-        /**
-         * Get the client ID for this origin
-         *
-         * @private
-         */
-        getClientId(): string;
-        /** @internal */
-        getStoredLoginHint(): string | undefined;
-        /** @internal */
-        storeLoginHint(userId: string): void;
-        /** @internal */
-        clearLoginHint(): void;
-        /**
-         * List the authenticated user's authorized RP apps.
-         *
-         * Returns the intersection of the user's FedCM grants and the currently-
-         * approved RP catalog — what powers the "Connected apps" management UI in
-         * @oxyhq/services. Requires a real user session; service tokens are
-         * rejected by the underlying endpoint.
-         */
-        listAuthorizedApps(): Promise<AuthorizedApp[]>;
-        /**
-         * Revoke the authenticated user's authorization for a specific RP origin.
-         *
-         * The next FedCM sign-in from that origin will require explicit re-consent.
-         * The corresponding cache entry is invalidated so a subsequent
-         * `listAuthorizedApps()` call sees fresh data.
-         */
-        revokeAuthorizedApp(origin: string): Promise<void>;
-        httpService: import("../HttpService").HttpService;
-        cloudURL: string;
-        config: import("../OxyServices.base").OxyConfig;
-        __resetTokensForTests(): void;
-        makeRequest<T_1>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: any, options?: import("../HttpService").RequestOptions): Promise<T_1>;
-        getBaseURL(): string;
-        getSessionBaseUrl(): string;
-        getClient(): import("../HttpService").HttpService;
-        createLinkedClient(config: import("../OxyServices.base").OxyConfig): import("..").LinkedHttpClient;
-        getMetrics(): {
-            totalRequests: number;
-            successfulRequests: number;
-            failedRequests: number;
-            cacheHits: number;
-            cacheMisses: number;
-            averageResponseTime: number;
-        };
-        clearCache(): void;
-        clearCacheEntry(key: string): void;
-        clearCacheByPrefix(prefix: string): number;
-        getCacheStats(): {
-            size: number;
-            hits: number;
-            misses: number;
-            hitRate: number;
-        };
-        getCloudURL(): string;
-        setTokens(accessToken: string): void;
-        clearTokens(): void;
-        onTokensChanged(listener: (accessToken: string | null) => void): () => void;
-        _cachedUserId: string | null | undefined;
-        _cachedAccessToken: string | null;
-        getCurrentUserId(): string | null;
-        hasValidToken(): boolean;
-        getAccessToken(): string | null;
-        establishDeviceRefreshSlot(): Promise<number | null>;
-        getAccessTokenExpiry(): number | null;
-        waitForAuth(timeoutMs?: number): Promise<boolean>;
-        withAuthRetry<T_1>(operation: () => Promise<T_1>, operationName: string, options?: {
-            maxRetries?: number;
-            retryDelay?: number;
-            authTimeoutMs?: number;
-        }): Promise<T_1>;
-        validate(): Promise<boolean>;
-        handleError(error: unknown): Error;
-        healthCheck(): Promise<{
-            status: string;
-            users?: number;
-            timestamp?: string;
-            [key: string]: any;
-        }>;
-    };
-    readonly DEFAULT_CONFIG_URL: "https://auth.oxy.so/fedcm.json";
-    readonly FEDCM_TIMEOUT: 15000;
-    readonly FEDCM_SILENT_TIMEOUT: 4000;
-    readonly FEDCM_ABORT_SETTLE_GRACE_MS: 500;
-    /**
-     * Check if FedCM is supported in the current browser
-     */
-    isFedCMSupported(): boolean;
-} & T;
-/**
- * Public summary of an RP application the user has authorized — mirrors the
- * `AuthorizedAppSummary` shape returned by `GET /fedcm/me/authorized-apps`.
- */
-export interface AuthorizedApp {
-    /** Normalised RP origin. */
-    origin: string;
-    /** Friendly display name. */
-    name: string;
-    /** Optional human-readable description. */
-    description?: string;
-    /** ISO-8601 timestamp of when the user first authorized this RP. */
-    firstGrantedAt: string;
-    /** ISO-8601 timestamp of the most recent FedCM exchange for this user+RP. */
-    lastUsedAt: string;
-}
-export { OxyServicesFedCMMixin as FedCMMixin };