@remit/web-client 0.0.325 → 0.0.326

package/dist/src/auth/better-auth-config.js

@@ -0,0 +1,215 @@
+import { createAuthClient } from "better-auth/react";
+import { NetworkError, taggedFetch } from "../lib/network-error";
+import { sessionStore } from "../lib/session-storage";
+import { getRuntimeConfig } from "../runtime-config";
+/**
+ * better-auth owns identity in the Postgres-parity / local mode. It is gated
+ * behind an explicit flag so the Cognito path and the existing no-auth e2e
+ * bypass are untouched unless a deployment opts in.
+ */
+export const isBetterAuthEnabled = () => getRuntimeConfig().betterAuthEnabled;
+/**
+ * Error code better-auth returns from `/sign-up/email` when signup is closed
+ * server-side (`disableSignUp`, driven by `SELF_SIGN_UP_ENABLED`). The client
+ * uses it as the single source of truth for the closed state, so the UI can
+ * never drift from the server.
+ */
+export const SIGN_UP_DISABLED_CODE = "EMAIL_PASSWORD_SIGN_UP_DISABLED";
+export const isSignUpDisabledError = (error) => typeof error === "object" &&
+    error !== null &&
+    error.code === SIGN_UP_DISABLED_CODE;
+// Same-origin: the client calls `/api/auth/*`, which the dev proxy forwards to
+// the backend's mounted better-auth handler.
+export const authClient = createAuthClient();
+const EXPIRY_SKEW_SECONDS = 60;
+// How long to stop reaching for the token endpoint after a mint is throttled.
+// A near-expiry token is still usable for `EXPIRY_SKEW_SECONDS`, so backing off
+// keeps a throttled window from turning every request into another mint attempt
+// against an endpoint that already said no.
+const REFRESH_BACKOFF_SECONDS = 30;
+// Survives page reloads and in-tab navigations so a fresh page load reuses the
+// session's token instead of minting a new one. Cleared on sign-out. Scoped to
+// the tab, not the origin: the token is short-lived and the httpOnly session
+// cookie remains the real credential.
+const STORAGE_KEY = "remit.better-auth.token";
+const readStore = () => {
+    const raw = sessionStore()?.getItem(STORAGE_KEY);
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed &&
+            typeof parsed === "object" &&
+            typeof parsed.value === "string" &&
+            typeof parsed.expiresAt === "number") {
+            return {
+                value: parsed.value,
+                expiresAt: parsed.expiresAt,
+            };
+        }
+    }
+    catch {
+        // A corrupt entry is treated as no token.
+    }
+    return null;
+};
+const writeStore = (token) => {
+    const store = sessionStore();
+    if (!store)
+        return;
+    try {
+        if (!token) {
+            store.removeItem(STORAGE_KEY);
+            return;
+        }
+        store.setItem(STORAGE_KEY, JSON.stringify(token));
+    }
+    catch {
+        // Storage being unavailable (private mode, quota) is not fatal: the
+        // in-memory cache still serves the current page.
+    }
+};
+let cached = null;
+let backoffUntil = 0;
+// Hydrate the in-memory cache from storage on first read of a page load, so a
+// token minted before a reload is reused rather than re-minted.
+const currentCache = () => {
+    if (cached)
+        return cached;
+    cached = readStore();
+    return cached;
+};
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+const decodeExp = (token) => {
+    const [, payload] = token.split(".");
+    if (!payload)
+        return nowSeconds();
+    try {
+        const json = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+        return typeof json.exp === "number" ? json.exp : nowSeconds();
+    }
+    catch {
+        return nowSeconds();
+    }
+};
+/**
+ * A session exists but no bearer token could be produced for it. Distinct from
+ * "signed out": there is nothing to fall back to, so the request that needed the
+ * token must not be sent. Carries the mint's HTTP status where there was one, so
+ * the shared classifier reads it like any other API failure.
+ */
+export class AuthTokenError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "AuthTokenError";
+        this.status = status;
+    }
+}
+const requestToken = async () => {
+    const res = await taggedFetch("/api/auth/token", {
+        credentials: "include",
+    });
+    if (!res.ok) {
+        throw new AuthTokenError(`Could not mint a session token: ${res.status} ${res.statusText}`, res.status);
+    }
+    const body = await res.json();
+    if (body &&
+        typeof body === "object" &&
+        "token" in body &&
+        typeof body.token === "string") {
+        return body.token;
+    }
+    throw new AuthTokenError("The token endpoint returned no token");
+};
+let inFlight = null;
+/**
+ * One mint at a time. A cold load renders many screens at once and each of their
+ * requests needs the same token; without this every one of them mints its own,
+ * and the burst is large enough to spend the auth tier's rate-limit budget. The
+ * slot is released once the mint settles, so a failure is not replayed to later
+ * callers — they mint again.
+ */
+const mint = () => {
+    if (inFlight)
+        return inFlight;
+    inFlight = requestToken()
+        .then((token) => {
+        cached = { value: token, expiresAt: decodeExp(token) };
+        writeStore(cached);
+        backoffUntil = 0;
+        return token;
+    })
+        .finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+};
+const isFresh = (token) => token.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds();
+const isUsable = (token) => token.expiresAt > nowSeconds();
+/**
+ * A mint failure the held token is allowed to ride out: a request timeout (408),
+ * throttling (429), a server-side fault (5xx), or a transport failure that never
+ * reached the server. These say nothing about the session's validity, so keeping
+ * the token the tab already holds is correct. A 4xx that is not 408 or 429 does
+ * not qualify — least of all a 401/403, which is the server revoking the session.
+ */
+const isTransientMintFailure = (error) => {
+    if (error instanceof NetworkError)
+        return true;
+    if (error instanceof AuthTokenError) {
+        return (error.status === 408 || error.status === 429 || (error.status ?? 0) >= 500);
+    }
+    return false;
+};
+/**
+ * The mint was refused because the session is no longer valid. The held token is
+ * signed for that same revoked session, so it must be discarded rather than
+ * served until it expires.
+ */
+const isRevocation = (error) => error instanceof AuthTokenError &&
+    (error.status === 401 || error.status === 403);
+/**
+ * Return a valid RS256 JWT for the current session, minting a fresh one only
+ * when the cached token is missing or within the skew window of expiry. The API
+ * interceptor attaches it as a Bearer token; the backend verifies it against the
+ * JWKS.
+ *
+ * A throttled, faulted, or unreachable refresh never discards a token that is
+ * still usable: the request keeps the session it already holds and the endpoint
+ * is left alone until the backoff clears. A revocation (401/403) is the opposite
+ * — the session behind the held token is gone, so it is cleared and the failure
+ * propagates to re-authentication rather than serving a dead token until expiry.
+ * Only a mint with nothing usable to fall back to throws otherwise — returning
+ * null would put the request on the wire without an Authorization header, and the
+ * backend answers that with a 401 that names a missing token rather than the mint
+ * that failed.
+ */
+export const fetchBetterAuthToken = async () => {
+    const current = currentCache();
+    if (current && isFresh(current)) {
+        return current.value;
+    }
+    if (current && isUsable(current) && nowSeconds() < backoffUntil) {
+        return current.value;
+    }
+    try {
+        return await mint();
+    }
+    catch (error) {
+        if (isRevocation(error)) {
+            resetBetterAuthTokenCache();
+            throw error;
+        }
+        if (current && isUsable(current) && isTransientMintFailure(error)) {
+            backoffUntil = nowSeconds() + REFRESH_BACKOFF_SECONDS;
+            return current.value;
+        }
+        throw error;
+    }
+};
+export const resetBetterAuthTokenCache = () => {
+    backoffUntil = 0;
+    writeStore(null);
+    cached = null;
+};

package/dist/src/auth/better-auth-provider.d.ts

@@ -0,0 +1,7 @@
+import type { AuthProvider } from "./provider";
+/**
+ * better-auth identity (the self-host default). Amplify is never referenced
+ * from this module or anything it imports, so a build that composes only this
+ * provider ships no Cognito code.
+ */
+export declare const betterAuthProvider: AuthProvider;

package/dist/src/auth/better-auth-provider.js

@@ -0,0 +1,15 @@
+import { BetterAuthShell } from "./BetterAuthShell";
+import { BetterAuthAccount } from "./better-auth/BetterAuthAccount";
+import { fetchBetterAuthToken, resetBetterAuthTokenCache, } from "./better-auth-config";
+/**
+ * better-auth identity (the self-host default). Amplify is never referenced
+ * from this module or anything it imports, so a build that composes only this
+ * provider ships no Cognito code.
+ */
+export const betterAuthProvider = {
+    configure: () => { },
+    getToken: fetchBetterAuthToken,
+    resetToken: resetBetterAuthTokenCache,
+    Shell: BetterAuthShell,
+    Account: BetterAuthAccount,
+};

package/dist/src/auth/cognito/CognitoAccount.d.ts

@@ -0,0 +1,8 @@
+import type { AuthAccountProps } from "../provider";
+/**
+ * Cognito identity for the account affordances. `useAuthenticator` throws when
+ * called outside `Authenticator.Provider`, which `CognitoShell` only mounts
+ * once Cognito is configured — so the hook-using inner is gated on that,
+ * constant for the app's lifetime, keeping the Rules of Hooks intact.
+ */
+export declare const CognitoAccount: ({ children, fallback, }: AuthAccountProps) => import("react").JSX.Element;

package/dist/src/auth/cognito/CognitoAccount.js

@@ -0,0 +1,32 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useAuthenticator } from "@aws-amplify/ui-react";
+import { isCognitoConfigured } from "../amplify-config";
+import { isSignOutVisible } from "../sign-out-visibility";
+const cognitoUserEmail = (user) => {
+    if (!user)
+        return null;
+    return user.signInDetails?.loginId ?? user.username ?? null;
+};
+const CognitoAccountInner = ({ children, fallback = null, }) => {
+    const { authStatus, signOut, user } = useAuthenticator((ctx) => [
+        ctx.authStatus,
+        ctx.signOut,
+        ctx.user,
+    ]);
+    if (!isSignOutVisible({ configured: true, authStatus })) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return (_jsx(_Fragment, { children: children({ email: cognitoUserEmail(user), signOut: () => signOut() }) }));
+};
+/**
+ * Cognito identity for the account affordances. `useAuthenticator` throws when
+ * called outside `Authenticator.Provider`, which `CognitoShell` only mounts
+ * once Cognito is configured — so the hook-using inner is gated on that,
+ * constant for the app's lifetime, keeping the Rules of Hooks intact.
+ */
+export const CognitoAccount = ({ children, fallback = null, }) => {
+    if (!isCognitoConfigured()) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return (_jsx(CognitoAccountInner, { fallback: fallback, children: children }));
+};

package/dist/src/auth/cognito/CognitoShell.d.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from "react";
+interface CognitoShellProps {
+    children: ReactNode;
+}
+export declare const CognitoShell: ({ children }: CognitoShellProps) => import("react").JSX.Element;
+export {};

package/dist/src/auth/cognito/CognitoShell.js

@@ -0,0 +1,204 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Authenticator, createTheme, ThemeProvider, useAuthenticator, } from "@aws-amplify/ui-react";
+import { AuthCard, AuthFooter, AuthHero, Banner } from "@remit/ui";
+import { AppShellSkeleton } from "../../components/layout/AppShellSkeleton";
+import { authFooterNote } from "../account-menu-mode";
+import { isCognitoConfigured } from "../amplify-config";
+const REMIT_FONT = 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+const cssVar = (name) => `var(${name})`;
+/* remit-ui semantic vars (tokens.css declares these on :root / .dark).
+   We reference the raw vars — not the Tailwind `--color-*` aliases —
+   because the `@theme inline` block inlines those into utilities rather
+   than guaranteeing them as custom properties. */
+const BRAND = cssVar("--accent");
+const BRAND_HOVER = cssVar("--accent-hover");
+const BRAND_SOFT = cssVar("--accent-soft");
+const BRAND_FG = cssVar("--accent-fg");
+const CARD_BG = cssVar("--surface");
+const CARD_FG = cssVar("--fg");
+const PAGE_BG = cssVar("--surface-sunken");
+const MUTED_FG = cssVar("--fg-muted");
+const BORDER = cssVar("--line");
+const remitTheme = createTheme({
+    name: "remit",
+    tokens: {
+        colors: {
+            brand: {
+                primary: {
+                    10: { value: BRAND_SOFT },
+                    20: { value: BRAND_SOFT },
+                    40: { value: BRAND },
+                    60: { value: BRAND },
+                    80: { value: BRAND },
+                    90: { value: BRAND },
+                    100: { value: BRAND },
+                },
+            },
+            background: {
+                primary: { value: CARD_BG },
+                secondary: { value: PAGE_BG },
+            },
+            font: {
+                primary: { value: CARD_FG },
+                secondary: { value: MUTED_FG },
+                tertiary: { value: MUTED_FG },
+                interactive: { value: BRAND },
+                inverse: { value: BRAND_FG },
+                hover: { value: BRAND },
+                focus: { value: BRAND },
+                active: { value: BRAND },
+            },
+            border: {
+                primary: { value: BORDER },
+                secondary: { value: BORDER },
+                focus: { value: BRAND },
+            },
+        },
+        fonts: {
+            default: {
+                variable: { value: REMIT_FONT },
+                static: { value: REMIT_FONT },
+            },
+        },
+        radii: {
+            /* Literal values from the remit-ui radius scale (2/3/5/7/10px).
+               Tailwind's `@theme inline` only emits theme variables that are
+               referenced from compiled CSS — var(--radius-*) lookups from
+               this JS theme object are invisible to its scanner, so they
+               would resolve to nothing at runtime. */
+            small: { value: "3px" },
+            medium: { value: "5px" },
+            large: { value: "7px" },
+        },
+        components: {
+            authenticator: {
+                router: {
+                    borderColor: { value: BORDER },
+                    borderWidth: { value: "1px" },
+                    boxShadow: {
+                        value: "0 10px 30px -10px rgb(15 23 42 / 0.18), 0 4px 12px -6px rgb(15 23 42 / 0.1)",
+                    },
+                    backgroundColor: { value: CARD_BG },
+                },
+                form: {
+                    padding: { value: "1.75rem" },
+                },
+                orContainer: {
+                    color: { value: MUTED_FG },
+                },
+            },
+            button: {
+                color: { value: CARD_FG },
+                primary: {
+                    backgroundColor: { value: BRAND },
+                    color: { value: BRAND_FG },
+                    _hover: {
+                        backgroundColor: { value: BRAND_HOVER },
+                        color: { value: BRAND_FG },
+                    },
+                    _focus: {
+                        backgroundColor: { value: BRAND },
+                        color: { value: BRAND_FG },
+                    },
+                    _active: {
+                        backgroundColor: { value: BRAND },
+                        color: { value: BRAND_FG },
+                    },
+                },
+                link: {
+                    color: { value: BRAND },
+                    _hover: {
+                        color: { value: BRAND },
+                        backgroundColor: { value: "transparent" },
+                    },
+                    _focus: {
+                        color: { value: BRAND },
+                        backgroundColor: { value: "transparent" },
+                    },
+                    _active: {
+                        color: { value: BRAND },
+                        backgroundColor: { value: "transparent" },
+                    },
+                },
+            },
+            fieldcontrol: {
+                color: { value: CARD_FG },
+                borderColor: { value: BORDER },
+                _focus: {
+                    borderColor: { value: BRAND },
+                    boxShadow: { value: `0 0 0 2px ${BRAND}` },
+                },
+            },
+            field: {
+                label: {
+                    color: { value: CARD_FG },
+                },
+            },
+            tabs: {
+                borderColor: { value: BORDER },
+                item: {
+                    color: { value: MUTED_FG },
+                    backgroundColor: { value: "transparent" },
+                    _active: {
+                        color: { value: BRAND },
+                        borderColor: { value: BRAND },
+                        backgroundColor: { value: "transparent" },
+                    },
+                    _hover: {
+                        color: { value: BRAND },
+                    },
+                    _focus: {
+                        color: { value: BRAND },
+                    },
+                },
+            },
+            heading: {
+                color: { value: CARD_FG },
+            },
+            text: {
+                color: { value: CARD_FG },
+            },
+        },
+    },
+});
+// Amplify's default placeholders are title-case ("Enter your Username"); the
+// design + app copy convention is lowercase (#883).
+const authFormFields = {
+    signIn: {
+        username: { placeholder: "Enter your username" },
+        password: { placeholder: "Enter your password" },
+    },
+    signUp: {
+        username: { placeholder: "Enter your username" },
+        password: { placeholder: "Enter your password" },
+        confirm_password: { placeholder: "Confirm your password" },
+    },
+};
+const LocalDevBanner = () => (_jsx(Banner, { tone: "warning", className: "fixed top-0 left-0 right-0 z-50 h-7 sm:h-10 overflow-hidden border-x-0 border-t-0", children: _jsxs("span", { className: "flex items-center gap-2", children: [_jsx("strong", { className: "font-semibold shrink-0", children: "Local dev" }), _jsx("span", { className: "truncate hidden sm:inline", children: "\u2014 Cognito not configured. Set VITE_COGNITO_USER_POOL_ID and VITE_COGNITO_CLIENT_ID in .env.local to enable sign-in." }), _jsx("span", { className: "truncate sm:hidden", children: "\u2014 no Cognito; signed out" })] }) }));
+const CognitoAuthFooter = () => (_jsx(AuthFooter, { note: authFooterNote({
+        betterAuthEnabled: false,
+        cognitoConfigured: isCognitoConfigured(),
+    }) }));
+const SignInGate = ({ children }) => {
+    const { authStatus } = useAuthenticator((ctx) => [ctx.authStatus]);
+    if (authStatus === "authenticated") {
+        return _jsx(_Fragment, { children: children });
+    }
+    // While Amplify hydrates a stored session, render the app-shell skeleton
+    // instead of flashing the sign-in form (or a blank screen) — most returning
+    // users resolve to `authenticated` and never see the form.
+    if (authStatus === "configuring") {
+        return _jsx(AppShellSkeleton, {});
+    }
+    return (_jsx(ThemeProvider, { theme: remitTheme, children: _jsxs(AuthCard, { children: [_jsx(AuthHero, {}), _jsx(Authenticator, { hideSignUp: false, formFields: authFormFields, components: { Footer: CognitoAuthFooter } })] }) }));
+};
+export const CognitoShell = ({ children }) => {
+    if (!isCognitoConfigured()) {
+        // The dev banner is fixed at the top. Pad content below it AND shrink the
+        // inner `main` (hardcoded `h-dvh`) by the banner height — otherwise main's
+        // full 100dvh starts below the 40px padding and overflows, pushing pinned
+        // footers like the compose Send bar 40px below the fold (#788).
+        return (_jsxs("div", { className: "pt-7 sm:pt-10 [&_#main-content]:h-[calc(100dvh-1.75rem)] sm:[&_#main-content]:h-[calc(100dvh-2.5rem)]", children: [_jsx(LocalDevBanner, {}), children] }));
+    }
+    return (_jsx(Authenticator.Provider, { children: _jsx(SignInGate, { children: children }) }));
+};

package/dist/src/auth/cognito/cognito-token.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The Cognito bearer token: the Amplify session's ID token, cached until it
+ * nears expiry. Returns `null` when Cognito is not configured (local dev), so
+ * the request simply carries no token. This is the `getToken` behind the
+ * Cognito auth provider — the `aws-amplify/auth` dependency lives here, never in
+ * the shell or a screen.
+ */
+export declare const getCognitoToken: () => Promise<string | null>;
+export declare const resetCognitoTokenCache: () => void;

package/dist/src/auth/cognito/cognito-token.js

@@ -0,0 +1,36 @@
+import { fetchAuthSession } from "aws-amplify/auth";
+import { isCognitoConfigured } from "../amplify-config";
+const EXPIRY_SKEW_SECONDS = 60;
+let cached = null;
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+const isUsable = (token) => token !== null && token.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds();
+const refreshCognitoToken = async () => {
+    const session = await fetchAuthSession();
+    const idToken = session.tokens?.idToken;
+    if (!idToken) {
+        cached = null;
+        return null;
+    }
+    cached = {
+        value: idToken.toString(),
+        expiresAt: idToken.payload.exp ?? nowSeconds() + EXPIRY_SKEW_SECONDS,
+    };
+    return cached.value;
+};
+/**
+ * The Cognito bearer token: the Amplify session's ID token, cached until it
+ * nears expiry. Returns `null` when Cognito is not configured (local dev), so
+ * the request simply carries no token. This is the `getToken` behind the
+ * Cognito auth provider — the `aws-amplify/auth` dependency lives here, never in
+ * the shell or a screen.
+ */
+export const getCognitoToken = async () => {
+    if (!isCognitoConfigured())
+        return null;
+    if (isUsable(cached))
+        return cached.value;
+    return refreshCognitoToken();
+};
+export const resetCognitoTokenCache = () => {
+    cached = null;
+};

package/dist/src/auth/cognito-provider.d.ts

@@ -0,0 +1,8 @@
+import type { AuthProvider } from "./provider";
+/**
+ * Cognito (AWS Amplify) identity. Importing this module is what pulls Amplify
+ * into a build — a distributor that composes a different provider never
+ * references it, so `aws-amplify` and `@aws-amplify/ui-react` stay out of that
+ * bundle.
+ */
+export declare const cognitoAuthProvider: AuthProvider;

package/dist/src/auth/cognito-provider.js

@@ -0,0 +1,17 @@
+import { configureAmplify } from "./amplify-config";
+import { CognitoAccount } from "./cognito/CognitoAccount";
+import { CognitoShell } from "./cognito/CognitoShell";
+import { getCognitoToken, resetCognitoTokenCache, } from "./cognito/cognito-token";
+/**
+ * Cognito (AWS Amplify) identity. Importing this module is what pulls Amplify
+ * into a build — a distributor that composes a different provider never
+ * references it, so `aws-amplify` and `@aws-amplify/ui-react` stay out of that
+ * bundle.
+ */
+export const cognitoAuthProvider = {
+    configure: configureAmplify,
+    getToken: getCognitoToken,
+    resetToken: resetCognitoTokenCache,
+    Shell: CognitoShell,
+    Account: CognitoAccount,
+};

package/dist/src/auth/combined-provider.d.ts

@@ -0,0 +1,2 @@
+import type { AuthProvider } from "./provider";
+export declare const combinedAuthProvider: AuthProvider;

package/dist/src/auth/combined-provider.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { configureAmplify } from "./amplify-config";
+import { isBetterAuthEnabled } from "./better-auth-config";
+import { betterAuthProvider } from "./better-auth-provider";
+import { cognitoAuthProvider } from "./cognito-provider";
+/**
+ * Both identity systems in one build, selected at runtime by
+ * `betterAuthEnabled`. This is the default composition and what
+ * `@remit/web-client-dist` ships — one artifact that serves a Cognito or a
+ * better-auth deployment depending on `config.js`. A distributor that wants a
+ * single provider composes `cognitoAuthProvider` or `betterAuthProvider`
+ * directly and omits the other.
+ */
+const CombinedShell = ({ children }) => isBetterAuthEnabled() ? (_jsx(betterAuthProvider.Shell, { children: children })) : (_jsx(cognitoAuthProvider.Shell, { children: children }));
+const CombinedAccount = (props) => isBetterAuthEnabled() ? (_jsx(betterAuthProvider.Account, { ...props })) : (_jsx(cognitoAuthProvider.Account, { ...props }));
+export const combinedAuthProvider = {
+    configure: configureAmplify,
+    getToken: () => isBetterAuthEnabled()
+        ? betterAuthProvider.getToken()
+        : cognitoAuthProvider.getToken(),
+    resetToken: () => {
+        betterAuthProvider.resetToken();
+        cognitoAuthProvider.resetToken();
+    },
+    Shell: CombinedShell,
+    Account: CombinedAccount,
+};

package/dist/src/auth/provider.d.ts

@@ -0,0 +1,51 @@
+import { type FC, type ReactNode } from "react";
+/**
+ * The auth-integration seam. A deployment composes the web client against
+ * exactly one provider — the identity system it runs — and never ships the
+ * others. `mountApp` receives the chosen provider and publishes it here; the
+ * app shell and every screen read it through `useAuthProvider`, so no surface
+ * imports a specific identity system directly.
+ */
+export interface AuthAccount {
+    email: string | null;
+    signOut: () => void | Promise<void>;
+}
+export interface AuthAccountProps {
+    children: (account: AuthAccount) => ReactNode;
+    /** Rendered when no session is active. Defaults to nothing. */
+    fallback?: ReactNode;
+}
+export interface AuthProvider {
+    /** Called once at boot, before render, to initialize the identity SDK. */
+    configure(): void;
+    /**
+     * The current session's bearer token. The API interceptor and the raw content
+     * fetch read it through here, so the identity SDK stays inside the provider.
+     *
+     * `null` means this deployment has no identity to present — no identity system
+     * is composed, or none is configured — and the request is expected to travel
+     * unauthenticated. It never means the token could not be produced: a provider
+     * that holds a session and fails to mint a token throws, because a request
+     * that cannot be authenticated must not be sent.
+     */
+    getToken(): Promise<string | null>;
+    /** Drop any cached token so the next `getToken` re-mints. */
+    resetToken(): void;
+    /** The sign-in gate: renders children only once a session is established. */
+    Shell: FC<{
+        children: ReactNode;
+    }>;
+    /**
+     * Render-prop over the active session's identity and sign-out action.
+     * Renders `fallback` when no session is active.
+     */
+    Account: FC<AuthAccountProps>;
+}
+/**
+ * The zero-identity provider. It has no session and no identity SDK, so a
+ * surface that renders without a mounted provider (an isolated component
+ * render, a harness) degrades to "signed out" instead of crashing.
+ */
+export declare const noneAuthProvider: AuthProvider;
+export declare const AuthProviderProvider: import("react").Provider<AuthProvider>;
+export declare const useAuthProvider: () => AuthProvider;

package/dist/src/auth/provider.js

@@ -0,0 +1,18 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const Passthrough = ({ children }) => (_jsx(_Fragment, { children: children }));
+/**
+ * The zero-identity provider. It has no session and no identity SDK, so a
+ * surface that renders without a mounted provider (an isolated component
+ * render, a harness) degrades to "signed out" instead of crashing.
+ */
+export const noneAuthProvider = {
+    configure: () => { },
+    getToken: async () => null,
+    resetToken: () => { },
+    Shell: Passthrough,
+    Account: ({ fallback = null }) => _jsx(_Fragment, { children: fallback }),
+};
+const AuthProviderContext = createContext(noneAuthProvider);
+export const AuthProviderProvider = AuthProviderContext.Provider;
+export const useAuthProvider = () => useContext(AuthProviderContext);