Module: routes/trigger

Webhook handlers require BOTH:

1. A valid HMAC signature from the deployment provider (proves Vercel/ Netlify sent the payload — protects against forged calls).
2. A project-scoped trigger token via requireTrigger (proves which project should run — without this, a single global webhook secret would let any signed payload trigger any project ID in the URL).

Conclude a GitHub Check Run once the Sentri run reaches a terminal state.

Placement rationale (deviates from NEXT.md INT-002 sketch): NEXT.md suggests this hook lives in testRunner.js onComplete. We keep it here because (a) testRunner.js has no internal completion hook — runWithAbort.onComplete is the hook, fired from this file already; (b) only the trigger path carries GitHub repo/sha context, so wiring it through the runner would require threading run.githubCheck plumbing into a module that has no other reason to know about integrations; (c) keeping integration side-effects at the route layer matches the pattern used by fireNotifications (FEA-001) just above this call. Errors are always logged + swallowed so a GitHub outage never fails the underlying Sentri run (INT-002 anti-pattern guard).

HMAC signature verification for deployment-webhook payloads.

Per-provider algorithm choice is dictated by each provider, not by us:

• Vercel: HMAC-SHA1 over the raw body (X-Vercel-Signature header). Vercel's current webhook spec still signs with SHA-1; any change would have to come from Vercel. HMAC-SHA1 (unlike plain SHA-1) is not known to be vulnerable — the keyed prefix construction defeats the collision attacks that retired SHA-1 for certificate signing. Pre-image resistance in HMAC depends on the key, not the hash, so an attacker who cannot guess VERCEL_WEBHOOK_SECRET cannot forge a valid signature.
• Netlify: HMAC-SHA256 over the raw body (X-Netlify-Token header).

If you're auditing this and wondering "why SHA-1?" — the answer is interoperability with the provider's signing scheme. When Vercel upgrades their webhook signatures, bump algo for the "vercel" branch here.

Build a type: "crawl" run object aligned with routes/runs.js:71-83.

Build a type: "test_run" run object aligned with routes/runs.js:188-213.

AUTO-001: persisted testQueue mirrors the approved-test order (audit fidelity) with per-row riskScore; budget-skipped tests are pre-seeded into results as skipped (over_budget) so every approved test has an observable resolution. total reflects the approved set, not the post-budget dispatch slice.

POST /api/projects/:id/trigger Token-authenticated endpoint for CI/CD pipelines (ENH-011).

Authentication

Pass the project trigger token as a Bearer token:

Authorization: Bearer <plaintext-token>

This endpoint does NOT accept JWTs — only tokens created via POST /api/projects/:id/trigger-tokens.

Request body (all fields optional)

{
  "callbackUrl":  "https://ci.example.com/hooks/sentri",
  "dialsConfig":  { "parallelWorkers": 2 }
}

Response 202 Accepted

{ "runId": "RUN-42", "statusUrl": "https://sentri.example.com/api/runs/RUN-42" }

Poll statusUrl until status is no longer "running".

Error responses

Launch a crawl run against a deployment-preview URL. Shared by the Vercel and Netlify webhook handlers below — kept in one place so the run-object shape and runWithAbort wiring stay aligned with runs.js:71-127 (the canonical crawl entry point).

The caller must have already (a) verified the provider's HMAC signature, (b) authenticated the trigger token via requireTrigger, and (c) validated previewUrl via SSRF guard.

AUTO-015b: emits a dedicated crawl.start.deployment activity row (see below) alongside the standard crawl.start, so the "Last deployment run" badge on the project header can distinguish webhook-launched crawls from manually-triggered ones via the activity log without a schema change.

Prepare a GitHub Check Run for a Sentri run, returning the metadata to persist on run.githubCheck (or null when no check should be created).

Idempotency contract (INT-002): GitHub retries failed webhook deliveries (any non-2xx) with exponential backoff for up to 24h, always using the same X-GitHub-Delivery UUID. The delivery ID — not the commit SHA — is the correct idempotency key:

• Same delivery ID → GitHub is retrying. Return existing check, do not create a new run, do not transition state on GitHub.
• New delivery ID for the same SHA → distinct event (e.g. rerequested after a user clicks "Re-run"). Create a fresh Check Run.

Thin wrapper around safeFetch for the callbackUrl POST. Best-effort: errors are silently caught so a failing callback never affects the run outcome.