@growth-labs/auth 0.12.0 → 0.14.0

package/src/utils/tokens.ts

@@ -3,6 +3,7 @@ import { JWTExpired } from 'jose/errors'
 import type { TokenRefreshResult } from '../types.js'
 import { createClientSecretBasicAuthHeader } from './client-secret-header.js'
 import { extractIdentityId } from './identity.js'
+import { singleFlightRefresh } from './refresh-flight.js'
 
 type JWKSFunction = ReturnType<typeof createLocalJWKSet>
 
@@ -231,14 +232,55 @@ function tokenResultFromClaims(
 	}
 }
 
-export async function refreshTokens(
+/**
+ * Why a refresh produced no tokens. `invalid_grant` is the issuer saying it does
+ * not recognise this refresh token — the strongest signal there is, but NOT
+ * proof: the issuer's token store is eventually consistent, so a token only
+ * seconds old can read as missing from another location. Every other reason may
+ * simply pass on a later request. A caller must never discard the session on
+ * any of them; signing in again overwrites the cookies without help.
+ */
+export type RefreshFailureReason =
+	| 'invalid_grant'
+	| 'issuer_rejected'
+	| 'issuer_error'
+	| 'malformed_response'
+	| 'claims_rejected'
+	| 'network'
+	| 'not_configured'
+	/** The refresher returned nothing and did not say why. */
+	| 'unreported'
+
+export interface RefreshFailure {
+	reason: RefreshFailureReason
+	/** HTTP status of the issuer's answer, when there was one. */
+	status?: number
+	/** The OAuth `error` code the issuer returned, when it was readable. */
+	error?: string
+}
+
+async function oauthErrorCode(response: Response): Promise<string | undefined> {
+	try {
+		const body: unknown = await response.json()
+		const code = (body as { error?: unknown } | null)?.error
+		return typeof code === 'string' ? code : undefined
+	} catch {
+		return undefined
+	}
+}
+
+interface RefreshExchange {
+	result: TokenRefreshResult | null
+	failure: RefreshFailure | null
+}
+
+async function exchangeRefreshToken(
 	issuer: string,
 	refreshToken: string,
-	clientId?: string,
-	clientSecret?: string,
-	resource?: string,
-): Promise<TokenRefreshResult | null> {
-	if (!resource) return null
+	clientId: string | undefined,
+	clientSecret: string | undefined,
+	resource: string,
+): Promise<RefreshExchange> {
 	try {
 		const params = new URLSearchParams({
 			grant_type: 'refresh_token',
@@ -260,18 +302,71 @@ export async function refreshTokens(
 			body: params.toString(),
 		})
 
-		if (!response.ok) return null
+		if (!response.ok) {
+			const error = await oauthErrorCode(response)
+			const reason: RefreshFailureReason =
+				error === 'invalid_grant'
+					? 'invalid_grant'
+					: response.status >= 500
+						? 'issuer_error'
+						: 'issuer_rejected'
+			return {
+				result: null,
+				failure: { reason, status: response.status, ...(error ? { error } : {}) },
+			}
+		}
 
-		const data = await response.json()
-		if (!tokenResponseHasTokens(data)) return null
+		const data: unknown = await response.json().catch(() => null)
+		if (!tokenResponseHasTokens(data)) {
+			return { result: null, failure: { reason: 'malformed_response', status: response.status } }
+		}
 
 		const claims = await verifyIssuedAccessTokenClaims(issuer, data.access_token, resource)
-		if (!claims) return null
+		if (!claims) {
+			return { result: null, failure: { reason: 'claims_rejected', status: response.status } }
+		}
 
-		return tokenResultFromClaims(data.access_token, data.refresh_token, claims)
+		return {
+			result: tokenResultFromClaims(data.access_token, data.refresh_token, claims),
+			failure: null,
+		}
 	} catch {
+		return { result: null, failure: { reason: 'network' } }
+	}
+}
+
+/**
+ * Exchange a refresh token for new tokens. Concurrent calls for the same token
+ * (same issuer, client and resource) within one isolate share a single
+ * exchange and receive its outcome — see `refresh-flight.ts` for why the scope
+ * is the isolate and nothing is cached once the flight settles. `onFailure` is
+ * this caller's own reporter and fires for followers as well as the leader.
+ */
+export async function refreshTokens(
+	issuer: string,
+	refreshToken: string,
+	clientId?: string,
+	clientSecret?: string,
+	resource?: string,
+	onFailure?: (failure: RefreshFailure) => void,
+): Promise<TokenRefreshResult | null> {
+	// Reporting is advisory: a callback that throws must not change the outcome.
+	const report = (failure: RefreshFailure): void => {
+		try {
+			onFailure?.(failure)
+		} catch {
+			/* the caller's reporter is not this function's failure */
+		}
+	}
+	if (!resource) {
+		report({ reason: 'not_configured' })
 		return null
 	}
+	const exchange = await singleFlightRefresh([issuer, clientId ?? '', resource, refreshToken], () =>
+		exchangeRefreshToken(issuer, refreshToken, clientId, clientSecret, resource),
+	)
+	if (exchange.failure) report(exchange.failure)
+	return exchange.result
 }
 
 export function decodeJwtPayload(jwt: string): Record<string, unknown> {

package/src/workers.ts

@@ -3,6 +3,8 @@ import { getCookie, setCookie } from './utils/cookies.js'
 import { extractIdentityId } from './utils/identity.js'
 import { resolveInternalIssuer } from './utils/issuer.js'
 import { generatePKCE } from './utils/pkce.js'
+import { classifyRefreshCarrier, prefetchDeferredResponse } from './utils/refresh-carrier.js'
+import { singleFlightRefresh } from './utils/refresh-flight.js'
 import { generateState, verifyState } from './utils/state.js'
 import { type VerifiedClaims, verifyAccessToken } from './utils/tokens.js'
 
@@ -87,6 +89,13 @@ export interface Session {
 	Principal: Principal | null
 	Tokens: Tokens | null
 	Refreshed: boolean
+	/**
+	 * The request carried a refresh token that was deliberately not spent: it
+	 * is a beacon or a prefetch whose response the browser would not apply, so
+	 * the next consumable request refreshes instead (0.14.0). A guest request,
+	 * nothing more; never clear cookies on it.
+	 */
+	Deferred?: true
 }
 
 export interface WorkersAuthVariables {
@@ -671,12 +680,22 @@ async function getSessionNormalized(
 		}
 	}
 	if (refreshToken) {
+		// Only a response the browser is waiting for can deliver the rotated
+		// token; a beacon or prefetch is answered as a guest (refresh-carrier.ts).
+		if (classifyRefreshCarrier(request) !== 'consumable') {
+			return { Principal: null, Tokens: null, Refreshed: false, Deferred: true }
+		}
 		const form = new URLSearchParams()
 		form.set('grant_type', 'refresh_token')
 		form.set('refresh_token', refreshToken)
 		form.set('client_id', config.clientId)
 		form.set('resource', config.resource)
-		const result = await requestTokens(config, request, form)
+		// Concurrent requests presenting the same token share one exchange
+		// (refresh-flight.ts); the leader's request resolves the client secret.
+		const result = await singleFlightRefresh(
+			[config.issuerInternal, config.clientId, config.resource, refreshToken],
+			() => requestTokens(config, request, form),
+		)
 		if (result) {
 			return { Principal: result.principal, Tokens: result.tokens, Refreshed: true }
 		}
@@ -727,6 +746,11 @@ export function Middleware(config: WorkersAuthConfig): WorkersAuthMiddleware {
 		}
 		context.set('session', session)
 		context.set('principal', session.Principal)
+		// A prefetched page rendered as a guest would be shown to the member on
+		// navigation as if they had signed out; a non-2xx is dropped instead.
+		if (session.Deferred && classifyRefreshCarrier(request) === 'prefetch') {
+			return prefetchDeferredResponse()
+		}
 		if (!session.Principal && isGated(normalized, new URL(request.url).pathname)) {
 			const login = new URL(normalized.loginPath, request.url)
 			login.searchParams.set('redirect', new URL(request.url).pathname)