fix(webhook,internal): auth-first ordering + distinct error codes (API-19/26/27/28/77/78/96/97/98)

[mastermanas805]

What

Closes BUG-API-019, 026, 027, 028, 077, 078, 096, 097, 098 from the 2026-05-29 QA pass.

Two related fail-closed inversions:

1. Webhook routes /api/v1/email/webhook/brevo + /ses returned a generic 401 (error: "invalid_signature") for BOTH the secret-unset path and the signature-mismatch path. Operators chasing "Brevo can't post delivery events" got the canonical "log in for a new INSTANODE_TOKEN" agent_action — useless because the actual fault was an undeployed BREVO_WEBHOOK_SECRET. The bug is even more pointed on prod: every Brevo bounce/complaint/unsubscribe was silently lost, breaking CLAUDE.md rule 12 (email truth surface). Same pattern on SES/SNS.

2. Internal routes /internal/teams/:id/terminate, /internal/email/resend-magic-link, /internal/teams/:id/backup-quota/refund parsed the path :id / body BEFORE checking the worker JWT — so an unauthenticated probe could distinguish "path malformed" (400) from "auth bad" (401) by the envelope code, inverting the fail-closed posture documented for the /internal/* routes.

How

• Auth-first ordering on all three /internal/* handlers. Each now runs a preVerify* pass (signature + alg pin + purpose + iat freshness) BEFORE path / body parse. The team_id / link_id binding check stays in the second-phase verify, after the path / body parses cleanly. Pre-fix probes that could shape-fingerprint the route via 400 vs 401 envelope codes now see uniform 401 internal_token_required for every unauth call.

• Distinct error codes per failure class on the email-provider webhook routes:

  • webhook_secret_mismatch — operator hasn't deployed the env var
  • webhook_signature_mismatch — secret IS set, payload didn't verify
  • webhook_method_not_allowed — GET on a POST-only webhook URL (BUG-API-098 — dashboard pre-flight)

  Each carries an operator-targeted agent_action (NOT the user-targeted "log in to mint a new INSTANODE_TOKEN") so an alert correctly tells the operator to fix the deploy / dashboard, not the user to log in.

• internal_token_required as the canonical /internal/* auth-fail code.

• GET handlers on Brevo + SES webhook URLs. Return 405 + Allow: POST so a provider dashboard pre-flight that GETs the URL sees "URL exists, method wrong" instead of the catch-all 401.

• Metric instant_webhook_auth_failures_total{webhook,reason} with labels {brevo_hmac, ses_sns} x {secret_unset, signature_mismatch}. Operators can split "we forgot to deploy the secret" from "the provider rotated their key" with one query.

• NR alert webhook-auth-failures.json — CRITICAL on reason=secret_unset within 5 min (fix is one kubectl set env), per CLAUDE.md rule 25.

Tests

• 12 new hermetic tests in internal/handlers/auth_first_ordering_test.go covering every fail-first path (BUG-API-019/026/027/028/077/078/096/097/098). No DB required — sqlmock + Fiber app.
• 3 pre-existing tests updated that asserted the broken pre-fix ordering (invalid_body / invalid_link_id / invalid_team_id arms — now exercised with a valid JWT so the body / path arm stays covered).
• OpenAPI route-coverage gate updated — new GET 405 handlers added to the intentionallyHidden whitelist (provider-dashboard plumbing, not agent-facing).
• TestCodeToAgentAction_NoOrphans + TestErrorCode_HasAgentAction registry gates green.

Surface checklist

• api/internal/handlers/{email_webhooks,internal_*}.go — handler ordering + codes
• api/internal/handlers/helpers.go — codeToAgentAction (5 new entries: webhook_secret_mismatch, webhook_signature_mismatch, webhook_method_not_allowed, internal_token_required, invalid_message)
• api/internal/router/router.go — GET 405 handlers registered
• api/internal/metrics/metrics.go — instant_webhook_auth_failures_total
• api/internal/handlers/openapi_test.go — GET routes whitelisted
• infra/newrelic/alerts/webhook-auth-failures.json — NR alert (rule 25)
• [N/A] OpenAPI spec — GET endpoints are 405 plumbing, not agent surface
• [N/A] content/llms.txt — no contract change to public API
• [N/A] CHANGELOG — internal hardening, no user-visible surface change

Live verify plan (post-merge)

1. curl https://api.instanode.dev/healthz | jq .commit_id matches HEAD
2. curl -X POST https://api.instanode.dev/api/v1/email/webhook/brevo -d '{}' → 401 + error: "webhook_secret_mismatch" (NOT unauthorized)
3. curl -X GET https://api.instanode.dev/api/v1/email/webhook/brevo → 405 + Allow: POST + error: "webhook_method_not_allowed"
4. curl -X POST https://api.instanode.dev/internal/teams/NOT-A-UUID/terminate → 401 + error: "internal_token_required" (NOT 400 invalid_team_id)
5. curl -X POST https://api.instanode.dev/internal/email/resend-magic-link -d 'JUNK' → 401 + error: "internal_token_required" (NOT 400 invalid_body)

Constraints respected

• /webhooks/brevo/:secret (the transactional-delivery receiver — PR fix(onboarding,brevo): /start always 302 + Brevo 401 carries correct agent_action (API-5/6) #172) is untouched — worker rule 12 path still works.
• 401 still fires on every unauth call — only the REASON code and ordering changed.

🤖 Generated with Claude Code