@iqauth/sdk 2.0.0

package/dist/service.mjs

@@ -0,0 +1,25 @@
+import {
+  IQAuthClient
+} from "./chunk-JQWYIIIS.mjs";
+import {
+  ErrorCodes,
+  IQAuthError
+} from "./chunk-6I6RM4MN.mjs";
+import "./chunk-Y6FXYEAI.mjs";
+
+// src/service.ts
+var ServiceIQAuthClient = class extends IQAuthClient {
+  constructor(config) {
+    super({ ...config, environment: "service" });
+  }
+};
+function createServiceClient(config) {
+  return new ServiceIQAuthClient(config);
+}
+export {
+  ErrorCodes,
+  IQAuthClient,
+  IQAuthError,
+  ServiceIQAuthClient,
+  createServiceClient
+};

package/dist/signIn-C8f6qVjD.d.mts

@@ -0,0 +1,238 @@
+import { b as ParsedPublishableKey } from './publishableKey-B5DIK81A.mjs';
+import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.mjs';
+
+/**
+ * SessionManager — core browser-side session state.
+ *
+ * Responsibilities:
+ *   - Hold the in-memory access token and decoded user claims.
+ *   - Coordinate token refresh as a single-flight promise (concurrent fetches
+ *     wait on the same refresh).
+ *   - Synchronize session state across tabs in the same origin via
+ *     BroadcastChannel.
+ *   - Provide an `auth.fetch()` style helper that auto-attaches the access
+ *     token and retries once on 401/TOKEN_EXPIRED.
+ *
+ * Storage:
+ *   - Access token + claims live in memory only.
+ *   - Refresh token lives in a first-party cookie (`iqauth_rt`). Sent to the
+ *     refresh endpoint via `credentials: "include"` and as a JSON body.
+ */
+
+type SessionStatus = "loading" | "authenticated" | "unauthenticated";
+/**
+ * Pluggable refresh-token storage. Apps that own a backend can pass a
+ * delegate that POSTs the refresh token to a server route which sets an
+ * httpOnly first-party cookie (the Phase D backend middleware does this
+ * automatically). When unset, the SDK falls back to a JS-readable
+ * first-party cookie — convenient for browser-only apps but not as resistant
+ * to XSS exfiltration.
+ */
+interface RefreshTokenStore {
+    read(): string | null | Promise<string | null>;
+    write(token: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+interface SessionSnapshot {
+    status: SessionStatus;
+    accessToken: string | null;
+    user: SessionUser | null;
+    claims: JwtClaims | null;
+    tenantId: string | null;
+    /** Last error encountered during bootstrap/refresh. Cleared on success. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** Monotonically increasing version; bumped on every state change. */
+    version: number;
+}
+interface SessionManagerOptions {
+    publishableKey: string;
+    /**
+     * Override the IQAuth issuer URL. Inferred from the publishable key when
+     * omitted. Useful for tests or staging shards.
+     */
+    issuer?: string;
+    /** BroadcastChannel name; defaults to `iqauth.<appId>`. */
+    channelName?: string;
+    /** When true, proactively refresh ~60s before access token expiry. */
+    proactiveRefresh?: boolean;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`. Tests
+     * inject a mock here.
+     */
+    fetchImpl?: typeof fetch;
+    /** Optional override for the refresh endpoint path. */
+    refreshPath?: string;
+    /** Optional override for the userinfo endpoint path. */
+    userinfoPath?: string;
+    /** Set to false to disable cookie writes (refresh token kept in memory). */
+    useCookies?: boolean;
+    /**
+     * Custom refresh-token storage. Use this to delegate cookie management to
+     * the app's backend (so the cookie can be httpOnly). Defaults to a
+     * JS-readable first-party cookie.
+     */
+    tokenStore?: RefreshTokenStore;
+    /**
+     * Soft cap (ms) on how long a tab will wait for another tab's in-flight
+     * refresh to finish before falling back to its own. Defaults to 4000.
+     */
+    crossTabLockTimeoutMs?: number;
+}
+declare class SessionManager {
+    private snapshot;
+    private listeners;
+    private refreshPromise;
+    private channel;
+    private readonly tabId;
+    private readonly fetchImpl;
+    private readonly key;
+    private readonly issuer;
+    private readonly refreshPath;
+    private readonly userinfoPath;
+    private readonly useCookies;
+    private readonly proactiveRefresh;
+    private readonly tokenStore;
+    private readonly crossTabLockTimeoutMs;
+    private proactiveTimer;
+    private bootstrapped;
+    /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */
+    private remoteRefreshWaiters;
+    /** Active claims by other tabs (keyed by source tabId). */
+    private foreignClaim;
+    constructor(options: SessionManagerOptions);
+    get publishableKey(): ParsedPublishableKey;
+    get appKey(): string;
+    get tenantIdFromKey(): string;
+    get issuerUrl(): string;
+    getSnapshot(): SessionSnapshot;
+    subscribe(listener: (s: SessionSnapshot) => void): () => void;
+    /**
+     * One-time bootstrap: warm the session from the refresh cookie if present.
+     * Safe to call multiple times.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Single-flight token refresh, coordinated across tabs via BroadcastChannel.
+     *
+     * Per-tab: concurrent callers share the same `refreshPromise`.
+     * Cross-tab: a tab that wants to refresh first broadcasts a `refresh:claim`
+     * with its tabId + timestamp. If it has already received a competing claim
+     * with an earlier timestamp (or lower tabId on tie), it waits for that
+     * tab's `refresh:done` message instead of issuing its own HTTP request.
+     * This prevents two tabs racing on rotating refresh tokens, which would
+     * invalidate the session.
+     */
+    refresh(): Promise<boolean>;
+    private runRefresh;
+    private claimWins;
+    private waitForForeignRefresh;
+    /**
+     * Apply an access token (e.g. fresh from a callback exchange) to the
+     * session and notify subscribers and other tabs.
+     */
+    applyAccessToken(accessToken: string, refreshToken?: string): void;
+    /**
+     * Returns a valid access token, refreshing once if it is expired or about
+     * to expire. Resolves to `null` if the session can no longer be revived.
+     */
+    getToken(): Promise<string | null>;
+    /**
+     * Browser-safe HTTP wrapper. Attaches the current access token and retries
+     * once on 401 (refreshing in between). Rejects with an `IQAuthError` on
+     * the second 401 — the caller is then responsible for redirecting to
+     * sign-in (typically by letting the unauthenticated state surface through
+     * `<SignedOut/>`).
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Clear the session locally and broadcast a sign-out to other tabs. Does
+     * not call the server — callers (e.g. signOut helper) are responsible for
+     * the server-side logout request.
+     */
+    signOutLocal(status?: SessionStatus): void;
+    destroy(): void;
+    private setStatus;
+    private setError;
+    private update;
+    private isTokenExpiringSoon;
+    private scheduleProactiveRefresh;
+    private broadcast;
+    private broadcastEnvelope;
+    private onBroadcast;
+}
+
+/**
+ * Sign-in / sign-out / callback helpers that build on top of the
+ * SessionManager. These are usable both from React (via the hook helpers in
+ * `@iqauth/sdk/react`) and from plain JS / non-React UIs.
+ */
+
+interface SignInOptions {
+    /**
+     * Where the user should land after signing in. Defaults to the current
+     * `window.location.href`.
+     */
+    returnTo?: string;
+    /** Path on the IQAuth host that renders the hosted login UI. */
+    signInPath?: string;
+    /**
+     * Where the IQAuth host should redirect the browser back to once login
+     * completes. Defaults to `<origin>/auth/callback` and **must** be
+     * registered as an allowed redirect URI for the app.
+     */
+    redirectUri?: string;
+    /** Extra OIDC scopes beyond `openid` to request. */
+    scope?: string;
+}
+interface SignOutOptions {
+    /** Where to send the user after sign out. Defaults to the current page. */
+    returnTo?: string;
+    /** Path on the IQAuth host for the logout endpoint. */
+    logoutPath?: string;
+    /** Skip the network call to IQAuth and just clear the local session. */
+    localOnly?: boolean;
+}
+interface CallbackResult {
+    ok: boolean;
+    returnTo: string;
+    error?: string;
+}
+/**
+ * Build the hosted sign-in URL with PKCE + state, persist the PKCE record,
+ * and return the URL. The caller is responsible for redirecting; for the
+ * common case use {@link redirectToSignIn}.
+ */
+declare function buildSignInUrl(manager: SessionManager, opts?: SignInOptions): Promise<string>;
+declare function redirectToSignIn(manager: SessionManager, opts?: SignInOptions): Promise<void>;
+/**
+ * Convenience wrapper used by `useAuth().signIn()`. Identical to
+ * {@link redirectToSignIn} but accepts the same shape as Clerk's
+ * `signIn({ redirectUrl })`.
+ */
+declare function signIn(manager: SessionManager, opts?: SignInOptions): Promise<void>;
+/**
+ * Exchange the authorization code from the callback URL for tokens and seed
+ * the session manager. Returns a {@link CallbackResult} describing where the
+ * caller should navigate next.
+ *
+ * Typical usage in an SPA route handler:
+ * ```tsx
+ * const res = await handleAuthCallback(manager);
+ * window.location.replace(res.returnTo);
+ * ```
+ */
+declare function handleAuthCallback(manager: SessionManager, options?: {
+    url?: string;
+    tokenPath?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<CallbackResult>;
+/**
+ * Clear the local session, ask IQAuth to revoke the refresh token, and
+ * optionally redirect.
+ */
+declare function signOut(manager: SessionManager, opts?: SignOutOptions): Promise<void>;
+
+export { type CallbackResult as C, SessionManager as S, type SessionSnapshot as a, type SignInOptions as b, type SignOutOptions as c, type SessionManagerOptions as d, type SessionStatus as e, buildSignInUrl as f, signOut as g, handleAuthCallback as h, redirectToSignIn as r, signIn as s };

package/dist/signIn-Cy2lbEXb.d.ts

@@ -0,0 +1,238 @@
+import { b as ParsedPublishableKey } from './publishableKey-B5DIK81A.js';
+import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.js';
+
+/**
+ * SessionManager — core browser-side session state.
+ *
+ * Responsibilities:
+ *   - Hold the in-memory access token and decoded user claims.
+ *   - Coordinate token refresh as a single-flight promise (concurrent fetches
+ *     wait on the same refresh).
+ *   - Synchronize session state across tabs in the same origin via
+ *     BroadcastChannel.
+ *   - Provide an `auth.fetch()` style helper that auto-attaches the access
+ *     token and retries once on 401/TOKEN_EXPIRED.
+ *
+ * Storage:
+ *   - Access token + claims live in memory only.
+ *   - Refresh token lives in a first-party cookie (`iqauth_rt`). Sent to the
+ *     refresh endpoint via `credentials: "include"` and as a JSON body.
+ */
+
+type SessionStatus = "loading" | "authenticated" | "unauthenticated";
+/**
+ * Pluggable refresh-token storage. Apps that own a backend can pass a
+ * delegate that POSTs the refresh token to a server route which sets an
+ * httpOnly first-party cookie (the Phase D backend middleware does this
+ * automatically). When unset, the SDK falls back to a JS-readable
+ * first-party cookie — convenient for browser-only apps but not as resistant
+ * to XSS exfiltration.
+ */
+interface RefreshTokenStore {
+    read(): string | null | Promise<string | null>;
+    write(token: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+interface SessionSnapshot {
+    status: SessionStatus;
+    accessToken: string | null;
+    user: SessionUser | null;
+    claims: JwtClaims | null;
+    tenantId: string | null;
+    /** Last error encountered during bootstrap/refresh. Cleared on success. */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** Monotonically increasing version; bumped on every state change. */
+    version: number;
+}
+interface SessionManagerOptions {
+    publishableKey: string;
+    /**
+     * Override the IQAuth issuer URL. Inferred from the publishable key when
+     * omitted. Useful for tests or staging shards.
+     */
+    issuer?: string;
+    /** BroadcastChannel name; defaults to `iqauth.<appId>`. */
+    channelName?: string;
+    /** When true, proactively refresh ~60s before access token expiry. */
+    proactiveRefresh?: boolean;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`. Tests
+     * inject a mock here.
+     */
+    fetchImpl?: typeof fetch;
+    /** Optional override for the refresh endpoint path. */
+    refreshPath?: string;
+    /** Optional override for the userinfo endpoint path. */
+    userinfoPath?: string;
+    /** Set to false to disable cookie writes (refresh token kept in memory). */
+    useCookies?: boolean;
+    /**
+     * Custom refresh-token storage. Use this to delegate cookie management to
+     * the app's backend (so the cookie can be httpOnly). Defaults to a
+     * JS-readable first-party cookie.
+     */
+    tokenStore?: RefreshTokenStore;
+    /**
+     * Soft cap (ms) on how long a tab will wait for another tab's in-flight
+     * refresh to finish before falling back to its own. Defaults to 4000.
+     */
+    crossTabLockTimeoutMs?: number;
+}
+declare class SessionManager {
+    private snapshot;
+    private listeners;
+    private refreshPromise;
+    private channel;
+    private readonly tabId;
+    private readonly fetchImpl;
+    private readonly key;
+    private readonly issuer;
+    private readonly refreshPath;
+    private readonly userinfoPath;
+    private readonly useCookies;
+    private readonly proactiveRefresh;
+    private readonly tokenStore;
+    private readonly crossTabLockTimeoutMs;
+    private proactiveTimer;
+    private bootstrapped;
+    /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */
+    private remoteRefreshWaiters;
+    /** Active claims by other tabs (keyed by source tabId). */
+    private foreignClaim;
+    constructor(options: SessionManagerOptions);
+    get publishableKey(): ParsedPublishableKey;
+    get appKey(): string;
+    get tenantIdFromKey(): string;
+    get issuerUrl(): string;
+    getSnapshot(): SessionSnapshot;
+    subscribe(listener: (s: SessionSnapshot) => void): () => void;
+    /**
+     * One-time bootstrap: warm the session from the refresh cookie if present.
+     * Safe to call multiple times.
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Single-flight token refresh, coordinated across tabs via BroadcastChannel.
+     *
+     * Per-tab: concurrent callers share the same `refreshPromise`.
+     * Cross-tab: a tab that wants to refresh first broadcasts a `refresh:claim`
+     * with its tabId + timestamp. If it has already received a competing claim
+     * with an earlier timestamp (or lower tabId on tie), it waits for that
+     * tab's `refresh:done` message instead of issuing its own HTTP request.
+     * This prevents two tabs racing on rotating refresh tokens, which would
+     * invalidate the session.
+     */
+    refresh(): Promise<boolean>;
+    private runRefresh;
+    private claimWins;
+    private waitForForeignRefresh;
+    /**
+     * Apply an access token (e.g. fresh from a callback exchange) to the
+     * session and notify subscribers and other tabs.
+     */
+    applyAccessToken(accessToken: string, refreshToken?: string): void;
+    /**
+     * Returns a valid access token, refreshing once if it is expired or about
+     * to expire. Resolves to `null` if the session can no longer be revived.
+     */
+    getToken(): Promise<string | null>;
+    /**
+     * Browser-safe HTTP wrapper. Attaches the current access token and retries
+     * once on 401 (refreshing in between). Rejects with an `IQAuthError` on
+     * the second 401 — the caller is then responsible for redirecting to
+     * sign-in (typically by letting the unauthenticated state surface through
+     * `<SignedOut/>`).
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Clear the session locally and broadcast a sign-out to other tabs. Does
+     * not call the server — callers (e.g. signOut helper) are responsible for
+     * the server-side logout request.
+     */
+    signOutLocal(status?: SessionStatus): void;
+    destroy(): void;
+    private setStatus;
+    private setError;
+    private update;
+    private isTokenExpiringSoon;
+    private scheduleProactiveRefresh;
+    private broadcast;
+    private broadcastEnvelope;
+    private onBroadcast;
+}
+
+/**
+ * Sign-in / sign-out / callback helpers that build on top of the
+ * SessionManager. These are usable both from React (via the hook helpers in
+ * `@iqauth/sdk/react`) and from plain JS / non-React UIs.
+ */
+
+interface SignInOptions {
+    /**
+     * Where the user should land after signing in. Defaults to the current
+     * `window.location.href`.
+     */
+    returnTo?: string;
+    /** Path on the IQAuth host that renders the hosted login UI. */
+    signInPath?: string;
+    /**
+     * Where the IQAuth host should redirect the browser back to once login
+     * completes. Defaults to `<origin>/auth/callback` and **must** be
+     * registered as an allowed redirect URI for the app.
+     */
+    redirectUri?: string;
+    /** Extra OIDC scopes beyond `openid` to request. */
+    scope?: string;
+}
+interface SignOutOptions {
+    /** Where to send the user after sign out. Defaults to the current page. */
+    returnTo?: string;
+    /** Path on the IQAuth host for the logout endpoint. */
+    logoutPath?: string;
+    /** Skip the network call to IQAuth and just clear the local session. */
+    localOnly?: boolean;
+}
+interface CallbackResult {
+    ok: boolean;
+    returnTo: string;
+    error?: string;
+}
+/**
+ * Build the hosted sign-in URL with PKCE + state, persist the PKCE record,
+ * and return the URL. The caller is responsible for redirecting; for the
+ * common case use {@link redirectToSignIn}.
+ */
+declare function buildSignInUrl(manager: SessionManager, opts?: SignInOptions): Promise<string>;
+declare function redirectToSignIn(manager: SessionManager, opts?: SignInOptions): Promise<void>;
+/**
+ * Convenience wrapper used by `useAuth().signIn()`. Identical to
+ * {@link redirectToSignIn} but accepts the same shape as Clerk's
+ * `signIn({ redirectUrl })`.
+ */
+declare function signIn(manager: SessionManager, opts?: SignInOptions): Promise<void>;
+/**
+ * Exchange the authorization code from the callback URL for tokens and seed
+ * the session manager. Returns a {@link CallbackResult} describing where the
+ * caller should navigate next.
+ *
+ * Typical usage in an SPA route handler:
+ * ```tsx
+ * const res = await handleAuthCallback(manager);
+ * window.location.replace(res.returnTo);
+ * ```
+ */
+declare function handleAuthCallback(manager: SessionManager, options?: {
+    url?: string;
+    tokenPath?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<CallbackResult>;
+/**
+ * Clear the local session, ask IQAuth to revoke the refresh token, and
+ * optionally redirect.
+ */
+declare function signOut(manager: SessionManager, opts?: SignOutOptions): Promise<void>;
+
+export { type CallbackResult as C, SessionManager as S, type SessionSnapshot as a, type SignInOptions as b, type SignOutOptions as c, type SessionManagerOptions as d, type SessionStatus as e, buildSignInUrl as f, signOut as g, handleAuthCallback as h, redirectToSignIn as r, signIn as s };