Certscore

CertScore

CertScore（certscore.ai）は、公開ウェブサイトをスキャンして、アクセシビリティ、プライバシー、Cookie、ポリシー、開示に関する潜在的なリスクシグナルを検出する、実運用を意識した MVP です。法的な認証プラットフォームではなく、リスクシグナルの監視製品です。

モノレポの構成

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：プロダクト向けウェブアプリとコントロールプレーンのワークフロー
• apps/validation-worker：WC01 が所有するアクティブな検証ランタイム
• packages/shared：共有定数、型、バリデーター、スコアリング設定、スケジューリングヘルパー
• packages/web-bot-auth：サーバー専用の Web Bot Auth 署名およびキーディレクトリヘルパー
• packages/db：PostgreSQL クエリヘルパー、マイグレーション、シード SQL、環境変数ヘルパー
• packages/ui：再利用可能な UI プリミティブ

リポジトリの境界

WC01 は現在、プロダクト／コントロールプレーンのリポジトリです。

• プロダクトのウェブフロー、スキャンの作成、レポート、検証はここで行います
• スタンドアロンのスキャナーランタイムは現在 WS01 にあります
• スキャナーの運用上の変更、クローラーの ID 作業、スキャナーのデプロイフローは WS01 で開始してください

MVP に含まれる機能

• プレビュースキャンの導線を備えた公開ホームページ
• Google OAuth とメール／パスワードのログインフローを備えた Better Auth
• 組織の初期設定と保護されたワークスペースルート
• ドメイン管理、プラン制限、クライアントのグループ化
• スキャナーサービスによるクレーム処理に対応した DB ベースのスキャン作成
• クロール／検出、アクセシビリティ、プライバシー、法務に関するヒューリスティック
• 決定論的なスコアリング、正規化されたレポートペイロード、認証済みレポート UI
• スキャナーによる PDF の生成とアップロード
• 回帰サマリーと定期的な再スキャン
• レポートと PDF 向けの軽量なブランディング

MCP Light

CertScore.ai MCP Light は、公開ウェブサイトのプライバシースキャン向けにホストされた、無料で認証不要の 3 ツール統合です。プライバシー、Cookie、トラッカー、同意、ポリシー、規制審査、HTTPS/TLS、および対象となる拒否後の Reject Path シグナルについて、証拠に基づく情報を検出します。結果には CertScore スコアと、人間およびエージェントによるレビューを支援する証拠が含まれます。法的助言、認証、コンプライアンスの判定ではありません。

CertScore を Cursor に追加 · MCP Light のランディングページ · Cursor Directory の掲載ページ · エージェントのインストールガイド · インストールの完全なリファレンス · 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 またはワーカーのデプロイ設定にのみ存在するようにします
9. S3_BUCKET で指定された S3 互換バケットを作成します。
10. 検証ランタイム用に Playwright Chromium をインストールします：

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

11. 検証ワーカーを監視モードで起動して、検証のローカル開発を開始します：

• 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 キーディレクトリを公開し、Cloudflare Verified Bot ワークフロー向けに送信する HTTP クローラーリクエストに署名できます。

必須の設定：

• 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 を実行し、ランタイムのデプロイ先とリビジョンが一致していることを確認してください
• 現行の Web デプロイ運用手順書として docs/aws-web-ecs-cutover-plan.md を使用してください
• 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 ブラウザーをインストール済み
• ワーカープロセスを稼働中
• スケジューラーの cron を設定済み
• 最初のドメインのスキャンに成功済み
• レポートの生成に成功済み
• PDF エクスポートの生成に成功済み

初回の本番環境での検証

デプロイ後、次の順序で検証します：

1. 上記の環境変数とランタイムのチェックを実行します
2. ログインと組織の初期設定を確認します
3. プレビューのスキャンフローを確認します
4. フルスキャンの完了を確認します
5. 検出結果、スコア、レポートの永続化を確認します
6. PDF エクスポートを確認します
7. 2 回目のスキャンで回帰を確認します
8. 毎時のスケジューラーのスイープ経路を確認します

運用上の注意

• WS01 のスタンドアロンスキャナーが、クロール、監査、スコアリング、レポート作成、PDF 生成、スケジュールされたスイープのロジックを管理します。
• PDF 生成に失敗しても、スキャンや Web レポートは無効になりません。
• 回帰計算に失敗しても、スキャンやレポートは無効になりません。
• アプリは実行時に重要な環境変数を検証し、必須の設定が不足している場合は、より明確なメッセージを表示して即座に失敗するようになりました。

参考資料

• Better Auth のドキュメント
• PostgreSQL のドキュメント
• Amazon S3 API リファレンス