@blamejs/core 0.8.43 → 0.8.49

package/lib/http-client.js

@@ -1,75 +1,50 @@
 "use strict";
 /**
- * HTTP client primitive — Promise-returning, AbortSignal-aware,
- * connection-pooled, streaming-capable, HTTP/2-capable.
+ * @module b.httpClient
+ * @nav    HTTP
+ * @title  Http Client
  *
- * Built on node:http, node:https, and node:http2. Zero npm runtime
- * dependency. Same caller surface for h1 and h2; the protocol version
- * is negotiated per-origin via ALPN (h2 preferred, h1 fallback).
+ * @intro
+ *   Outbound HTTP client with SSRF gate, retry, circuit breaker,
+ *   wall-clock + idle timeouts, AbortSignal propagation, connection
+ *   pooling, streaming, and ALPN-negotiated HTTP/2. Built on node:http,
+ *   node:https, and node:http2 with zero npm runtime dependency.
  *
- * Single entry point:
+ *   Every outbound request flows through `b.ssrfGuard` out of the box:
+ *   hostname → DNS lookup is pinned to vetted IP literals, RFC 1918 /
+ *   loopback / link-local / IPv6 ULA destinations are refused, and the
+ *   redirect chain is re-validated at every hop so a 302 to
+ *   `http://169.254.169.254/` (cloud metadata) can't smuggle past the
+ *   first-hop gate. The same DNS pinning applies to retries — there's
+ *   no retry path that bypasses the guard.
  *
- *   await httpClient.request({
- *     method,             // string, default GET
- *     url,                // string or URL
- *     headers,            // object, default {}
- *     body,               // Buffer | string | Readable | undefined
- *     timeoutMs,          // wall-clock cap (caller-chosen, no default)
- *     idleTimeoutMs,      // zero-progress idle cap (default 30s)
- *     responseMode,       // "buffer" (default) | "stream" | "always-resolve"
- *     maxResponseBytes,   // for buffer mode (default 16 MiB control,
- *                         //   1 GiB GET — operators with > 1 GiB
- *                         //   stored objects must use stream mode)
- *     onChunk,            // (chunk: Buffer) => void — fires for each
- *                         //   response chunk in BOTH buffer and stream
- *                         //   modes. Use to hash bytes during pipe-to-disk
- *                         //   without an extra Transform pass.
- *     signal,             // AbortSignal — propagated to req/stream
- *     errorClass,         // FrameworkError subclass
- *     observer,           // optional (stage, info) => void hook
- *     agent,              // override per-origin pool (h1 only)
- *     preferH2,           // bool — for cleartext h2 (h2c). HTTPS origins
- *                         //   already attempt h2 via ALPN; this flag is
- *                         //   for HTTP origins (internal services, tests)
- *                         //   that explicitly speak h2c.
- *   })
- *     → { statusCode, headers, body }
+ *   Protocol selection is automatic. HTTPS origins handshake with
+ *   ALPN `['h2', 'http/1.1']` and cache the resulting transport per
+ *   `<protocol>//<hostname>:<port>`. While a transport is mid-negotiate
+ *   the cache holds the in-flight Promise so concurrent calls to a new
+ *   origin coalesce onto a single connection. h2 GOAWAY or session
+ *   error evicts the entry; the next request reconnects.
  *
- * Protocol selection:
+ *   Resiliency defaults: TLS 1.3 minimum, PQC-preferred `ecdhCurve`
+ *   group order, split wall-clock vs zero-progress idle timeouts,
+ *   request-body stream errors propagated to the returned Promise,
+ *   and h2 stream cancellation via NGHTTP2_CANCEL (clean, not
+ *   `stream.destroy`) when the AbortSignal fires.
  *
- *   - HTTPS origin: TLS handshake with ALPN ['h2', 'http/1.1']. If
- *     server picks 'h2', subsequent requests to that origin multiplex
- *     over the same h2 session. If server picks 'h1', the cached
- *     transport is an https.Agent with keepAlive.
- *
- *   - HTTP origin without preferH2: h1 only.
- *   - HTTP origin with preferH2: h2c (cleartext h2). No ALPN — caller
- *     attests the server speaks h2c. Used by internal services and
- *     test fixtures (mock h2 server).
- *
- * Per-origin transport cache:
- *
- *   key = "<protocol>//<hostname>:<port>"
- *   value = { kind: 'h1', lib, agent } | { kind: 'h2', session }
- *
- *   While a transport is being negotiated (TLS handshake / h2 connect)
- *   the cache holds the in-flight Promise so concurrent calls to a
- *   new origin coalesce onto the same connection.
- *
- * Resiliency:
- *   - Wall-clock + idle timeouts (split — slow-progress vs zero-progress)
- *   - AbortSignal propagated to req.destroy / stream.close
- *   - TLS 1.3 minimum + PQC ecdhCurve preference
- *   - h2 session GOAWAY / error → cache eviction; next request reconnects
- *   - h2 stream cancellation via NGHTTP2_CANCEL on abort (clean, not destroy)
- *   - Request-body stream errors propagated to Promise rejection
+ * @card
+ *   Outbound HTTP client with SSRF gate, retry, circuit breaker, wall-clock + idle timeouts, AbortSignal propagation, connection pooling, streaming, and ALPN-negotiated HTTP/2.
  */
 
+var fs = require("fs");
 var http  = require("http");
 var https = require("https");
 var http2 = require("http2");
+var nodeCrypto = require("crypto");
+var nodePath = require("path");
 var nodeStream = require("node:stream");
+var streamPromises = require("node:stream/promises");
 var { URL } = require("url");
+var atomicFile = require("./atomic-file");
 var C = require("./constants");
 var crypto = require("./crypto");
 var pqcAgent = require("./pqc-agent");
@@ -78,7 +53,8 @@ var safeBuffer = require("./safe-buffer");
 var safeUrl = require("./safe-url");
 var ssrfGuard = require("./ssrf-guard");
 var networkProxy = require("./network-proxy");
-var { FrameworkError } = require("./framework-error");
+var validateOpts = require("./validate-opts");
+var { FrameworkError, HttpClientError } = require("./framework-error");
 
 // Per-origin transport cache. Entry is either the resolved transport
 // object or a pending Promise that resolves to one. The Promise form
@@ -121,6 +97,15 @@ var _transports = new Map();
 //   built into the protocol, with replay protection at the QUIC
 //   layer. The framework's `b.httpClient` is HTTP/1.1 + HTTP/2 only;
 //   operators wanting h3 wire their own client.
+//
+//   QUIC retry / address-validation (RFC 9000 §8 + RFC 9001 §6) is
+//   deferred-with-condition: outbound h3 negotiation re-opens when
+//   Node's `--experimental-quic` graduates to stable and ships a
+//   `node:http3` module. The escape hatch today is `opts.agent` —
+//   operators on internal-mesh deployments that already terminate h3
+//   pass their own h3 agent rather than the framework rolling its
+//   own implementation under an experimental Node flag. SECURITY.md
+//   "Watch list" tracks the re-open trigger.
 
 // Pool tuning for the HTTP-client transport cache. Keep-alive is
 // shorter than the standalone pqc-agent default (1s vs 30s) because
@@ -143,6 +128,31 @@ var DEFAULT_AGENT_OPTS = Object.freeze({
 
 var HTTP_CLIENT_AGENT_OPTS = Object.assign({}, DEFAULT_AGENT_OPTS);
 
+/**
+ * @primitive b.httpClient.configurePool
+ * @signature b.httpClient.configurePool(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.httpClient.request
+ *
+ * Updates the keepAlive Agent options used for new h1 transports and
+ * tears down the per-origin transport cache so subsequent requests
+ * pick up the fresh values. Existing in-flight responses keep their
+ * old transport. Throws on unknown keys, non-positive integers, or a
+ * non-boolean `keepAlive`. Use at boot when the default 16/8 socket
+ * caps don't match the operator's downstream concurrency budget.
+ *
+ * @opts
+ *   keepAlive:      true,   // boolean — whether to reuse sockets
+ *   keepAliveMsecs: 1000,   // positive integer ms between keep-alive probes
+ *   maxSockets:     16,     // positive integer — concurrent sockets per origin
+ *   maxFreeSockets: 8,      // positive integer — idle sockets retained per origin
+ *   scheduling:     "lifo", // "lifo" | "fifo"
+ *
+ * @example
+ *   b.httpClient.configurePool({ maxSockets: 64, maxFreeSockets: 32 });
+ *   // → undefined   (cache cleared; next request builds a 64-socket pool)
+ */
 function configurePool(opts) {
   if (!opts || typeof opts !== "object") {
     throw new Error("httpClient.configurePool: opts must be an object");
@@ -639,6 +649,49 @@ function _stripCrossOriginAuth(headers) {
   return out;
 }
 
+/**
+ * @primitive b.httpClient.request
+ * @signature b.httpClient.request(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.httpClient.downloadStream, b.httpClient.uploadMultipartStream, b.ssrfGuard
+ *
+ * Promise-returning, AbortSignal-aware HTTP request. Negotiates h2 /
+ * h1 per-origin via ALPN, reuses transports from the cache, runs every
+ * destination through `b.ssrfGuard` before connecting, and re-validates
+ * each redirect hop. Returns `{ statusCode, headers, body }` for the
+ * default `"buffer"` mode; `"stream"` returns a Readable for the body.
+ * Sensitive headers (Authorization / Cookie / Proxy-Authorization) are
+ * stripped on cross-origin redirect. Body-stream errors propagate to
+ * the rejected Promise.
+ *
+ * @opts
+ *   method:           "GET",         // HTTP method
+ *   url:              <required>,    // string or URL — destination
+ *   headers:          {},            // request headers
+ *   body:             undefined,     // Buffer | string | Readable | undefined
+ *   timeoutMs:        undefined,     // wall-clock cap; no default — operator chooses
+ *   idleTimeoutMs:    30000,         // zero-progress cap
+ *   responseMode:     "buffer",      // "buffer" | "stream" | "always-resolve"
+ *   maxResponseBytes: undefined,     // 16 MiB control / 1 GiB GET defaults; ignored in "stream"
+ *   onChunk:          undefined,     // (chunk: Buffer) => void — fires per response chunk
+ *   signal:           undefined,     // AbortSignal — propagated to req / stream
+ *   errorClass:       HttpClientError, // FrameworkError subclass for thrown errors
+ *   observer:         undefined,     // (stage, info) => void — lifecycle hook
+ *   agent:            undefined,     // override per-origin Agent (h1 only)
+ *   preferH2:         false,         // attempt h2c against an HTTP origin (no ALPN)
+ *   before:           undefined,     // array of (opts) => opts | Promise — request mutators
+ *   after:            undefined,     // array of (response) => response | Promise — response mutators
+ *   onUploadProgress: undefined,     // (bytesSent, totalBytes?) => void
+ *
+ * @example
+ *   var res = await b.httpClient.request({
+ *     method:    "GET",
+ *     url:       "https://example.com/health",
+ *     timeoutMs: 5000,
+ *   });
+ *   // → { statusCode: 200, headers: { "content-type": "application/json", ... }, body: <Buffer> }
+ */
 function request(opts) {
   if (!opts || !opts.url) {
     return Promise.reject(_makeError(opts && opts.errorClass, "BAD_ARG", "url is required", true));
@@ -1395,6 +1448,377 @@ function _requestH2(transport, u, opts) {
   });
 }
 
+// ---- Streaming primitives ----
+//
+// downloadStream — pipe a response body to a tmp file, hash-while-piping,
+// atomic-rename on hash match. Operators receive `{ statusCode,
+// bytesWritten, hash }`; on hash mismatch the tmp file is deleted and an
+// HttpClientError with code "httpclient/hash-mismatch" is thrown.
+//
+// uploadMultipartStream — POST a file body via multipart/form-data
+// without buffering. Streams from disk through the request body using
+// `fs.createReadStream` + `node:stream/promises` pipeline.
+//
+// Both compose through `request()` (responseMode: "stream") so safeUrl,
+// ssrfGuard, allowedHosts, network-proxy, audit-on-host-deny, and the
+// per-origin transport cache apply unchanged.
+
+// Algorithms exposed to operators. Defaults to PQC-first sha3-512;
+// callers needing legacy-peer interop with sha-256 (S3 ETag class) opt
+// in explicitly.
+var ALLOWED_DOWNLOAD_HASH_ALGS = ["sha3-512", "sha-256", "sha-512", "shake256"];
+var DEFAULT_DOWNLOAD_HASH_ALG  = "sha3-512";
+var DEFAULT_DOWNLOAD_FILE_MODE = 0o600;
+
+function _hcErr(code, message, statusCode) {
+  return new HttpClientError(code, message, true, statusCode);
+}
+
+// Throw at config-time if opts shape is malformed — operator catches the
+// typo here, not inside the request loop.
+function _validateDownloadOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _hcErr("httpclient/bad-opts", "downloadStream: opts must be an object");
+  }
+  validateOpts.requireNonEmptyString(opts.url, "downloadStream: url",
+    HttpClientError, "httpclient/bad-opts");
+  validateOpts.requireNonEmptyString(opts.dest, "downloadStream: dest",
+    HttpClientError, "httpclient/bad-opts");
+  validateOpts.optionalNonEmptyString(opts.hash, "downloadStream: hash",
+    HttpClientError, "httpclient/bad-opts");
+  if (opts.hash !== undefined && ALLOWED_DOWNLOAD_HASH_ALGS.indexOf(opts.hash) === -1) {
+    throw _hcErr("httpclient/bad-opts",
+      "downloadStream: hash must be one of " + ALLOWED_DOWNLOAD_HASH_ALGS.join(", ") +
+      "; got " + JSON.stringify(opts.hash));
+  }
+  if (opts.expected !== undefined) {
+    validateOpts.requireNonEmptyString(opts.expected, "downloadStream: expected",
+      HttpClientError, "httpclient/bad-opts");
+    if (!safeBuffer.isHex(opts.expected)) {
+      throw _hcErr("httpclient/bad-opts",
+        "downloadStream: expected must be a non-empty hex digest");
+    }
+  }
+  validateOpts.optionalPositiveFinite(opts.timeoutMs, "downloadStream: timeoutMs",
+    HttpClientError, "httpclient/bad-opts");
+  if (opts.maxBytes !== undefined &&
+      (typeof opts.maxBytes !== "number" || !isFinite(opts.maxBytes) || opts.maxBytes <= 0 ||
+       Math.floor(opts.maxBytes) !== opts.maxBytes)) {
+    throw _hcErr("httpclient/bad-opts",
+      "downloadStream: maxBytes must be a positive finite integer");
+  }
+}
+
+function _emitAudit(opts, action, outcome, metadata) {
+  if (!opts || !opts.audit || typeof opts.audit.safeEmit !== "function") return;
+  try {
+    opts.audit.safeEmit({
+      action:   action,
+      outcome:  outcome,
+      resource: { kind: "outbound.http", id: String(opts.url || "") },
+      metadata: metadata || {},
+    });
+  } catch (_e) { /* audit best-effort */ }
+}
+
+/**
+ * @primitive b.httpClient.downloadStream
+ * @signature b.httpClient.downloadStream(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.httpClient.request, b.httpClient.uploadMultipartStream, b.atomicFile.ensureDir
+ *
+ * Streams a remote resource to disk while hashing the bytes in flight,
+ * then atomically renames the tmp file to `opts.dest` only after the
+ * hash matches `opts.expected` (when supplied). Hash mismatch deletes
+ * the tmp file and throws `httpclient/hash-mismatch`. Composes through
+ * `request({ responseMode: "stream" })` so the SSRF gate, allowedHosts
+ * filter, network proxy, and per-origin transport cache all apply.
+ *
+ * @opts
+ *   url:       <required>,    // string — source
+ *   dest:      <required>,    // absolute filesystem path — final landing
+ *   hash:      "sha3-512",    // "sha3-512" | "sha-256" | "sha-512" | "shake256"
+ *   expected:  undefined,     // hex digest; when set, verified before rename
+ *   timeoutMs: undefined,     // wall-clock cap
+ *   maxBytes:  undefined,     // positive integer — abort past this size
+ *   audit:     undefined,     // audit sink with safeEmit({...})
+ *
+ * @example
+ *   var result = await b.httpClient.downloadStream({
+ *     url:      "https://example.com/release.tar.gz",
+ *     dest:     "/var/lib/blamejs/release.tar.gz",
+ *     hash:     "sha3-512",
+ *     expected: "9f86d081884c7d65...d4e5",
+ *   });
+ *   // → { statusCode: 200, bytesWritten: 1048576, hash: "9f86d081884c7d65...d4e5" }
+ */
+async function downloadStream(opts) {
+  _validateDownloadOpts(opts);
+  var alg     = opts.hash || DEFAULT_DOWNLOAD_HASH_ALG;
+  var dest    = opts.dest;
+  var tmpPath = dest + ".tmp-" + crypto.generateToken(C.BYTES.bytes(8));
+  var dir     = nodePath.dirname(dest);
+
+  atomicFile.ensureDir(dir);
+
+  // Stream-mode request — body is a Readable that emits the response
+  // chunks. The framework's onChunk path is intentionally NOT used here
+  // because we own the destination tmp file and need precise error
+  // ordering between hash + write-fsync + rename.
+  var res;
+  try {
+    res = await request({
+      method:           "GET",
+      url:              opts.url,
+      headers:          opts.headers || {},
+      responseMode:     "stream",
+      timeoutMs:        opts.timeoutMs,
+      idleTimeoutMs:    opts.idleTimeoutMs,
+      signal:           opts.signal,
+      agent:            opts.agent,
+      allowedProtocols: opts.allowedProtocols,
+      allowedHosts:     opts.allowedHosts,
+      allowInternal:    opts.allowInternal,
+      audit:            opts.audit,
+      errorClass:       HttpClientError,
+    });
+  } catch (e) {
+    _emitAudit(opts, "system.httpclient.download_stream.refused", "denied", {
+      reason: "request-failed", message: e.message, code: e.code,
+    });
+    throw e;
+  }
+
+  if (res.statusCode < 200 || res.statusCode >= 300) {
+    // Stream mode of request() already rejected on >=400 above, so this
+    // branch covers 1xx/3xx surfaces that slipped through. Drain + refuse.
+    if (res.body && typeof res.body.resume === "function") res.body.resume();
+    _emitAudit(opts, "system.httpclient.download_stream.refused", "denied", {
+      reason: "non-2xx", statusCode: res.statusCode,
+    });
+    throw _hcErr("httpclient/http-error",
+      "downloadStream: upstream returned HTTP " + res.statusCode, res.statusCode);
+  }
+
+  var hasher  = nodeCrypto.createHash(alg);
+  var counter = new nodeStream.Transform({
+    transform: function (chunk, _enc, cb) {
+      hasher.update(chunk);
+      counter.bytesWritten += chunk.length;
+      if (typeof opts.maxBytes === "number" && counter.bytesWritten > opts.maxBytes) {
+        return cb(_hcErr("httpclient/response-too-large",
+          "downloadStream: response body exceeds maxBytes " + opts.maxBytes, res.statusCode));
+      }
+      cb(null, chunk);
+    },
+  });
+  counter.bytesWritten = 0;
+
+  var fileStream = fs.createWriteStream(tmpPath, { mode: DEFAULT_DOWNLOAD_FILE_MODE, flags: "w" });
+
+  try {
+    await streamPromises.pipeline(res.body, counter, fileStream);
+  } catch (e) {
+    // Pipeline failure → tmp may be partially written. Remove + audit.
+    try { fs.unlinkSync(tmpPath); } catch (_u) { /* best-effort cleanup */ }
+    _emitAudit(opts, "system.httpclient.download_stream.refused", "denied", {
+      reason: "pipeline-failed", message: e.message, code: e.code,
+    });
+    if (e && e.isHttpClientError) throw e;
+    throw _hcErr(e.code || "httpclient/pipeline-failed",
+      "downloadStream: pipeline failed: " + (e.message || String(e)), res.statusCode);
+  }
+
+  // fsync the file's data + close. atomicFile.fsync is best-effort
+  // across platforms but matches the discipline of the rest of the
+  // framework's atomic-write paths.
+  try {
+    var fd = fs.openSync(tmpPath, "r+");
+    try { atomicFile.fsync(fd); } finally { try { fs.closeSync(fd); } catch (_c) { /* best-effort fd close */ } }
+  } catch (_fe) { /* fsync best-effort */ }
+
+  var actualHex = hasher.digest("hex");
+  if (typeof opts.expected === "string" && opts.expected.length > 0) {
+    var expected = opts.expected.toLowerCase();
+    if (actualHex.toLowerCase() !== expected) {
+      try { fs.unlinkSync(tmpPath); } catch (_u) { /* best-effort cleanup */ }
+      _emitAudit(opts, "system.httpclient.download_stream.refused", "denied", {
+        reason: "hash-mismatch", alg: alg, expected: expected, actual: actualHex,
+        statusCode: res.statusCode, bytesWritten: counter.bytesWritten,
+      });
+      throw _hcErr("httpclient/hash-mismatch",
+        "downloadStream: hash mismatch (alg=" + alg + ", expected=" + expected +
+        ", actual=" + actualHex + ")", res.statusCode);
+    }
+  }
+
+  // Atomic rename + dir fsync.
+  try {
+    fs.renameSync(tmpPath, dest);
+    atomicFile.fsyncDir(dir);
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch (_u) { /* best-effort cleanup */ }
+    _emitAudit(opts, "system.httpclient.download_stream.refused", "denied", {
+      reason: "rename-failed", message: e.message,
+    });
+    throw _hcErr("httpclient/rename-failed",
+      "downloadStream: rename to " + dest + " failed: " + e.message, res.statusCode);
+  }
+
+  _emitAudit(opts, "system.httpclient.download_stream.completed", "allowed", {
+    statusCode:   res.statusCode,
+    bytesWritten: counter.bytesWritten,
+    alg:          alg,
+    hashVerified: typeof opts.expected === "string" && opts.expected.length > 0,
+  });
+
+  return {
+    statusCode:   res.statusCode,
+    bytesWritten: counter.bytesWritten,
+    hash:         actualHex,
+  };
+}
+
+// ---- uploadMultipartStream ----
+
+function _validateUploadOpts(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw _hcErr("httpclient/bad-opts", "uploadMultipartStream: opts must be an object");
+  }
+  validateOpts.requireNonEmptyString(opts.url, "uploadMultipartStream: url",
+    HttpClientError, "httpclient/bad-opts");
+  if (!opts.file || typeof opts.file !== "object") {
+    throw _hcErr("httpclient/bad-opts", "uploadMultipartStream: file must be an object");
+  }
+  validateOpts.requireNonEmptyString(opts.file.path, "uploadMultipartStream: file.path",
+    HttpClientError, "httpclient/bad-opts");
+  validateOpts.requireNonEmptyString(opts.file.fieldName, "uploadMultipartStream: file.fieldName",
+    HttpClientError, "httpclient/bad-opts");
+  if (opts.fields !== undefined && (typeof opts.fields !== "object" || opts.fields === null || Array.isArray(opts.fields))) {
+    throw _hcErr("httpclient/bad-opts", "uploadMultipartStream: fields must be an object");
+  }
+  validateOpts.optionalPositiveFinite(opts.timeoutMs, "uploadMultipartStream: timeoutMs",
+    HttpClientError, "httpclient/bad-opts");
+  if (opts.maxBytes !== undefined &&
+      (typeof opts.maxBytes !== "number" || !isFinite(opts.maxBytes) || opts.maxBytes <= 0 ||
+       Math.floor(opts.maxBytes) !== opts.maxBytes)) {
+    throw _hcErr("httpclient/bad-opts",
+      "uploadMultipartStream: maxBytes must be a positive finite integer");
+  }
+}
+
+/**
+ * @primitive b.httpClient.uploadMultipartStream
+ * @signature b.httpClient.uploadMultipartStream(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.httpClient.request, b.httpClient.downloadStream
+ *
+ * POSTs a file body via `multipart/form-data` without buffering the
+ * file in memory. Streams from disk through the request body using
+ * `fs.createReadStream` + `node:stream/promises` pipeline. Throws
+ * `httpclient/missing-file` when `opts.file.path` doesn't exist or
+ * isn't a regular file. Composes through `request()` so SSRF gating,
+ * proxy routing, and the per-origin transport cache apply unchanged.
+ *
+ * @opts
+ *   url:       <required>,    // string — destination
+ *   file:      <required>,    // { path, fieldName, filename?, contentType? }
+ *   fields:    undefined,     // object — extra form fields { name: value, ... }
+ *   timeoutMs: undefined,     // wall-clock cap
+ *   maxBytes:  undefined,     // positive integer — refuse files larger than this
+ *   audit:     undefined,     // audit sink with safeEmit({...})
+ *
+ * @example
+ *   var res = await b.httpClient.uploadMultipartStream({
+ *     url:    "https://example.com/upload",
+ *     file:   {
+ *       path:        "/var/lib/blamejs/release.tar.gz",
+ *       fieldName:   "artifact",
+ *       contentType: "application/gzip",
+ *     },
+ *     fields: { releaseTag: "v1.2.3" },
+ *   });
+ *   // → { statusCode: 200, headers: { ... }, body: <Buffer> }
+ */
+async function uploadMultipartStream(opts) {
+  _validateUploadOpts(opts);
+
+  var filePath = opts.file.path;
+  var st;
+  try { st = fs.statSync(filePath); }
+  catch (e) {
+    _emitAudit(opts, "system.httpclient.upload_stream.refused", "denied", {
+      reason: "missing-file", path: filePath, message: e.message,
+    });
+    throw _hcErr("httpclient/missing-file",
+      "uploadMultipartStream: file.path not readable: " + e.message);
+  }
+  if (!st.isFile()) {
+    _emitAudit(opts, "system.httpclient.upload_stream.refused", "denied", {
+      reason: "not-a-regular-file", path: filePath,
+    });
+    throw _hcErr("httpclient/missing-file",
+      "uploadMultipartStream: file.path is not a regular file");
+  }
+
+  var filename = (typeof opts.file.filename === "string" && opts.file.filename.length > 0)
+    ? opts.file.filename
+    : nodePath.basename(filePath);
+  var contentType = (typeof opts.file.contentType === "string" && opts.file.contentType.length > 0)
+    ? opts.file.contentType
+    : "application/octet-stream";
+
+  // Reuse the existing multipart shorthand by passing { filePath } —
+  // it produces a Readable body + sets Content-Length when sizes resolve.
+  // _buildMultipartBody is internal; we route through request()'s
+  // multipart shorthand so the same wire path applies.
+  var fileSpec = {
+    field:       opts.file.fieldName,
+    filePath:    filePath,
+    filename:    filename,
+    contentType: contentType,
+  };
+
+  var res;
+  try {
+    res = await request({
+      method:           "POST",
+      url:              opts.url,
+      headers:          opts.headers || {},
+      multipart:        { fields: opts.fields || {}, files: [fileSpec], streaming: true },
+      timeoutMs:        opts.timeoutMs,
+      idleTimeoutMs:    opts.idleTimeoutMs,
+      signal:           opts.signal,
+      agent:            opts.agent,
+      allowedProtocols: opts.allowedProtocols,
+      allowedHosts:     opts.allowedHosts,
+      allowInternal:    opts.allowInternal,
+      maxResponseBytes: opts.maxResponseBytes,
+      audit:            opts.audit,
+      errorClass:       HttpClientError,
+    });
+  } catch (e) {
+    _emitAudit(opts, "system.httpclient.upload_stream.refused", "denied", {
+      reason: "request-failed", message: e.message, code: e.code,
+    });
+    throw e;
+  }
+
+  _emitAudit(opts, "system.httpclient.upload_stream.completed", "allowed", {
+    statusCode: res.statusCode,
+    fileBytes:  st.size,
+    fieldName:  opts.file.fieldName,
+    filename:   filename,
+  });
+
+  return {
+    statusCode: res.statusCode,
+    response:   res,
+  };
+}
+
 // ---- Test helpers ----
 
 function _resetForTest() {
@@ -1424,10 +1848,13 @@ function _getCachedTransportKind(url) {
 
 module.exports = {
   request:                    request,
+  downloadStream:             downloadStream,
+  uploadMultipartStream:      uploadMultipartStream,
   configurePool:              configurePool,
   DEFAULT_CONTROL_PLANE_CAP:  DEFAULT_CONTROL_PLANE_CAP,
   DEFAULT_GET_CAP:            DEFAULT_GET_CAP,
   DEFAULT_AGENT_OPTS:         DEFAULT_AGENT_OPTS,
+  ALLOWED_DOWNLOAD_HASH_ALGS: ALLOWED_DOWNLOAD_HASH_ALGS,
   _resetForTest:              _resetForTest,
   _getCachedTransportCount:   _getCachedTransportCount,
   _getCachedTransportKind:    _getCachedTransportKind,