base-idp 1.0.1 → 1.1.0

package/dist/browser-paseto.d.ts

@@ -0,0 +1,13 @@
+import type { BaseIdpPublicKeySet, VerifiedPrincipal, VerifyAccessTokenOptions } from "./types.js";
+/**
+ * Verify a Base IDP PASETO v4.public token using the Web Crypto API.
+ *
+ * Unlike the server-side verifyPasetoV4Public in paseto.ts this function is
+ * fully async because crypto.subtle.verify is always asynchronous.
+ */
+export declare function verifyPasetoV4PublicBrowser(token: string, keySet: BaseIdpPublicKeySet, config: {
+    issuer: string;
+    audience?: string;
+    requiredScope?: string;
+}, options?: VerifyAccessTokenOptions): Promise<VerifiedPrincipal>;
+//# sourceMappingURL=browser-paseto.d.ts.map

package/dist/browser-paseto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-paseto.d.ts","sourceRoot":"","sources":["../src/browser-paseto.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAEV,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAWpB;;;;;GAKG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,mBAAmB,EAC3B,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACrE,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,iBAAiB,CAAC,CAqF5B"}

package/dist/browser-paseto.js

@@ -0,0 +1,116 @@
+/**
+ * Browser-compatible PASETO v4.public verifier.
+ *
+ * Identical protocol to paseto.ts but uses Web Crypto API (crypto.subtle)
+ * instead of node:crypto so it can be bundled into browser applications.
+ * Ed25519 verification via crypto.subtle requires Chrome 113+, Firefox 129+,
+ * Safari 17+ (all major modern browsers).
+ */
+import { base64UrlDecode, concatBytes, utf8Decode, utf8Encode } from "./base64url.js";
+import { idpError } from "./errors.js";
+const HEADER = utf8Encode("v4.public.");
+const IMPLICIT_ASSERTION = utf8Encode("square-experience:idp:access:v1");
+/**
+ * Verify a Base IDP PASETO v4.public token using the Web Crypto API.
+ *
+ * Unlike the server-side verifyPasetoV4Public in paseto.ts this function is
+ * fully async because crypto.subtle.verify is always asynchronous.
+ */
+export async function verifyPasetoV4PublicBrowser(token, keySet, config, options = {}) {
+    const parts = token.split(".");
+    if (parts.length !== 4 || parts[0] !== "v4" || parts[1] !== "public") {
+        throw idpError("invalid_token", "token is not PASETO v4.public");
+    }
+    const payload = base64UrlDecode(parts[2]);
+    const footerBytes = base64UrlDecode(parts[3]);
+    if (payload.length <= 64) {
+        throw idpError("invalid_token", "PASETO payload is too short");
+    }
+    const footer = JSON.parse(utf8Decode(footerBytes));
+    if (footer.alg !== "v4.public" || footer.typ !== "paseto" || !footer.kid) {
+        throw idpError("invalid_token", "PASETO footer is not a Base IDP v4.public footer");
+    }
+    const publicKey = keySet.keys.find((key) => key.kid === footer.kid && key.alg === "v4.public");
+    if (!publicKey) {
+        throw idpError("unknown_kid", "PASETO key id is not in the Base IDP key set");
+    }
+    const message = payload.subarray(0, payload.length - 64);
+    const signature = payload.subarray(payload.length - 64);
+    const rawPublicKey = base64UrlDecode(publicKey.public_key_base64);
+    if (rawPublicKey.length !== 32 || signature.length !== 64) {
+        throw idpError("invalid_key", "Ed25519 public key or signature has an unexpected size");
+    }
+    // Build the Pre-Authentication Encoding (PAE) message
+    const pae = preAuthEncode([HEADER, message, footerBytes, IMPLICIT_ASSERTION]);
+    // Verify using the Web Crypto API Ed25519 (no node:crypto dependency)
+    let valid;
+    try {
+        const cryptoKey = await crypto.subtle.importKey("raw", rawPublicKey.buffer.slice(rawPublicKey.byteOffset, rawPublicKey.byteOffset + rawPublicKey.byteLength), { name: "Ed25519" }, false, ["verify"]);
+        const paeBuffer = pae.buffer.slice(pae.byteOffset, pae.byteOffset + pae.byteLength);
+        const sigBuffer = signature.buffer.slice(signature.byteOffset, signature.byteOffset + signature.byteLength);
+        valid = await crypto.subtle.verify("Ed25519", cryptoKey, sigBuffer, paeBuffer);
+    }
+    catch {
+        throw idpError("invalid_key", "Ed25519 key import or verification failed");
+    }
+    if (!valid) {
+        throw idpError("invalid_signature", "PASETO signature verification failed");
+    }
+    const claims = JSON.parse(utf8Decode(message));
+    validateClaims(claims, {
+        issuer: options.issuer ?? config.issuer,
+        audience: options.audience ?? config.audience ?? "square-experience",
+        requiredScope: options.requiredScope ?? config.requiredScope,
+        maxClockSkewSeconds: options.maxClockSkewSeconds ?? 30,
+    });
+    return {
+        id: claims.gid,
+        subject: claims.sub,
+        email: claims.email,
+        name: claims.name,
+        role: claims.role,
+        scopes: claims.scp ?? [],
+        accountContext: claims.ctx,
+        claims,
+    };
+}
+function validateClaims(claims, options) {
+    if (claims.token_use !== "access") {
+        throw idpError("invalid_claims", "token_use must be 'access'");
+    }
+    if (claims.iss !== options.issuer || claims.aud !== options.audience) {
+        throw idpError("invalid_claims", "issuer or audience mismatch");
+    }
+    const now = Date.now();
+    const skewMs = options.maxClockSkewSeconds * 1000;
+    if (Date.parse(claims.exp) <= now - skewMs) {
+        throw idpError("token_expired", "access token has expired");
+    }
+    if (Date.parse(claims.nbf) > now + skewMs) {
+        throw idpError("token_not_yet_valid", "access token is not yet valid");
+    }
+    if (options.requiredScope && !(claims.scp ?? []).includes(options.requiredScope)) {
+        throw idpError("insufficient_scope", `required scope '${options.requiredScope}' is missing`);
+    }
+    if (!claims.gid || !claims.sub || !claims.sid || !claims.ctx || !claims.role) {
+        throw idpError("invalid_claims", "required identity claims are missing from the token");
+    }
+}
+// Pre-Authentication Encoding as defined by PASETO spec
+function preAuthEncode(pieces) {
+    const out = [uint64le(pieces.length)];
+    for (const piece of pieces) {
+        out.push(uint64le(piece.length), piece);
+    }
+    return concatBytes(out);
+}
+function uint64le(value) {
+    const out = new Uint8Array(8);
+    let current = BigInt(value);
+    for (let i = 0; i < 8; i++) {
+        out[i] = Number(current & 0xffn);
+        current >>= 8n;
+    }
+    return out;
+}
+//# sourceMappingURL=browser-paseto.js.map

package/dist/browser-paseto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-paseto.js","sourceRoot":"","sources":["../src/browser-paseto.ts"],"names":[],"mappings":"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"}

package/dist/browser.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Browser Client SDK — BrowserBaseIdpClient
+ *
+ * This is the client-side entry point for every browser app.
+ * It owns the complete auth flow:
+ *
+ *   1. loginWithRedirect()  — generates PKCE, stores state in sessionStorage, redirects to Base IDP
+ *   2. handleRedirectCallback() — validates state, exchanges code, verifies token, stores session
+ *   3. getSession() / getUser() / isAuthenticated() — synchronous session access
+ *   4. getAccessToken() — returns a live token, refreshes transparently if near expiry
+ *   5. refreshSession() — explicit refresh using the stored refresh token
+ *   6. logout() — clears session, optionally redirects
+ *   7. onSessionChange() — reactive session event subscription
+ *
+ * Zero Node.js dependencies. Runs in any modern browser or Deno/Cloudflare Workers.
+ */
+import { BaseIdPClient } from "./client.js";
+import type { AuthSession, BrowserBaseIdpConfig, LoginWithRedirectOptions, SessionChangeListener, VerifiedPrincipal, VerifyAccessTokenOptions } from "./types.js";
+export type HandleCallbackResult = {
+    principal: VerifiedPrincipal;
+    /** The `returnTo` path that was saved before the redirect, if any */
+    returnTo?: string;
+};
+export declare class BrowserBaseIdpClient extends BaseIdPClient {
+    private readonly browserCfg;
+    private readonly persistSession;
+    private readonly prefix;
+    private session;
+    private readonly listeners;
+    private refreshTimer;
+    constructor(browserCfg: BrowserBaseIdpConfig);
+    /**
+     * Discover and cache the client configuration from Base IDP.
+     * Call this once on app start before using any other method.
+     */
+    init(): Promise<void>;
+    /**
+     * Start the PKCE authorization code flow.
+     *
+     * - Generates a fresh code_verifier + S256 challenge
+     * - Stores `{ state, codeVerifier, redirectUri, returnTo }` in sessionStorage
+     * - Redirects the browser to Base IDP's authorization endpoint
+     *
+     * Call `handleRedirectCallback()` on the redirect URI page to complete login.
+     */
+    loginWithRedirect(options?: LoginWithRedirectOptions): Promise<void>;
+    /**
+     * Handle the OAuth2 redirect callback.
+     *
+     * Reads `code` and `state` from the URL (or the `url` argument),
+     * validates state against the pending transaction in sessionStorage,
+     * exchanges the code for tokens, verifies the access token, and
+     * stores the resulting session.
+     *
+     * Returns `{ principal, returnTo }` so the app can navigate to the
+     * original destination.
+     */
+    handleRedirectCallback(url?: string): Promise<HandleCallbackResult>;
+    /**
+     * Synchronously return the current session, or null if not authenticated.
+     */
+    getSession(): AuthSession | null;
+    /**
+     * Synchronously return the current user (VerifiedPrincipal), or null.
+     */
+    getUser(): VerifiedPrincipal | null;
+    /**
+     * Returns true if there is a session whose access token has not yet expired.
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Return a live access token, transparently refreshing it if it is within
+     * REFRESH_THRESHOLD_MS (60 s) of expiry.
+     *
+     * Throws `not_authenticated` if there is no session at all.
+     * Throws `session_expired` if the refresh also fails.
+     */
+    getAccessToken(options?: Pick<VerifyAccessTokenOptions, "requiredScope">): Promise<string>;
+    /**
+     * Force a token refresh using the stored refresh token.
+     * Updates the in-memory (and optionally persisted) session.
+     */
+    refreshSession(): Promise<AuthSession>;
+    /**
+     * Clear the session and optionally redirect to a post-logout URL.
+     */
+    logout(options?: {
+        returnTo?: string;
+    }): void;
+    /**
+     * Subscribe to session lifecycle events (`signed_in`, `signed_out`,
+     * `refreshed`, `expired`).
+     *
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const off = auth.onSessionChange(({ type, session }) => {
+     *   if (type === "signed_out") router.push("/login");
+     * });
+     * // Later:
+     * off();
+     */
+    onSessionChange(listener: SessionChangeListener): () => void;
+    private verifyTokenBrowser;
+    private storeSession;
+    private clearSession;
+    private loadPersistedSession;
+    private scheduleRefresh;
+    private toPublicSession;
+    private emit;
+}
+/**
+ * Create a browser auth client from config.
+ *
+ * @example
+ * // Vite / Vanilla browser app
+ * const auth = createBrowserBaseIdpAuth({
+ *   key: import.meta.env.VITE_BASE_IDP_KEY,
+ *   issuer: import.meta.env.VITE_BASE_IDP_ISSUER,
+ *   persistSession: true,
+ * });
+ *
+ * // On app load
+ * await auth.init();
+ *
+ * // Start login
+ * await auth.loginWithRedirect({ returnTo: "/dashboard" });
+ *
+ * // On the callback page
+ * const { principal, returnTo } = await auth.handleRedirectCallback();
+ */
+export declare function createBrowserBaseIdpAuth(config: BrowserBaseIdpConfig): BrowserBaseIdpClient;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,wBAAwB,EAExB,qBAAqB,EACrB,iBAAiB,EACjB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAwBpB,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,qBAAa,oBAAqB,SAAQ,aAAa;IAOzC,OAAO,CAAC,QAAQ,CAAC,UAAU;IANvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyC;IACnE,OAAO,CAAC,YAAY,CAA8C;gBAErC,UAAU,EAAE,oBAAoB;IAqB7D;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;;;;;;OAQG;IACG,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IAsD9E;;;;;;;;;;OAUG;IACG,sBAAsB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAuDzE;;OAEG;IACH,UAAU,IAAI,WAAW,GAAG,IAAI;IAShC;;OAEG;IACH,OAAO,IAAI,iBAAiB,GAAG,IAAI;IAInC;;OAEG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;;;OAMG;IACG,cAAc,CAAC,OAAO,GAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuBpG;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IA2B5C;;OAEG;IACH,MAAM,CAAC,OAAO,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IASjD;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,QAAQ,EAAE,qBAAqB,GAAG,MAAM,IAAI;YAS9C,kBAAkB;IAShC,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,YAAY;IAmBpB,OAAO,CAAC,oBAAoB;IAc5B,OAAO,CAAC,eAAe;IAiBvB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,IAAI;CASb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,oBAAoB,GAAG,oBAAoB,CAE3F"}

package/dist/browser.js

@@ -0,0 +1,382 @@
+/**
+ * Browser Client SDK — BrowserBaseIdpClient
+ *
+ * This is the client-side entry point for every browser app.
+ * It owns the complete auth flow:
+ *
+ *   1. loginWithRedirect()  — generates PKCE, stores state in sessionStorage, redirects to Base IDP
+ *   2. handleRedirectCallback() — validates state, exchanges code, verifies token, stores session
+ *   3. getSession() / getUser() / isAuthenticated() — synchronous session access
+ *   4. getAccessToken() — returns a live token, refreshes transparently if near expiry
+ *   5. refreshSession() — explicit refresh using the stored refresh token
+ *   6. logout() — clears session, optionally redirects
+ *   7. onSessionChange() — reactive session event subscription
+ *
+ * Zero Node.js dependencies. Runs in any modern browser or Deno/Cloudflare Workers.
+ */
+import { BaseIdPClient } from "./client.js";
+import { generatePKCE } from "./pkce.js";
+import { idpError } from "./errors.js";
+import { verifyPasetoV4PublicBrowser } from "./browser-paseto.js";
+// How many milliseconds before expiry we proactively refresh the token.
+const REFRESH_THRESHOLD_MS = 60_000;
+export class BrowserBaseIdpClient extends BaseIdPClient {
+    browserCfg;
+    persistSession;
+    prefix;
+    session = null;
+    listeners = new Set();
+    refreshTimer = null;
+    constructor(browserCfg) {
+        super(browserCfg);
+        this.browserCfg = browserCfg;
+        this.persistSession = browserCfg.persistSession ?? false;
+        this.prefix = browserCfg.storagePrefix ?? "base_idp";
+        // Apply browser-specific overrides on top of the base config
+        if (browserCfg.redirectUri)
+            this.cfg.redirectUri = browserCfg.redirectUri;
+        if (browserCfg.audience)
+            this.cfg.audience = browserCfg.audience;
+        if (browserCfg.scopes) {
+            this.cfg.scopes = this.scopes(browserCfg.scopes);
+        }
+        // Eagerly restore any persisted session from storage
+        this.session = this.loadPersistedSession();
+        if (this.session) {
+            this.scheduleRefresh();
+        }
+    }
+    // ── Initialise ─────────────────────────────────────────────────────────────
+    /**
+     * Discover and cache the client configuration from Base IDP.
+     * Call this once on app start before using any other method.
+     */
+    async init() {
+        await this.resolveConfig();
+        if (!this.session) {
+            this.session = this.loadPersistedSession();
+            if (this.session)
+                this.scheduleRefresh();
+        }
+    }
+    // ── Login ──────────────────────────────────────────────────────────────────
+    /**
+     * Start the PKCE authorization code flow.
+     *
+     * - Generates a fresh code_verifier + S256 challenge
+     * - Stores `{ state, codeVerifier, redirectUri, returnTo }` in sessionStorage
+     * - Redirects the browser to Base IDP's authorization endpoint
+     *
+     * Call `handleRedirectCallback()` on the redirect URI page to complete login.
+     */
+    async loginWithRedirect(options = {}) {
+        await this.resolveConfig();
+        // Confidential clients require a client_secret for code exchange.
+        // Secrets must never appear in browser bundles — reject early with a
+        // clear developer message instead of failing silently at the token endpoint.
+        if (this.cfg.confidential) {
+            throw idpError("confidential_client_in_browser", "This client is registered as confidential (requires a client_secret). " +
+                "Browser apps must use a public PKCE client. " +
+                "Either register a new public client for this app, or route the OAuth callback " +
+                "through a backend server that holds the secret and calls exchangeCode() there.");
+        }
+        const pkce = await generatePKCE();
+        const state = options.state ?? generateRandom(32);
+        const nonce = options.nonce ?? generateRandom(16);
+        const redirectUri = options.redirectUri ?? this.cfg.redirectUri;
+        if (!redirectUri) {
+            throw idpError("invalid_config", "redirectUri is required — pass it in BrowserBaseIdpConfig or LoginWithRedirectOptions");
+        }
+        const tx = {
+            state,
+            codeVerifier: pkce.verifier,
+            redirectUri,
+            returnTo: options.returnTo,
+            nonce,
+            createdAt: Date.now(),
+        };
+        sessionStorage.setItem(`${this.prefix}.txs.${state}`, JSON.stringify(tx));
+        const url = this.authorizeUrl({
+            state,
+            nonce,
+            codeChallenge: pkce.challenge,
+            codeChallengeMethod: "S256",
+            redirectUri,
+            scopes: options.scopes ?? this.cfg.scopes,
+            additionalParameters: options.additionalParameters,
+        });
+        window.location.assign(url);
+    }
+    // ── Callback ───────────────────────────────────────────────────────────────
+    /**
+     * Handle the OAuth2 redirect callback.
+     *
+     * Reads `code` and `state` from the URL (or the `url` argument),
+     * validates state against the pending transaction in sessionStorage,
+     * exchanges the code for tokens, verifies the access token, and
+     * stores the resulting session.
+     *
+     * Returns `{ principal, returnTo }` so the app can navigate to the
+     * original destination.
+     */
+    async handleRedirectCallback(url) {
+        const searchString = url ? new URL(url).search : window.location.search;
+        const params = new URLSearchParams(searchString);
+        // Surface IDP-level errors (access_denied, etc.) before anything else
+        const errorParam = params.get("error");
+        if (errorParam) {
+            const desc = params.get("error_description") ?? errorParam;
+            throw idpError("oauth_callback_error", desc);
+        }
+        const code = params.get("code");
+        const state = params.get("state") ?? "";
+        if (!code) {
+            throw idpError("missing_code", "no authorization code found in the callback URL");
+        }
+        // Retrieve and remove the pending PKCE transaction
+        const txKey = `${this.prefix}.txs.${state}`;
+        const txRaw = sessionStorage.getItem(txKey);
+        if (!txRaw) {
+            throw idpError("invalid_state", "no pending auth transaction for this state value — possible CSRF or stale redirect");
+        }
+        const tx = JSON.parse(txRaw);
+        sessionStorage.removeItem(txKey);
+        // Exchange authorization code for token pair
+        const tokens = await this.exchangeCode({
+            code,
+            codeVerifier: tx.codeVerifier,
+            redirectUri: tx.redirectUri,
+        });
+        // Verify the access token using the browser-safe PASETO verifier
+        const principal = await this.verifyTokenBrowser(tokens.access_token);
+        const internal = {
+            principal,
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: Date.now() + tokens.expires_in * 1000,
+            refreshExpiresAt: tokens.refresh_token_expires_at,
+        };
+        this.storeSession(internal);
+        return { principal, returnTo: tx.returnTo };
+    }
+    // ── Session access ─────────────────────────────────────────────────────────
+    /**
+     * Synchronously return the current session, or null if not authenticated.
+     */
+    getSession() {
+        if (!this.session)
+            return null;
+        return {
+            principal: this.session.principal,
+            accessToken: this.session.accessToken,
+            expiresAt: this.session.expiresAt,
+        };
+    }
+    /**
+     * Synchronously return the current user (VerifiedPrincipal), or null.
+     */
+    getUser() {
+        return this.session?.principal ?? null;
+    }
+    /**
+     * Returns true if there is a session whose access token has not yet expired.
+     */
+    isAuthenticated() {
+        return this.session !== null && this.session.expiresAt > Date.now();
+    }
+    /**
+     * Return a live access token, transparently refreshing it if it is within
+     * REFRESH_THRESHOLD_MS (60 s) of expiry.
+     *
+     * Throws `not_authenticated` if there is no session at all.
+     * Throws `session_expired` if the refresh also fails.
+     */
+    async getAccessToken(options = {}) {
+        if (!this.session) {
+            throw idpError("not_authenticated", "no active session — call loginWithRedirect() first");
+        }
+        if (this.session.expiresAt - Date.now() < REFRESH_THRESHOLD_MS) {
+            await this.refreshSession();
+        }
+        if (!this.session) {
+            throw idpError("session_expired", "session expired and could not be refreshed automatically");
+        }
+        if (options.requiredScope && !this.session.principal.scopes.includes(options.requiredScope)) {
+            throw idpError("insufficient_scope", `required scope '${options.requiredScope}' is not present in the session`);
+        }
+        return this.session.accessToken;
+    }
+    /**
+     * Force a token refresh using the stored refresh token.
+     * Updates the in-memory (and optionally persisted) session.
+     */
+    async refreshSession() {
+        if (!this.session?.refreshToken) {
+            throw idpError("not_authenticated", "no refresh token available");
+        }
+        try {
+            const tokens = await this.refresh({ refreshToken: this.session.refreshToken });
+            const principal = await this.verifyTokenBrowser(tokens.access_token);
+            const internal = {
+                principal,
+                accessToken: tokens.access_token,
+                refreshToken: tokens.refresh_token,
+                expiresAt: Date.now() + tokens.expires_in * 1000,
+                refreshExpiresAt: tokens.refresh_token_expires_at,
+            };
+            this.storeSession(internal, "refreshed");
+            return this.getSession();
+        }
+        catch {
+            this.clearSession();
+            throw idpError("refresh_failed", "token refresh failed — user must sign in again");
+        }
+    }
+    // ── Logout ─────────────────────────────────────────────────────────────────
+    /**
+     * Clear the session and optionally redirect to a post-logout URL.
+     */
+    logout(options = {}) {
+        this.clearSession();
+        if (options.returnTo) {
+            window.location.assign(options.returnTo);
+        }
+    }
+    // ── Session change events ──────────────────────────────────────────────────
+    /**
+     * Subscribe to session lifecycle events (`signed_in`, `signed_out`,
+     * `refreshed`, `expired`).
+     *
+     * Returns an unsubscribe function.
+     *
+     * @example
+     * const off = auth.onSessionChange(({ type, session }) => {
+     *   if (type === "signed_out") router.push("/login");
+     * });
+     * // Later:
+     * off();
+     */
+    onSessionChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    async verifyTokenBrowser(token) {
+        await this.resolveConfig();
+        const keySet = await this.publicKeys();
+        return verifyPasetoV4PublicBrowser(token, keySet, {
+            issuer: this.cfg.issuer,
+            audience: this.cfg.audience,
+        });
+    }
+    storeSession(internal, eventType = "signed_in") {
+        this.session = internal;
+        if (this.persistSession) {
+            try {
+                localStorage.setItem(`${this.prefix}.session`, JSON.stringify(internal));
+            }
+            catch {
+                // Storage quota exceeded or private-browsing restriction — fail silently
+            }
+        }
+        this.scheduleRefresh();
+        this.emit({ type: eventType, session: this.toPublicSession(internal) });
+    }
+    clearSession() {
+        this.session = null;
+        if (this.persistSession) {
+            try {
+                localStorage.removeItem(`${this.prefix}.session`);
+            }
+            catch {
+                // Ignore
+            }
+        }
+        if (this.refreshTimer !== null) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        this.emit({ type: "signed_out", session: null });
+    }
+    loadPersistedSession() {
+        if (!this.persistSession)
+            return null;
+        try {
+            const raw = localStorage.getItem(`${this.prefix}.session`);
+            if (!raw)
+                return null;
+            const parsed = JSON.parse(raw);
+            // Accept even expired sessions so refreshSession() can still run
+            if (!parsed.accessToken || !parsed.refreshToken || !parsed.principal)
+                return null;
+            return parsed;
+        }
+        catch {
+            return null;
+        }
+    }
+    scheduleRefresh() {
+        if (this.refreshTimer !== null) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+        if (!this.session)
+            return;
+        const msUntilExpiry = this.session.expiresAt - Date.now();
+        const delay = Math.max(0, msUntilExpiry - REFRESH_THRESHOLD_MS);
+        this.refreshTimer = setTimeout(() => {
+            this.refreshSession().catch(() => {
+                this.emit({ type: "expired", session: null });
+            });
+        }, delay);
+    }
+    toPublicSession(internal) {
+        return {
+            principal: internal.principal,
+            accessToken: internal.accessToken,
+            expiresAt: internal.expiresAt,
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Never let a subscriber error crash the auth flow
+            }
+        }
+    }
+}
+/**
+ * Create a browser auth client from config.
+ *
+ * @example
+ * // Vite / Vanilla browser app
+ * const auth = createBrowserBaseIdpAuth({
+ *   key: import.meta.env.VITE_BASE_IDP_KEY,
+ *   issuer: import.meta.env.VITE_BASE_IDP_ISSUER,
+ *   persistSession: true,
+ * });
+ *
+ * // On app load
+ * await auth.init();
+ *
+ * // Start login
+ * await auth.loginWithRedirect({ returnTo: "/dashboard" });
+ *
+ * // On the callback page
+ * const { principal, returnTo } = await auth.handleRedirectCallback();
+ */
+export function createBrowserBaseIdpAuth(config) {
+    return new BrowserBaseIdpClient(config);
+}
+// ── Private utils ──────────────────────────────────────────────────────────
+function generateRandom(bytes) {
+    const arr = new Uint8Array(bytes);
+    crypto.getRandomValues(arr);
+    return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+//# sourceMappingURL=browser.js.map