@remit/web-client 0.0.1

package/src/auth/auth-error.ts

@@ -0,0 +1,107 @@
+import { getErrorStatus, isAbortError } from "@/lib/error-classifier";
+import { reportFatalError } from "@/lib/fatal-error";
+
+/**
+ * How an auth (better-auth) failure should surface.
+ *
+ *  - "network"    — the request never reached the server (offline / unreachable).
+ *                   Inline, correctable by the user: check the connection.
+ *  - "validation" — an expected, user-correctable rejection the server
+ *                   described (email already registered, weak password, wrong
+ *                   credentials). Inline, surfacing the server's own message.
+ *  - "fatal"      — a 404, or any other unexpected 4xx/5xx from our own API. The
+ *                   deployment or the client/server contract is broken and there
+ *                   is nothing the user can retry their way out of. Escalates to
+ *                   the full-screen fatal page with a bug-report link.
+ */
+export type AuthErrorClass = "network" | "validation" | "fatal";
+
+/** The request being attempted, for a fatal report that names method and path. */
+export interface AuthRequest {
+	method: string;
+	path: string;
+}
+
+/** better-auth's client sentinel for a fetch that never got an HTTP response. */
+const FETCH_ERROR_STATUS_TEXT = "Fetch Error";
+
+const readString = (error: unknown, key: string): string | undefined => {
+	if (error && typeof error === "object" && key in error) {
+		const value = (error as Record<string, unknown>)[key];
+		if (typeof value === "string" && value.trim().length > 0) return value;
+	}
+	return undefined;
+};
+
+/** The human message better-auth attaches to a known, expected rejection. */
+export const authServerMessage = (error: unknown): string | undefined =>
+	readString(error, "message");
+
+const isNetworkFailure = (error: unknown): boolean => {
+	if (isAbortError(error)) return false;
+	if (readString(error, "statusText") === FETCH_ERROR_STATUS_TEXT) return true;
+	return getErrorStatus(error) === undefined;
+};
+
+/**
+ * Sort an auth failure into how it should surface. A 404 or any other
+ * unexpected 4xx/5xx from our own API is fatal — a broken deployment or
+ * contract, not something a retry fixes. Only a statusless connectivity failure
+ * or an expected, server-described rejection stays inline.
+ */
+export const classifyAuthError = (error: unknown): AuthErrorClass => {
+	if (isNetworkFailure(error)) return "network";
+	const status = getErrorStatus(error);
+	if (status === undefined) return "fatal";
+	if (status === 404 || status >= 500) return "fatal";
+	if (authServerMessage(error)) return "validation";
+	return "fatal";
+};
+
+const NETWORK_MESSAGE =
+	"Can't reach the server. You may be offline — check your connection and try again.";
+
+/** The inline banner text for a network or validation failure. */
+export const authInlineMessage = (
+	error: unknown,
+	kind: AuthErrorClass,
+): string => {
+	if (kind === "network") return NETWORK_MESSAGE;
+	return authServerMessage(error) ?? "Please check your details and try again.";
+};
+
+const statusSummary = (error: unknown): string => {
+	const status = getErrorStatus(error);
+	if (status === undefined) return "no response";
+	const statusText = readString(error, "statusText");
+	return statusText ? `${status} ${statusText}` : String(status);
+};
+
+/** The message shown on the fatal page and prefilled into the bug report. */
+export const buildFatalAuthMessage = (
+	error: unknown,
+	request: AuthRequest,
+): string => {
+	const summary = statusSummary(error);
+	const guidance =
+		getErrorStatus(error) === 404
+			? "The endpoint did not respond as expected — check that the backend is running and up to date (see the deployment guide's troubleshooting section)."
+			: "The server returned an unexpected response.";
+	const server = authServerMessage(error);
+	const serverLine = server ? ` Server said: ${server}.` : "";
+	return `${request.method} ${request.path} failed: ${summary}. ${guidance}${serverLine}`;
+};
+
+/**
+ * Escalate an unexpected auth failure to the full-screen fatal page. The message
+ * names the method, path, and status; the overlay carries the bug-report link.
+ * Not recoverable — a broken route or contract does not resolve on retry.
+ */
+export const reportFatalAuthError = (
+	error: unknown,
+	request: AuthRequest,
+): void => {
+	reportFatalError(new Error(buildFatalAuthMessage(error, request)), {
+		recoverable: false,
+	});
+};

package/src/auth/auth-interceptor.test.ts

@@ -0,0 +1,86 @@
+import assert from "node:assert";
+import { describe, test } from "node:test";
+import { type AuthProvider, noneAuthProvider } from "./provider";
+
+type RequestFn = (req: Request) => Promise<Request>;
+
+declare global {
+	// eslint-disable-next-line no-var
+	var __REMIT_CLIENT_MOCKS__: { requestFns: RequestFn[] } | undefined;
+}
+
+let cacheBust = 1000;
+
+const providerWithToken = (
+	getToken: AuthProvider["getToken"],
+): AuthProvider => ({ ...noneAuthProvider, getToken });
+
+const loadInterceptor = async () => {
+	cacheBust += 1;
+	globalThis.__REMIT_CLIENT_MOCKS__ = { requestFns: [] };
+	return import(`./auth-interceptor.ts?v=${cacheBust}`);
+};
+
+describe("installAuthInterceptor", () => {
+	test("registers exactly one request interceptor", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(providerWithToken(async () => null));
+		assert.equal(globalThis.__REMIT_CLIENT_MOCKS__?.requestFns.length, 1);
+	});
+
+	test("is idempotent — subsequent calls do not register additional interceptors", async () => {
+		const mod = await loadInterceptor();
+		const provider = providerWithToken(async () => null);
+		mod.installAuthInterceptor(provider);
+		mod.installAuthInterceptor(provider);
+		mod.installAuthInterceptor(provider);
+		assert.equal(globalThis.__REMIT_CLIENT_MOCKS__?.requestFns.length, 1);
+	});
+
+	test("attaches the provider's Bearer token when one exists", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(providerWithToken(async () => "ID-TOKEN-123"));
+		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
+		assert.ok(fn, "expected interceptor fn to be registered");
+		const req = new Request("https://api.example.com/thing");
+		const out = await fn(req);
+		assert.equal(out.headers.get("Authorization"), "Bearer ID-TOKEN-123");
+	});
+
+	test("omits Authorization header when the provider returns no token", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(providerWithToken(async () => null));
+		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
+		assert.ok(fn);
+		const req = new Request("https://api.example.com/thing");
+		const out = await fn(req);
+		assert.equal(out.headers.get("Authorization"), null);
+	});
+
+	test("preserves caller-supplied headers when adding Authorization", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(providerWithToken(async () => "TOK"));
+		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
+		assert.ok(fn);
+		const req = new Request("https://api.example.com/thing", {
+			headers: { "X-Trace-Id": "abc-123", "Content-Type": "application/json" },
+		});
+		const out = await fn(req);
+		assert.equal(out.headers.get("X-Trace-Id"), "abc-123");
+		assert.equal(out.headers.get("Content-Type"), "application/json");
+		assert.equal(out.headers.get("Authorization"), "Bearer TOK");
+	});
+
+	test("propagates errors when the provider's getToken rejects (let it crash)", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(
+			providerWithToken(async () => {
+				throw new Error("session fetch failed");
+			}),
+		);
+		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];
+		assert.ok(fn);
+		const req = new Request("https://api.example.com/thing");
+		await assert.rejects(() => fn(req), /session fetch failed/);
+	});
+});

package/src/auth/auth-interceptor.ts

@@ -0,0 +1,23 @@
+import { client } from "@remit/api-http-client/client.gen.ts";
+import type { AuthProvider } from "./provider";
+
+let installed = false;
+
+/**
+ * Attach the composed provider's bearer token to every API request. Called once
+ * from `mountApp` with the app's chosen provider, so the token source is the
+ * same `AuthProvider` the shell and screens read — no separate seam.
+ */
+export const installAuthInterceptor = (authProvider: AuthProvider): void => {
+	if (installed) return;
+
+	client.interceptors.request.use(async (request) => {
+		const token = await authProvider.getToken();
+		if (token) {
+			request.headers.set("Authorization", `Bearer ${token}`);
+		}
+		return request;
+	});
+
+	installed = true;
+};

package/src/auth/auth.css

@@ -0,0 +1,334 @@
+/*
+ * Auth screen — explicit structural overrides for the Amplify Authenticator.
+ *
+ * Strategy: unlayered CSS beats every @layer (including Tailwind preflight
+ * and @layer amplify). All selectors are scoped to [data-auth-page] so
+ * nothing outside the sign-in screen is affected.
+ *
+ * We own ALL structural styling — tab layout, spacing, active highlight,
+ * field/label padding, input sizing, button sizing, form container padding.
+ * Colors come from remit-ui CSS vars (--accent, --surface, --fg, --line, …)
+ * which the Amplify <ThemeProvider> tokens in AuthShell.tsx also reference,
+ * so the two systems stay in sync without duplication.
+ *
+ * Do not add rules for colors here — use the ThemeProvider tokens in
+ * AuthShell.tsx for that.
+ */
+
+/* ------------------------------------------------------------------ */
+/* Router / form container                                              */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] [data-amplify-authenticator] {
+  display: block;
+  width: 100%;
+}
+
+[data-auth-page] [data-amplify-authenticator] [data-amplify-container] {
+  width: 100%;
+  place-self: unset;
+}
+
+[data-auth-page] [data-amplify-authenticator] [data-amplify-router] {
+  border-radius: 7px;
+  overflow: hidden;
+  border-width: 1px;
+  border-style: solid;
+  border-color: var(--line);
+  background-color: var(--surface);
+  box-shadow:
+    0 10px 30px -10px rgb(15 23 42 / 0.18),
+    0 4px 12px -6px rgb(15 23 42 / 0.1);
+}
+
+[data-auth-page] [data-amplify-authenticator] [data-amplify-form] {
+  padding: 1.75rem;
+}
+
+[data-auth-page] [data-amplify-authenticator] [data-amplify-footer] {
+  padding-bottom: 1rem;
+  text-align: center;
+}
+
+/* ------------------------------------------------------------------ */
+/* Tabs — Sign In / Create Account                                      */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] .amplify-tabs__list {
+  display: flex;
+  flex-direction: row;
+  gap: 0;
+  background-color: transparent;
+  border-bottom: 2px solid var(--line);
+  border-top: none;
+  border-left: none;
+  border-right: none;
+  box-shadow: none;
+}
+
+[data-auth-page] .amplify-tabs__item {
+  position: relative;
+  flex: 1 1 0;
+  box-sizing: border-box;
+  background-color: transparent;
+  color: var(--fg-muted);
+  font-size: 0.875rem;
+  font-weight: 600;
+  text-align: center;
+  padding: 0.875rem 1rem;
+  border: none;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -2px;
+  cursor: pointer;
+  transition: color 0.15s, border-color 0.15s;
+  outline: none;
+  letter-spacing: 0;
+}
+
+[data-auth-page] .amplify-tabs__item:hover {
+  color: var(--accent);
+  background-color: transparent;
+  cursor: pointer;
+}
+
+[data-auth-page] .amplify-tabs__item--active,
+[data-auth-page] .amplify-tabs__item[data-state="active"] {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+  background-color: transparent;
+}
+
+[data-auth-page] .amplify-tabs__item:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: -2px;
+  z-index: 2;
+}
+
+[data-auth-page] .amplify-tabs__panel {
+  display: none;
+  padding: 0;
+}
+
+[data-auth-page] .amplify-tabs__panel--active {
+  display: block;
+}
+
+/* ------------------------------------------------------------------ */
+/* Flex utility used throughout the form                                */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] .amplify-flex {
+  display: flex;
+  align-items: stretch;
+  flex-wrap: nowrap;
+  gap: 1rem;
+}
+
+/* ------------------------------------------------------------------ */
+/* Fields and labels                                                    */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] .amplify-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  font-size: 1rem;
+  width: 100%;
+}
+
+[data-auth-page] .amplify-label {
+  display: block;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  color: var(--fg);
+  margin-bottom: 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* Inputs                                                               */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] .amplify-input {
+  display: block;
+  box-sizing: border-box;
+  width: 100%;
+  font-size: 0.9375rem;
+  line-height: 1.5;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  padding-left: 0.875rem;
+  padding-right: 0.875rem;
+  border-width: 1px;
+  border-style: solid;
+  border-color: var(--line);
+  border-radius: 5px;
+  background-color: var(--surface);
+  color: var(--fg);
+  outline: none;
+  transition: border-color 0.15s, box-shadow 0.15s;
+  -webkit-user-select: text;
+     -moz-user-select: text;
+          user-select: text;
+}
+
+[data-auth-page] .amplify-input:focus {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 2px var(--accent);
+}
+
+[data-auth-page] .amplify-input[disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+/* password field inner group */
+[data-auth-page] .amplify-field-group {
+  display: flex;
+  width: 100%;
+}
+
+[data-auth-page] .amplify-field-group .amplify-input {
+  flex: 1 1 0;
+  border-top-right-radius: 0;
+  border-bottom-right-radius: 0;
+}
+
+[data-auth-page] .amplify-field-group__outer-end {
+  display: flex;
+}
+
+[data-auth-page] .amplify-field-group__outer-end .amplify-button {
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+  border-left: none;
+}
+
+/* ------------------------------------------------------------------ */
+/* Buttons                                                              */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] .amplify-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  font-size: 0.9375rem;
+  font-weight: 600;
+  line-height: 1.5;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
+  padding-left: 1rem;
+  padding-right: 1rem;
+  border-radius: 5px;
+  border-width: 1px;
+  border-style: solid;
+  cursor: pointer;
+  transition: background-color 0.15s, color 0.15s, border-color 0.15s;
+  -webkit-user-select: none;
+     -moz-user-select: none;
+          user-select: none;
+  white-space: nowrap;
+}
+
+/* primary — "Sign In" / "Create Account" submit */
+[data-auth-page] .amplify-button--primary {
+  width: 100%;
+  background-color: var(--accent);
+  color: var(--accent-fg);
+  border-color: var(--accent);
+}
+
+[data-auth-page] .amplify-button--primary:hover {
+  background-color: var(--accent-hover);
+  border-color: var(--accent-hover);
+  color: var(--accent-fg);
+}
+
+[data-auth-page] .amplify-button--primary:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* default — secondary / password-reveal */
+[data-auth-page] .amplify-button--default {
+  background-color: transparent;
+  color: var(--fg);
+  border-color: var(--line);
+}
+
+[data-auth-page] .amplify-button--default:hover {
+  background-color: var(--surface-sunken);
+  border-color: var(--line);
+}
+
+/* link — "Forgot your password?" etc. */
+[data-auth-page] .amplify-button--link {
+  background-color: transparent;
+  border-color: transparent;
+  color: var(--accent);
+  padding-left: 0;
+  padding-right: 0;
+  font-weight: 500;
+}
+
+[data-auth-page] .amplify-button--link:hover {
+  background-color: transparent;
+  border-color: transparent;
+  color: var(--accent);
+  text-decoration: underline;
+}
+
+/* ------------------------------------------------------------------ */
+/* Form vertical rhythm — space between fields                          */
+/* ------------------------------------------------------------------ */
+
+[data-auth-page] [data-amplify-form] .amplify-flex[data-orientation="vertical"] {
+  flex-direction: column;
+  gap: 1.125rem;
+}
+
+/* submit button row */
+[data-auth-page] [data-amplify-form] .amplify-button--primary {
+  margin-top: 0.5rem;
+}
+
+/* "or" divider */
+[data-auth-page] .amplify-divider {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: var(--fg-muted);
+  font-size: 0.75rem;
+  margin: 0.5rem 0;
+}
+
+[data-auth-page] .amplify-divider::before,
+[data-auth-page] .amplify-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background-color: var(--line);
+}
+
+/* error / alert */
+[data-auth-page] .amplify-alert {
+  font-size: 0.8125rem;
+  padding: 0.625rem 0.875rem;
+  border-radius: 5px;
+  border-width: 1px;
+  border-style: solid;
+}
+
+/* password show/hide icon button */
+[data-auth-page] .amplify-field__show-password {
+  background-color: transparent;
+  border-left-width: 1px;
+  border-left-style: solid;
+  border-left-color: var(--line);
+  border-top-color: var(--line);
+  border-right-color: var(--line);
+  border-bottom-color: var(--line);
+  color: var(--fg-muted);
+  padding-left: 0.75rem;
+  padding-right: 0.75rem;
+}

package/src/auth/better-auth/BetterAuthAccount.tsx

@@ -0,0 +1,25 @@
+import { authClient, resetBetterAuthTokenCache } from "../better-auth-config";
+import type { AuthAccountProps } from "../provider";
+
+/**
+ * better-auth identity for the account affordances. Reads the active session
+ * from its session hook; signing out also clears the cached bearer token so a
+ * stale token never rides a post-sign-out request.
+ */
+export const BetterAuthAccount = ({
+	children,
+	fallback = null,
+}: AuthAccountProps) => {
+	const { data: session } = authClient.useSession();
+
+	if (!session) {
+		return <>{fallback}</>;
+	}
+
+	const signOut = async () => {
+		await authClient.signOut();
+		resetBetterAuthTokenCache();
+	};
+
+	return <>{children({ email: session.user.email ?? null, signOut })}</>;
+};

package/src/auth/better-auth-config.ts

@@ -0,0 +1,85 @@
+import { createAuthClient } from "better-auth/react";
+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 = (): boolean =>
+	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: unknown): boolean =>
+	typeof error === "object" &&
+	error !== null &&
+	(error as { code?: unknown }).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;
+
+interface CachedToken {
+	value: string;
+	expiresAt: number;
+}
+
+let cached: CachedToken | null = null;
+
+const nowSeconds = (): number => Math.floor(Date.now() / 1000);
+
+const decodeExp = (token: string): number => {
+	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();
+	}
+};
+
+const requestToken = async (): Promise<string | null> => {
+	const res = await fetch("/api/auth/token", { credentials: "include" });
+	if (!res.ok) return null;
+	const body: unknown = await res.json();
+	if (
+		body &&
+		typeof body === "object" &&
+		"token" in body &&
+		typeof (body as { token: unknown }).token === "string"
+	) {
+		return (body as { token: string }).token;
+	}
+	return null;
+};
+
+/**
+ * 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.
+ */
+export const fetchBetterAuthToken = async (): Promise<string | null> => {
+	if (cached && cached.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds()) {
+		return cached.value;
+	}
+	const token = await requestToken();
+	cached = token ? { value: token, expiresAt: decodeExp(token) } : null;
+	return token;
+};
+
+export const resetBetterAuthTokenCache = (): void => {
+	cached = null;
+};

package/src/auth/better-auth-provider.tsx

@@ -0,0 +1,20 @@
+import { BetterAuthShell } from "./BetterAuthShell";
+import { BetterAuthAccount } from "./better-auth/BetterAuthAccount";
+import {
+	fetchBetterAuthToken,
+	resetBetterAuthTokenCache,
+} from "./better-auth-config";
+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 const betterAuthProvider: AuthProvider = {
+	configure: () => {},
+	getToken: fetchBetterAuthToken,
+	resetToken: resetBetterAuthTokenCache,
+	Shell: BetterAuthShell,
+	Account: BetterAuthAccount,
+};