Penetration test preparation (draft)

Scope package for a third-party pentest before SOC 2 Type II. Not a test report — hand this to the vendor with a scoped API key.

Public summary: security.html

In scope

Surface	URL / entry	Notes
REST API	https://api.webmailagent.com	Bearer API key; team-scoped
Remote MCP	POST https://api.webmailagent.com/mcp	OAuth mat_ or API key
OAuth discovery	/.well-known/oauth-authorization-server	RFC 8414
Dashboard (static)	https://webmailagent.com/dashboard.html	Uses same API key in browser storage
Inbound webhooks	POST /webhooks/resend · POST /webhooks/resend/team/:teamId	Signature verification
Stripe webhook	POST /webhooks/stripe	Disabled until billing live

Out of scope (unless agreed)

• Cloudflare / Neon / Resend control planes (shared responsibility)
• Customer SMTP senders (untrusted inbound email content — see abuse policy)
• Auth0 tenant admin (IdP config)
• DDoS / volumetric only (Cloudflare edge)
• Social engineering of operator

Test account

Provide the vendor a dedicated team API key with:

• labelPrefix: pentest- (scoped create)
• Not readOnly
• Documented expiry and revocation in dashboard

Safe flows without real SMTP:

MAILAGENT_API_URL=https://api.webmailagent.com \
MAILAGENT_API_KEY=ma_… \
  npm run test:contract:qa

Uses POST …/simulate — no DATABASE_URL, no real email.

Priority test cases

Authentication & authorization

• API key required on all /v1/* (except public meta, webhooks with own auth)
• Cross-team IDOR: inbox/message/domain/audit of another team → 404/403
• Scoped key: readOnly cannot create/delete; labelPrefix enforced
• MCP session binding; expired mat_ JWT rejected
• OIDC state/PKCE if browser login in scope

Webhooks

• Resend signature bypass → 401
• Team webhook path with wrong teamId → no cross-tenant delivery
• Stripe webhook without valid signature → 400

Secrets & data

• Dedicated Resend key not returned in API responses after save
• Raw MIME / attachments only for owning team
• No API keys in GET /v1/agent, dashboard JS, or Codex plugin bundle

Abuse

• Rate limits per key (429)
• Oversized attachment / MIME limits
• Simulate endpoint cannot target another team's inbox

Deliverables (from vendor)

• Executive summary + severity-rated findings (CVSS or equivalent)
• Remediation retest window (e.g. 30 days)
• No public disclosure before coordinated fix

Internal baseline (run anytime)

npm run doctor:security

CI: security-baseline.yml on every PR/push to main + weekly.

Maps to: policy files, npm audit, GitHub secret scanning, verify:codex, HOL scanner workflow.

Related

• SOC2.md · OPERATOR-ACCESS.md · SECURITY.md