@growth-labs/conformance

中文文档
0.19.0发布于 2026/11/06TypeScriptES Module近 30 天下载 6656

Reusable fleet publication conformance harness for Growth Labs sites: headers, cache, metadata, structured data, images, publication surfaces, and evidence bundles.

原始使用文档
文档目录9 节
  1. Cache Safety
  2. Route conformance for a built Worker
  3. Install
  4. Basic Usage
  5. Deployment Endpoint Adapter
  6. Shared Header Policy
  7. Analytics tag sources (@growth-labs/analytics)
  8. Fixture Commands
  9. Evidence Shape

@growth-labs/conformance

Reusable publication conformance harness for Growth Labs sites. It validates per-site fixtures and emits machine-parseable evidence bundles for render, cache, security headers, metadata, structured data, images, publication surfaces, Discover eligibility, and build evidence.

This package is consumed by sites and CI jobs. It is not a central fleet runtime and it does not fetch, mutate, deploy, or store fleet state.

Public or crawler fixtures can explicitly approve scoped inline styles with expected.publicInlineStyles: { attributes: true, elements: true }. Both booleans are required; each true requires the corresponding style-src-attr or style-src-elem 'unsafe-inline' grant in the actual enforced CSP. Omission or false retains the existing strict/attribute-inventory validation. This contract does not allow private audiences, simultaneous receipt-free attributes and an inventory receipt, or unsafe-inline in scripts, default-src, or unscoped style-src.

Cache Safety

import {
    applyPrivateNoStore,
    assertSafeEntrypointCacheConfiguration,
    evaluateCacheSafety,
    scanRequestStateLeaks,
} from '@growth-labs/conformance/cache-safety'

assertSafeEntrypointCacheConfiguration(finalWranglerConfig) validates unknown input with Zod and throws on unsafe or malformed deployment cache settings. Global/default entrypoints remain uncached; only the typed PublicPages worker export can opt in, without cross-version reuse. Cache keys and worker export keys are strict; unrelated Wrangler fields and non-worker options are preserved. Final environment overrides remain forbidden. The validator does not mutate input.

The cache-safety contract keeps the default gateway uncached, requires an explicit free-only named PublicPages safety contract when public HTML caching is enabled, and verifies a non-public and side-effect-free inner renderer with an explicit forwarded-header allowlist, and proves HIT still executes the outer gateway side effects. applyPrivateNoStore() writes the complete Cache-Control/CDN-Cache-Control/Cloudflare-CDN-Cache-Control triplet and removes Cookie from Vary.

Omitted cache evidence fails with cache.evidence.missing. A public response with Set-Cookie fails unless it carries the complete triplet. Vary: Cookie always fails—even alongside the private triplet—because Cookie variance is not part of the supported contract; remove it after marking the response private.

The body scanner accepts controlled request-state sentinels and detects their literal, URI, JSON, and base64 forms. Its receipt exposes only state categories and encodings—never raw sentinel values. cacheSafetyLiveResultSchema validates the bounded result.

Route conformance for a built Worker

runWorkerRoutes() (subpath @growth-labs/conformance/worker-routes, Node only, needs the optional peer miniflare) boots the built Worker from dist/server in Miniflare with a small committed D1 fixture and requests the routes a publication must answer. It asserts status, <title>, canonical, JSON-LD type and og:image (and content type and a body marker for the feeds, sitemap and robots.txt), and returns the result as conformance findings.

import { defaultRoutes, formatRouteReport } from '@growth-labs/conformance'
import { runWorkerRoutes } from '@growth-labs/conformance/worker-routes'

const report = await runWorkerRoutes({
    site: 'megaprojects',
    origin: 'https://megaprojects.pub',
    serverDir: new URL('../dist/server/', import.meta.url).pathname,
    bindings: { SITE_URL: 'https://megaprojects.pub' },
    d1: {
        SITE_DB: {
            migrationsDir: 'migrations', // the site's own migrations, applied in file-name order
            sql: readFileSync('tests/fixtures/routes.sql', 'utf8'), // optional; one statement per line
            seed: async (db) => {}, // optional; seed through the app's code, e.g. the CMS engine
        },
    },
    stubServices: ['ASSETS', 'AUTH'], // answer 503 unless `serviceBindings` supplies one
    routes: defaultRoutes({ article: '/articles/newest', video: '/videos/first' }),
})
if (report.status === 'fail') throw new Error(formatRouteReport(report))

Finding codes: route.status.unexpected (a 500 on / is this one, with the start of the body as evidence), route.content_type.unexpected, route.body.expected_missing, route.title.missing, route.canonical.missing, route.canonical.mismatch, route.structured_data.type_missing, route.og_image.missing, route.fetch.failed. A route spec can override any expectation (status may be a list, jsonLdTypes entries may be alternatives). The pure half (evaluateRoute, buildRouteReport) runs on responses captured any other way.

Install

pnpm add @growth-labs/conformance

Basic Usage

import { runFleetConformance, runSiteConformance } from '@growth-labs/conformance'

const fixture = {
    id: 'fronts:article:public',
    site: 'fronts',
    environment: 'production',
    url: 'https://fronts.co/example',
    renderMode: 'ssr',
    audience: 'public',
    response: {
        status: 200,
        headers: {
            'content-security-policy': "default-src 'self'; script-src 'self' 'nonce-runtime'",
            'strict-transport-security': 'max-age=31536000',
            'cross-origin-opener-policy': 'same-origin',
            'cross-origin-resource-policy': 'same-origin',
            'x-frame-options': 'DENY',
            'x-content-type-options': 'nosniff',
            'referrer-policy': 'strict-origin-when-cross-origin',
            'permissions-policy': 'camera=(), microphone=(), geolocation=()',
            'cache-control': 'public, max-age=0, s-maxage=300',
        },
        html: '<!doctype html>...',
    },
    expected: {
        canonicalUrl: 'https://fronts.co/example',
        schemaTypes: ['NewsArticle'],
        discoverEligible: true,
        framePolicy: {
            ancestors: ["'none'"],
            legacyHeader: 'DENY',
        },
    },
    publicationSurfaces: [
        { name: 'sitemap', status: 'present', httpStatus: 200, bodyBytes: 1024 },
        { name: 'robots', status: 'present', httpStatus: 200, bodyBytes: 256 },
        { name: 'feed', status: 'na', capabilityBoundary: 'No editorial feed', evidence: 'site type' },
    ],
    cacheVariants: [
        { audience: 'public', cacheKey: 'fronts:public:/example' },
        { audience: 'crawler', cacheKey: 'fronts:crawler:/example' },
    ],
    cacheSafety: {
        defaultGatewayCacheEnabled: false,
        publicHtmlAllowlist: [],
        inner: {
            publiclyRoutable: false,
            forwardedHeaders: ['accept-language'],
            allowedForwardedHeaders: ['accept-language'],
            sideEffects: false,
        },
        gateway: { hitRunsSideEffects: true },
        response: {
            personalized: false,
            headers: { 'cache-control': 'public, s-maxage=300' },
            body: '<!doctype html>...',
            sentinels: [],
        },
    },
    securityReceipts: {
        functionalProbes: [
            { name: 'oauth', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'media', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'images', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'analytics', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'embeds', status: 'pass', evidence: 'sanitized consumer probe receipt' },
            { name: 'error-pages', status: 'pass', evidence: 'sanitized consumer probe receipt' },
        ],
        cspReports: [
            {
                name: 'csp-report-canary',
                status: 'pass',
                endpoint: 'consumer-owned-report-endpoint',
                evidence: 'sanitized CSP report or blocked-canary receipt',
            },
        ],
        inlineStyleAttributes: {
            commitSha: 'bd39d718f6a5b0df9a249e11638a8b430050941e',
            occurrenceCount: 4,
            evidence: {
                tool: 'platform-foundations:inline-style-inventory@1',
                outputHash: 'sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
            },
        },
    },
    buildEvidence: {
        commitSha: 'bd39d718f6a5b0df9a249e11638a8b430050941e',
        packageVersions: { '@growth-labs/conformance': '0.6.0', '@growth-labs/seo': '0.9.0' },
        staticHeaderPolicy: true,
        ssrHeaderPolicy: true,
    },
}

const siteBundle = runSiteConformance(fixture)
const fleetBundle = runFleetConformance([fixture])

Deployment Endpoint Adapter

Consumers own the route, the conformance artifact, and the Cloudflare [version_metadata] binding. The CI/build probe step runs runSiteConformance(), serializes the result to a JSON artifact file, and bundles that file with the Worker. The adapter reads the pre-built artifact at module load (not per request) and serves it:

import artifact from './conformance-artifact.json' with { type: 'json' }
import { initConformanceEndpoint } from '@growth-labs/conformance/endpoint'

// Artifact produced by the CI probe step before deployment.
// Static import: a missing conformance-artifact.json is a build-time error —
// the Worker never starts if the artifact is absent.
// Artifact is parsed, schema-stripped, bounded, and serialized ONCE here.
const handler = initConformanceEndpoint(artifact, 'fronts')

// src/pages/.well-known/growth-labs-conformance.json.ts
export function GET({ locals, request }) {
    return handler.handle({
        method: request.method,
        versionMetadata: locals.runtime.env.CF_VERSION_METADATA,
    })
}

export const HEAD = GET

initConformanceEndpoint parses the artifact, validates it against the v2 schema, checks environment: 'production' and the expected site, requires buildEvidence.commitSha (lowercase 40-character hex) and buildEvidence.generatedAt (timezone-qualified ISO-8601 datetime), and serializes the schema-stripped body bytes once. Per-request handling only validates the method and compares versionMetadata.tag against the baked commit SHA — no I/O, no probe execution, no re-serialization. Missing/malformed artifacts and wrong site/environment produce a handler that always returns 503. The adapter never reads or serializes environment bindings, request headers, Cloudflare version IDs, Cloudflare version timestamps, internal exceptions, or fields outside the parsed v2 schema. It does not perform heuristic secret detection: documented free-form strings such as finding messages, finding evidence, remediation text, and receipt evidence remain unchanged and are the consumer's sanitization responsibility.

Shared Header Policy

Use buildSharedPublicationHeaders() when a site wants the package-owned baseline for SSR and static response headers. Astro sites on releases that support security.csp should let Astro own the per-route hash CSP and retain the remaining shared headers. The package peer contract remains the estate's optional Astro 6 contract:

import {
    buildAstroCspConfig,
    buildSharedPublicationHeaders,
} from '@growth-labs/conformance/policy'

const csp = buildAstroCspConfig({
    scriptSources: ['https://challenges.cloudflare.com'],
    styleSources: ['https://fonts.googleapis.com'],
})

const headers = buildSharedPublicationHeaders({
    renderMode: 'ssr',
    audience: 'public',
    contentSecurityPolicy: false,
    markdownTwinUrl: 'https://example.com/article.md',
})

Analytics tag sources (@growth-labs/analytics)

Sites that enable the @growth-labs/analytics external tags must add the tags' exact origins to the SecurityHeadersConfig allowlists (same exact-HTTPS-origin form as the examples above — no wildcards for script hosts). Both tags are external <script src> with no inline bootstrap, so hash-based CSP needs only these origins, not a per-render inline hash:

const csp = buildAstroCspConfig({
    scriptSources: [
        'https://static.cloudflareinsights.com', // Cloudflare Web Analytics beacon (cookieless)
        'https://www.googletagmanager.com',      // GA4 gtag.js loader (consent-gated)
    ],
    connectSources: [
        'https://cloudflareinsights.com',        // CWA RUM upload
        'https://www.google-analytics.com',      // GA4 collect
        'https://*.google-analytics.com',
        'https://*.analytics.google.com',
    ],
    imgSources: [
        'https://www.google-analytics.com',      // GA4 pixel fallback
        'https://*.google-analytics.com',
    ],
})

Add a source only for the tags a site actually enables (CWA-only sites omit the GA4 origins, and vice versa).

The fixture default is the non-embeddable policy above. For a deliberately embeddable route, declare its exact response class and omit a conflicting X-Frame-Options header:

expected: {
    framePolicy: {
        ancestors: ['https://trusted.example'],
        legacyHeader: 'omit',
    },
}

Accepted ancestors are 'none', 'self', https:, and exact HTTPS origins; wildcards, paths, credentials, query strings, and fragments are rejected. DENY is valid only with 'none', and SAMEORIGIN only with 'self'; broader embeddable policies must use legacyHeader: 'omit' to avoid contradictory browser behavior.

Astro 6 security.csp cannot represent attribute-scoped style resources. If a route still emits HTML style attributes, keep the Astro-native helper fail-closed and serve a response-header CSP with style-src-attr plus the validated inlineStyleAttributes receipt in the conformance fixture. The receipt requires the exact lowercase 40-character build commit SHA, a positive occurrence count, the versioned scanner identity, and the lowercase SHA-256 content hash of its machine output. The same receipt must appear in the conformance fixture and its commit must match buildEvidence.commitSha. Do not use an inline-style allowance as a generic compatibility fix.

The policy emits CSP, HSTS, frame protection, MIME sniffing protection, COOP, CORP, referrer policy, permissions policy, cache semantics, and optional markdown twin Link metadata. Private audiences use private, no-store; public SSR uses short shared-cache semantics; public static surfaces get longer shared-cache semantics.

HSTS defaults to max-age=31536000 only. Add includeSubDomains and preload through strictTransportSecurity: { includeSubDomains: true, preload: true } only after the consumer has separately verified the full host inventory can enforce HTTPS. COOP defaults to same-origin and CORP defaults to same-origin; consumers may override them only when verified OAuth popup, media, or embed constraints require a looser policy and the receipt proves the result under enforced CSP.

Fixture Commands

The root repo exposes:

pnpm run conformance:test-fixtures
pnpm run conformance:verify-schema

The fixture command proves the required negative fixtures fail loudly with stable finding codes:

  • csp-unsafe-inline
  • missing-coop
  • missing-corp
  • hsts-below-one-year
  • csp-wildcard-default-src
  • csp-unsafe-eval
  • csp-inline-executable-without-nonce-or-hash
  • conflicting-duplicate-security-header
  • missing-functional-probe-receipt
  • missing-csp-report-receipt
  • failed-csp-report-receipt
  • headers-static-only-while-ssr-missing
  • undeclared-na
  • stringified-is-accessible-for-free
  • video-object-date-only-upload-date
  • missing-image-dimensions
  • hero-under-1200px
  • missing-max-image-preview-large
  • crawler-public-cache-key-collision
  • runtime-canonical-override-not-applied
  • llms-runtime-static-shadow
  • default-entrypoint-cache-enabled
  • public-html-without-named-renderer
  • named-renderer-not-free-only
  • stored-member-response
  • stored-crawler-body-response
  • stored-set-cookie-response
  • raw-credential-forwarded-to-inner
  • cached-body-request-state-leak
  • gateway-hit-side-effects-bypassed
  • personalized-public-response
  • public-set-cookie-response
  • vary-cookie-response

Evidence Shape

runSiteConformance() returns a SiteEvidenceBundle; runFleetConformance() returns a FleetEvidenceBundle. Both are validated by exported Zod schemas and carry schemaVersion: "growth-labs.conformance.v2" so downstream jobs can parse them without relying on console text.

Schema v2 adds securityReceipts to fixtures and site evidence bundles. Existing v1 fixtures must add explicit functional-probe receipts for oauth, media, images, analytics, embeds, and error-pages, plus at least one passing CSP reporting/canary receipt. The package does not perform those live probes itself; consumer CI supplies sanitized pass/fail/NA receipts.

版本与发布记录

@growth-labs/conformance 共发布 25 个版本,首次发布于 2026/07/16;过去 12 个月发布了 25 个版本。

版本发布日期距今
0.19.0latest2026/11/0611 天前
0.18.02026/10/2523 天前
0.17.02026/10/1829 天前
0.16.02026/10/081 个月前
0.15.02026/10/081 个月前
0.14.12026/09/201 个月前

关于 @growth-labs/conformance 的常见问题

@growth-labs/conformance 是什么?

Reusable fleet publication conformance harness for Growth Labs sites: headers, cache, metadata, structured data, images, publication surfaces, and evidence bundles.

如何安装 @growth-labs/conformance?

在项目目录运行 npm install @growth-labs/conformance,或使用 pnpm add / yarn add / bun add。

@growth-labs/conformance 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@growth-labs/conformance 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@growth-labs/conformance 可以商用吗?

@growth-labs/conformance 使用 未声明 许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利,商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括,不构成法律意见,请以许可原文为准。

@growth-labs/conformance 的下载量有多少?

根据 npm 官方下载统计,@growth-labs/conformance 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,656 次,日均约 222 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@growth-labs/conformance 还在维护吗?

最新版本 0.19.0 发布于 2026/11/06(11 天前);至今共发布 25 个版本,其中过去 12 个月发布了 25 个;首次发布于 2026/07/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。