@growth-labs/conformance 0.1.0

package/src/policy.ts

@@ -0,0 +1,97 @@
+import type { Audience, HeaderMap, RenderMode } from './schema.js'
+
+export const REQUIRED_SECURITY_HEADERS = [
+	'content-security-policy',
+	'strict-transport-security',
+	'x-frame-options',
+	'x-content-type-options',
+	'referrer-policy',
+	'permissions-policy',
+] as const
+
+export interface HeaderPolicyOptions {
+	renderMode: RenderMode
+	audience: Audience
+	nonce?: string
+	markdownTwinUrl?: string
+}
+
+export interface CachePolicyOptions {
+	renderMode: RenderMode
+	audience: Audience
+}
+
+export function buildSharedPublicationHeaders(
+	options: HeaderPolicyOptions,
+): Record<string, string> {
+	const headers: Record<string, string> = {
+		'Content-Security-Policy': buildContentSecurityPolicy(options.nonce),
+		'Strict-Transport-Security': 'max-age=31536000; includeSubDomains; preload',
+		'X-Frame-Options': 'DENY',
+		'X-Content-Type-Options': 'nosniff',
+		'Referrer-Policy': 'strict-origin-when-cross-origin',
+		'Permissions-Policy':
+			'accelerometer=(), camera=(), geolocation=(), gyroscope=(), microphone=(), payment=(), usb=()',
+		'Cache-Control': buildCacheControl(options),
+	}
+
+	if (options.markdownTwinUrl) {
+		headers.Link = `<${options.markdownTwinUrl}>; rel="alternate"; type="text/markdown"`
+	}
+
+	return headers
+}
+
+export function buildContentSecurityPolicy(nonce?: string): string {
+	const scriptSources = ["'self'"]
+	const styleSources = ["'self'"]
+	if (nonce) {
+		scriptSources.push(`'nonce-${nonce}'`)
+		styleSources.push(`'nonce-${nonce}'`)
+	}
+
+	return [
+		"default-src 'self'",
+		`script-src ${scriptSources.join(' ')}`,
+		`style-src ${styleSources.join(' ')}`,
+		"img-src 'self' data: https:",
+		"font-src 'self' data:",
+		"connect-src 'self' https:",
+		"object-src 'none'",
+		"base-uri 'self'",
+		"frame-ancestors 'none'",
+		'upgrade-insecure-requests',
+	].join('; ')
+}
+
+export function buildCacheControl({ renderMode, audience }: CachePolicyOptions): string {
+	if (isPrivateAudience(audience)) return 'private, no-store'
+	if (renderMode === 'static') {
+		return 'public, max-age=300, s-maxage=86400, stale-while-revalidate=604800'
+	}
+	return 'public, max-age=0, s-maxage=300, stale-while-revalidate=86400'
+}
+
+export function normalizeHeaders(headers: HeaderMap | undefined): Record<string, string> {
+	const normalized: Record<string, string> = {}
+	if (!headers) return normalized
+
+	for (const [name, value] of Object.entries(headers)) {
+		if (typeof value === 'string') {
+			normalized[name.toLowerCase()] = value
+		} else if (Array.isArray(value)) {
+			normalized[name.toLowerCase()] = value.join(', ')
+		}
+	}
+
+	return normalized
+}
+
+export function isPrivateAudience(audience: Audience): boolean {
+	return (
+		audience === 'subscriber' ||
+		audience === 'member' ||
+		audience === 'admin' ||
+		audience === 'private'
+	)
+}

package/src/runner.ts

@@ -0,0 +1,477 @@
+import { extractHtmlSignals, getSchemaTypes, type HtmlSignals, nodeHasSchemaType } from './html.js'
+import { isPrivateAudience, normalizeHeaders, REQUIRED_SECURITY_HEADERS } from './policy.js'
+import {
+	type Audience,
+	type ConformanceCheckReceipt,
+	type ConformanceFinding,
+	type ConformanceFixture,
+	type ConformanceFixtureInput,
+	conformanceFixtureSchema,
+	EVIDENCE_SCHEMA_VERSION,
+	type FleetEvidenceBundle,
+	fleetEvidenceBundleSchema,
+	type SiteEvidenceBundle,
+	siteEvidenceBundleSchema,
+} from './schema.js'
+
+const REQUIRED_PUBLICATION_SURFACES = ['sitemap', 'robots', 'feed'] as const
+const DISCOVER_HERO_MIN_WIDTH = 1200
+
+export interface RunConformanceOptions {
+	now?: () => string
+}
+
+export function runSiteConformance(
+	input: ConformanceFixtureInput,
+	options: RunConformanceOptions = {},
+): SiteEvidenceBundle {
+	const fixture = conformanceFixtureSchema.parse(input)
+	const generatedAt = options.now?.() ?? new Date().toISOString()
+	const htmlSignals = extractHtmlSignals(fixture.response.html ?? fixture.response.body ?? '')
+	const checks = [
+		checkSecurityHeaders(fixture),
+		checkMetadata(fixture, htmlSignals),
+		checkStructuredData(fixture, htmlSignals),
+		checkImages(fixture, htmlSignals),
+		checkPublicationSurfaces(fixture),
+		checkCache(fixture),
+		checkBuildEvidence(fixture),
+	]
+	const findings = checks.flatMap((check) => check.findings)
+	const summary = summarizeChecks(checks)
+	const bundle: SiteEvidenceBundle = {
+		schemaVersion: EVIDENCE_SCHEMA_VERSION,
+		generatedAt,
+		fixtureId: fixture.id,
+		site: fixture.site,
+		environment: fixture.environment,
+		url: fixture.url,
+		status: findings.some((finding) => finding.severity === 'error') ? 'fail' : 'pass',
+		summary,
+		checks,
+		findings,
+	}
+
+	return siteEvidenceBundleSchema.parse(bundle)
+}
+
+export function runFleetConformance(
+	inputs: ConformanceFixtureInput[],
+	options: RunConformanceOptions = {},
+): FleetEvidenceBundle {
+	const generatedAt = options.now?.() ?? new Date().toISOString()
+	const sites = inputs.map((input) => runSiteConformance(input, { now: () => generatedAt }))
+	const summary = sites.reduce(
+		(acc, site) => {
+			acc.pass += site.summary.pass
+			acc.fail += site.summary.fail
+			acc.na += site.summary.na
+			acc.findings += site.summary.findings
+			return acc
+		},
+		{ pass: 0, fail: 0, na: 0, findings: 0, sites: sites.length },
+	)
+
+	const bundle: FleetEvidenceBundle = {
+		schemaVersion: EVIDENCE_SCHEMA_VERSION,
+		generatedAt,
+		status: sites.some((site) => site.status === 'fail') ? 'fail' : 'pass',
+		summary,
+		sites,
+	}
+
+	return fleetEvidenceBundleSchema.parse(bundle)
+}
+
+function checkSecurityHeaders(fixture: ConformanceFixture): ConformanceCheckReceipt {
+	const headers = normalizeHeaders(fixture.response.headers)
+	const findings: ConformanceFinding[] = []
+	const missingSecurityHeaders = REQUIRED_SECURITY_HEADERS.filter((name) => !headers[name])
+
+	if (
+		fixture.renderMode === 'ssr' &&
+		fixture.buildEvidence?.staticHeaderPolicy === true &&
+		fixture.buildEvidence.ssrHeaderPolicy !== true &&
+		missingSecurityHeaders.length > 0
+	) {
+		findings.push({
+			code: 'security.headers.static_only_for_ssr',
+			severity: 'error',
+			message:
+				'SSR response is missing runtime security headers while build evidence only declares static header policy.',
+			path: 'response.headers',
+			evidence: `missing=${missingSecurityHeaders.join(',')}`,
+			remediation:
+				'Apply the shared header policy in the Worker response path as well as static output.',
+		})
+	}
+
+	for (const header of missingSecurityHeaders) {
+		findings.push({
+			code: 'security.header.missing',
+			severity: 'error',
+			message: `Missing required security header: ${header}.`,
+			path: `response.headers.${header}`,
+		})
+	}
+
+	const csp = headers['content-security-policy']
+	if (csp?.toLowerCase().includes('unsafe-inline')) {
+		findings.push({
+			code: 'security.csp.unsafe_inline',
+			severity: 'error',
+			message: 'Content-Security-Policy must not allow unsafe-inline script or style execution.',
+			path: 'response.headers.content-security-policy',
+			evidence: csp,
+			remediation: 'Use nonces or hashes in the shared CSP policy instead of unsafe-inline.',
+		})
+	}
+
+	const xContentType = headers['x-content-type-options']
+	if (xContentType && xContentType.toLowerCase() !== 'nosniff') {
+		findings.push({
+			code: 'security.header.invalid',
+			severity: 'error',
+			message: 'X-Content-Type-Options must be nosniff.',
+			path: 'response.headers.x-content-type-options',
+			evidence: xContentType,
+		})
+	}
+
+	const hsts = headers['strict-transport-security']
+	if (hsts && !/max-age=\d+/i.test(hsts)) {
+		findings.push({
+			code: 'security.header.invalid',
+			severity: 'error',
+			message: 'Strict-Transport-Security must declare max-age.',
+			path: 'response.headers.strict-transport-security',
+			evidence: hsts,
+		})
+	}
+
+	const cacheControl = headers['cache-control']
+	if (!cacheControl) {
+		findings.push({
+			code: 'cache.header.missing',
+			severity: 'error',
+			message: 'HTML responses must declare Cache-Control semantics.',
+			path: 'response.headers.cache-control',
+		})
+	} else if (isPrivateAudience(fixture.audience) && /\bpublic\b/i.test(cacheControl)) {
+		findings.push({
+			code: 'cache.private_audience_public',
+			severity: 'error',
+			message: 'Private or entitled audience responses must not use public cache semantics.',
+			path: 'response.headers.cache-control',
+			evidence: cacheControl,
+		})
+	}
+
+	return receipt('security-headers', findings)
+}
+
+function checkMetadata(
+	fixture: ConformanceFixture,
+	htmlSignals: HtmlSignals,
+): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = []
+
+	if (!htmlSignals.canonicalUrl) {
+		findings.push({
+			code: 'metadata.canonical.missing',
+			severity: 'error',
+			message: 'Renderable HTML must include a canonical link.',
+			path: 'html.head.link[rel=canonical]',
+		})
+	} else if (
+		fixture.expected.canonicalUrl &&
+		htmlSignals.canonicalUrl !== fixture.expected.canonicalUrl
+	) {
+		findings.push({
+			code: 'metadata.canonical.runtime_override_not_applied',
+			severity: 'error',
+			message: 'Rendered canonical URL does not match the runtime canonical override.',
+			path: 'html.head.link[rel=canonical].href',
+			evidence: `expected=${fixture.expected.canonicalUrl}; actual=${htmlSignals.canonicalUrl}`,
+			remediation: 'Apply runtime canonical composition before rendering metadata.',
+		})
+	}
+
+	const robots = htmlSignals.robotsContent
+	const robotsDirectives =
+		robots
+			?.toLowerCase()
+			.split(',')
+			.map((part) => part.trim()) ?? []
+	if (!robotsDirectives.includes('max-image-preview:large')) {
+		findings.push({
+			code: 'metadata.robots.missing_max_image_preview_large',
+			severity: 'error',
+			message: 'Robots metadata must include max-image-preview:large for Discover eligibility.',
+			path: 'html.head.meta[name=robots].content',
+			evidence: robots ?? 'missing',
+			remediation: 'Compose robots metadata globally with max-image-preview:large.',
+		})
+	}
+
+	return receipt('metadata', findings)
+}
+
+function checkStructuredData(
+	fixture: ConformanceFixture,
+	htmlSignals: HtmlSignals,
+): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = htmlSignals.jsonLdParseErrors.map((error) => ({
+		code: 'structured_data.json_ld.invalid',
+		severity: 'error',
+		message: `Invalid JSON-LD: ${error.message}`,
+		path: error.path,
+	}))
+
+	const allTypes = new Set(htmlSignals.jsonLdNodes.flatMap((node) => getSchemaTypes(node)))
+	for (const expectedType of fixture.expected.schemaTypes) {
+		if (!allTypes.has(expectedType)) {
+			findings.push({
+				code: 'structured_data.schema_type.missing',
+				severity: 'error',
+				message: `Expected JSON-LD schema type ${expectedType} was not rendered.`,
+				path: 'jsonLd.@type',
+			})
+		}
+	}
+
+	htmlSignals.jsonLdNodes.forEach((node, index) => {
+		if (
+			(nodeHasSchemaType(node, 'Article') ||
+				nodeHasSchemaType(node, 'NewsArticle') ||
+				nodeHasSchemaType(node, 'VideoObject')) &&
+			typeof node.isAccessibleForFree === 'string'
+		) {
+			findings.push({
+				code: 'structured_data.is_accessible_for_free.stringified',
+				severity: 'error',
+				message: 'isAccessibleForFree must be a boolean, not a string.',
+				path: `jsonLd[${index}].isAccessibleForFree`,
+				evidence: node.isAccessibleForFree,
+				remediation: 'Return structured data objects with boolean values before serialization.',
+			})
+		}
+
+		if (nodeHasSchemaType(node, 'VideoObject') && isDateOnlyString(node.uploadDate)) {
+			findings.push({
+				code: 'structured_data.video_object.upload_date.date_only',
+				severity: 'error',
+				message: 'VideoObject uploadDate must include a full ISO date-time with timezone.',
+				path: `jsonLd[${index}].uploadDate`,
+				evidence: String(node.uploadDate),
+				remediation: 'Use an ISO 8601 date-time such as 2026-07-15T14:30:00Z.',
+			})
+		}
+	})
+
+	return receipt('structured-data', findings)
+}
+
+function checkImages(
+	fixture: ConformanceFixture,
+	htmlSignals: HtmlSignals,
+): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = []
+	const images = htmlSignals.jsonLdImages
+
+	if (fixture.expected.discoverEligible && images.length === 0) {
+		findings.push({
+			code: 'images.discover_image.missing',
+			severity: 'error',
+			message: 'Discover-eligible pages must expose structured image data.',
+			path: 'jsonLd.image',
+		})
+	}
+
+	for (const image of images) {
+		if (image.width === undefined || image.height === undefined) {
+			findings.push({
+				code: 'images.dimensions.missing',
+				severity: 'error',
+				message: 'Structured image objects must include width and height.',
+				path: image.path,
+				evidence: image.url,
+				remediation: 'Return JSON-LD image objects with url, width, and height.',
+			})
+		}
+	}
+
+	const measuredWidths = images
+		.map((image) => image.width)
+		.filter((width): width is number => typeof width === 'number')
+	if (
+		fixture.expected.discoverEligible &&
+		measuredWidths.length > 0 &&
+		Math.max(...measuredWidths) < DISCOVER_HERO_MIN_WIDTH
+	) {
+		findings.push({
+			code: 'images.hero.under_1200',
+			severity: 'error',
+			message: 'Discover-eligible hero image width must be at least 1200px.',
+			path: 'jsonLd.image',
+			evidence: `maxWidth=${Math.max(...measuredWidths)}`,
+			remediation: 'Provide a 1200px or larger image variant in JSON-LD and social metadata.',
+		})
+	}
+
+	return receipt('images', findings)
+}
+
+function checkPublicationSurfaces(fixture: ConformanceFixture): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = []
+	const surfacesByName = new Map(
+		fixture.publicationSurfaces.map((surface) => [surface.name, surface]),
+	)
+
+	for (const required of REQUIRED_PUBLICATION_SURFACES) {
+		if (!surfacesByName.has(required)) {
+			findings.push({
+				code: 'publication.surface.missing',
+				severity: 'error',
+				message: `Publication surface ${required} must be present or explicitly declared NA.`,
+				path: `publicationSurfaces.${required}`,
+			})
+		}
+	}
+
+	fixture.publicationSurfaces.forEach((surface, index) => {
+		const path = `publicationSurfaces[${index}]`
+		if (surface.status === 'na') {
+			if (!surface.capabilityBoundary || !surface.evidence) {
+				findings.push({
+					code: 'publication.na.undeclared',
+					severity: 'error',
+					message: 'NA publication surfaces require a capability boundary and evidence.',
+					path,
+					evidence: surface.name,
+					remediation:
+						'Declare why the site cannot provide the surface and attach supporting evidence.',
+				})
+			}
+			return
+		}
+
+		if (surface.status === 'missing') {
+			findings.push({
+				code: 'publication.surface.missing',
+				severity: 'error',
+				message: `Publication surface ${surface.name} is missing.`,
+				path,
+			})
+			return
+		}
+
+		if (surface.httpStatus !== undefined && surface.httpStatus >= 400) {
+			findings.push({
+				code: 'publication.surface.http_error',
+				severity: 'error',
+				message: `Publication surface ${surface.name} returned HTTP ${surface.httpStatus}.`,
+				path: `${path}.httpStatus`,
+			})
+		}
+
+		if (surface.bodyBytes !== undefined && surface.bodyBytes === 0) {
+			findings.push({
+				code: 'publication.surface.empty',
+				severity: 'error',
+				message: `Publication surface ${surface.name} has an empty body.`,
+				path: `${path}.bodyBytes`,
+			})
+		}
+	})
+
+	return receipt('publication-surfaces', findings)
+}
+
+function checkCache(fixture: ConformanceFixture): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = []
+	const variants = fixture.cacheVariants
+
+	for (let leftIndex = 0; leftIndex < variants.length; leftIndex += 1) {
+		for (let rightIndex = leftIndex + 1; rightIndex < variants.length; rightIndex += 1) {
+			const left = variants[leftIndex]
+			const right = variants[rightIndex]
+			if (!left || !right || left.cacheKey !== right.cacheKey) continue
+			if (isCrawlerPublicCollision(left.audience, right.audience)) {
+				findings.push({
+					code: 'cache.crawler_public_key_collision',
+					severity: 'error',
+					message: 'Crawler and public HTML variants must not share a cache key.',
+					path: `cacheVariants[${leftIndex}],cacheVariants[${rightIndex}]`,
+					evidence: left.cacheKey,
+					remediation:
+						'Include audience/crawler class in cache keys when content or headers differ.',
+				})
+			}
+		}
+	}
+
+	return receipt('cache', findings)
+}
+
+function checkBuildEvidence(fixture: ConformanceFixture): ConformanceCheckReceipt {
+	const findings: ConformanceFinding[] = []
+	const buildEvidence = fixture.buildEvidence
+
+	if (!buildEvidence) {
+		findings.push({
+			code: 'build.evidence.missing',
+			severity: 'error',
+			message: 'Conformance fixtures must include build evidence.',
+			path: 'buildEvidence',
+		})
+		return receipt('build-evidence', findings)
+	}
+
+	if (!buildEvidence.commitSha && !buildEvidence.artifactId) {
+		findings.push({
+			code: 'build.evidence.identity_missing',
+			severity: 'error',
+			message: 'Build evidence must include a commit SHA or artifact identifier.',
+			path: 'buildEvidence',
+		})
+	}
+
+	if (Object.keys(buildEvidence.packageVersions).length === 0) {
+		findings.push({
+			code: 'build.evidence.package_versions_missing',
+			severity: 'error',
+			message: 'Build evidence must include package versions used by the site.',
+			path: 'buildEvidence.packageVersions',
+		})
+	}
+
+	return receipt('build-evidence', findings)
+}
+
+function summarizeChecks(checks: ConformanceCheckReceipt[]) {
+	return checks.reduce(
+		(acc, check) => {
+			acc[check.status] += 1
+			acc.findings += check.findings.length
+			return acc
+		},
+		{ pass: 0, fail: 0, na: 0, findings: 0 },
+	)
+}
+
+function receipt(name: string, findings: ConformanceFinding[]): ConformanceCheckReceipt {
+	return {
+		name,
+		status: findings.some((finding) => finding.severity === 'error') ? 'fail' : 'pass',
+		findings,
+	}
+}
+
+function isDateOnlyString(value: unknown): boolean {
+	return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)
+}
+
+function isCrawlerPublicCollision(left: Audience, right: Audience): boolean {
+	return (left === 'crawler' && right === 'public') || (left === 'public' && right === 'crawler')
+}