@iqauth/sdk 2.2.0 → 2.5.0

package/dist/{signIn-BVDTIA_t.d.ts → signIn-OCr88Zf8.d.ts}

@@ -1,5 +1,5 @@
 import { c as ParsedPublishableKey } from './publishableKey-BaR0HoAH.js';
-import { d as SessionUser, J as JwtClaims } from './types-Cxl3bQHt.js';
+import { J as JwtClaims, d as SessionUser } from './types-DZAflmmq.js';
 
 /**
  * SessionManager — core browser-side session state.
@@ -28,9 +28,17 @@ type SessionStatus = "loading" | "authenticated" | "unauthenticated";
  * first-party cookie — convenient for browser-only apps but not as resistant
  * to XSS exfiltration.
  */
+/**
+ * Optional context handed to `RefreshTokenStore.write`. Multi-account stores
+ * use it to route the token to the correct per-account cookie when no
+ * "active" account is set yet (i.e. immediately after `addAccount()`).
+ */
+interface RefreshTokenWriteContext {
+    claims?: JwtClaims | null;
+}
 interface RefreshTokenStore {
     read(): string | null | Promise<string | null>;
-    write(token: string): void | Promise<void>;
+    write(token: string, ctx?: RefreshTokenWriteContext): void | Promise<void>;
     clear(): void | Promise<void>;
 }
 interface SessionSnapshot {
@@ -101,6 +109,17 @@ interface SessionManagerOptions {
      * Defaults to `false` to preserve pre-2.0.3 behavior.
      */
     serverManagedSession?: boolean;
+    /**
+     * F14 — Override the names of the cookies the SDK reads/writes. Useful when
+     * a host app already uses `iqauth_rt`/`iqauth_at` for an unrelated purpose
+     * or wants to prefix all SDK cookies. Only the `refresh` cookie is written
+     * by the browser SDK directly; `access` is for parity with the backend
+     * helpers/middleware which read it via the same umbrella option.
+     */
+    cookieNames?: {
+        refresh?: string;
+        access?: string;
+    };
 }
 declare class SessionManager {
     private snapshot;
@@ -115,9 +134,10 @@ declare class SessionManager {
     private readonly userinfoPath;
     private readonly useCookies;
     private readonly proactiveRefresh;
-    private readonly tokenStore;
+    private tokenStore;
     private readonly crossTabLockTimeoutMs;
     private readonly serverManagedSession;
+    private readonly refreshCookieName;
     private proactiveTimer;
     private bootstrapped;
     /** Pending refresh awaited by other tabs after a `refresh:claim` from us. */
@@ -129,6 +149,8 @@ declare class SessionManager {
     get appKey(): string;
     get tenantIdFromKey(): string;
     get issuerUrl(): string;
+    /** Cookie name the SDK uses for the refresh token (overridable via `cookieNames.refresh`). */
+    get refreshCookie(): string;
     getSnapshot(): SessionSnapshot;
     subscribe(listener: (s: SessionSnapshot) => void): () => void;
     /**
@@ -175,6 +197,12 @@ declare class SessionManager {
      * the server-side logout request.
      */
     signOutLocal(status?: SessionStatus): void;
+    /**
+     * Replace the refresh-token store at runtime. Used by the F22
+     * `<MultisessionAppSupport>` wrapper to swap in a `MultiAccountTokenStore`
+     * after the manager has already been constructed by `<IQAuthProvider>`.
+     */
+    setTokenStore(store: RefreshTokenStore): void;
     destroy(): void;
     private setStatus;
     private setError;
@@ -186,6 +214,180 @@ declare class SessionManager {
     private onBroadcast;
 }
 
+/**
+ * Passwordless helpers (Task #91 / F24/F25/F31). Browser-only — these wrap
+ * the issuer's `/api/v1/auth/{magic-link,passkeys,identities}` routes so
+ * non-React consumers (vanilla JS, Vue, Svelte) can integrate without
+ * pulling in framework code. React consumers should prefer the hooks
+ * exported from `@iqauth/sdk/react`.
+ *
+ * All calls use `credentials: "include"` so the issuer can promote the
+ * minted session to httpOnly cookies (`iqauth_at` / `iqauth_rt`) when
+ * the caller forwards the `x-iqauth-session: cookie` header.
+ *
+ * `iqAuthBaseUrl` is the issuer URL (e.g. https://auth.example.com); it
+ * must NOT end with a slash.
+ */
+type PasswordlessOptions = {
+    iqAuthBaseUrl: string;
+    /** When true (default), tells the issuer to set httpOnly cookies on success. */
+    cookieSession?: boolean;
+};
+type MagicLinkRequestInput = {
+    email: string;
+    /** App identifier — accepts the app id, key, or omitted for global links. */
+    appId?: string;
+    redirectUri: string;
+};
+declare function requestMagicLink(opts: PasswordlessOptions, input: MagicLinkRequestInput): Promise<{
+    ok: true;
+}>;
+declare function verifyMagicLink(opts: PasswordlessOptions, token: string): Promise<{
+    accessToken?: string;
+    user?: unknown;
+    redirectUri?: string;
+}>;
+type PasskeyAuthInput = {
+    email?: string;
+};
+declare function beginPasskeyAuthentication(opts: PasswordlessOptions, input?: PasskeyAuthInput): Promise<unknown>;
+declare function finishPasskeyAuthentication(opts: PasswordlessOptions, response: unknown): Promise<unknown>;
+declare function beginPasskeyRegistration(opts: PasswordlessOptions): Promise<unknown>;
+declare function finishPasskeyRegistration(opts: PasswordlessOptions, response: unknown, name?: string): Promise<unknown>;
+/**
+ * End-to-end passkey sign-in convenience. Loads `@simplewebauthn/browser` on
+ * demand (peer dependency) so callers that never use passkeys don't pay the
+ * bundle cost.
+ */
+declare function signInWithPasskey(opts: PasswordlessOptions, input?: PasskeyAuthInput): Promise<unknown>;
+declare function enrollPasskey(opts: PasswordlessOptions, name?: string): Promise<unknown>;
+type LinkedIdentity = {
+    id: string;
+    provider: string;
+    providerUserId: string | null;
+    linkedAt: string;
+    label?: string | null;
+    name?: string | null;
+    canUnlink: boolean;
+};
+declare function listLinkedIdentities(opts: PasswordlessOptions): Promise<LinkedIdentity[]>;
+type LinkProviderInput = {
+    provider: "google";
+    idToken: string;
+    reauth: {
+        password?: string;
+    };
+} | {
+    provider: string;
+    opaque: {
+        providerUserId: string;
+        verifiedBy: string;
+    };
+    reauth: {
+        password?: string;
+    };
+};
+declare function linkProvider(opts: PasswordlessOptions, input: LinkProviderInput): Promise<{
+    ok: true;
+}>;
+type UnlinkProviderInput = {
+    provider: string;
+    reauth: {
+        password?: string;
+    };
+};
+declare function unlinkProvider(opts: PasswordlessOptions, input: UnlinkProviderInput): Promise<{
+    ok: true;
+}>;
+
+/**
+ * Browser-only storage helpers used by the SessionManager.
+ *
+ * Storage strategy (Phase B):
+ *   - Access token: in memory only (held by SessionManager).
+ *   - Refresh token: first-party cookie on the app's own domain. The cookie
+ *     is set by the SDK callback handler and cleared on signOut.
+ *
+ * NOTE: Cookies set from JS cannot be httpOnly. Phase D (cookie-aware
+ * middleware) will move refresh-token cookie management into the app's
+ * backend so it can be httpOnly. Until then, the SDK uses a `Secure`,
+ * `SameSite=Lax` first-party cookie as a pragmatic stopgap. Nothing
+ * privileged ever lives in localStorage.
+ */
+declare const REFRESH_COOKIE = "iqauth_rt";
+interface CookieOptions {
+    maxAgeSeconds?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: "lax" | "strict" | "none";
+}
+declare function setCookie(name: string, value: string, opts?: CookieOptions): void;
+declare function getCookie(name: string): string | null;
+declare function clearCookie(name: string, opts?: CookieOptions): void;
+
+/**
+ * F22 — Multi-account registry.
+ *
+ * Persists the set of accounts currently signed in to a given app (keyed by
+ * the app's publishableKey appId) plus which one is "active". Each account
+ * stores a single per-account refresh cookie named `iqauth_rt_<accountId>`
+ * (where `accountId` is the user's `sub` claim), so SessionManager can
+ * pivot to any account by reading a different cookie + calling refresh().
+ *
+ * NOTE: We deliberately do NOT store refresh tokens in localStorage — they
+ * stay in cookies (same security posture as the single-account default).
+ * localStorage holds only public profile data + ordering metadata.
+ */
+
+interface AccountRecord {
+    accountId: string;
+    userId: string;
+    email: string;
+    name: string;
+    tenantId: string | null;
+    addedAt: number;
+}
+declare class AccountRegistry {
+    private readonly appId;
+    private listeners;
+    private storageHandler;
+    constructor(appId: string);
+    destroy(): void;
+    list(): AccountRecord[];
+    active(): string | null;
+    get(accountId: string): AccountRecord | null;
+    upsert(rec: AccountRecord): void;
+    setActive(accountId: string | null): void;
+    remove(accountId: string): void;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Read the refresh token for a specific account from its per-account
+     * cookie. Used by `MultiAccountTokenStore.read()`.
+     */
+    readRefreshToken(accountId: string): string | null;
+    /**
+     * Persist a refresh token to the per-account cookie. Caller is the
+     * SessionManager via `MultiAccountTokenStore.write()`.
+     */
+    writeRefreshToken(accountId: string, token: string, opts?: CookieOptions): void;
+    clearRefreshToken(accountId: string): void;
+    private notify;
+}
+/**
+ * RefreshTokenStore that reads/writes the active account's per-account
+ * cookie. Falls back to a configurable single-account store when no active
+ * account is set (e.g. before the first sign-in completes).
+ */
+declare class MultiAccountTokenStore implements RefreshTokenStore {
+    private readonly registry;
+    private readonly fallback;
+    constructor(registry: AccountRegistry, fallback: RefreshTokenStore);
+    read(): string | null | Promise<string | null>;
+    write(token: string, ctx?: RefreshTokenWriteContext): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+
 /**
  * Sign-in / sign-out / callback helpers that build on top of the
  * SessionManager. These are usable both from React (via the hook helpers in
@@ -208,6 +410,20 @@ interface SignInOptions {
     redirectUri?: string;
     /** Extra OIDC scopes beyond `openid` to request. */
     scope?: string;
+    /**
+     * F14 — Override SDK cookie names. `refresh` controls where the JS
+     * fallback writes the refresh token after the callback exchange.
+     */
+    cookieNames?: {
+        refresh?: string;
+    };
+    /**
+     * OIDC `prompt` parameter. `"login"` forces the IQAuth host to show the
+     * sign-in form even if a single-sign-on session already exists — used by
+     * the multi-account `addAccount()` helper to add a second account in
+     * parallel rather than re-using the active session.
+     */
+    prompt?: "login" | "none" | "consent" | "select_account";
 }
 interface SignOutOptions {
     /** Where to send the user after sign out. Defaults to the current page. */
@@ -216,6 +432,14 @@ interface SignOutOptions {
     logoutPath?: string;
     /** Skip the network call to IQAuth and just clear the local session. */
     localOnly?: boolean;
+    /**
+     * Also clear the IQAuth single-sign-on session (the `iq_sso` cookie on the
+     * issuer host). When `true` (the default), the next visit to `/sign-in`
+     * will show the login form instead of silently resuming the prior session.
+     * Set to `false` to preserve SSO across other apps in the same IQAuth
+     * tenant (e.g. log out of one app but stay signed in to others).
+     */
+    endSsoSession?: boolean;
 }
 interface CallbackResult {
     ok: boolean;
@@ -250,6 +474,10 @@ declare function handleAuthCallback(manager: SessionManager, options?: {
     url?: string;
     tokenPath?: string;
     fetchImpl?: typeof fetch;
+    /** F14 — refresh-cookie name override (defaults to `manager.refreshCookie`). */
+    cookieNames?: {
+        refresh?: string;
+    };
 }): Promise<CallbackResult>;
 /**
  * Clear the local session, ask IQAuth to revoke the refresh token, and
@@ -257,4 +485,4 @@ declare function handleAuthCallback(manager: SessionManager, options?: {
  */
 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 };
+export { AccountRegistry as A, clearCookie as B, type CallbackResult as C, getCookie as D, setCookie as E, type LinkedIdentity as L, type MagicLinkRequestInput as M, type PasswordlessOptions as P, type RefreshTokenStore as R, SessionManager as S, type UnlinkProviderInput as U, type SessionManagerOptions as a, type SessionSnapshot as b, type SessionStatus as c, beginPasskeyAuthentication as d, beginPasskeyRegistration as e, finishPasskeyAuthentication as f, finishPasskeyRegistration as g, enrollPasskey as h, linkProvider as i, type PasskeyAuthInput as j, type LinkProviderInput as k, listLinkedIdentities as l, MultiAccountTokenStore as m, type AccountRecord as n, buildSignInUrl as o, handleAuthCallback as p, redirectToSignIn as q, requestMagicLink as r, signInWithPasskey as s, signIn as t, unlinkProvider as u, verifyMagicLink as v, signOut as w, type SignInOptions as x, type SignOutOptions as y, REFRESH_COOKIE as z };

package/dist/test.d.mts

@@ -0,0 +1,86 @@
+/**
+ * @iqauth/sdk/test — in-process test issuer.
+ *
+ * Spawns an http.Server that exposes a JWKS endpoint, an OIDC discovery
+ * doc, a token endpoint that accepts a code-exchange call, and a userinfo
+ * endpoint. Mints valid RS256 JWTs against a freshly-generated keypair so
+ * integration tests can write `<IQAuthProvider iqAuthBaseUrl={baseUrl}>`
+ * without a live IQAuth dependency.
+ *
+ *   import { createTestIssuer } from "@iqauth/sdk/test";
+ *   const issuer = await createTestIssuer({ port: 0 });
+ *   const token = issuer.mintToken({ sub: "u1", roles: ["tenant_admin"] });
+ *   // …point your SDK / fetch / supertest at issuer.baseUrl
+ *   await issuer.close();
+ *
+ * Out of scope: this does NOT mock SSO providers (Google, Microsoft) or
+ * the full DispositionIQ admin/permissions API surface. It implements
+ * exactly enough of the issuer to satisfy the SDK's verify path and the
+ * common code-exchange flow used by integration tests.
+ */
+interface MintTokenOptions {
+    sub?: string;
+    email?: string;
+    name?: string;
+    tenantId?: string;
+    vendorId?: string | null;
+    roles?: string[];
+    entitlements?: string[];
+    sessionId?: string;
+    jti?: string;
+    scopeContext?: unknown;
+    loginMethod?: string;
+    /** Override the audience array. Defaults to `["dispositioniq"]`. */
+    audience?: string | string[];
+    /** Override `iss` for negative tests. Defaults to the issuer's baseUrl. */
+    issuer?: string;
+    /** Token lifetime in seconds. Defaults to 900 (15min). */
+    expiresInSeconds?: number;
+    /** Backdate `iat` (and consequently `exp`) for expired-token tests. */
+    iat?: number;
+    /** Free-form extra claims. */
+    [key: string]: unknown;
+}
+interface MintAuthCodeOptions extends MintTokenOptions {
+    /** Refresh token returned alongside the access token at exchange time. */
+    refreshToken?: string;
+}
+interface CreateTestIssuerOptions {
+    /** Port to bind. Use `0` (default) for an OS-assigned free port. */
+    port?: number;
+    /** Hostname to bind. Defaults to `127.0.0.1`. */
+    host?: string;
+    /** Tenant id baked into minted publishable keys. Defaults to `tenant-test`. */
+    tenantId?: string;
+    /** App id baked into minted publishable keys. Defaults to `app-test`. */
+    appId?: string;
+    /**
+     * Key id used in the JWT header and JWKS entry. Defaults to a
+     * crypto-random value so concurrent test issuers don't collide caches.
+     */
+    kid?: string;
+    /** Default audience used when callers don't override it. Defaults to `["dispositioniq"]`. */
+    defaultAudience?: string[];
+}
+interface TestIssuer {
+    /** Base URL of the running issuer, e.g. `http://127.0.0.1:54321`. */
+    baseUrl: string;
+    /** A `pk_test_…` publishable key encoding `{iss=baseUrl, appId, tenantId, kid}`. */
+    publishableKey: string;
+    /** Key id used to sign tokens — useful when tests want to assert headers. */
+    kid: string;
+    /** PEM-encoded RSA public key. */
+    publicKey: string;
+    /** Sign a JWT and return it. */
+    mintToken: (opts?: MintTokenOptions) => string;
+    /**
+     * Pre-register an authorization code that, when later exchanged at
+     * `POST /oidc/token`, returns the supplied claims as a fresh token pair.
+     */
+    mintAuthCode: (opts?: MintAuthCodeOptions) => string;
+    /** Stop accepting connections and free the port. */
+    close: () => Promise<void>;
+}
+declare function createTestIssuer(options?: CreateTestIssuerOptions): Promise<TestIssuer>;
+
+export { type CreateTestIssuerOptions, type MintAuthCodeOptions, type MintTokenOptions, type TestIssuer, createTestIssuer };

package/dist/test.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @iqauth/sdk/test — in-process test issuer.
+ *
+ * Spawns an http.Server that exposes a JWKS endpoint, an OIDC discovery
+ * doc, a token endpoint that accepts a code-exchange call, and a userinfo
+ * endpoint. Mints valid RS256 JWTs against a freshly-generated keypair so
+ * integration tests can write `<IQAuthProvider iqAuthBaseUrl={baseUrl}>`
+ * without a live IQAuth dependency.
+ *
+ *   import { createTestIssuer } from "@iqauth/sdk/test";
+ *   const issuer = await createTestIssuer({ port: 0 });
+ *   const token = issuer.mintToken({ sub: "u1", roles: ["tenant_admin"] });
+ *   // …point your SDK / fetch / supertest at issuer.baseUrl
+ *   await issuer.close();
+ *
+ * Out of scope: this does NOT mock SSO providers (Google, Microsoft) or
+ * the full DispositionIQ admin/permissions API surface. It implements
+ * exactly enough of the issuer to satisfy the SDK's verify path and the
+ * common code-exchange flow used by integration tests.
+ */
+interface MintTokenOptions {
+    sub?: string;
+    email?: string;
+    name?: string;
+    tenantId?: string;
+    vendorId?: string | null;
+    roles?: string[];
+    entitlements?: string[];
+    sessionId?: string;
+    jti?: string;
+    scopeContext?: unknown;
+    loginMethod?: string;
+    /** Override the audience array. Defaults to `["dispositioniq"]`. */
+    audience?: string | string[];
+    /** Override `iss` for negative tests. Defaults to the issuer's baseUrl. */
+    issuer?: string;
+    /** Token lifetime in seconds. Defaults to 900 (15min). */
+    expiresInSeconds?: number;
+    /** Backdate `iat` (and consequently `exp`) for expired-token tests. */
+    iat?: number;
+    /** Free-form extra claims. */
+    [key: string]: unknown;
+}
+interface MintAuthCodeOptions extends MintTokenOptions {
+    /** Refresh token returned alongside the access token at exchange time. */
+    refreshToken?: string;
+}
+interface CreateTestIssuerOptions {
+    /** Port to bind. Use `0` (default) for an OS-assigned free port. */
+    port?: number;
+    /** Hostname to bind. Defaults to `127.0.0.1`. */
+    host?: string;
+    /** Tenant id baked into minted publishable keys. Defaults to `tenant-test`. */
+    tenantId?: string;
+    /** App id baked into minted publishable keys. Defaults to `app-test`. */
+    appId?: string;
+    /**
+     * Key id used in the JWT header and JWKS entry. Defaults to a
+     * crypto-random value so concurrent test issuers don't collide caches.
+     */
+    kid?: string;
+    /** Default audience used when callers don't override it. Defaults to `["dispositioniq"]`. */
+    defaultAudience?: string[];
+}
+interface TestIssuer {
+    /** Base URL of the running issuer, e.g. `http://127.0.0.1:54321`. */
+    baseUrl: string;
+    /** A `pk_test_…` publishable key encoding `{iss=baseUrl, appId, tenantId, kid}`. */
+    publishableKey: string;
+    /** Key id used to sign tokens — useful when tests want to assert headers. */
+    kid: string;
+    /** PEM-encoded RSA public key. */
+    publicKey: string;
+    /** Sign a JWT and return it. */
+    mintToken: (opts?: MintTokenOptions) => string;
+    /**
+     * Pre-register an authorization code that, when later exchanged at
+     * `POST /oidc/token`, returns the supplied claims as a fresh token pair.
+     */
+    mintAuthCode: (opts?: MintAuthCodeOptions) => string;
+    /** Stop accepting connections and free the port. */
+    close: () => Promise<void>;
+}
+declare function createTestIssuer(options?: CreateTestIssuerOptions): Promise<TestIssuer>;
+
+export { type CreateTestIssuerOptions, type MintAuthCodeOptions, type MintTokenOptions, type TestIssuer, createTestIssuer };