@smartcrab/browser 0.1.0

package/dist/client.js

@@ -0,0 +1,551 @@
+import { clientIdSchema, emailChallengeResponseSchema, emailVerifyResponseSchema, meDeleteResponseSchema, meEmailChangeStartResponseSchema, meEmailChangeVerifyNewResponseSchema, meEmailChangeVerifyOldResponseSchema, meIdentitiesListResponseSchema, meIdentityLinkResponseSchema, meIdentityUnlinkResponseSchema, mePasskeyDeleteResponseSchema, mePasskeyRegistrationOptionsResponseSchema, mePasskeyRegistrationVerifyResponseSchema, mePasskeysListResponseSchema, meSessionRevokeResponseSchema, meSessionsListResponseSchema, meSessionsRevokeAllResponseSchema, meUpdateResponseSchema, meUserSchema, passkeyAuthenticationOptionsResponseSchema, passkeyAuthenticationVerifyResponseSchema, passkeyRegistrationOptionsResponseSchema, publicConfigResponseSchema, scopeStringSchema, socialStartResponseSchema, tokenResponseSchema, transactionCancelResponseSchema, transactionCompleteResponseSchema, transactionCreateResponseSchema, transactionGetResponseSchema, transactionPasskeyRegistrationVerifyResponseSchema, } from "@smartcrab/contracts-public";
+import { err, ok } from "@smartcrab/contracts-public";
+import { buildUrl, isOAuthErrorCode, requestJson } from "./http.js";
+import { generateNonce, generatePkcePair, generateState } from "./pkce.js";
+import { navigatorWebAuthnPort } from "./webauthn.js";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+const EXPIRY_SKEW_MS = 30_000;
+/** Matches the transaction lifetime implied by design.md §16.1's example (10 minutes). */
+const PENDING_AUTHORIZATION_TTL_MS = 10 * 60 * 1000;
+const defaultFetchPort = (url, init) => fetch(url, init);
+const defaultRedirectPort = {
+    assign: (url) => {
+        if (typeof window !== "undefined") {
+            window.location.assign(url);
+        }
+    },
+};
+const PENDING_AUTHORIZATION_STORAGE_PREFIX = "@smartcrab/browser:pending:";
+const isPendingAuthorization = (value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    return (typeof record["state"] === "string" &&
+        typeof record["nonce"] === "string" &&
+        typeof record["codeVerifier"] === "string" &&
+        typeof record["redirectUri"] === "string" &&
+        typeof record["createdAt"] === "number" &&
+        Number.isFinite(record["createdAt"]));
+};
+const encodeSegment = encodeURIComponent;
+export const createBrowserAuthClient = (config) => {
+    // Programmer-error validation: fail fast at factory time (not a runtime
+    // failure channel, hence a TypeError rather than an Outcome).
+    if (!URL.canParse(config.baseUrl)) {
+        throw new TypeError(`baseUrl is not a valid URL: ${config.baseUrl}`);
+    }
+    if (!clientIdSchema.safeParse(config.clientId).success) {
+        throw new TypeError("clientId is not a valid cli_ identifier");
+    }
+    const scope = config.scope ?? "openid profile email";
+    if (!scopeStringSchema.safeParse(scope).success) {
+        throw new TypeError(`scope contains unknown tokens: ${scope}`);
+    }
+    if (config.redirectUri.length === 0) {
+        throw new TypeError("redirectUri must not be empty");
+    }
+    const baseUrl = config.baseUrl.replace(/\/+$/, "");
+    const fetchPort = config.fetch ?? defaultFetchPort;
+    const webAuthn = config.webAuthn ?? navigatorWebAuthnPort;
+    const redirectPort = config.redirect ?? defaultRedirectPort;
+    const now = config.now ?? (() => Date.now());
+    const storage = config.refreshTokenStorage;
+    // Tokens stay in this closure; only short-lived PKCE callback state uses sessionStorage.
+    let tokenSet = null;
+    let cachedIssuer = config.issuer ?? null;
+    let inflightRefresh = null;
+    const pendingByState = new Map();
+    const listeners = new Set();
+    let snapshot = { status: "signed_out", hasRefreshToken: false };
+    const notify = () => {
+        snapshot =
+            tokenSet === null
+                ? { status: "signed_out", hasRefreshToken: false }
+                : {
+                    status: "signed_in",
+                    accessTokenExpiresAt: tokenSet.accessTokenExpiresAt,
+                    scope: tokenSet.scope,
+                    hasRefreshToken: tokenSet.refreshToken !== null,
+                };
+        for (const listener of listeners) {
+            listener(snapshot);
+        }
+    };
+    const prunePending = () => {
+        const cutoff = now() - PENDING_AUTHORIZATION_TTL_MS;
+        for (const [state, pending] of pendingByState) {
+            if (pending.createdAt < cutoff)
+                pendingByState.delete(state);
+        }
+    };
+    // Storage is a navigation-recovery aid: unavailable storage (Node/SSR, blocked storage,
+    // quota) or malformed entries fall back to the in-memory copy. Exception boundaries are
+    // promise rejection handlers, never try/catch (scripts/check-backend-error-style.ts).
+    const registerPending = async (pending) => {
+        prunePending();
+        pendingByState.set(pending.state, pending);
+        await Promise.resolve()
+            .then(() => sessionStorage.setItem(`${PENDING_AUTHORIZATION_STORAGE_PREFIX}${pending.state}`, JSON.stringify(pending)))
+            .then(undefined, () => undefined);
+    };
+    const consumePending = async (state) => {
+        const inMemory = pendingByState.get(state) ?? null;
+        pendingByState.delete(state);
+        const stored = await Promise.resolve()
+            .then(() => {
+            const key = `${PENDING_AUTHORIZATION_STORAGE_PREFIX}${state}`;
+            const serialized = sessionStorage.getItem(key);
+            if (serialized === null)
+                return null;
+            sessionStorage.removeItem(key);
+            const parsed = JSON.parse(serialized);
+            return isPendingAuthorization(parsed) && parsed.state === state ? parsed : null;
+        })
+            .then(undefined, () => null);
+        const pending = inMemory ?? stored;
+        if (pending === null || now() - pending.createdAt > PENDING_AUTHORIZATION_TTL_MS) {
+            return null;
+        }
+        return pending;
+    };
+    const applyTokenResponse = async (tokenResponse) => {
+        const refreshToken = tokenResponse.refresh_token ?? tokenSet?.refreshToken ?? null;
+        tokenSet = {
+            accessToken: tokenResponse.access_token,
+            accessTokenExpiresAt: now() + tokenResponse.expires_in * 1000,
+            scope: tokenResponse.scope,
+            refreshToken,
+        };
+        const persistToken = tokenResponse.refresh_token;
+        if (persistToken !== undefined && storage !== undefined) {
+            // Best-effort: a failing storage port must not break authentication.
+            await Promise.resolve()
+                .then(() => storage.save(persistToken))
+                .then(undefined, () => undefined);
+        }
+        notify();
+        return {
+            accessTokenExpiresAt: tokenSet.accessTokenExpiresAt,
+            scope: tokenSet.scope,
+            hasRefreshToken: refreshToken !== null,
+        };
+    };
+    const clearSession = () => {
+        tokenSet = null;
+        if (storage !== undefined) {
+            void Promise.resolve()
+                .then(() => storage.clear())
+                .then(undefined, () => undefined);
+        }
+        notify();
+    };
+    const request = (method, path, schema, options) => requestJson(fetchPort, {
+        method,
+        url: buildUrl(baseUrl, path, options?.query),
+        ...(options?.body !== undefined ? { body: options.body } : {}),
+        ...(options?.accessToken !== undefined ? { accessToken: options.accessToken } : {}),
+    }, schema);
+    const getPublicConfig = () => request("GET", "/v1/config", publicConfigResponseSchema, {
+        query: { client_id: config.clientId },
+    });
+    const resolveIssuer = async () => {
+        if (cachedIssuer !== null)
+            return ok(cachedIssuer);
+        const configOutcome = await getPublicConfig();
+        if (!configOutcome.ok)
+            return configOutcome;
+        cachedIssuer = configOutcome.value.issuer;
+        return ok(cachedIssuer);
+    };
+    // --- transactions -----------------------------------------------------------
+    const createTransaction = async (input) => {
+        const pkce = await generatePkcePair();
+        const state = input?.state ?? generateState();
+        const nonce = input?.nonce ?? generateNonce();
+        const resource = input?.resource ?? config.resource;
+        const body = {
+            client_id: config.clientId,
+            redirect_uri: config.redirectUri,
+            code_challenge: pkce.challenge,
+            code_challenge_method: "S256",
+            state,
+            nonce,
+            scope: input?.scope ?? scope,
+            ...(resource !== undefined ? { resource: [...resource] } : {}),
+            // The SPA drives the ceremony itself and calls `/complete` over XHR
+            // (design.md §16.3), which is the `native_return` mode.
+            response_mode: "native_return",
+        };
+        const outcome = await request("POST", "/v1/auth/transactions", transactionCreateResponseSchema, { body });
+        if (!outcome.ok)
+            return outcome;
+        await registerPending({
+            state,
+            nonce,
+            codeVerifier: pkce.verifier,
+            redirectUri: config.redirectUri,
+            createdAt: now(),
+        });
+        return ok({
+            transactionId: outcome.value.transaction_id,
+            state,
+            expiresAt: outcome.value.expires_at,
+            availableMethods: outcome.value.available_methods,
+        });
+    };
+    const transactionPath = (transactionId) => `/v1/auth/transactions/${encodeSegment(transactionId)}`;
+    const getTransaction = (transactionId) => request("GET", transactionPath(transactionId), transactionGetResponseSchema);
+    const cancelTransaction = (transactionId) => request("POST", `${transactionPath(transactionId)}/cancel`, transactionCancelResponseSchema, {
+        body: {},
+    });
+    // --- email OTP -----------------------------------------------------------------
+    const startEmailOtp = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/email/start`, emailChallengeResponseSchema, {
+        body: input,
+    });
+    const resendEmailOtp = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/email/resend`, emailChallengeResponseSchema, { body: input });
+    const verifyEmailOtp = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/email/verify`, emailVerifyResponseSchema, {
+        body: input,
+    });
+    // --- passkeys --------------------------------------------------------------------
+    const getPasskeyRegistrationOptions = (transactionId) => request("POST", `${transactionPath(transactionId)}/passkeys/registration/options`, passkeyRegistrationOptionsResponseSchema, {
+        body: {},
+    });
+    const verifyPasskeyRegistration = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/passkeys/registration/verify`, transactionPasskeyRegistrationVerifyResponseSchema, { body: input });
+    const startPasskeyRegistration = async (transactionId, input) => {
+        if (!webAuthn.isAvailable()) {
+            return err({
+                type: "webauthn_error",
+                reason: "not_supported",
+                message: "WebAuthn is not available",
+            });
+        }
+        const options = await getPasskeyRegistrationOptions(transactionId);
+        if (!options.ok)
+            return options;
+        const credential = await webAuthn.create(options.value);
+        if (!credential.ok)
+            return credential;
+        return verifyPasskeyRegistration(transactionId, {
+            credential: credential.value,
+            ...(input?.name !== undefined ? { name: input.name } : {}),
+        });
+    };
+    const getPasskeyAuthenticationOptions = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/passkeys/authentication/options`, passkeyAuthenticationOptionsResponseSchema, { body: input ?? {} });
+    const verifyPasskeyAuthentication = (transactionId, input) => request("POST", `${transactionPath(transactionId)}/passkeys/authentication/verify`, passkeyAuthenticationVerifyResponseSchema, { body: input });
+    const startPasskeyAuthentication = async (transactionId, input) => {
+        if (!webAuthn.isAvailable()) {
+            return err({
+                type: "webauthn_error",
+                reason: "not_supported",
+                message: "WebAuthn is not available",
+            });
+        }
+        const options = await getPasskeyAuthenticationOptions(transactionId, input);
+        if (!options.ok)
+            return options;
+        const credential = await webAuthn.get(options.value);
+        if (!credential.ok)
+            return credential;
+        return verifyPasskeyAuthentication(transactionId, { credential: credential.value });
+    };
+    // --- social -----------------------------------------------------------------------
+    const startSocialSignIn = async (transactionId, provider) => {
+        const outcome = await request("POST", `${transactionPath(transactionId)}/social/${encodeSegment(provider)}/start`, socialStartResponseSchema, { body: {} });
+        if (!outcome.ok)
+            return outcome;
+        // design.md §22.3/§20.6: top-level navigation only; the SPA resumes via
+        // the redirect back to `redirectUri`.
+        redirectPort.assign(outcome.value.authorization_url);
+        return outcome;
+    };
+    // --- completion + token exchange ------------------------------------------------------
+    const completeTransaction = async (transactionId) => {
+        const outcome = await request("POST", `${transactionPath(transactionId)}/complete`, transactionCompleteResponseSchema, {
+            body: {},
+        });
+        if (!outcome.ok)
+            return outcome;
+        if (outcome.value.redirect_uri !== config.redirectUri) {
+            // design.md §15.9: exact redirect matching. A mismatch here is a server
+            // contract violation (or an attack), never a usable code.
+            return err({
+                type: "invalid_response",
+                message: "complete response redirect_uri does not match the configured redirectUri",
+            });
+        }
+        return outcome;
+    };
+    const exchangeAuthorizationCode = async (input) => {
+        const pending = await consumePending(input.state);
+        if (pending === null) {
+            // Unknown, expired, or already-consumed state: possible CSRF/replay.
+            return err({ type: "state_mismatch" });
+        }
+        const issuerOutcome = await resolveIssuer();
+        if (!issuerOutcome.ok)
+            return issuerOutcome;
+        const body = {
+            grant_type: "authorization_code",
+            code: input.code,
+            redirect_uri: pending.redirectUri,
+            code_verifier: pending.codeVerifier,
+            client_id: config.clientId,
+            ...(config.resource !== undefined ? { resource: [...config.resource] } : {}),
+        };
+        const outcome = await requestJson(fetchPort, { method: "POST", url: `${issuerOutcome.value}/oauth2/token`, body }, tokenResponseSchema);
+        if (!outcome.ok)
+            return outcome;
+        return ok(await applyTokenResponse(outcome.value));
+    };
+    // --- hosted (redirect) authorization ------------------------------------------------------
+    const createHostedAuthorizationUrl = async () => {
+        const issuerOutcome = await resolveIssuer();
+        if (!issuerOutcome.ok)
+            return issuerOutcome;
+        const pkce = await generatePkcePair();
+        const state = generateState();
+        const nonce = generateNonce();
+        const params = new URLSearchParams();
+        params.set("response_type", "code");
+        params.set("client_id", config.clientId);
+        params.set("redirect_uri", config.redirectUri);
+        params.set("scope", scope);
+        params.set("state", state);
+        params.set("nonce", nonce);
+        params.set("code_challenge", pkce.challenge);
+        params.set("code_challenge_method", "S256");
+        for (const resource of config.resource ?? []) {
+            params.append("resource", resource);
+        }
+        await registerPending({
+            state,
+            nonce,
+            codeVerifier: pkce.verifier,
+            redirectUri: config.redirectUri,
+            createdAt: now(),
+        });
+        return ok({ url: `${issuerOutcome.value}/oauth2/authorize?${params.toString()}`, state });
+    };
+    const beginHostedAuthorization = async () => {
+        const outcome = await createHostedAuthorizationUrl();
+        if (!outcome.ok)
+            return outcome;
+        redirectPort.assign(outcome.value.url);
+        return ok({ state: outcome.value.state });
+    };
+    const handleHostedAuthorizationCallback = async (callbackUrl) => {
+        if (!URL.canParse(callbackUrl)) {
+            return err({ type: "invalid_response", message: "callback URL is not parseable" });
+        }
+        const url = new URL(callbackUrl);
+        const state = url.searchParams.get("state");
+        const errorParam = url.searchParams.get("error");
+        if (errorParam !== null) {
+            if (state !== null)
+                await consumePending(state);
+            // RFC 6749 §4.1.2.1 error redirect. The code list is closed; an unknown
+            // value means the callback is not contract-shaped.
+            if (!isOAuthErrorCode(errorParam)) {
+                return err({
+                    type: "invalid_response",
+                    message: `callback carried an unknown OAuth error: ${errorParam}`,
+                });
+            }
+            const description = url.searchParams.get("error_description");
+            return err({
+                type: "oauth_error",
+                code: errorParam,
+                ...(description !== null ? { description } : {}),
+            });
+        }
+        const code = url.searchParams.get("code");
+        if (code === null || state === null) {
+            if (state !== null)
+                await consumePending(state);
+            return err({ type: "invalid_response", message: "callback URL is missing code or state" });
+        }
+        return exchangeAuthorizationCode({ code, state });
+    };
+    // --- token / session management -------------------------------------------------------------
+    const refreshSession = () => {
+        if (inflightRefresh !== null)
+            return inflightRefresh;
+        const pending = (async () => {
+            const refreshToken = tokenSet?.refreshToken ?? null;
+            if (refreshToken === null) {
+                return err({ type: "not_authenticated" });
+            }
+            const issuerOutcome = await resolveIssuer();
+            if (!issuerOutcome.ok)
+                return issuerOutcome;
+            const body = {
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: config.clientId,
+                ...(config.resource !== undefined ? { resource: [...config.resource] } : {}),
+            };
+            const outcome = await requestJson(fetchPort, { method: "POST", url: `${issuerOutcome.value}/oauth2/token`, body }, tokenResponseSchema);
+            if (!outcome.ok) {
+                // design.md §21.7: invalid_grant kills the local session entirely;
+                // transient failures (network/5xx/429) must not.
+                if (outcome.error.type === "oauth_error" && outcome.error.code === "invalid_grant") {
+                    clearSession();
+                }
+                return outcome;
+            }
+            return ok(await applyTokenResponse(outcome.value));
+        })();
+        inflightRefresh = pending;
+        const clearInflight = () => {
+            if (inflightRefresh === pending)
+                inflightRefresh = null;
+        };
+        void pending.then(clearInflight, clearInflight);
+        return pending;
+    };
+    const getAccessToken = async () => {
+        if (tokenSet !== null && now() < tokenSet.accessTokenExpiresAt - EXPIRY_SKEW_MS) {
+            return ok(tokenSet.accessToken);
+        }
+        if (tokenSet !== null && tokenSet.refreshToken !== null) {
+            const refreshed = await refreshSession();
+            if (!refreshed.ok)
+                return refreshed;
+            const current = tokenSet;
+            if (current === null)
+                return err({ type: "not_authenticated" });
+            return ok(current.accessToken);
+        }
+        return err({ type: "not_authenticated" });
+    };
+    const restoreSession = async () => {
+        if (storage === undefined)
+            return err({ type: "not_authenticated" });
+        // A rejecting storage port is treated as "nothing persisted".
+        const persisted = await Promise.resolve()
+            .then(() => storage.load())
+            .then((value) => value, () => null);
+        if (persisted === null)
+            return err({ type: "not_authenticated" });
+        tokenSet = {
+            accessToken: "",
+            accessTokenExpiresAt: 0,
+            scope: "",
+            refreshToken: persisted,
+        };
+        return refreshSession();
+    };
+    const signOut = async () => {
+        const refreshToken = tokenSet?.refreshToken ?? null;
+        if (refreshToken !== null && cachedIssuer !== null) {
+            // Best-effort revocation (RFC 7009; design.md §15.8): the endpoint
+            // succeeds even for unknown tokens, and local cleanup proceeds
+            // regardless of the outcome.
+            const body = {
+                token: refreshToken,
+                token_type_hint: "refresh_token",
+                client_id: config.clientId,
+            };
+            await requestJson(fetchPort, { method: "POST", url: `${cachedIssuer}/oauth2/revoke`, body }, {
+                safeParse: () => ({ success: true, data: {} }),
+            });
+        }
+        clearSession();
+        return ok({ signedOut: true });
+    };
+    // --- /v1/me -------------------------------------------------------------------------
+    const authed = async (method, path, schema, body) => {
+        const token = await getAccessToken();
+        if (!token.ok)
+            return token;
+        return request(method, path, schema, {
+            accessToken: token.value,
+            ...(body !== undefined ? { body } : {}),
+        });
+    };
+    const getMe = () => authed("GET", "/v1/me", meUserSchema);
+    const updateMe = (input) => authed("PATCH", "/v1/me", meUpdateResponseSchema, input);
+    const listMyPasskeys = () => authed("GET", "/v1/me/passkeys", mePasskeysListResponseSchema);
+    const getMyPasskeyRegistrationOptions = () => authed("POST", "/v1/me/passkeys/registration/options", mePasskeyRegistrationOptionsResponseSchema, {});
+    const verifyMyPasskeyRegistration = (input) => authed("POST", "/v1/me/passkeys/registration/verify", mePasskeyRegistrationVerifyResponseSchema, input);
+    const registerMyPasskey = async (input) => {
+        if (!webAuthn.isAvailable()) {
+            return err({
+                type: "webauthn_error",
+                reason: "not_supported",
+                message: "WebAuthn is not available",
+            });
+        }
+        const options = await getMyPasskeyRegistrationOptions();
+        if (!options.ok)
+            return options;
+        const credential = await webAuthn.create(options.value);
+        if (!credential.ok)
+            return credential;
+        return verifyMyPasskeyRegistration({
+            credential: credential.value,
+            ...(input?.name !== undefined ? { name: input.name } : {}),
+        });
+    };
+    const deleteMyPasskey = (passkeyId) => authed("DELETE", `/v1/me/passkeys/${encodeSegment(passkeyId)}`, mePasskeyDeleteResponseSchema);
+    const listMyIdentities = () => authed("GET", "/v1/me/identities", meIdentitiesListResponseSchema);
+    const linkMyIdentity = (provider, input) => authed("POST", `/v1/me/identities/${encodeSegment(provider)}/link`, meIdentityLinkResponseSchema, input);
+    const unlinkMyIdentity = (identityId) => authed("DELETE", `/v1/me/identities/${encodeSegment(identityId)}`, meIdentityUnlinkResponseSchema);
+    const listMySessions = () => authed("GET", "/v1/me/sessions", meSessionsListResponseSchema);
+    const revokeMySession = (sessionId) => authed("DELETE", `/v1/me/sessions/${encodeSegment(sessionId)}`, meSessionRevokeResponseSchema);
+    const revokeAllMySessions = () => authed("DELETE", "/v1/me/sessions", meSessionsRevokeAllResponseSchema);
+    const startMyEmailChange = (input) => authed("POST", "/v1/me/email/change/start", meEmailChangeStartResponseSchema, input);
+    const verifyMyEmailChangeOld = (input) => authed("POST", "/v1/me/email/change/verify-old", meEmailChangeVerifyOldResponseSchema, input);
+    const verifyMyEmailChangeNew = (input) => authed("POST", "/v1/me/email/change/verify-new", meEmailChangeVerifyNewResponseSchema, input);
+    const deleteMyAccount = () => authed("DELETE", "/v1/me", meDeleteResponseSchema);
+    return {
+        getPublicConfig,
+        createTransaction,
+        getTransaction,
+        cancelTransaction,
+        startEmailOtp,
+        resendEmailOtp,
+        verifyEmailOtp,
+        getPasskeyRegistrationOptions,
+        verifyPasskeyRegistration,
+        startPasskeyRegistration,
+        getPasskeyAuthenticationOptions,
+        verifyPasskeyAuthentication,
+        startPasskeyAuthentication,
+        startSocialSignIn,
+        completeTransaction,
+        exchangeAuthorizationCode,
+        createHostedAuthorizationUrl,
+        beginHostedAuthorization,
+        handleHostedAuthorizationCallback,
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        isPasskeySupported: () => webAuthn.isAvailable(),
+        getAccessToken,
+        refreshSession,
+        restoreSession,
+        signOut,
+        getMe,
+        updateMe,
+        listMyPasskeys,
+        getMyPasskeyRegistrationOptions,
+        verifyMyPasskeyRegistration,
+        registerMyPasskey,
+        deleteMyPasskey,
+        listMyIdentities,
+        linkMyIdentity,
+        unlinkMyIdentity,
+        listMySessions,
+        revokeMySession,
+        revokeAllMySessions,
+        startMyEmailChange,
+        verifyMyEmailChangeOld,
+        verifyMyEmailChangeNew,
+        deleteMyAccount,
+    };
+};

package/dist/errors.d.ts

@@ -0,0 +1,95 @@
+import type { OAuthErrorCode } from "@smartcrab/contracts-public";
+/**
+ * Error model for `@smartcrab/browser` (design.md §26.3, §32).
+ *
+ * Every client method resolves to `Outcome<T, BrowserAuthError>`; nothing
+ * throws for expected failure modes. The union mirrors what the public API
+ * can actually put on the wire:
+ *
+ * - `network_error` — fetch itself failed (DNS, TLS, abort, CORS). Retryable.
+ * - `invalid_response` — a 2xx body failed the contracts-public zod schema,
+ *   an error body was not Problem Details / OAuth error shaped, or the body
+ *   was not JSON at all. Never trust the wire (IMPL_NOTES §1).
+ * - `rate_limited` — HTTP 429; `retryAfterSeconds` reflects the `Retry-After`
+ *   header when present (design.md §22's rate limit surface).
+ * - `problem_details` — RFC 9457 body from the API (`code` is the snake_case
+ *   platform error code, e.g. `invalid_request`, `not_found`).
+ * - `oauth_error` — RFC 6749 §5.2 error from the token endpoint (the
+ *   `OAUTH_ERROR_CODES` set from contracts-public).
+ * - `state_mismatch` — an authorization/complete callback carried a `state`
+ *   the client never issued (CSRF/replay protection, design.md §32.1).
+ * - `not_authenticated` — a token was required but none is held and no
+ *   refresh path exists.
+ * - `webauthn_error` — the platform authenticator ceremony failed or is
+ *   unavailable (design.md §17, §21.2 normalization rule).
+ */
+export interface NetworkFailureError {
+    readonly type: "network_error";
+    readonly message: string;
+    readonly retryable: true;
+}
+export interface InvalidResponseError {
+    readonly type: "invalid_response";
+    readonly message: string;
+    /** HTTP status of the offending response, when a response was received at all. */
+    readonly status?: number;
+}
+export interface RateLimitedError {
+    readonly type: "rate_limited";
+    readonly retryable: true;
+    /** Whole-second delay from the `Retry-After` header; absent when the server sent none. */
+    readonly retryAfterSeconds?: number;
+    readonly requestId?: string;
+}
+export interface ProblemDetailsError {
+    readonly type: "problem_details";
+    /** `type` URI from the Problem Details body. */
+    readonly problemType: string;
+    /** Platform snake_case error code (`code` extension member). */
+    readonly code: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail?: string;
+    readonly requestId?: string;
+}
+export interface OAuthFailureError {
+    readonly type: "oauth_error";
+    readonly code: OAuthErrorCode;
+    readonly description?: string;
+    /** HTTP status for token-endpoint errors; absent for front-channel (redirect) errors. */
+    readonly status?: number;
+}
+export interface StateMismatchError {
+    readonly type: "state_mismatch";
+}
+export interface NotAuthenticatedError {
+    readonly type: "not_authenticated";
+}
+export type WebAuthnFailureReason = "not_supported" | "cancelled" | "failed";
+export interface WebAuthnFailureError {
+    readonly type: "webauthn_error";
+    readonly reason: WebAuthnFailureReason;
+    readonly message: string;
+}
+export type BrowserAuthError = NetworkFailureError | InvalidResponseError | RateLimitedError | ProblemDetailsError | OAuthFailureError | StateMismatchError | NotAuthenticatedError | WebAuthnFailureError;
+/** Validated RFC 9457 Problem Details body as sent by the platform (design.md §26.3). */
+export interface ProblemDetailsWire {
+    readonly type: string;
+    readonly title: string;
+    readonly status: number;
+    readonly detail?: string;
+    readonly code?: string;
+    readonly requestId?: string;
+}
+/**
+ * Narrows an already-JSON-parsed body to the Problem Details shape. Field
+ * types are checked one by one; extension members are ignored (carried by the
+ * server for its own diagnostics, not part of the client contract).
+ */
+export declare const parseProblemDetailsWire: (value: unknown) => ProblemDetailsWire | null;
+/** Validated RFC 6749 §5.2 error body (token endpoint). */
+export interface OAuthErrorWire {
+    readonly error: string;
+    readonly description?: string;
+}
+export declare const parseOAuthErrorWire: (value: unknown) => OAuthErrorWire | null;