@growth-labs/auth 0.10.0 → 0.10.2

package/src/utils/client-secret.ts

@@ -1,22 +1,144 @@
 import { getRuntimeEnv } from '../runtime.js'
+import {
+	type ClientSecretLiteral,
+	isClientSecretLiteral,
+	literalClientSecret,
+} from './client-secret-literal.js'
 
-interface SecretsStoreBinding {
-	get(): Promise<string>
+export type { ClientSecretLiteral }
+export { isClientSecretLiteral, literalClientSecret }
+
+export type ClientSecretResolutionErrorCode =
+	| 'BINDING_REJECTED'
+	| 'BINDING_MALFORMED'
+	| 'BINDING_EMPTY'
+	| 'BINDING_MISSING'
+
+export type ClientSecretResult =
+	| { ok: true; secret: string | null }
+	| { ok: false; code: ClientSecretResolutionErrorCode }
+
+type PerRequestCache = Map<string, Promise<ClientSecretResult>>
+
+const CLIENT_SECRET_READ_TIMEOUT_MS = 5_000
+const CLIENT_SECRET_READ_TIMEOUT = Symbol('client-secret-read-timeout')
+
+// Module-private request-lifetime cache. The WeakMap is keyed strictly by
+// Request; entries are naturally collectible with the Request and are never
+// attached to consumer-visible Request properties or symbols.
+const requestCache = new WeakMap<Request, PerRequestCache>()
+
+function getPerRequestCache(request: Request): PerRequestCache {
+	let cache = requestCache.get(request)
+	if (!cache) {
+		cache = new Map<string, Promise<ClientSecretResult>>()
+		requestCache.set(request, cache)
+	}
+	return cache
 }
 
-export async function resolveClientSecret(clientSecret?: string): Promise<string | undefined> {
-	if (!clientSecret) return undefined
+async function doResolve(clientSecretName: string): Promise<ClientSecretResult> {
+	const runtimeEnv = getRuntimeEnv()
+	let hasOwnBinding: boolean
+	try {
+		hasOwnBinding = Object.hasOwn(runtimeEnv, clientSecretName)
+	} catch {
+		return { ok: false, code: 'BINDING_MALFORMED' }
+	}
+	if (!hasOwnBinding) return { ok: false, code: 'BINDING_MISSING' }
+
+	let runtimeValue: unknown
+	try {
+		runtimeValue = runtimeEnv[clientSecretName]
+	} catch {
+		return { ok: false, code: 'BINDING_MALFORMED' }
+	}
 
-	const runtimeValue = getRuntimeEnv()[clientSecret]
 	if (typeof runtimeValue === 'string') {
-		return runtimeValue.length > 0 ? runtimeValue : undefined
+		// Use trim() only to detect all-whitespace emptiness; return original bytes.
+		return runtimeValue.trim().length > 0
+			? { ok: true, secret: runtimeValue }
+			: { ok: false, code: 'BINDING_EMPTY' }
 	}
-	if (isSecretsStoreBinding(runtimeValue)) {
-		const resolved = await runtimeValue.get()
-		return resolved.length > 0 ? resolved : undefined
+
+	if (typeof runtimeValue === 'object' && runtimeValue !== null) {
+		let get: unknown
+		try {
+			get = Reflect.get(runtimeValue, 'get')
+		} catch {
+			return { ok: false, code: 'BINDING_MALFORMED' }
+		}
+		if (typeof get !== 'function') return { ok: false, code: 'BINDING_MALFORMED' }
+
+		let resolved: unknown
+		let timeoutId: ReturnType<typeof setTimeout> | undefined
+		try {
+			const timeout = new Promise<typeof CLIENT_SECRET_READ_TIMEOUT>((resolve) => {
+				timeoutId = setTimeout(
+					() => resolve(CLIENT_SECRET_READ_TIMEOUT),
+					CLIENT_SECRET_READ_TIMEOUT_MS,
+				)
+			})
+			const read = Promise.resolve(Reflect.apply(get, runtimeValue, []))
+			resolved = await Promise.race([read, timeout])
+		} catch {
+			return { ok: false, code: 'BINDING_REJECTED' }
+		} finally {
+			if (timeoutId !== undefined) clearTimeout(timeoutId)
+		}
+		if (resolved === CLIENT_SECRET_READ_TIMEOUT) {
+			return { ok: false, code: 'BINDING_REJECTED' }
+		}
+		if (typeof resolved !== 'string') return { ok: false, code: 'BINDING_MALFORMED' }
+		return resolved.trim().length > 0
+			? { ok: true, secret: resolved }
+			: { ok: false, code: 'BINDING_EMPTY' }
 	}
 
-	return clientSecret
+	// Own binding key exists but is neither a string nor a Secrets Store binding.
+	return { ok: false, code: 'BINDING_MALFORMED' }
+}
+
+export async function resolveClientSecret(
+	clientSecret: string | ClientSecretLiteral | undefined,
+	request?: Request,
+): Promise<ClientSecretResult> {
+	// undefined means no clientSecret is configured — public client
+	if (clientSecret === undefined) return { ok: true, secret: null }
+
+	// Explicit literal: use value directly, no binding lookup, no I/O, no caching.
+	if (isClientSecretLiteral(clientSecret)) {
+		const { value } = clientSecret
+		return value.trim().length > 0
+			? { ok: true, secret: value }
+			: { ok: false, code: 'BINDING_EMPTY' }
+	}
+
+	// Runtime config is a serialization boundary. Any object that was not
+	// explicitly rehydrated into a module-issued literal is malformed config,
+	// never a value on which string methods may be invoked.
+	if (typeof clientSecret !== 'string') {
+		return { ok: false, code: 'BINDING_MALFORMED' }
+	}
+
+	// Empty/whitespace-only binding name is invalid configuration, not a public client.
+	if (clientSecret.trim().length === 0) {
+		return { ok: false, code: 'BINDING_EMPTY' }
+	}
+
+	// Non-empty string: treat as a binding name, cache per (Request, name).
+	if (request) {
+		const cache = getPerRequestCache(request)
+		let pending = cache.get(clientSecret)
+		if (!pending) {
+			pending = doResolve(clientSecret)
+			cache.set(clientSecret, pending)
+		}
+		return pending
+	}
+
+	// No Request context: resolve without caching (test or internal call).
+	return doResolve(clientSecret)
 }
 
 export function createClientSecretBasicAuthHeader(clientId: string, clientSecret: string): string {
@@ -27,11 +149,3 @@ function formEncode(value: string): string {
 	const params = new URLSearchParams({ value })
 	return params.toString().slice('value='.length)
 }
-
-function isSecretsStoreBinding(value: unknown): value is SecretsStoreBinding {
-	return (
-		typeof value === 'object' &&
-		value !== null &&
-		typeof (value as { get?: unknown }).get === 'function'
-	)
-}

package/src/utils/fail-closed.ts

@@ -0,0 +1,74 @@
+import type { ClientSecretResolutionErrorCode } from './client-secret.js'
+
+export type ClientSecretFailureSurface =
+	| 'middleware_refresh'
+	| 'callback_exchange'
+	| 'logout_revocation'
+	| 'route_preflight'
+	| 'route_exchange'
+	| 'server_auth_client'
+
+export interface ClientSecretFailureSignal {
+	readonly surface: ClientSecretFailureSurface
+	readonly code: ClientSecretResolutionErrorCode
+}
+
+// Shared no-store headers for all secret-resolution failure responses.
+const SECURITY_HEADERS: Record<string, string> = {
+	'Cache-Control': 'private, no-store',
+	Pragma: 'no-cache',
+	Expires: '0',
+}
+
+function acceptsJson(request: Request | undefined): boolean {
+	const accept = request?.headers.get('accept') ?? ''
+	return accept
+		.split(',')
+		.some((value) => value.trim().toLowerCase().split(';')[0] === 'application/json')
+}
+
+// Fixed-vocabulary 503 for secret-resolution failures on all surfaces.
+// Browser callers receive bounded plain text; JSON callers receive one fixed
+// JSON error. Neither class reflects a path, provider, error code, raw error,
+// secret value, or stack. Callers must invoke this before issuer I/O.
+export function reportClientSecretResolutionFailure(signal: ClientSecretFailureSignal): void {
+	try {
+		console.error('[growth-labs/auth] client_secret_resolution_failed', {
+			surface: signal.surface,
+			code: signal.code,
+		})
+	} catch {
+		// Observability must never replace the bounded fail-closed response.
+	}
+}
+
+export function secretResolutionFailureResponse(
+	request?: Request,
+	signal?: ClientSecretFailureSignal,
+): Response {
+	if (signal) reportClientSecretResolutionFailure(signal)
+	if (acceptsJson(request)) {
+		return Response.json(
+			{ error: 'auth_service_unavailable' },
+			{ status: 503, headers: new Headers(SECURITY_HEADERS as HeadersInit) },
+		)
+	}
+
+	return new Response('Service unavailable', {
+		status: 503,
+		headers: new Headers({
+			...SECURITY_HEADERS,
+			'Content-Type': 'text/plain; charset=UTF-8',
+		}),
+	})
+}
+
+// Typed error thrown by server-helper headersFor() on secret binding failure.
+// Exported so consumers can distinguish secret-resolution failure from
+// network/credential failure in custom server-side auth flows.
+export class ClientSecretResolutionError extends Error {
+	override readonly name = 'ClientSecretResolutionError'
+	constructor(public readonly code: ClientSecretResolutionErrorCode) {
+		super('client_secret_binding_unavailable')
+	}
+}

package/src/utils/index.ts

@@ -10,6 +10,13 @@ export {
 	normalizeAuthProvider,
 	trackAuthEvent,
 } from './analytics.js'
+export type {
+	ClientSecretLiteral,
+	ClientSecretResolutionErrorCode,
+	ClientSecretResult,
+} from './client-secret.js'
+export { isClientSecretLiteral, literalClientSecret } from './client-secret.js'
+export { ClientSecretResolutionError } from './fail-closed.js'
 export {
 	type BridgeMigrationOptions,
 	type BridgeMigrationStatement,
@@ -25,7 +32,13 @@ export {
 	rewriteLegacyIdentitySubjects,
 } from './identity.js'
 export { signIdentityCookie, verifyIdentityCookie } from './identity-cookie.js'
-export { getAuthorizationUrl, getMagicLinkUrl, getPasswordLoginUrl } from './openauth.js'
+export {
+	EXCHANGE_SECRET_FAILURE,
+	type ExchangeSecretFailure,
+	getAuthorizationUrl,
+	getMagicLinkUrl,
+	getPasswordLoginUrl,
+} from './openauth.js'
 export { createPKCEChallenge, generatePKCE } from './pkce.js'
 export { generateState, verifyState } from './state.js'
 export type { VerifiedClaims } from './tokens.js'

package/src/utils/openauth.ts

@@ -1,6 +1,10 @@
 import { getConfig } from '../config-store.js'
 import type { TokenExchangeResult } from '../types.js'
-import { createClientSecretBasicAuthHeader, resolveClientSecret } from './client-secret.js'
+import {
+	type ClientSecretResolutionErrorCode,
+	createClientSecretBasicAuthHeader,
+	resolveClientSecret,
+} from './client-secret.js'
 import { resolveInternalIssuer } from './issuer.js'
 import { generatePKCE } from './pkce.js'
 import { generateState } from './state.js'
@@ -86,22 +90,42 @@ function tokenResponseHasTokens(
 	)
 }
 
+// Bounded sentinel returned when exchangeCode cannot resolve the client secret.
+// Callers check `'secretFailed' in result` to distinguish this from an
+// ordinary token-exchange failure (null) and route to a fail-closed 503
+// rather than a generic auth_failed redirect.
+export interface ExchangeSecretFailure {
+	readonly secretFailed: true
+	readonly code: ClientSecretResolutionErrorCode
+}
+
+// Backward-compatible exported sentinel for callers that only need a bounded
+// representative failure. Runtime exchangeCode results carry the actual code.
+export const EXCHANGE_SECRET_FAILURE: ExchangeSecretFailure = Object.freeze({
+	secretFailed: true,
+	code: 'BINDING_REJECTED',
+})
+
 export async function exchangeCode(
 	callbackUrl: URL,
 	code: string,
 	codeVerifier: string,
 	providerFromCookie?: TokenExchangeResult['provider'],
-): Promise<TokenExchangeResult | null> {
+	request?: Request,
+): Promise<TokenExchangeResult | ExchangeSecretFailure | null> {
 	const options = getConfig()
 	const issuer = resolveInternalIssuer(options)
 	const clientId = options.clientId || callbackUrl.hostname
 	const redirectUri = new URL(options.callbackPath, callbackUrl.origin).toString()
-	const clientSecret = await resolveClientSecret(options.clientSecret)
+	const secretResult = await resolveClientSecret(options.clientSecret, request)
+	if (!secretResult.ok) {
+		return Object.freeze({ secretFailed: true as const, code: secretResult.code })
+	}
 	const headers: Record<string, string> = {
 		'Content-Type': 'application/x-www-form-urlencoded',
 	}
-	if (clientSecret) {
-		headers.Authorization = createClientSecretBasicAuthHeader(clientId, clientSecret)
+	if (secretResult.secret) {
+		headers.Authorization = createClientSecretBasicAuthHeader(clientId, secretResult.secret)
 	}
 	const body = new URLSearchParams({
 		grant_type: 'authorization_code',