@oxyhq/core 5.4.3 → 6.0.0

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

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

@@ -1,138 +0,0 @@
-/**
- * Central Cross-Domain SSO (opaque-code) Mixin
- *
- * Implements the Relying-Party half of TRUE central cross-domain SSO
- * (Google/Meta/Clerk style). The central IdP at `auth.oxy.so` owns the session;
- * an RP bounces a top-level redirect (prompt=none) to `auth.oxy.so/sso`, which
- * returns an OPAQUE single-use code in the redirect fragment. The RP then
- * exchanges that code here for the real session.
- *
- * Security properties:
- *   - NO token/JWT ever travels in a URL — only the opaque code does. The real
- *     `accessToken` is delivered exclusively in this exchange response body.
- *   - The exchange is a CORS POST with NO credentials/cookies — the opaque code
- *     is the only bearer of authority, and the central store burns it atomically
- *     (single-use). Sending no cookies keeps the request a clean, ambient-
- *     authority-free bearer exchange that the central `POST /sso/exchange`
- *     endpoint validates by `Origin` against the code's bound `clientOrigin`.
- *   - The code is minted server-side bound to the RP origin and expires in
- *     seconds, so a leaked code is useless cross-origin and short-lived.
- *
- * On success the mixin plants the returned access token via
- * `httpService.setTokens(...)` — mirroring `exchangeIdTokenForSession` /
- * `verifyChallenge` — so callers do NOT need to plant tokens manually.
- */
-import type { OxyServicesBase } from '../OxyServices.base';
-import type { SessionLoginResponse } from '../models/session';
-/**
- * Generate a cryptographically secure state value for the SSO bounce.
- *
- * Exposed as a module-level helper (in addition to the instance method below)
- * so consumers that do not yet hold an `OxyServices` instance can still mint a
- * bounce state. Uses `crypto.randomUUID` with a `getRandomValues` fallback.
- */
-export declare function generateSsoState(): string;
-export declare function OxyServicesSsoMixin<T extends typeof OxyServicesBase>(Base: T): {
-    new (...args: any[]): {
-        /**
-         * Generate cryptographically secure state for the SSO bounce (CSRF
-         * protection). Delegates to the module-level {@link generateSsoState}
-         * helper, which uses `crypto.randomUUID` when available and falls back to
-         * `crypto.getRandomValues`.
-         */
-        generateSsoState(): string;
-        /**
-         * Exchange an opaque single-use SSO code for the real Oxy session.
-         *
-         * POSTs `{ code }` to `${getSessionBaseUrl()}/sso/exchange` as a CORS
-         * request with NO credentials/cookies. On success the returned access token
-         * is planted via `httpService.setTokens(...)` (matching
-         * `exchangeIdTokenForSession` / `verifyChallenge`), so callers do not need
-         * to plant tokens manually.
-         *
-         * @param code - The opaque single-use code delivered in the SSO return
-         *   fragment (see {@link parseSsoReturnFragment}). The central store burns
-         *   it atomically on exchange.
-         * @param state - The state value returned alongside the code. In browsers,
-         *   when an SSO bounce state is still stored for the current origin, this
-         *   must match before any token-committing exchange is attempted.
-         * @returns The resolved {@link SessionLoginResponse}.
-         */
-        exchangeSsoCode(code: string, state?: string): Promise<SessionLoginResponse>;
-        /**
-         * Mint a server-formed `/sso/establish` URL for the caller's OWN session,
-         * bound to an approved RP `origin`.
-         *
-         * Bearer-authenticated (the session id is taken from the caller's own
-         * bearer, server-side — never from any argument). The server validates that
-         * `origin` is an approved client origin (and matches the request `Origin`),
-         * derives the per-apex IdP host (`auth.<apex>`), mints a short-lived HS256
-         * establish-token, and returns a fully-formed
-         * `https://<auth-host>/sso/establish?et=…&return_to=<origin>/__oxy/sso-callback&state=<state>`.
-         *
-         * Used AFTER a web device-flow claim to plant the durable first-party
-         * `fedcm_session` cookie so a reload can re-mint a token (see
-         * {@link establishIdpSessionAfterClaim}). Cache-free (a POST is never
-         * cached, but `cache: false` is explicit).
-         *
-         * @param origin - The RP origin (`window.location.origin`) to establish for.
-         * @param state - The CSRF state echoed back in the callback fragment; the
-         *   caller persists the SAME value under `ssoStateKey(origin)` so the
-         *   post-bounce `sso-return` step validates it.
-         */
-        requestSsoEstablishUrl(origin: string, state: string): Promise<{
-            establishUrl: 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;
-        }>;
-    };
-} & T;

package/dist/types/utils/ssoEstablish.d.ts

@@ -1,85 +0,0 @@
-/**
- * Post-claim durable-session establish hop (web device-flow / "Sign in with
- * Oxy" QR).
- *
- * A WEB device-flow claim (`claimSessionByToken`) plants only IN-MEMORY tokens:
- * unlike a redirect/FedCM/silent sign-in, it never causes the IdP to plant a
- * `fedcm_session` cookie. So a reload has nothing to restore from — the
- * silent-iframe and `/sso` paths find no IdP session and the session is lost.
- *
- * This primitive closes that gap. AFTER the claim has committed and the session
- * has been durably persisted, it performs ONE top-level establish hop through
- * the RP's own per-apex IdP host (`auth.<rp-apex>`), reusing the EXISTING
- * `/sso/establish` endpoint: the server mints a short-lived, host+audience-bound
- * establish-token and returns a fully-formed establish URL; navigating to it
- * plants the durable first-party `fedcm_session` cookie and bounces back to the
- * RP callback with an opaque code the standard `sso-return` cold-boot step
- * exchanges.
- *
- * It reuses the SAME per-origin `sessionStorage` bounce contract
- * (`ssoStateKey` / `ssoGuardKey` / `ssoDestKey`) that {@link buildSsoBounceUrl}
- * primes for the terminal `/sso` bounce, so the post-bounce `sso-return` step
- * (`consumeSsoReturn`) validates the CSRF `state`, exchanges the code, and
- * restores the user's real destination with no extra wiring.
- *
- * Contract:
- *  - WEB only — off-web / native it is a no-op returning `false`.
- *  - NEVER fires while sitting on the central IdP origin (that would loop the
- *    IdP against itself).
- *  - Bounce state is persisted ONLY after the establish-URL request succeeds, so
- *    a failed request leaves no stale state behind.
- *  - SINGLE attempt: the caller invokes this exactly once per successful claim.
- *    On ANY failure it does NOT navigate and returns `false`, leaving the
- *    committed in-memory session exactly as-is (the user is no worse off than
- *    before this hop existed).
- *  - Total: never throws. Failures are reported via {@link deps.onError} only.
- */
-/**
- * The minimal SDK surface this hop needs: mint a server-formed establish URL
- * bound to the caller's own session for an approved RP origin. Structural so the
- * primitive is unit-testable with a stub and never imports the full client.
- */
-export interface SsoEstablishClient {
-    requestSsoEstablishUrl(origin: string, state: string): Promise<{
-        establishUrl: string;
-    }>;
-}
-/**
- * Injectable web seams for {@link establishIdpSessionAfterClaim}. Every seam is
- * overridable so the primitive is fully unit-testable with fakes and so native
- * callers rely on the defaults (which resolve to `window.*` only when a browser
- * is present). Defaults are evaluated lazily inside the function so importing
- * this module never touches `window`.
- */
-export interface EstablishAfterClaimDeps {
-    /** Per-tab SSO bounce store. Default: `window.sessionStorage`. */
-    storage?: Pick<Storage, 'getItem' | 'setItem'>;
-    /** The current location. Default: `window.location`. */
-    location?: Pick<Location, 'origin' | 'href'>;
-    /** Top-level navigation seam. Default: {@link ssoNavigate} (`location.assign`). */
-    navigate?: (url: string) => void;
-    /**
-     * Whether the current environment is a web browser with usable
-     * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
-     * window.sessionStorage !== 'undefined'`.
-     */
-    isWeb?: () => boolean;
-    /** CSRF state generator. Default: {@link generateSsoState}. */
-    generateState?: () => string;
-    /** Epoch-ms clock for the bounce guard. Default: `Date.now`. */
-    now?: () => number;
-    /**
-     * Optional debug hook invoked with the thrown error when the establish
-     * request (or state persistence) fails. NEVER rethrown. Default: no-op.
-     */
-    onError?: (error: unknown) => void;
-}
-/**
- * Perform the post-claim establish hop. Returns `true` when a navigation to the
- * establish URL was initiated (the document is being torn down and replaced by
- * the IdP), `false` on every no-op / failure path.
- *
- * @param client - The exchange surface (`oxyServices.requestSsoEstablishUrl`).
- * @param deps - Injectable web seams; see {@link EstablishAfterClaimDeps}.
- */
-export declare function establishIdpSessionAfterClaim(client: SsoEstablishClient, deps?: EstablishAfterClaimDeps): Promise<boolean>;

package/dist/types/utils/ssoReturn.d.ts

@@ -1,146 +0,0 @@
-/**
- * Parse the SSO return fragment delivered by the central IdP.
- *
- * After a top-level redirect bounce to `auth.oxy.so/sso` (prompt=none), the
- * central IdP returns the Relying Party to its `redirect_uri` with the result
- * encoded in the URL fragment (the `#…` part). The fragment is used — not a
- * query string — so the opaque single-use code never reaches a server access
- * log, a `Referer` header, or browser history in a recoverable form.
- *
- * Three outcomes are possible:
- *   - `#oxy_sso=ok&code=<opaque>&state=<state>` — the IdP had a session; the RP
- *     exchanges `code` (via `oxy.exchangeSsoCode`) for the real session. NO
- *     token/JWT ever appears in the URL — only the opaque code.
- *   - `#oxy_sso=none&state=<state>` — the IdP had no session (prompt=none, user
- *     not signed in centrally). The RP shows its own signed-out UI.
- *   - `#oxy_sso=error&state=<state>` — the bounce failed. The RP recovers.
- *
- * This parser is pure and defensive: it never throws, and `kind` is strictly
- * one of `'ok' | 'none' | 'error'`. It returns `null` when the fragment is not
- * an oxy_sso fragment at all (i.e. `oxy_sso` is absent or an unrecognised
- * value), so the caller can ignore unrelated fragments without special-casing.
- */
-import type { SessionLoginResponse } from '../models/session';
-/**
- * The recognised outcomes of an SSO bounce.
- */
-export type SsoReturnKind = 'ok' | 'none' | 'error';
-/**
- * The parsed result of an SSO return fragment.
- *
- * `code` is present only for `kind: 'ok'`. `state` echoes the CSRF state the RP
- * generated for the bounce (when the IdP round-tripped it).
- */
-export interface SsoReturnResult {
-    kind: SsoReturnKind;
-    code?: string;
-    state?: string;
-}
-/**
- * Parse an SSO return fragment.
- *
- * @param hash - The URL fragment, with or without the leading `#`
- *   (e.g. `location.hash`). May be `undefined`/empty.
- * @returns The parsed result when `hash` is a recognised oxy_sso fragment,
- *   otherwise `null`. Never throws.
- */
-export declare function parseSsoReturnFragment(hash: string | undefined | null): SsoReturnResult | null;
-/**
- * Injectable dependencies for {@link consumeSsoReturn}.
- *
- * Every web seam (storage, location, history, web-detection) is injectable so
- * the function is fully unit-testable with fakes and so SSR / native callers
- * can supply their own (or rely on the defaults, which resolve to `window.*`
- * only when a browser is present). Defaults are evaluated lazily inside
- * `consumeSsoReturn` so importing this module never touches `window`.
- */
-export interface ConsumeSsoReturnDeps {
-    /** Per-tab SSO state store. Default: `window.sessionStorage`. */
-    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
-    /** The current location. Default: `window.location`. */
-    location?: Pick<Location, 'hash' | 'origin' | 'pathname' | 'search'>;
-    /** History API for fragment stripping / dest restore. Default: `window.history`. */
-    history?: Pick<History, 'replaceState'>;
-    /**
-     * Whether the current environment is a web browser with usable
-     * `sessionStorage`. Default: `typeof window !== 'undefined' && typeof
-     * window.sessionStorage !== 'undefined'`.
-     */
-    isWeb?: () => boolean;
-    /**
-     * Optional debug hook invoked with the thrown error when the code exchange
-     * fails. NEVER rethrown — `consumeSsoReturn` is total. Default: no-op.
-     */
-    onExchangeError?: (error: unknown) => void;
-    /**
-     * Notify URL-driven routers (Expo Router / React Navigation web) that the
-     * location changed via `history.replaceState`, which does NOT itself emit
-     * `popstate`. Default: dispatch a real `PopStateEvent` on `window` when
-     * present; no-op off-web. Called ONLY after a successful same-origin
-     * dest restore on the `ok` path (never when the dest is rejected/absent).
-     * NEVER throws.
-     */
-    dispatchPopState?: () => void;
-    /**
-     * Hard, full-document navigation used to leave the internal callback path on
-     * every NON-`ok` outcome (`none`/`error`, state-mismatch, missing code,
-     * failed exchange, missing sessionId). A SOFT `history.replaceState` +
-     * synthetic `popstate` does NOT reliably make Expo Router / TanStack Router
-     * re-resolve away from the 404 they have already rendered for the
-     * unregistered callback route — so for these outcomes (where there is no
-     * in-memory session to preserve) a full navigation is both safe and
-     * guaranteed to clear the 404. Default: `window.location.replace(url)` when
-     * present; feature-detected end to end so it never throws off-web.
-     */
-    hardRedirect?: (url: string) => void;
-}
-/**
- * Consume an SSO return: the commit-free, security-critical kernel of the
- * cross-domain SSO `sso-return` cold-boot step.
- *
- * This performs the CSRF/fragment/exchange/dest-restore/loop-breaker sequence
- * and RETURNS the exchanged session (or `null`). It deliberately does NOT
- * commit any UI/auth state — each provider commits its own way AROUND this
- * (e.g. `@oxyhq/services` `OxyContext` calls its `handleWebSSOSession`,
- * `@oxyhq/auth` `WebOxyProvider` updates its React state). Hoisting the kernel
- * here keeps the two providers byte-for-byte identical on the parts that matter
- * for security (state validation, fragment stripping order, loop prevention).
- *
- * Security/loop invariants (preserved exactly from both former copies):
- *   - The fragment is stripped via `history.replaceState` FIRST — before the
- *     exchange — so the opaque code never lingers in the URL, browser history,
- *     or a `Referer` header even if a later step throws.
- *   - `state` must match (CSRF). A mismatch or a missing code sets the
- *     NO_SESSION flag so `sso-bounce` is disabled (no rebounce loop).
- *   - `none`/`error` outcomes set BOTH the NO_SESSION flag and the
- *     outcome-independent attempted-flag (the load2 half of the loop proof).
- *   - A throwing exchange is caught, reported via `onExchangeError`, and
- *     treated exactly like "no session" (never loops, never rethrows).
- *   - On EVERY consumed outcome (ok, none, error, state-mismatch, no-code,
- *     failed-exchange, no-sessionId) — not just ok — if the page landed on
- *     {@link SSO_CALLBACK_PATH}, the user is taken to a same-origin TARGET so
- *     they are never stranded on the internal callback path (which is an
- *     unregistered route in every consumer router → a hard 404). The target is
- *     the stored DEST when it parses as same-origin (an attacker-planted
- *     cross-origin / protocol-relative dest is rejected), ELSE the app root
- *     (`origin + '/'`). The DEST key is removed unconditionally.
- *   - For the `ok` outcome the target is applied via a SOFT
- *     `history.replaceState` + synthetic `popstate` so the freshly exchanged
- *     in-memory session the provider is about to commit is preserved (no
- *     reload). `popstate` is dispatched only on the `ok` same-origin restore.
- *   - For every NON-`ok` outcome there is no in-memory session to preserve, and
- *     the consumer router has ALREADY synchronously rendered its 404 for the
- *     unregistered callback route — a soft replaceState+popstate does not
- *     reliably make it re-resolve. So these outcomes perform a HARD
- *     full-document navigation to the target (`hardRedirect`), which is both
- *     safe (nothing to lose) and guaranteed to clear the 404 in every router.
- *
- * Total: this function NEVER throws. Off-web it is a no-op returning `null`.
- *
- * @param oxy - The exchange surface (`oxyServices.exchangeSsoCode`).
- * @param deps - Injectable web seams; see {@link ConsumeSsoReturnDeps}.
- * @returns The exchanged session on success, otherwise `null`.
- */
-export declare function consumeSsoReturn(oxy: {
-    exchangeSsoCode: (code: string, state?: string) => Promise<SessionLoginResponse>;
-}, deps?: ConsumeSsoReturnDeps): Promise<SessionLoginResponse | null>;