Certscore

CertScore

CertScore（certscore.ai）是一款以投入生产为目标的 MVP，用于扫描公开网站，发现潜在的无障碍、隐私、Cookie、政策和披露风险信号。它是一款风险信号监测产品，并非法律认证平台。

Monorepo 结构

website-signal-risk-scanner/
├─ apps/
│  ├─ web/
│  └─ validation-worker/
├─ packages/
│  ├─ shared/
│  ├─ web-bot-auth/
│  ├─ db/
│  └─ ui/
├─ docs/
├─ .env.example
├─ turbo.json
├─ package.json
└─ pnpm-workspace.yaml

工作区软件包

• apps/web：面向用户的 Web 应用和控制平面工作流
• apps/validation-worker：由 WC01 负责的活动验证运行时
• packages/shared：共享常量、类型、验证器、评分配置和调度辅助工具
• packages/web-bot-auth：仅限服务端使用的 Web Bot Auth 签名和密钥目录辅助工具
• packages/db：PostgreSQL 查询辅助工具、迁移、种子 SQL 和环境变量辅助工具
• packages/ui：可复用的 UI 基础组件

仓库边界

WC01 现在是产品／控制平面仓库。

• 产品 Web 流程、扫描创建、报告和验证仍由此处负责
• 独立扫描器运行时现已位于 WS01
• 扫描器运维变更、爬虫身份工作和扫描器部署流程应从 WS01 发起

MVP 包含的内容

• 带有预览扫描流程的公开主页
• 使用 Google OAuth 和电子邮件／密码登录流程的 Better Auth
• 组织初始化和受保护的工作区路由
• 域名管理、计划限制和客户端分组
• 由数据库支持的扫描创建，并由扫描器服务认领
• 爬取／发现、无障碍、隐私和法律启发式检查
• 确定性评分、规范报告负载和经过身份验证的报告 UI
• 扫描器生成 PDF 并上传
• 回归摘要和定期重新扫描
• 报告和 PDF 的轻量品牌定制

MCP Light

CertScore.ai MCP Light 是一款免费、无需身份验证、托管式的三工具集成，用于公开网站隐私扫描。它可检测有证据支持的隐私、Cookie、跟踪器、同意机制、政策、法规审查、HTTPS/TLS，以及符合条件的拒绝后 Reject Path 信号。结果包含 CertScore 评分及支持性证据，供人工和 Agent 审查；这些结果不构成法律建议、认证或合规性判定。

将 CertScore 添加到 Cursor · MCP Light 介绍页 · Cursor Directory 列表 · Agent 安装指南 · 完整安装参考 · MCP 软件包指南

试用方法：Use CertScore.ai to review [PUBLIC URL] before launch. Report the CertScore score, evidence-backed findings, Reject Path observations when available, coverage limitations, and the report URL.

环境变量

此单体仓库应使用 apps/web/.env.local 作为唯一的本地开发运行时环境文件：

• 将 apps/web/.env.example 复制到 apps/web/.env.local

仅将 .env.example 用作共享键的参考模板。不要依赖根目录下的 .env.local 配置应用运行时。

建议在 WC01 中按以下方式划分环境：

• 本地 Web + 本地验证运行时：专用的开发 PostgreSQL 数据库和兼容 S3 的存储
• 生产 Web + 生产验证运行时：专用的生产 PostgreSQL 数据库和兼容 S3 的存储

除非你有意测试生产环境的行为，否则不要让 localhost 指向生产数据库或使用生产身份验证凭据。

Web 应用必需的变量：

• NEXT_PUBLIC_APP_URL
• DATABASE_URL
• BETTER_AUTH_SECRET
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• S3_BUCKET
• S3_REGION
• S3_ACCESS_KEY_ID
• S3_SECRET_ACCESS_KEY

WC01 中验证运行时必需的变量：

• DATABASE_URL
• OPENAI_API_KEY

可选但建议配置：

• WORKER_CONCURRENCY
• PLAYWRIGHT_BROWSERS_PATH
• VALIDATION_OPENAI_MODEL
• VALIDATION_NANO_MODEL
• WEB_BOT_AUTH_ENABLED
• WEB_BOT_AUTH_PRIVATE_KEY_PEM
• WEB_BOT_AUTH_SIGNATURE_AGENT_URL

本地开发设置

本地开发请使用 Node 22、23 或 24。Node 20 低于工作区要求的最低版本；由于 Node 25 可能导致应用路由和 localhost 上的外部服务调用出现 DNS 解析失败，因此不受支持。

1. 安装依赖：
   • pnpm install
2. 复制环境模板：
   • cp apps/web/.env.example apps/web/.env.local
3. 启动专用的 PostgreSQL 本地开发实例。
4. 应用 packages/db/migrations 中的 SQL 迁移。
5. 需要时，使用 packages/db/seed/0001_dev_seed.sql 填充本地开发数据。
6. 配置 Better Auth 提供商设置：
   • 如已启用，则配置 Google OAuth
   • 按需配置邮箱/密码及验证设置
7. 配置身份验证重定向 URL：
   • Google OAuth 必须允许 Better Auth 的提供商回调路由：
   • http://localhost:3000/api/auth/callback/google
   • http://127.0.0.1:3000/api/auth/callback/google
   • https://certscore.ai/api/auth/callback/google
   • /auth/callback 仅是应用别名路由；它不是 Better Auth 发起 Google 身份验证时使用的重定向 URI
8. 隔离本地和生产身份验证：
   • 本地 NEXT_PUBLIC_APP_URL 应为 http://localhost:3000
   • 本地数据库和身份验证密钥应来自开发环境
   • 生产密钥只能存在于当前 AWS/Web 部署或 Worker 部署设置中
9. 创建 S3_BUCKET 所指向的兼容 S3 存储桶。
10. 为验证运行时安装 Playwright Chromium：

• pnpm --filter @website-signal-risk-scanner/validation-worker exec playwright install chromium

11. 启动带文件监视功能的验证 Worker，进行本地开发：

• pnpm dev:validation

12. 需要时，单独启动本地主应用：

• pnpm --filter @website-signal-risk-scanner/web dev

13. 需要在本地独立运行扫描器时，请使用 WS01。
14. 使用与 localhost:3000 相同的开发数据库和存储环境变量，在本地启动独立扫描器：

• pnpm dev:scanner:local

15. 仅当你想在 WC01 中同时运行 Web 和验证时，才使用组合式本地运行器：

• pnpm dev:all

16. 需要时，手动运行验证调度器扫描：

• pnpm dev:validation:scheduler

开发验证

发布更改前，请运行以下命令：

• pnpm turbo run typecheck
• pnpm turbo run build

针对验证的检查：

• pnpm --filter @website-signal-risk-scanner/validation-worker typecheck
• pnpm test:scan-pipeline

扫描流水线测试具有确定性，可在本地通过 apps/validation-worker/src/validation/pipeline.test.ts 运行。

WC01 中标准化的关注项生命周期记录在 docs/normalized-concern-pipeline.md 中。

CI 验证

GitHub Actions 工作流：.github/workflows/accessibility-validation.yml

• worker-scan-pipeline-tests 会在推送到 main、创建拉取请求以及手动触发时运行。它会安装 Chromium、对 validation-worker 进行类型检查，并运行 pnpm test:scan-pipeline。
• live-validation-smoke 会在确定性任务之后运行；只有配置了运行时密钥时，才会执行 pnpm --filter @website-signal-risk-scanner/validation-worker smoke:validation。
• 如果缺少这些密钥，实时冒烟测试任务会跳过，只运行确定性扫描流水线任务。

运行时验证工具

首次部署验证前，请使用以下轻量检查：

• pnpm dev:storage:local
• pnpm --filter @website-signal-risk-scanner/web check-env
• pnpm check-env:validation
• pnpm --filter @website-signal-risk-scanner/validation-worker check-env
• pnpm --filter @website-signal-risk-scanner/validation-worker check-runtime

在本地运行验证时，pnpm dev:storage:local 会根据 apps/web/.env.local 中的 S3 设置启动 MinIO，并在需要时创建已配置的存储桶。 请同时运行 pnpm dev:scanner:local 和 pnpm dev:validation:worker。

使用此运行时冒烟测试辅助工具：

• pnpm --filter @website-signal-risk-scanner/validation-worker scheduler

完整的运行时 QA 流程记录在 docs/runtime-validation.md 中。 验证流水线的设计和部署方式记录在 docs/validation-pipeline-plan.md 中。 验证爬虫的部署和 VM 运维手册记录在 docs/validation-ops-runbook.md 中。 Cloudflare Verified Bot 的设置记录在 docs/cloudflare-web-bot-auth.md 中。

Web Bot Auth

ConsentCheck 可以公开一个经过签名的 HTTP Message Signatures 密钥目录，并为发出的 HTTP 爬虫请求签名，以支持 Cloudflare Verified Bot 工作流。

必需配置：

• WEB_BOT_AUTH_ENABLED
• WEB_BOT_AUTH_PRIVATE_KEY_PEM
• WEB_BOT_AUTH_SIGNATURE_AGENT_URL
• WEB_BOT_AUTH_EXPIRES_SECONDS
• WEB_BOT_AUTH_INCLUDE_NONCE

常用命令：

• pnpm web-bot-auth:generate
• pnpm web-bot-auth:print
• pnpm web-bot-auth:test-request
• pnpm test:web-bot-auth

生产部署

Web 运行时

• 面向公众的线上 Web 部署目标是 certscore.ai 对应的 AWS ECS/Fargate 路径
• consentcheck.site 由 WC01 之外的主体管理，不得通过此仓库部署
• main 通过 .github/workflows/web-aws-ecs-deploy.yml 部署
• 拓扑更改前后运行 pnpm ops:check:deploy，以发现过时的本地假设
• 部署后针对公共主机运行 pnpm ops:check:live，以验证运行时目标和版本是否一致
• 将 docs/aws-web-ecs-cutover-plan.md 视为当前 Web 部署运维手册
• 仅将 docs/deploy-amplify.md 作为未来状态的参考资料

验证与扫描器运行时

• 不要将 WC01 用作主要的扫描器部署路径
• 使用 WS01 部署扫描器运行时
• 将 WC01 部署指南限定为 Web 和验证
• 将 Web 生产环境、验证工作进程和扫描器运行时保留为三条独立的部署路径
• 对 WC01 验证运行时的更改，使用 AWS 验证部署通道

数据库、身份验证和存储

• 创建与本地开发环境分开的生产环境 PostgreSQL、Better Auth 和兼容 S3 的存储资源
• 按顺序应用所有迁移
• 仅配置生产站点 URL 和生产重定向 URL
• 创建 S3_BUCKET 引用的报告存储桶

调度器

推荐的生产触发方式：

• 如果启用了验证运行时，每小时运行一次验证调度器扫描

命令：

• pnpm dev:validation:scheduler

主扫描器调度器现在位于 WS01。

部署就绪检查清单

• 已配置环境变量
• 已创建 PostgreSQL 数据库
• 已应用数据库迁移
• 已配置 Better Auth 提供商
• 已创建兼容 S3 的存储桶
• 已安装 Playwright 浏览器
• Worker 进程正在运行
• 已配置调度器 cron
• 已成功扫描第一个域名
• 已成功生成报告
• 已成功生成 PDF 导出文件

首次生产环境验证

部署后，按以下顺序进行验证：

1. 运行上述环境和运行时检查
2. 验证登录和组织初始化
3. 验证预览扫描流程
4. 验证完整扫描是否完成
5. 验证发现项、评分和报告是否持久化
6. 验证 PDF 导出
7. 验证第二次扫描时的回归检测
8. 验证每小时调度器扫描流程

运营说明

• WS01 中的独立扫描器负责爬取、审计、评分、报告、PDF 生成和定时扫描逻辑。
• PDF 生成失败不会使扫描或网页报告失效。
• 回归计算失败不会使扫描或报告失效。
• 应用会在运行时验证关键环境变量；缺少必需配置时，现在会快速失败并显示更清晰的消息。

参考资料

• Better Auth 文档
• PostgreSQL 文档
• Amazon S3 API 参考