@growth-labs/auth 0.10.0 → 0.10.3

package/src/utils/csp.ts

@@ -0,0 +1,167 @@
+/**
+ * Self-contained Content-Security-Policy for auth renderer pages.
+ *
+ * WHY THIS EXISTS. The auth integration serves its UI surfaces (`/login`,
+ * `/verify-code`, `/password`, `/forgot-password`, `/reset-password`) from
+ * `injectRoute`-registered Astro endpoints that return a raw `Response` built
+ * from an HTML string. Astro's native hash-based `security.csp` only rewrites
+ * *component-rendered* pages — it scans the rendered document, hashes inline
+ * `<script>`/`<style>`, and injects a `<meta http-equiv>` CSP. An endpoint that
+ * returns its own `Response` bypasses that pass entirely, so on a site with an
+ * enforced `security.csp` the auth pages ship transport headers but NO CSP and
+ * their inline theme-bootstrap script is un-hashed (fulcrum-labs/warfronts
+ * verified live: `/login` 200, no `Content-Security-Policy` header or meta).
+ *
+ * This is the auth-side analogue of the `@growth-labs/consent@0.7.1`
+ * `context.csp.insertScriptHash` fix. Consent registers its banner hash and
+ * lets Astro render the CSP meta into the `.astro` page; auth has no Astro page
+ * to carry a meta, so it computes the sha256 hashes of its own inline scripts
+ * and styles and emits the `<meta http-equiv="Content-Security-Policy">` itself.
+ * Browsers combine a CSP meta with any CSP response header by intersection, so a
+ * site keeps owning the transport-header CSP (or none) while auth owns the meta
+ * on its own surfaces — exactly the model warfronts documents (CSP lives in the
+ * meta on SSR pages; the transport middleware never emits a CSP header).
+ */
+
+/** A sha256 CSP source expression, e.g. `sha256-<base64>`. */
+export type CspHash = `sha256-${string}`
+
+/**
+ * Compute the CSP sha256 hash of an inline `<script>`/`<style>` body. Hashes the
+ * exact bytes the browser hashes — the raw text between the element's open and
+ * close tags, with no trimming — so the emitted `'sha256-…'` matches what the
+ * browser recomputes for the served content. Mirrors the consent package's
+ * `sha256CspHash` (SHA-256 → base64) so the two packages stay wire-compatible.
+ */
+export async function sha256CspHash(content: string): Promise<CspHash> {
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(content))
+	const base64 = btoa(String.fromCharCode(...new Uint8Array(digest)))
+	return `sha256-${base64}`
+}
+
+/** Inner text of every inline `<script>` (no `src=`) and `<style>` element. */
+interface InlineSources {
+	scripts: string[]
+	styles: string[]
+}
+
+const INLINE_SCRIPT_RE = /<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi
+const INLINE_STYLE_RE = /<style\b[^>]*>([\s\S]*?)<\/style\s*>/gi
+const HAS_SRC_RE = /\bsrc\s*=/i
+
+/**
+ * Extract the inner bodies of inline `<script>` and `<style>` elements. A
+ * `<script src=…>` reference has no hashable body (its bytes live at another
+ * URL, covered by `script-src 'self'`) and is skipped. Empty bodies are skipped
+ * — an empty inline script needs no hash. De-duplicates identical bodies so an
+ * element repeated on a page contributes a single hash.
+ */
+export function extractInlineSources(html: string): InlineSources {
+	const scripts = new Set<string>()
+	const styles = new Set<string>()
+
+	for (const match of html.matchAll(INLINE_SCRIPT_RE)) {
+		const attrs = match[1] ?? ''
+		const body = match[2] ?? ''
+		if (HAS_SRC_RE.test(attrs)) continue
+		if (body.length === 0) continue
+		scripts.add(body)
+	}
+
+	for (const match of html.matchAll(INLINE_STYLE_RE)) {
+		const body = match[1] ?? ''
+		if (body.length === 0) continue
+		styles.add(body)
+	}
+
+	return { scripts: [...scripts], styles: [...styles] }
+}
+
+/** True when the document already carries a CSP `<meta http-equiv>` tag. */
+export function hasCspMeta(html: string): boolean {
+	return /<meta\b[^>]*\bhttp-equiv\s*=\s*["']?content-security-policy["']?/i.test(html)
+}
+
+/**
+ * Build the CSP policy string for an auth page from its inline-source hashes.
+ *
+ * - `default-src 'self'` is the floor; anything not otherwise named falls here.
+ * - `script-src 'self' <hashes>` allows same-origin scripts plus the exact
+ *   inline scripts on the page. No `'unsafe-inline'`: every inline script is
+ *   hashed, so the policy stays strict.
+ * - `style-src 'self' <hashes>` does the same for inline `<style>` blocks.
+ * - `style-src-attr 'unsafe-inline'` permits inline `style="…"` attributes,
+ *   which are NOT hashable (Astro's own CSP takes the same allowance for
+ *   attribute styles). Element styles remain hash-pinned.
+ * - `img-src 'self' data: https:` covers the brand logo and inline data URIs.
+ * - `connect-src 'self'` bounds fetch/XHR (the code-request/verify POSTs are
+ *   same-origin). `form-action 'self'` bounds the login/verify form posts.
+ * - `object-src 'none'`, `base-uri 'self'`, `frame-ancestors 'none'` are the
+ *   standard hardening trio (no plugins, no base-tag hijack, no framing).
+ */
+export function buildAuthCspPolicy(sources: {
+	scriptHashes: CspHash[]
+	styleHashes: CspHash[]
+}): string {
+	const scriptSrc = ["script-src 'self'", ...sources.scriptHashes.map((h) => `'${h}'`)].join(' ')
+	const styleSrc = ["style-src 'self'", ...sources.styleHashes.map((h) => `'${h}'`)].join(' ')
+	return [
+		"default-src 'self'",
+		scriptSrc,
+		styleSrc,
+		"style-src-attr 'unsafe-inline'",
+		"img-src 'self' data: https:",
+		"connect-src 'self'",
+		"form-action 'self'",
+		"object-src 'none'",
+		"base-uri 'self'",
+		"frame-ancestors 'none'",
+	].join('; ')
+}
+
+function escapeHtmlAttribute(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+}
+
+/**
+ * Insert `tag` immediately after the opening `<head>` (or, absent a head, after
+ * `<html>`, or as a prefix) so the policy is parsed before any inline content.
+ */
+function injectIntoHead(html: string, tag: string): string {
+	const headOpen = /<head\b[^>]*>/i.exec(html)
+	if (headOpen) {
+		const at = headOpen.index + headOpen[0].length
+		return `${html.slice(0, at)}${tag}${html.slice(at)}`
+	}
+	const htmlOpen = /<html\b[^>]*>/i.exec(html)
+	if (htmlOpen) {
+		const at = htmlOpen.index + htmlOpen[0].length
+		return `${html.slice(0, at)}${tag}${html.slice(at)}`
+	}
+	return `${tag}${html}`
+}
+
+/**
+ * Compute the auth CSP for `html` and return the document with a
+ * `<meta http-equiv="Content-Security-Policy">` inserted at the top of `<head>`.
+ *
+ * Idempotent: if the document already carries a CSP meta (a consumer renderer
+ * that emits its own), the input is returned unchanged so we never emit two
+ * conflicting policies (browsers would intersect them and likely break the
+ * page). Every inline `<script>`/`<style>` the page ships is hash-pinned, so the
+ * emitted policy is strict — no `'unsafe-inline'` for scripts or element styles.
+ */
+export async function injectAuthCsp(html: string): Promise<string> {
+	if (hasCspMeta(html)) return html
+	const { scripts, styles } = extractInlineSources(html)
+	const scriptHashes = await Promise.all(scripts.map(sha256CspHash))
+	const styleHashes = await Promise.all(styles.map(sha256CspHash))
+	const policy = buildAuthCspPolicy({ scriptHashes, styleHashes })
+	const tag = `<meta http-equiv="Content-Security-Policy" content="${escapeHtmlAttribute(policy)}">`
+	return injectIntoHead(html, tag)
+}

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,21 @@ export {
 	normalizeAuthProvider,
 	trackAuthEvent,
 } from './analytics.js'
+export type {
+	ClientSecretLiteral,
+	ClientSecretResolutionErrorCode,
+	ClientSecretResult,
+} from './client-secret.js'
+export { isClientSecretLiteral, literalClientSecret } from './client-secret.js'
+export {
+	buildAuthCspPolicy,
+	type CspHash,
+	extractInlineSources,
+	hasCspMeta,
+	injectAuthCsp,
+	sha256CspHash,
+} from './csp.js'
+export { ClientSecretResolutionError } from './fail-closed.js'
 export {
 	type BridgeMigrationOptions,
 	type BridgeMigrationStatement,
@@ -25,7 +40,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',