Skip to content

Threat model ​

What rust-fetch defends against, what it leaves to you, and where each protection is checked. This is the single place that states it; the security guide has the configuration, and its claims table has the tests (IDs such as C09 below refer to it).

Status. Written by the maintainer's tooling and not yet reviewed by anyone else (#223). Treat it as a draft until it is.

Assets ​

IDAssetWhere it lives
A1Credentials the application sends: Authorization, Cookie, API keys, passwords in URLs, request bodiesRequest headers, URLs and bodies, in process memory and on the wire
A2The host's network position: what the machine can reach that an outsider cannot (cloud metadata, internal services, localhost)The process's sockets
A3Process memory and availabilityThe Node.js or browser process
A4Integrity of the published package and its buildnpm, GitHub Actions, the Rust and npm dependency trees

Attackers ​

IDAttackerControls
T1A malicious or compromised serverEverything in a response: status, headers, framing, body, redirects, timing
T2A user of the application (or any source of data the application passes on)A URL, a header value, a path, an option value
T3Code in the same process that pollutes Object.prototypeInherited properties that options and Node.js internals may read
T4A malicious dependencyCode that runs in the build, or in the user's process
T5A compromised CI or release stepThe published artifact
T6A network attacker between client and serverTraffic on the path, certificates they can obtain

Adapters and trust boundaries ​

The Rust core, compiled to Wasm, holds the policy (validation, URL resolution, retries, timeouts, limits, errors). A transport moves bytes. Which transport runs depends on the runtime and the request.

AdapterRuns inTrustsEnforces itself
Wasm coreNode.js, browsersIts caller, which can be T2's data; its transport, for framingValidation and URL rules (C17, C18), retry and timeout policy (C24), response and line limits (C19, C21), load shedding (C22)
node:httpNode.jsNode's HTTP parser (llhttp) and TLS (OpenSSL)The SSRF check at connect time (C09, C10, C11, C12), cross-origin credential stripping (C14, C15, C16), refused redirect schemes (C28)
Native addonNode.js, when builthyper for HTTP/1.1, rustls for TLSThe same redirect and limit rules, and a TLS configuration, pool and cancellation scope of its own per adapter (C26: by design, not tested across threads). It is not used when allowPrivateNetwork: false, a proxy, streaming bodies or progress callbacks are in play: those requests take node:http even when the addon is loaded
Browser fetch()BrowsersThe browser: CORS, mixed content, TLS, redirect credential rulesSize limits and timeouts in the core. allowPrivateNetwork does nothing here, because a browser tab cannot see the address it connects to. The build asks for nothing a strict Content Security Policy blocks, except 'wasm-unsafe-eval' (C30)
Browser XMLHttpRequestBrowsersThe same browser rulesUsed for upload progress; same limits as fetch()
WebSocketNode.js (built-in WebSocket, through undici), browsersThe runtime's WebSocketA checked connection pool with the SSRF rule on every connection and reconnection (C13), bounded send queues (C23)

Threats and what answers them ​

Each threat names a protection with its claim ID, or says why there is none.

IDAttackerThreatProtectionResidual risk
TM01T1A response bigger than memory, including a decompression bombmaxResponseBytes (C19)Opt-in: the default is no limit. Only gzip has a bomb test
TM02T1An endless line or event in a streammaxLineBytes, maxEventBytes (C21)Defaults apply to streams only
TM03T1A server that never finishes: trickled headers or body, endless 1xx, endless redirect bodyPhase timeouts and deadlineMs (C24), redirect body limit (C20)Opt-in timers; timeoutMs has a default
TM04T1Malformed HTTP framing: conflicting lengths, bad chunks, smuggled second responseRejected by llhttp on node:http, bounded by hyper on the addon. The next request never receives an earlier responseThe addon accepts Content-Length with Transfer-Encoding, reads it as chunked and closes the connection afterwards (#243)
TM05T1A redirect to another origin to collect credentialsCross-origin stripping (C14, C15), allowInsecureRedirects: false (C16), refused schemes (C28)allowInsecureRedirects defaults to following https to http; browsers follow their own rules
TM06T1A redirect or DNS answer that moves a request to an internal addressThe SSRF check on every resolved address and every hop (C09, C10, C13)Opt-in, Node.js only. In browsers, none
TM07T2A user-supplied URL aimed at the host's network (SSRF)allowPrivateNetwork: false (C09 to C13)Opt-in. Ranges are tested by sample; a full range test is pending (#237). A proxy that resolves names is refused for names (C12)
TM08T2A user-supplied path that replaces the host of a baseUrl, taking the credentials with itallowAbsoluteUrls: false and path rules (C17)Opt-in for absolute URLs
TM09T2CR or LF in a header name or valueRejected before sending (C18)None known
TM10T3Inherited properties redirect requests (proxy, dispatcher, ca) or change optionsPrototype-free state and own-property options (C07, C08)Tested for the options the project knows. A new Node.js option name is a risk until added
TM11T4A malicious npm dependencyNo runtime dependencies (C01, C02, C03)Rust dependencies: audited weekly (C29), unsafe inventory pending (#246)
TM12T4, T5A compromised workflow, action or releasePinned actions, workflow lint, dependency audit, provenance verified after publish (C04, C29)A maintainer account compromise is outside the checks. The Wasm is rebuilt twice before every release and the latest release is rebuilt weekly and compared with npm (#232)
TM13T1, T3Secrets copied into logs, traces or errorsRedaction in hooks and logs (C25)Thrown errors keep no URL password or fragment, and redactUrl covers the cause chain (#238, #239). Residual: the query string stays in error.url unless redactUrl is set
TM14T6Interception of traffic or a forged certificateTLS verification on by default on both Node transports, with Node's warning when turned off. The per-case TLS table comes with the matrix test (#245)node:http accepts a name only in the subject, and on Node 20 and 22 a 1024 bit RSA key (#244). Not yet merged: the matrix test
TM16T4, T5The package itself does something unexpected: a request at import, telemetry, an update checkNo request at import (C05). No telemetry or update check in the source (C06)C06 is a source review, not a test. The native addon's sockets are outside C05's check
TM15T2Resource exhaustion by volume: more requests than the upstream can answermaxPendingRequests (C22), WebSocket queue limits (C23)Opt-in

C27, the comparison with fetch() and axios, is a statement about other clients, not a protection. Every other claim in the claims table is named above, and claims.test.mjs fails if a claim ID is in neither this table nor the adapters table. A claim that answers no threat does not belong in the guide.

Non-goals ​

These are not defended against, so add your own controls:

  • Egress control. The library cannot replace a firewall, an egress proxy or an allowlist of destinations. allowPrivateNetwork: false removes one class of target; it does not make a URL safe to fetch.
  • The caller's own authorization. Whether a user may ask for a given URL, and what you do with the response, is the application's decision.
  • A compromised host or runtime. Someone who controls the process, NODE_OPTIONS, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED or the proxy environment variables controls the client. Trust is process-wide.
  • Browser behaviour. CORS, mixed content, private-network access and certificate handling belong to the browser. Options that need the connected address do nothing there.
  • Secrets in memory. Credentials stay in memory as strings for the life of the request. There is no zeroing.
  • Content. The library does not validate, sanitize or sandbox what a server sends. JSON parsing and rendering are yours.
  • Traffic analysis, timing and covert channels.
  • A malicious maintainer or registry. Provenance shows where a package was built, not that its source is benign.

Known gaps ​

Open items that weaken a row above: #223 (no external review). The security guide and this page should change in the same pull request as any of them.

Released under the MIT or Apache-2.0 license.