{
  "markdown": "# CertScore\n\nCertScore (`certscore.ai`) is a production-minded MVP for scanning public websites for potential accessibility, privacy, cookie, policy, and disclosure risk signals. It is a risk signal and monitoring product, not a legal certification platform.\n\n## Monorepo structure\n\n```text\nwebsite-signal-risk-scanner/\n├─ apps/\n│  ├─ web/\n│  └─ validation-worker/\n├─ packages/\n│  ├─ shared/\n│  ├─ web-bot-auth/\n│  ├─ db/\n│  └─ ui/\n├─ docs/\n├─ .env.example\n├─ turbo.json\n├─ package.json\n└─ pnpm-workspace.yaml\n```\n\n## Workspace packages\n\n- `apps/web`: product-facing web app and control-plane workflows\n- `apps/validation-worker`: active validation runtime owned by `WC01`\n- `packages/shared`: shared constants, types, validators, scoring config, and scheduling helpers\n- `packages/web-bot-auth`: server-only Web Bot Auth signing and key-directory helpers\n- `packages/db`: PostgreSQL query helpers, migrations, seed SQL, and env helpers\n- `packages/ui`: reusable UI primitives\n\n## Repo boundary\n\n`WC01` is now the product/control-plane repo.\n\n- product web flows, scan creation, reporting, and validation stay here\n- the standalone scanner runtime now lives in `WS01`\n- scanner operational changes, crawler identity work, and scanner deploy flow should originate in `WS01`\n\n## What the MVP includes\n\n- public homepage with preview scan funnel\n- Better Auth with Google OAuth and email/password login flows\n- organization bootstrap and protected workspace routes\n- domain management, plan limits, and client grouping\n- DB-backed scan creation with scanner-service claiming\n- crawl/discovery, accessibility, privacy, and legal heuristics\n- deterministic scoring, canonical report payloads, and authenticated report UI\n- scanner-generated PDF generation and upload\n- regression summaries and scheduled rescans\n- lightweight branding for reports and PDFs\n\n## MCP Light\n\nCertScore.ai MCP Light is the free, no-auth, hosted three-tool integration for public website privacy scans. It detects evidence-backed privacy, cookie, tracker, consent, policy, regulatory-review, HTTPS/TLS, and eligible Reject Path post-refusal signals. Results include a CertScore score and supporting evidence for human and agentic review; they are not legal advice, certification, or a compliance determination.\n\n[Add CertScore to Cursor](https://cursor.com/link/mcp/install?name=CertScore.ai&config=eyJ1cmwiOiJodHRwczovL21jcC5jZXJ0c2NvcmUuYWkvbWNwL2xpZ2h0In0%3D) · [MCP Light landing page](https://certscore.ai/mcp/light?utm_source=github&utm_medium=repository&utm_campaign=mcp_light) · [Cursor Directory listing](https://cursor.directory/plugins/certscoreai-mcp-light) · [Agent installation guide](llms-install.md) · [Full installation reference](docs/mcp-light-install.md) · [MCP package guide](packages/certscore-mcp/README.md)\n\nTry it with: `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.`\n\n## Environment variables\n\nThis monorepo should use [apps/web/.env.local](apps/web/.env.local) as the single local development runtime env:\n\n- copy [apps/web/.env.example](apps/web/.env.example) to [apps/web/.env.local](apps/web/.env.local)\n\nUse [.env.example](.env.example) only as a reference template for shared keys. Do not rely on a root `.env.local` for app runtime configuration.\n\nRecommended environment split inside `WC01`:\n\n- local web + local validation runtime: dedicated dev PostgreSQL database plus S3-compatible storage\n- production web + production validation runtime: dedicated production PostgreSQL database plus S3-compatible storage\n\nDo not point localhost at the production database or production auth credentials unless you are intentionally testing production behavior.\n\nRequired for the web app:\n\n- `NEXT_PUBLIC_APP_URL`\n- `DATABASE_URL`\n- `BETTER_AUTH_SECRET`\n- `GOOGLE_CLIENT_ID`\n- `GOOGLE_CLIENT_SECRET`\n- `S3_BUCKET`\n- `S3_REGION`\n- `S3_ACCESS_KEY_ID`\n- `S3_SECRET_ACCESS_KEY`\n\nRequired for the validation runtime in `WC01`:\n\n- `DATABASE_URL`\n- `OPENAI_API_KEY`\n\nOptional but recommended:\n\n- `WORKER_CONCURRENCY`\n- `PLAYWRIGHT_BROWSERS_PATH`\n- `VALIDATION_OPENAI_MODEL`\n- `VALIDATION_NANO_MODEL`\n- `WEB_BOT_AUTH_ENABLED`\n- `WEB_BOT_AUTH_PRIVATE_KEY_PEM`\n- `WEB_BOT_AUTH_SIGNATURE_AGENT_URL`\n\n## Local development setup\n\nUse Node 22, 23, or 24 for local development. Node 20 is below the workspace engine floor, and Node 25 is not supported because it can fail DNS resolution for app routes and external service calls on localhost.\n\n1. Install dependencies:\n   - `pnpm install`\n2. Copy the environment template:\n   - `cp apps/web/.env.example apps/web/.env.local`\n3. Start a dedicated PostgreSQL instance for local development.\n4. Apply the SQL migrations from [packages/db/migrations](packages/db/migrations).\n5. Seed local development data when needed with [packages/db/seed/0001_dev_seed.sql](packages/db/seed/0001_dev_seed.sql).\n6. Configure Better Auth provider settings:\n   - Google OAuth if enabled\n   - email/password and verification settings as needed\n7. Configure auth redirect URLs:\n   - Google OAuth must allow Better Auth's provider callback route:\n   - `http://localhost:3000/api/auth/callback/google`\n   - `http://127.0.0.1:3000/api/auth/callback/google`\n   - `https://certscore.ai/api/auth/callback/google`\n   - `/auth/callback` is only an app alias route; it is not the redirect URI Better Auth initiates with Google\n8. Keep local and production auth isolated:\n   - local `NEXT_PUBLIC_APP_URL` should be `http://localhost:3000`\n   - local database and auth secrets should come from the dev environment\n   - production secrets should exist only in the active AWS/web or worker deployment settings\n9. Create the S3-compatible bucket referenced by `S3_BUCKET`.\n10. Install Playwright Chromium for the validation runtime:\n   - `pnpm --filter @website-signal-risk-scanner/validation-worker exec playwright install chromium`\n11. Start validation local development with a watched validation worker:\n   - `pnpm dev:validation`\n12. Start the main local app by itself when needed:\n   - `pnpm --filter @website-signal-risk-scanner/web dev`\n13. Use `WS01` when you need the standalone scanner locally.\n14. Start the standalone scanner locally against the same dev database and storage env as `localhost:3000`:\n   - `pnpm dev:scanner:local`\n15. Use the combined local runner only when you want web + validation together in `WC01`:\n   - `pnpm dev:all`\n16. Run a validation scheduler sweep manually when needed:\n   - `pnpm dev:validation:scheduler`\n\n## Development verification\n\nUse these commands before shipping changes:\n\n- `pnpm turbo run typecheck`\n- `pnpm turbo run build`\n\nValidation-specific checks:\n\n- `pnpm --filter @website-signal-risk-scanner/validation-worker typecheck`\n- `pnpm test:scan-pipeline`\n\nThe scan pipeline test is deterministic and runs locally from `apps/validation-worker/src/validation/pipeline.test.ts`.\n\nThe normalized concern lifecycle in `WC01` is documented in [docs/normalized-concern-pipeline.md](docs/normalized-concern-pipeline.md).\n\n## CI validation\n\nGitHub Actions workflow: [.github/workflows/accessibility-validation.yml](.github/workflows/accessibility-validation.yml)\n\n- `worker-scan-pipeline-tests` runs on pushes to `main`, pull requests, and manual dispatch. It installs Chromium, typechecks `validation-worker`, and runs `pnpm test:scan-pipeline`.\n- `live-validation-smoke` runs after the deterministic job and executes `pnpm --filter @website-signal-risk-scanner/validation-worker smoke:validation` only when the runtime secrets are configured.\n- If those secrets are missing, the live smoke job is skipped and only the deterministic scan pipeline job runs.\n\n## Runtime validation tooling\n\nUse these lightweight checks before first deployment validation:\n\n- `pnpm dev:storage:local`\n- `pnpm --filter @website-signal-risk-scanner/web check-env`\n- `pnpm check-env:validation`\n- `pnpm --filter @website-signal-risk-scanner/validation-worker check-env`\n- `pnpm --filter @website-signal-risk-scanner/validation-worker check-runtime`\n\nFor local validation runs, `pnpm dev:storage:local` starts MinIO against the `apps/web/.env.local` S3 settings and creates the configured bucket when needed.\nRun it alongside `pnpm dev:scanner:local` and `pnpm dev:validation:worker`.\n\nUse this runtime smoke helper:\n\n- `pnpm --filter @website-signal-risk-scanner/validation-worker scheduler`\n\nThe full runtime QA sequence is documented in [docs/runtime-validation.md](docs/runtime-validation.md).\nThe validation pipeline design and deployment shape are documented in [docs/validation-pipeline-plan.md](docs/validation-pipeline-plan.md).\nThe validation crawler deployment and VM runbook is documented in [docs/validation-ops-runbook.md](docs/validation-ops-runbook.md).\nCloudflare Verified Bot setup is documented in [docs/cloudflare-web-bot-auth.md](docs/cloudflare-web-bot-auth.md).\n\n## Web Bot Auth\n\nConsentCheck can expose a signed HTTP Message Signatures key directory and sign outbound HTTP crawler requests for Cloudflare Verified Bot workflows.\n\nRequired configuration:\n\n- `WEB_BOT_AUTH_ENABLED`\n- `WEB_BOT_AUTH_PRIVATE_KEY_PEM`\n- `WEB_BOT_AUTH_SIGNATURE_AGENT_URL`\n- `WEB_BOT_AUTH_EXPIRES_SECONDS`\n- `WEB_BOT_AUTH_INCLUDE_NONCE`\n\nCommon commands:\n\n- `pnpm web-bot-auth:generate`\n- `pnpm web-bot-auth:print`\n- `pnpm web-bot-auth:test-request`\n- `pnpm test:web-bot-auth`\n\n## Production deployment\n\n### Web runtime\n\n- the live public web deployment target is the AWS ECS/Fargate path for `certscore.ai`\n- `consentcheck.site` is owned outside WC01 and must not be deployed by this repo\n- `main` deploys through [.github/workflows/web-aws-ecs-deploy.yml](.github/workflows/web-aws-ecs-deploy.yml)\n- run `pnpm ops:check:deploy` before or after topology changes to catch stale local assumptions\n- run `pnpm ops:check:live` against the public hosts to verify runtime target and revision alignment after deploy\n- treat [docs/aws-web-ecs-cutover-plan.md](docs/aws-web-ecs-cutover-plan.md) as the active web deployment runbook\n- treat [docs/deploy-amplify.md](docs/deploy-amplify.md) as future-state reference material only\n\n### Validation And Scanner Runtime\n\n- do not use `WC01` for the primary scanner deploy path\n- use `WS01` for scanner runtime deployment\n- keep `WC01` deployment guidance scoped to web and validation only\n- keep web production, validation worker, and scanner runtime as three distinct deployment paths\n- use the AWS validation deployment lane for `WC01` validation runtime changes\n\n### Database, Auth, and Storage\n\n- create production PostgreSQL, Better Auth, and S3-compatible storage resources separate from local development\n- apply all migrations in order\n- configure the production site URL and production redirect URLs only\n- create the report storage bucket referenced by `S3_BUCKET`\n\n### Scheduler\n\nRecommended production trigger:\n\n- run the validation scheduler sweep every hour if the validation runtime is enabled\n\nCommand:\n\n- `pnpm dev:validation:scheduler`\n\nThe primary scanner scheduler now lives in `WS01`.\n\n## Deployment readiness checklist\n\n- Environment variables configured\n- PostgreSQL database created\n- database migrations applied\n- Better Auth providers configured\n- S3-compatible storage bucket created\n- Playwright browsers installed\n- Worker process running\n- Scheduler cron configured\n- First domain scanned successfully\n- Report generated successfully\n- PDF export generated successfully\n\n## First production validation\n\nAfter deployment, validate in this order:\n\n1. run the env and runtime checks above\n2. verify login and organization bootstrap\n3. verify preview scan flow\n4. verify full scan completion\n5. verify findings, scores, and report persistence\n6. verify PDF export\n7. verify regression on a second scan\n8. verify the hourly scheduler sweep path\n\n## Operational notes\n\n- The standalone scanner in `WS01` owns crawl, auditing, scoring, reporting, PDF generation, and scheduled sweep logic.\n- PDF generation failures do not invalidate the scan or web report.\n- Regression calculation failures do not invalidate the scan or report.\n- The app validates critical env vars at runtime and now fails fast with clearer messages when required configuration is missing.\n\n## References\n\n- [Better Auth documentation](https://www.better-auth.com/)\n- [PostgreSQL documentation](https://www.postgresql.org/docs/)\n- [Amazon S3 API reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)\n",
  "bytes": 12516,
  "sha": "bdfa004b21238255a3f1e9429fe39efc3a6b5c225d64543d77f9f0551969138d",
  "repo_slug": "ergoveritas1-alt/certscore.ai",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_certscore_mcp_60b4e298/readme"
}