[spark-compete] fix: validate previewUrl against private/reserved hosts before fetch

[yossweh]

[spark-compete] fix: validate previewUrl against private/reserved hosts before fetch

pr_author: yossweh
repo: vibeforge1111/spark-telegram-bot
branch: fix/ssrf-preview-url-validation

---

actual_behavior

httpPreviewIsReachable() in src/missionRelay.ts:1238 fetches URLs from relay event previewUrl / preview_url fields without validating the target host. The normalizePreviewLink() function only checks for localhost:5555 and redirects those to project preview links, but passes through all other URLs unchanged — including internal network addresses like 169.254.169.254 (cloud metadata), 10.x.x.x, 172.16-31.x.x, 192.168.x.x, and .internal domains.

A compromised relay secret or malicious Spawner UI could inject relay events with previewUrl: "http://169.254.169.254/latest/meta-data/" causing the bot to make requests to cloud metadata endpoints, internal services, or other SSRF targets.

expected_behavior

httpPreviewIsReachable() should validate the URL hostname against private/reserved IP ranges and internal domains before making the HTTP request. URLs targeting internal hosts should be rejected without fetching.

public-safe proof of the exact failure

Before (current main):

async function httpPreviewIsReachable(url: string): Promise<boolean> {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 2500);
  // ... fetch(url) with no host validation
}

After (this PR):

function isPrivateOrReservedHost(hostname: string): boolean {
  const lower = hostname.toLowerCase().replace(/^\[|\]$/g, '');
  if (['127.0.0.1', 'localhost', '::1', '0.0.0.0'].includes(lower)) return true;
  if (lower.startsWith('10.')) return true;
  if (lower.startsWith('172.')) {
    const second = parseInt(lower.split('.')[1], 10);
    if (second >= 16 && second <= 31) return true;
  }
  if (lower.startsWith('192.168.')) return true;
  if (lower.startsWith('169.254.')) return true;
  if (lower === 'metadata.google.internal' || lower === 'metadata.google.com') return true;
  if (lower.endsWith('.internal') || lower.endsWith('.local')) return true;
  return false;
}

async function httpPreviewIsReachable(url: string): Promise<boolean> {
  try {
    const parsed = new URL(url);
    if (isPrivateOrReservedHost(parsed.hostname)) return false;
  } catch {
    return false;
  }
  // ... existing fetch logic
}

trust boundary touched by this change

Surface: Relay event previewUrl field → HTTP fetch in httpPreviewIsReachable()
Boundary change: Adds host validation before outbound HTTP request
What this does NOT change:

• Relay authentication (TELEGRAM_RELAY_SECRET)
• Preview link normalization logic
• Local link handling (non-HTTP paths)

targeted tests / smoke checks

#	Check	Expected result
1	httpPreviewIsReachable("http://169.254.169.254/latest/meta-data/")	Returns false
2	httpPreviewIsReachable("http://10.0.0.1:8080/admin")	Returns false
3	httpPreviewIsReachable("http://192.168.1.1/")	Returns false
4	httpPreviewIsReachable("http://metadata.google.internal/")	Returns false
5	httpPreviewIsReachable("http://example.com/preview")	Returns normally (fetch proceeds)
6	npm run build	Passes

risk notes

Which risky surface changed: Outbound HTTP fetch from relay events
Why the change is necessary: Prevents SSRF via malicious relay event previewUrl values
Secrets: No secrets introduced
Auth / session state: No changes to auth flow
Dependency / runtime behavior: No new deps; uses built-in URL constructor
File / network access: Restricts network access to non-internal hosts only
Prompt / tool execution: No changes
Rollback: Single-file revert
What reviewers / lab still need to verify: Test with real relay events to ensure legitimate preview URLs still work

duplicate_notes

Checked open PRs in spark-telegram-bot — no existing PR addresses SSRF in httpPreviewIsReachable() or validates previewUrl against internal IP ranges. PR #295 is about Builder bridge graceful degradation (different issue). This fix adds a new isPrivateOrReservedHost() function specifically for the relay preview URL fetch path.

review_claim

• impact_claim: medium
• evidence_types: redacted_terminal_excerpt, smoke_test
• review_state_requested: pr_review

team

hellenagent (hellen, yossweh, exelchapo) — llm_device_holder: yossweh

packet

{
  "schema": "spark-compete-hotfix-v1",
  "event": "spark-compete-first-event",
  "submission_mode": "public_repo_pr",
  "submission_target_url": "https://github.com/vibeforge1111/spark-telegram-bot/pull/843",
  "team": {
    "name": "hellenagent",
    "members": [
      "hellen",
      "yossweh",
      "exelchapo"
    ],
    "github_accounts": [
      "yossweh"
    ],
    "llm_device_holder": "yossweh",
    "device_holder_github": "yossweh"
  },
  "target_repo": {
    "id": "vibeforge1111/spark-telegram-bot",
    "source": "https://github.com/vibeforge1111/spark-telegram-bot",
    "owner_surface": "telegram-bot"
  },
  "issue": {
    "type": "bug",
    "title": "SSRF via unvalidated previewUrl in httpPreviewIsReachable",
    "severity": "medium",
    "affected_workflow": "relay event preview URL fetching",
    "actual_behavior": "httpPreviewIsReachable() fetches URLs from relay event previewUrl fields without validating against private/reserved IP ranges, allowing SSRF to cloud metadata, internal services, and loopback addresses",
    "expected_behavior": "URLs targeting private/reserved hosts should be rejected before making the HTTP request",
    "repro_steps": [
      "Send relay event with previewUrl set to http://169.254.169.254/latest/meta-data/",
      "Observe httpPreviewIsReachable() makes request to cloud metadata endpoint",
      "No host validation is performed before fetch"
    ]
  },
  "evidence": {
    "links": [
      "https://github.com/vibeforge1111/spark-telegram-bot/pull/843"
    ],
    "forbidden": [
      "do not include relay secrets",
      "do not include internal URLs"
    ],
    "safe_links_only": true,
    "before_after_proof": "Before: fetch(url) with no host validation. After: isPrivateOrReservedHost(parsed.hostname) check returns false for private IPs before fetch."
  },
  "proposed_fix": {
    "approach": "Add isPrivateOrReservedHost() function that checks hostname against loopback, private ranges (10.x, 172.16-31.x, 192.168.x), link-local (169.254.x), cloud metadata endpoints, and .internal/.local domains. Call it in httpPreviewIsReachable() before fetch().",
    "files_expected": [
      "src/missionRelay.ts"
    ],
    "tests_or_smoke": "Verify httpPreviewIsReachable returns false for 169.254.169.254, 10.0.0.1, 192.168.1.1, metadata.google.internal. Verify normal URLs still fetch. npm run build passes."
  },
  "pr": {
    "url": "https://github.com/vibeforge1111/spark-telegram-bot/pull/843",
    "branch": "fix/ssrf-preview-url-validation",
    "title_prefix": "[spark-compete]",
    "author_github": "yossweh",
    "body_must_include": [
      "packet",
      "team",
      "pr_author",
      "repo",
      "actual_behavior",
      "expected_behavior",
      "repro_steps",
      "before_after_proof",
      "tests_or_smoke",
      "duplicate_notes",
      "risk_notes",
      "review_claim"
    ]
  },
  "review_claim": {
    "impact_claim": "medium",
    "evidence_types": [
      "redacted_terminal_excerpt",
      "smoke_test",
      "redacted_conversation_excerpt"
    ],
    "review_state_requested": "pr_review",
    "duplicate_notes": "No existing PR addresses SSRF in httpPreviewIsReachable. PR #295 is about Builder bridge degradation (different issue).",
    "risk_notes": "Restricts outbound fetch to non-internal hosts. No new deps. Single-file change. Rollback: revert one commit."
  }
}