@oxyhq/core 5.5.0 → 7.0.0

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/fapiAutoDetect.d.ts

@@ -1,56 +0,0 @@
-/**
- * Auto-detect the FAPI (IdP) URL from the current browser hostname.
- *
- * This is the canonical cross-domain IdP-resolution primitive for the Oxy
- * ecosystem. Both candidate cross-domain SSO designs derive `auth.<rp-apex>`
- * through this helper; do not fork it.
- *
- * Clerk-style multi-domain SSO depends on the IdP being reachable on a
- * subdomain of the RP's own apex (e.g. `auth.mention.earth` CNAMEd to the
- * central Oxy IdP). That way every FedCM endpoint, the session cookie,
- * and any redirect target are same-site with the RP — the only way
- * to get first-party cookies in Safari ITP and Firefox Total Cookie
- * Protection.
- *
- * This helper computes `https://auth.<rp-apex>` from
- * `window.location.hostname` so a consuming app doesn't have to pass
- * `authWebUrl` explicitly. Returns `undefined` for environments where
- * auto-detection would be wrong:
- *
- *   - SSR / non-browser (no `window`).
- *   - `localhost`, `127.0.0.1`, IPv4/IPv6 literals.
- *   - Hostnames with fewer than two labels.
- *   - Hostnames where a registrable domain cannot be determined from the
- *     Public Suffix List, including private hosted suffixes such as
- *     `github.io`, `pages.dev`, and `netlify.app`.
- *
- * When the page is already loaded ON the IdP itself (`auth.<anything>`),
- * the helper returns the current origin so the SDK keeps everything
- * same-origin instead of hopping to a different IdP host.
- *
- * The IdP backend independently derives `iss`, `provider_urls`, and the
- * `fedcm.json` icon URLs from the request host
- * (`packages/auth/server/index.ts`), so an honest CNAME pair is all that
- * is required for end-to-end FedCM correctness — no per-RP config.
- */
-/**
- * Compute the bare registrable apex (eTLD+1) of a hostname using the Public
- * Suffix List, including private hosted suffixes.
- *
- * This is the pure host-handling kernel shared by {@link autoDetectAuthWebUrl}
- * and the IdP worker — it performs NO protocol handling, NO `auth.` prefixing,
- * and builds NO URL. It only answers "what is the registrable domain of this
- * host, or is that undefinable?".
- *
- * Returns `null` (apex undefinable) for:
- *   - empty input;
- *   - IPv4 literals (`192.168.1.10`);
- *   - IPv6 literals or any host carrying a port (`[::1]`, anything with `:`);
- *   - single-label hosts (`intranet`, `localhost`);
- *   - public suffixes without a registrable label (e.g. `co.uk`, `github.io`).
- *
- * @param hostname - A bare hostname (no scheme), e.g. `www.mention.earth`.
- * @returns The eTLD+1 (`mention.earth`), or `null` when undefinable.
- */
-export declare function registrableApex(hostname: string): string | null;
-export declare function autoDetectAuthWebUrl(location?: Pick<Location, 'hostname' | 'protocol'> | undefined): string | undefined;

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,156 +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). `reason` is present
- * only for a NON-`ok` outcome when the IdP supplied one.
- */
-export interface SsoReturnResult {
-    kind: SsoReturnKind;
-    code?: string;
-    state?: string;
-    /**
-     * Machine-readable reason accompanying a NON-`ok` outcome, when the central
-     * IdP supplies one (e.g. `no_cookie` | `stale_session` | `no_grant` |
-     * `no_grant_establish` on a `none` bounce). Purely informational: it lets a
-     * Relying Party surface WHY a silent probe returned no session (e.g. to brand
-     * a "sign in" screen) without re-deriving it. Absent on `ok`, and whenever the
-     * IdP did not include a `reason` param.
-     */
-    reason?: 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>;