@oxyhq/core 5.5.0 → 7.0.0

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 };

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

@@ -1,92 +0,0 @@
-import type { OxyServicesBase } from '../OxyServices.base';
-import type { SessionLoginResponse } from '../models/session';
-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 declare function OxyServicesRedirectAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
-    new (...args: 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;
-        signUpWithRedirect(options?: RedirectAuthOptions): void;
-        /**
-         * Legacy token-query callbacks are intentionally rejected. Modern providers
-         * complete redirect auth through `consumeSsoReturn`, which accepts only
-         * `#oxy_sso=ok&code=...`.
-         */
-        handleAuthCallback(): SessionLoginResponse | null;
-        restoreSession(): boolean;
-        clearStoredSession(): void;
-        getStoredSessionId(): string | null;
-        generateState(): string;
-        generateNonce(): string;
-        cleanAuthCallbackUrl(url: URL): 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;
-        }>;
-    };
-} & T;
-export { OxyServicesRedirectAuthMixin as RedirectAuthMixin };

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

@@ -1,132 +0,0 @@
-import type { OxyServicesBase } from "../OxyServices.base";
-import type { SessionLoginResponse } from "../models/session";
-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 declare function OxyServicesSilentAuthMixin<T extends typeof OxyServicesBase>(Base: T): {
-    new (...args: any[]): {
-        /** Resolve auth URL from config or static default (method, not getter — getters break in TS mixins) */
-        resolveAuthUrl(): string;
-        /**
-         * 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();
-         * }, []);
-         * ```
-         */
-        silentSignIn(options?: SilentAuthOptions): Promise<SessionLoginResponse | null>;
-        /**
-         * Wait for authentication response from iframe
-         *
-         * @private
-         */
-        waitForIframeAuth(iframe: HTMLIFrameElement, timeout: number, expectedOrigin: string): Promise<SessionLoginResponse | null>;
-        /**
-         * Generate nonce for replay attack prevention
-         *
-         * @private
-         */
-        generateNonce(): string;
-        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_AUTH_URL: "https://auth.oxy.so";
-    readonly SILENT_TIMEOUT: 5000;
-} & T;
-export { OxyServicesSilentAuthMixin as SilentAuthMixin };