# StormFetch Threat Model

## Security Goals

StormFetch is designed to make common HTTP-client mistakes harder:

- prevent SSRF to private networks and cloud metadata services
- avoid accidental credential forwarding across origins
- keep debug exports safe to share
- cap untrusted request and response payload sizes
- make release provenance verifiable

## In Scope

- URL construction from `baseURL`, `url`, `params`, and redirects
- host, protocol, CIDR, DNS, and private-network policy
- request headers, cookies, bearer tokens, XSRF headers, and proxy credentials
- request/response body size and JSON shape controls
- public debug helpers such as `history()`, `toCurl()`, and `toHAR()`
- npm package release workflows

## Explicit Non-Goals

- proving a remote API is trustworthy
- replacing browser CORS or server-side authorization
- preventing a developer from deliberately disabling safety controls
- guaranteeing TLS trust beyond platform certificate validation unless the app adds its own transport policy

## High-Risk Flows

### SSRF

Use `security.allowedHosts`, `blockedHosts`, `allowedCidrs`, `blockedCidrs`, `allowPrivateNetwork: false`, `blockCloudMetadata: true`, and `validateDns: true` for server-side request forwarding.

### Redirects

StormFetch strips credentials on cross-origin Node redirects and blocks HTTPS to HTTP redirects unless `allowHttp` is explicitly enabled. Redirect targets are re-checked by the security policy before the request continues.

### Debugging

Public debug exports redact sensitive headers, query values, URL credentials, and common token patterns. Keep `redactSensitiveHeaders` and `redactSensitiveData` enabled outside trusted local debugging.

### Supply Chain

Use the provided GitHub Actions publishing workflow with npm provenance. Consumers should verify package signatures before high-trust deployment.