Add SSRF protection for webhook URLs

[arongreenspan]

Summary

Implements Server-Side Request Forgery (SSRF) protection for webhook subscriptions by validating that webhook URLs do not target private or internal addresses. Validation occurs both at creation time (synchronous policy check) and at delivery time (with DNS resolution).

Changes

• New validation module (validateWebhookUrl.ts):

  • validateWebhookUrl() — synchronous policy check for URL format, scheme, and literal private addresses; usable in Zod refinements
  • resolveWebhookUrlBlockReason() — delivery-time check that re-validates and resolves hostnames to detect DNS rebinding attacks
  • isPrivateAddress() — classifies IPv4 and IPv6 addresses as private/reserved (loopback, RFC1918, link-local, multicast, etc.)
  • Environment-aware enforcement: disabled in local/test, enabled in pr/staging/prod

• Webhook schema validation (webhookSubscriptionSchemas.ts):

  • Added webhookUrlSchema Zod validator that rejects malformed URLs, non-HTTPS schemes (in enforced environments), and private addresses at creation time

• Webhook delivery (sendWebhook.ts):

  • Calls resolveWebhookUrlBlockReason() before fetching to block private-address URLs and DNS rebinding attempts
  • Added timestamp field to webhook payload (inside signed body) to allow receivers to reject replayed deliveries
  • Errors from SSRF checks are recorded with status 'error' in webhook events

• Test coverage (validateWebhookUrl.test.ts):

  • Comprehensive tests for IPv4/IPv6 private ranges, localhost variants, malformed URLs, scheme validation
  • Tests for DNS resolution blocking and rebinding detection
  • Tests for environment-aware enforcement (relaxed in local/test, strict in prod)

• Infisical CLI calls (infisicalSetup.ts, cloudflarePagesSetup.ts, init/api/infisical.ts):

  • Migrated from execAsync() (shell-based) to execFileAsync() (direct execution) to prevent command injection when interpolating arguments
  • Updated mock system to support execFileAsync()

• Dependencies:

  • Updated OpenTelemetry packages (0.215.0 → 0.218.0)
  • Updated Hono (4.12.15 → 4.12.25)
  • Updated protobufjs (7.5.6 → 7.6.3)
  • Added shell-quote resolution to prevent shell injection

Implementation Details

• Private address detection handles IPv4-mapped IPv6 addresses (e.g., ::ffff:192.168.1.1) and both dotted-decimal and hex-group representations
• DNS resolution failures are treated as pass-through (delivery will fail as unreachable on its own), avoiding false positives for misconfigured networks
• Enforcement is environment-aware: local development and tests allow private addresses for integration testing, while deployed environments enforce strict HTTPS + public addresses
• Webhook events record the SSRF block reason in the error field for audit/debugging purposes

https://claude.ai/code/session_015LJyNryMCkev9M8hDoz8GV

[agreenspan]

DEV-003 design decisions (brainstorm session)

Working through DEV-003 as a standalone, Biome-shaped tool. Locking the decisions below; open items listed at the bottom.

Naming

• atlas is the core word — the package, the @atlas block-opener tag, the .atlas/ config folder, and the atlas CLI binary all inherit it. Chosen for the map-vs-territory thesis (atlas generate → MAP.md).
• Two live nouns: atlas = the tool/map; seam = the nodes it charts (what @partOf/@uses point at). Whether to rename the node-noun for cartographic coherence is open.

Packaging

• Standalone repo/package; template is consumer Claude/refactor polymorphism hook #1.
• atlas ships default kinds / concerns (near-universal vocab).
• The consuming repo owns seams.ts (project-specific registry); atlas validates @partOf/@uses against it. Template ships a fuller set; atlas ships a smaller example set.

Registry change

• Remove status from the seam registry (and the Status type). It is the most rot-prone claim and the original cause of FEATURES.md drift — better derived (do the seam's tests pass? is it referenced?) than declared. Keep doc / ticket / note / ambient.

.atlas/ layout (Biome-like)

.atlas/
  config.ts     // rules: auto-stamp + ignore/coverage exemptions
  kinds.ts      // @kind vocab (atlas default, repo-extendable)
  concerns.ts   // @concern vocab (atlas default, repo-extendable)
  seams.ts      // the registry (repo-owned)

CLI

bunx atlas graph      // reverse indexes: seam -> files, file -> seams, @uses consumers
bunx atlas check      // presence + schema (+ @uses reconciliation)
bunx atlas coverage   // unannotated files, respects ignore rules
bunx atlas generate   // -> MAP.md (+ generated/verified FEATURES.md, later phase)

Block shape

@atlas opens the block, above the axis tags:

/**
 * @atlas
 * @kind controller
 * @partOf feature:tenancy
 * @uses primitive:authz, infrastructure:redis
 * @concern tenantIsolation
 */

Auto-stamp rules (the ~850-file problem)

config.ts holds glob rules with inline positional captures. The syntax carries intent:

• * — match one segment, discard
• ** — match many segments, discard
• $1, $2, … — match one segment, capture, referenced in tag values

You number only what you capture, in order of appearance — so ** is never a capture and the multi-segment ambiguity disappears.

stamp: [
  { include: 'apps/api/src/modules/$1/controllers/**', kind: 'controller', partOf: 'feature:$1' },
  { include: 'apps/api/src/modules/$1/routes/**',      kind: 'route',      partOf: 'feature:$1' },
  { include: 'packages/*/src/$1/**',                                       partOf: 'feature:$1' },
],
ignore: ['**/*.test.{ts,tsx}', '**/index.ts'],

Path→tag derivation is the default fill; explicit always wins (overload the stamped value on exception files). CI is presence + schema against the registry, so a mis-captured value (e.g. a $1 that isn't a real seam) fails loud.

Still open

• @uses enforcement — reconciliation-only (no @uses none boilerplate) vs enforced-present-but-empty; and scope (infra/primitive only vs all seam classes).
• @constructs vocabulary — currently unvalidated (no constructs.ts); @constructs appEventHandler from an earlier commit contradicts the decomposed @kind handler. Decide its value-space.
• Node-noun — keep "seam" vs cartography-align under the atlas metaphor.
• Stamp escape hatch — whether to allow a stamp(path) => tags function alongside glob+capture for rare cases.

Note: DEV-003 (and the docs reconciliation) is riding inside a PR titled "Add SSRF protection for webhook URLs." Recommend splitting DEV-003 into its own PR for reviewability.