@remit/web-client 0.0.29 → 0.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

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

@@ -1,5 +1,6 @@
 import assert from "node:assert";
 import { describe, test } from "node:test";
+import { AuthTokenError } from "./better-auth-config";
 import { type AuthProvider, noneAuthProvider } from "./provider";
 
 type RequestFn = (req: Request) => Promise<Request>;
@@ -47,7 +48,28 @@ describe("installAuthInterceptor", () => {
 		assert.equal(out.headers.get("Authorization"), "Bearer ID-TOKEN-123");
 	});
 
-	test("omits Authorization header when the provider returns no token", async () => {
+	test("abandons the request when the token cannot be minted — never sends it unauthenticated", async () => {
+		const mod = await loadInterceptor();
+		mod.installAuthInterceptor(
+			providerWithToken(async () => {
+				throw new AuthTokenError("Could not mint a session token: 429", 429);
+			}),
+		);
+		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),
+			(error: unknown) => {
+				assert.ok(error instanceof AuthTokenError);
+				assert.equal(error.status, 429);
+				return true;
+			},
+		);
+		assert.equal(req.headers.get("Authorization"), null);
+	});
+
+	test("omits Authorization header when the deployment presents no identity", async () => {
 		const mod = await loadInterceptor();
 		mod.installAuthInterceptor(providerWithToken(async () => null));
 		const fn = globalThis.__REMIT_CLIENT_MOCKS__?.requestFns[0];

package/src/auth/auth-interceptor.ts

@@ -7,6 +7,11 @@ 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.
+ *
+ * A provider that cannot produce a token throws, and that throw is left to
+ * propagate: the request is abandoned rather than sent without an Authorization
+ * header. Only the deployments that present no identity at all resolve to null,
+ * and for those an unauthenticated request is the intended one.
  */
 export const installAuthInterceptor = (authProvider: AuthProvider): void => {
 	if (installed) return;

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

@@ -51,11 +51,32 @@ const decodeExp = (token: string): number => {
 	}
 };
 
-const requestToken = async (): Promise<string | null> => {
+/**
+ * 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 {
+	readonly status: number | undefined;
+
+	constructor(message: string, status?: number) {
+		super(message);
+		this.name = "AuthTokenError";
+		this.status = status;
+	}
+}
+
+const requestToken = async (): Promise<string> => {
 	const res = await taggedFetch("/api/auth/token", {
 		credentials: "include",
 	});
-	if (!res.ok) return null;
+	if (!res.ok) {
+		throw new AuthTokenError(
+			`Could not mint a session token: ${res.status} ${res.statusText}`,
+			res.status,
+		);
+	}
 	const body: unknown = await res.json();
 	if (
 		body &&
@@ -65,7 +86,29 @@ const requestToken = async (): Promise<string | null> => {
 	) {
 		return (body as { token: string }).token;
 	}
-	return null;
+	throw new AuthTokenError("The token endpoint returned no token");
+};
+
+let inFlight: Promise<string> | null = 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 = (): Promise<string> => {
+	if (inFlight) return inFlight;
+	inFlight = requestToken()
+		.then((token) => {
+			cached = { value: token, expiresAt: decodeExp(token) };
+			return token;
+		})
+		.finally(() => {
+			inFlight = null;
+		});
+	return inFlight;
 };
 
 /**
@@ -73,14 +116,16 @@ const requestToken = async (): Promise<string | null> => {
  * 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.
+ *
+ * Never resolves to null: a failed mint throws. 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 (): Promise<string | null> => {
+export const fetchBetterAuthToken = async (): Promise<string> => {
 	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;
+	return mint();
 };
 
 export const resetBetterAuthTokenCache = (): void => {

package/src/auth/better-auth-token.test.ts

@@ -0,0 +1,152 @@
+import assert from "node:assert";
+import { afterEach, describe, test } from "node:test";
+import {
+	AuthTokenError,
+	fetchBetterAuthToken,
+	resetBetterAuthTokenCache,
+} from "./better-auth-config";
+
+const base64url = (value: string): string =>
+	Buffer.from(value, "utf8")
+		.toString("base64")
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+
+/** A token shaped like the one better-auth mints, valid for an hour. */
+const jwt = (label: string): string =>
+	`header.${base64url(
+		JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600, label }),
+	)}.signature`;
+
+const realFetch = globalThis.fetch;
+
+interface Stub {
+	calls: number;
+	release: () => void;
+}
+
+/** Stand in for the token endpoint, holding every request open until released. */
+const stubTokenEndpoint = (respond: (call: number) => Response): Stub => {
+	let open: () => void = () => {};
+	const gate = new Promise<void>((resolve) => {
+		open = resolve;
+	});
+	const stub: Stub = { calls: 0, release: () => open() };
+	globalThis.fetch = (async (input: RequestInfo | URL) => {
+		assert.match(String(input), /\/api\/auth\/token$/);
+		stub.calls += 1;
+		const call = stub.calls;
+		await gate;
+		return respond(call);
+	}) as typeof fetch;
+	return stub;
+};
+
+const tokenResponse = (token: string): Response =>
+	new Response(JSON.stringify({ token }), {
+		status: 200,
+		headers: { "Content-Type": "application/json" },
+	});
+
+afterEach(() => {
+	globalThis.fetch = realFetch;
+	resetBetterAuthTokenCache();
+});
+
+describe("fetchBetterAuthToken", () => {
+	test("concurrent callers share one mint instead of each firing their own", async () => {
+		const stub = stubTokenEndpoint((call) => tokenResponse(jwt(`t${call}`)));
+
+		const pending = Array.from({ length: 12 }, () => fetchBetterAuthToken());
+		stub.release();
+		const tokens = await Promise.all(pending);
+
+		assert.equal(stub.calls, 1);
+		assert.equal(new Set(tokens).size, 1);
+	});
+
+	test("a token minted once is reused from cache, without a second request", async () => {
+		const stub = stubTokenEndpoint(() => tokenResponse(jwt("cached")));
+		stub.release();
+
+		const first = await fetchBetterAuthToken();
+		const second = await fetchBetterAuthToken();
+
+		assert.equal(stub.calls, 1);
+		assert.equal(second, first);
+	});
+
+	test("a rejected mint throws with its status rather than resolving to null", async () => {
+		const stub = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+		stub.release();
+
+		await assert.rejects(
+			() => fetchBetterAuthToken(),
+			(error: unknown) => {
+				assert.ok(error instanceof AuthTokenError);
+				assert.equal(error.status, 429);
+				return true;
+			},
+		);
+	});
+
+	test("a response carrying no token throws rather than resolving to null", async () => {
+		const stub = stubTokenEndpoint(
+			() =>
+				new Response(JSON.stringify({}), {
+					status: 200,
+					headers: { "Content-Type": "application/json" },
+				}),
+		);
+		stub.release();
+
+		await assert.rejects(() => fetchBetterAuthToken(), AuthTokenError);
+	});
+
+	test("every caller sharing a failed mint sees the failure", async () => {
+		const stub = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+
+		const pending = Array.from({ length: 5 }, () =>
+			fetchBetterAuthToken().then(
+				() => "resolved",
+				(error: unknown) =>
+					error instanceof AuthTokenError ? "threw" : "other",
+			),
+		);
+		stub.release();
+		const outcomes = await Promise.all(pending);
+
+		assert.equal(stub.calls, 1);
+		assert.deepEqual(new Set(outcomes), new Set(["threw"]));
+	});
+
+	test("a failed mint is not replayed — the next caller mints again", async () => {
+		const failing = stubTokenEndpoint(() => new Response("", { status: 500 }));
+		failing.release();
+		await assert.rejects(() => fetchBetterAuthToken());
+
+		const succeeding = stubTokenEndpoint(() =>
+			tokenResponse(jwt("after-failure")),
+		);
+		succeeding.release();
+
+		assert.ok(await fetchBetterAuthToken());
+		assert.equal(succeeding.calls, 1);
+	});
+
+	test("a network failure propagates instead of yielding a tokenless request", async () => {
+		globalThis.fetch = (async () => {
+			throw new TypeError("Failed to fetch");
+		}) as typeof fetch;
+
+		await assert.rejects(
+			() => fetchBetterAuthToken(),
+			/could not be completed|Failed to fetch/i,
+		);
+	});
+});

package/src/auth/provider.tsx

@@ -22,9 +22,14 @@ export interface AuthProvider {
 	/** Called once at boot, before render, to initialize the identity SDK. */
 	configure(): void;
 	/**
-	 * The current session's bearer token, or `null` when signed out. The API
-	 * interceptor and the raw content fetch read it through here, so the identity
-	 * SDK stays inside the provider.
+	 * 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. */