@ 增长栏/ 合规
为增长实验室网站提供可重复使用的出版物兼容性利用。 它能验证 每一地点的固定装置和提供机器可分辨的证据包供制作, 缓存、 安全信头、 元数据、 结构数据、 图像、 发布 表面,发现资格,和建立证据.
这个包被站点和CI工作所消耗. 这不是中央舰队 运行时间和它不获取、变异、部署或储存舰队状态.
公共或爬行器固定装置可明确批准范围内含样式
expected.publicInlineStyles: { attributes: true, elements: true }两种布尔
需要; 每项 true 需要相应的 style-src-attr 或者说
style-src-elem 'unsafe-inline' 实际执行的CSP中的补助。 缺席或
false 保留现有的严格/属性库存验证。 本合同
不允许私人受众、同时免收属性和
库存接收,或脚本中不安全的内入,默认弧,或无范围样式弧.
缓存安全性
import {
applyPrivateNoStore,
assertSafeEntrypointCacheConfiguration,
evaluateCacheSafety,
scanRequestStateLeaks,
} from '@growth-labs/conformance/cache-safety'
assertSafeEntrypointCacheConfiguration(finalWranglerConfig) 验证未知
与 Zod 输入,并丢入不安全或错误的部署缓存设置.
全局/ 默认切入点仍然未标记; 只有输入 PublicPages 劳动者
导出可选择使用,而不进行交叉版本再利用。 缓存密钥和工人导出
键很严格;不相关的Wrangler字段和非工作选项被保存.
终极环境控制仍然被禁止。 校验器不突变输入 .
缓存- 安全合同保留默认网关, 需要明确
当公共 HTML 缓存启用时, 仅免费命名的 PublicPages 安全合同,
并验证一个非公共的、无副作用的内饰
带有明确的转发标题许可列表,并证明 HIT 仍然执行
外部网关副作用. applyPrivateNoStore() 写入完整
缓存控制/CDN-缓存控制/ Cloudflare-CDN-缓存控制 三进制并移除
瓦里来的饼干.
寄出缓存证据失败 cache.evidence.missingA. 公众的反应
与 Set-Cookie 除非它装满了三胞胎 否则失败了. Vary: Cookie
总是失败——即使与私人三胞胎在一起——因为 Cookie 差异不是
部分支持的合同; 在私人响应标记后删除.
机身扫描仪接受受控请求状态的监视器,并探测到它们
字形,URI,JSON,和 Base64 形式. 它的收受只暴露于国家类别
和编码,绝不是原始的. cacheSafetyLiveResultSchema 验证
设定的结果.
已建工人的路线
runWorkerRoutes() (传教士) @growth-labs/conformance/worker-routes只有节点,需要
选项对等点 miniflare给建筑工人穿靴子 dist/server 在微小的墙上
已承诺的D1固定,并要求出版物必须回答路线问题。 它声称地位,
<title>、犬科、JSON-LD类型和 og:image (和内容类型和
feed, sitemap and robots.txt),并返回结果作为符合性结果.
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))
查找代码 : route.status.unexpected (单位:500) / 是这个,从身体开始
证据, 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。一个路由 spec 可以覆盖任何期望
(单位:千美元)status 可能是一个列表, jsonLdTypes 条目可能是备选条目)。 纯度的一半
(单位:千美元)evaluateRoute, (中文(简体) ), buildRouteReport以其他方式获取的答复.
安装
pnpm add @growth-labs/conformance
基本用途
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])
部署端点适配器
消费者拥有这条路 符合礼仪的艺术品 和Cloudflare
[version_metadata] 装订。 CI/建设探险台阶运行
runSiteConformance(),将结果序列化为 JSON 文物文件
和工人把文件捆起来 适配器读取 预建的文物在
模块载荷(不是每个请求)并服务于:
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 剖析出文物,与v2相对验证
计划,检查 environment: 'production' 和预期网站,要求
buildEvidence.commitSha (小于40-特征六)和
buildEvidence.generatedAt (时间区合格ISO-8601日期时间),以及
序列化了一次图案的字节。 仅按请求处理
验证方法并进行比较 versionMetadata.tag 与被烧死的人作对
SHA——没有I/O,没有被探测器执行,没有被重新序列化. 失踪/畸形
文物和错误的站点/环境产生一个总是返回503的处理器.
适配器从不读取或序列化环境绑定,请求标题,
Cloudflare版本ID, Cloudflare版本时间戳, 内部例外,或
字段。 它不执行高压秘密
检测: 已记录的自由形式字符串, 如查找信件、 查找
证据、补救文本和收据证据保持不变,属于
消费者的消毒责任.
共享信头政策
使用 buildSharedPublicationHeaders() 当一个网站想要软件包拥有时
用于安全部门改革和静态反应头的基线。 关于释放物的天体站点
支助 security.csp 应让Astro拥有每道散列CSP并保留
剩下的共享标题。 包对等合同仍然是庄园的
可选Astro 6合同:
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',
})
分析标记来源 (@ growth-labs/analysis)
启用 @growth-labs/analytics 外部标签必须添加标签'
确切的来源 SecurityHeadersConfig 允许列表( 相同 )
窗体作为以上示例——脚本主机没有通配符。 两个标签都是
外部 <script src> 没有线性靴子,所以基于散列的CSP只需要
这些起源,而不是逐一递减的散列:
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',
],
})
仅为网站实际启用的标记添加源( CWA 仅网站省略 GA4起源,反之亦然).
固定默认是上面不可嵌入的政策. 为了一个故意
可嵌入的路径, 声明其确切的响应类别, 并省略一个相冲突
X-Frame-Options 页眉 :
expected: {
framePolicy: {
ancestors: ['https://trusted.example'],
legacyHeader: 'omit',
},
}
被接受的祖先为 'none', (中文(简体) ), 'self', (中文(简体) ), https:和确切的HTTPS起源;
通配符,路径,证书,查询字符串,和片段都被拒绝.
DENY 仅使用 'none',以及 SAMEORIGIN 仅使用 'self'宽
嵌入式政策必须使用 legacyHeader: 'omit' 避免矛盾
浏览器行为.
天体6号 security.csp 无法代表属性范围样式资源。 如果有的话
路由仍然发送 HTML style 属性,保留天体本地化帮助
故障关闭,并使用 style-src-attr 加减
已验证 inlineStyleAttributes 在符合性固定的接收。 这个
接收需要精确的 小写 40 字符构建 承诺 SHA,一个正数
发生数、版本扫描仪身份和小写SHA-256
其机器输出的散列内容。 同一收据必须在
遵守规定及其承诺必须相符 buildEvidence.commitSha选择
使用内置式的备忘作为通用相容性修补.
政策发布CSP,HSTS,帧保护,MIME嗅出保护,
COOP、CORP、裁判员政策、权限政策、缓存语义和可选
标记下双 Link 元数据。 私人受众使用 private, no-store· ;
公共 SSR 使用短的共享- cache 语义; 公共静态表面变长
共享缓存语义.
HSTS 默认为 max-age=31536000 只有这个 添加 includeSubDomains 财务报告和审定财务报表 preload
结束 strictTransportSecurity: { includeSubDomains: true, preload: true }
只有在消费者单独核实了完整的主机库存之后,才能
执行HTTPS. COOP 默认为 same-origin 和CORP 默认为
same-origin消费者只有在经过验证的 OAuth 弹出时才能超过,
或嵌入式制约需要宽松的政策,收据证明
执行的CSP的结果.
固定命令
根回波曝光:
pnpm run conformance:test-fixtures
pnpm run conformance:verify-schema
定点命令证明所需的负定出错 稳定查找代码 :
csp-unsafe-inlinemissing-coopmissing-corphsts-below-one-yearcsp-wildcard-default-srccsp-unsafe-evalcsp-inline-executable-without-nonce-or-hashconflicting-duplicate-security-headermissing-functional-probe-receiptmissing-csp-report-receiptfailed-csp-report-receiptheaders-static-only-while-ssr-missingundeclared-nastringified-is-accessible-for-freevideo-object-date-only-upload-datemissing-image-dimensionshero-under-1200pxmissing-max-image-preview-largecrawler-public-cache-key-collisionruntime-canonical-override-not-appliedllms-runtime-static-shadowdefault-entrypoint-cache-enabledpublic-html-without-named-renderernamed-renderer-not-free-onlystored-member-responsestored-crawler-body-responsestored-set-cookie-responseraw-credential-forwarded-to-innercached-body-request-state-leakgateway-hit-side-effects-bypassedpersonalized-public-responsepublic-set-cookie-responsevary-cookie-response
证据形状
runSiteConformance() 返回 a SiteEvidenceBundle· ; runFleetConformance()
返回 a FleetEvidenceBundle。二者均通过导出 Zod 计划验证
并携带 schemaVersion: "growth-labs.conformance.v2" 这样下游的工作就可以
在不依赖控制台文本的情况下分析它们.
Schema v2 添加 securityReceipts 给固定装置和现场证据包 现有
v1 固定装置必须添加明确的功能测试收据,用于 oauth, (中文(简体) ), media, (中文(简体) ),
images, (中文(简体) ), analytics, (中文(简体) ), embeds,以及 error-pages,加上至少一个经过的 CSP
报告/收到通知。 包裹本身不执行活探测器;
消费者CI提供消毒通行证/故障/NA收据.