@remit/web-client 0.0.32 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.32",
+  "version": "0.0.33",
   "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/better-auth-config.ts

@@ -29,12 +29,78 @@ 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";
+
 interface CachedToken {
 	value: string;
 	expiresAt: number;
 }
 
+const tokenStore = (): Storage | null => {
+	try {
+		return globalThis.sessionStorage ?? null;
+	} catch {
+		return null;
+	}
+};
+
+const readStore = (): CachedToken | null => {
+	const raw = tokenStore()?.getItem(STORAGE_KEY);
+	if (!raw) return null;
+	try {
+		const parsed: unknown = JSON.parse(raw);
+		if (
+			parsed &&
+			typeof parsed === "object" &&
+			typeof (parsed as CachedToken).value === "string" &&
+			typeof (parsed as CachedToken).expiresAt === "number"
+		) {
+			return {
+				value: (parsed as CachedToken).value,
+				expiresAt: (parsed as CachedToken).expiresAt,
+			};
+		}
+	} catch {
+		// A corrupt entry is treated as no token.
+	}
+	return null;
+};
+
+const writeStore = (token: CachedToken | null): void => {
+	const store = tokenStore();
+	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: CachedToken | null = 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 = (): CachedToken | null => {
+	if (cached) return cached;
+	cached = readStore();
+	return cached;
+};
 
 const nowSeconds = (): number => Math.floor(Date.now() / 1000);
 
@@ -103,6 +169,8 @@ const mint = (): Promise<string> => {
 	inFlight = requestToken()
 		.then((token) => {
 			cached = { value: token, expiresAt: decodeExp(token) };
+			writeStore(cached);
+			backoffUntil = 0;
 			return token;
 		})
 		.finally(() => {
@@ -111,23 +179,49 @@ const mint = (): Promise<string> => {
 	return inFlight;
 };
 
+const isFresh = (token: CachedToken): boolean =>
+	token.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds();
+
+const isUsable = (token: CachedToken): boolean =>
+	token.expiresAt > nowSeconds();
+
 /**
  * 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.
  *
- * 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.
+ * A throttled or failed 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. Only a mint with nothing usable to fall back to
+ * 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> => {
-	if (cached && cached.expiresAt - EXPIRY_SKEW_SECONDS > nowSeconds()) {
-		return cached.value;
+	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 (current && isUsable(current)) {
+			backoffUntil = nowSeconds() + REFRESH_BACKOFF_SECONDS;
+			return current.value;
+		}
+		throw error;
 	}
-	return mint();
 };
 
 export const resetBetterAuthTokenCache = (): void => {
+	backoffUntil = 0;
+	writeStore(null);
 	cached = null;
 };

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

@@ -13,12 +13,21 @@ const base64url = (value: string): string =>
 		.replace(/\//g, "_")
 		.replace(/=+$/, "");
 
-/** A token shaped like the one better-auth mints, valid for an hour. */
-const jwt = (label: string): string =>
+/** A token shaped like the one better-auth mints, expiring after `ttl` seconds. */
+const jwtExpiringIn = (label: string, ttl: number): string =>
 	`header.${base64url(
-		JSON.stringify({ exp: Math.floor(Date.now() / 1000) + 3600, label }),
+		JSON.stringify({ exp: Math.floor(Date.now() / 1000) + ttl, label }),
 	)}.signature`;
 
+/** A token shaped like the one better-auth mints, valid for an hour. */
+const jwt = (label: string): string => jwtExpiringIn(label, 3600);
+
+/**
+ * A token past its comfortable-refresh window but not yet expired: `getToken`
+ * treats it as needing a refresh while still holding it as a usable fallback.
+ */
+const nearExpiryJwt = (label: string): string => jwtExpiringIn(label, 30);
+
 const realFetch = globalThis.fetch;
 
 interface Stub {
@@ -149,4 +158,64 @@ describe("fetchBetterAuthToken", () => {
 			/could not be completed|Failed to fetch/i,
 		);
 	});
+
+	test("a throttled refresh keeps the still-valid token instead of discarding it", async () => {
+		const seed = stubTokenEndpoint(() =>
+			tokenResponse(nearExpiryJwt("still-valid")),
+		);
+		seed.release();
+		const held = await fetchBetterAuthToken();
+
+		const throttled = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+		throttled.release();
+		const afterThrottle = await fetchBetterAuthToken();
+
+		assert.equal(throttled.calls, 1);
+		assert.equal(afterThrottle, held);
+	});
+
+	test("after a throttled refresh it backs off rather than hammering the endpoint", async () => {
+		const seed = stubTokenEndpoint(() =>
+			tokenResponse(nearExpiryJwt("still-valid")),
+		);
+		seed.release();
+		const held = await fetchBetterAuthToken();
+
+		const throttled = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+		throttled.release();
+		await fetchBetterAuthToken();
+
+		const first = await fetchBetterAuthToken();
+		const second = await fetchBetterAuthToken();
+
+		assert.equal(throttled.calls, 1);
+		assert.equal(first, held);
+		assert.equal(second, held);
+	});
+
+	test("a throttled refresh with no usable token to fall back on still throws", async () => {
+		const seed = stubTokenEndpoint(() =>
+			tokenResponse(jwtExpiringIn("already-expired", -10)),
+		);
+		seed.release();
+		await fetchBetterAuthToken();
+
+		const throttled = stubTokenEndpoint(
+			() => new Response("", { status: 429, statusText: "Too Many Requests" }),
+		);
+		throttled.release();
+
+		await assert.rejects(
+			() => fetchBetterAuthToken(),
+			(error: unknown) => {
+				assert.ok(error instanceof AuthTokenError);
+				assert.equal(error.status, 429);
+				return true;
+			},
+		);
+	});
 });