@oxy.so/protocol 1.4.1 → 1.5.0

package/dist/cjs/node/constants.js

@@ -12,7 +12,7 @@
  * own shape constants live here.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = void 0;
+exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_BLOB_BODY_TIMEOUT_MS = exports.DEFAULT_CLIENT_BODY_TIMEOUT_MS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = void 0;
 /**
  * The node-protocol version advertised at the well-known manifest. Bumped only
  * on a breaking change to the wire shape of the log / head / record APIs. This
@@ -73,6 +73,14 @@ exports.NODE_SYNC_PUSH_PATH = '/sync/push';
 exports.NODE_BLOBS_PATH = '/blobs';
 /** Default time-to-first-byte deadline for a NodeClient request (ms). */
 exports.DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/**
+ * Default deadline for reading a whole JSON response body (head, log page,
+ * write result, `did.json`) once its headers have arrived (ms). The headers
+ * deadline above ends at the headers; this one stops a peer that then stalls.
+ */
+exports.DEFAULT_CLIENT_BODY_TIMEOUT_MS = 15000;
+/** Default deadline for reading a whole fetched blob body (up to {@link DEFAULT_MAX_BLOB_BYTES}) (ms). */
+exports.DEFAULT_BLOB_BODY_TIMEOUT_MS = 60000;
 /** Default redirect budget for a NodeClient request (each re-validated upstream). */
 exports.DEFAULT_CLIENT_MAX_REDIRECTS = 1;
 /** Default bounded read for a `/oxy/head` response (tiny JSON). */

package/dist/cjs/node/didWebResolver.js

@@ -91,6 +91,7 @@ function createDidWebResolver(fetch, options = {}) {
     const headersTimeoutMs = options.headersTimeoutMs ?? constants_1.DEFAULT_CLIENT_TIMEOUT_MS;
     const maxRedirects = options.maxRedirects ?? constants_1.DEFAULT_CLIENT_MAX_REDIRECTS;
     const maxBytes = options.maxBytes ?? constants_1.DEFAULT_DID_DOC_MAX_BYTES;
+    const bodyTimeoutMs = options.bodyTimeoutMs ?? constants_1.DEFAULT_CLIENT_BODY_TIMEOUT_MS;
     return {
         async resolve(subjectDid) {
             const url = didWebToUrl(subjectDid);
@@ -103,7 +104,7 @@ function createDidWebResolver(fetch, options = {}) {
                     res.destroy();
                     return null;
                 }
-                const body = await (0, httpFetch_1.readBoundedJson)(res, maxBytes);
+                const body = await (0, httpFetch_1.readBoundedJson)(res, maxBytes, bodyTimeoutMs);
                 const parsed = contracts_1.didDocumentSchema.safeParse(body);
                 if (!parsed.success) {
                     return null;

package/dist/cjs/node/httpFetch.js

@@ -10,17 +10,18 @@
  * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Either way
  * the SSRF/transport policy stays in the injected implementation, and the
- * bounded body read (the cap that stops a malicious node streaming forever)
- * stays here, close to the parsing.
+ * bounded body read (the byte cap and the body deadline that stop a malicious
+ * node streaming forever or stalling mid-body) stays here, close to the parsing.
  *
  * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
  * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
  * and `Buffer` is a `Uint8Array`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResponseTooLargeError = void 0;
+exports.ResponseTimeoutError = exports.ResponseTooLargeError = void 0;
 exports.readBoundedBytes = readBoundedBytes;
 exports.readBoundedJson = readBoundedJson;
+const constants_1 = require("./constants");
 /** Thrown when a response body exceeds the caller's byte ceiling. */
 class ResponseTooLargeError extends Error {
     constructor(maxBytes) {
@@ -31,16 +32,47 @@ class ResponseTooLargeError extends Error {
 }
 exports.ResponseTooLargeError = ResponseTooLargeError;
 /**
- * Read a response body into a single buffer, aborting (and destroying the
- * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
- * node that streams an unbounded body.
+ * Thrown when a response body does not end within the caller's deadline — a
+ * peer that sent its headers and then stalled or trickled the body. Unlike
+ * {@link ResponseTooLargeError} this says nothing about the peer's data, only
+ * that this attempt ran out of time: a caller treats it as transient and retries.
  */
-async function readBoundedBytes(res, maxBytes) {
+class ResponseTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`response body did not end within ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'ResponseTimeoutError';
+    }
+}
+exports.ResponseTimeoutError = ResponseTimeoutError;
+/**
+ * Read a response body into a single buffer, at most `maxBytes` and within
+ * `timeoutMs` for the WHOLE body (from the call until the stream ends). Past
+ * the cap it throws {@link ResponseTooLargeError}, past the deadline
+ * {@link ResponseTimeoutError}; on either, or a stream error, the stream is
+ * destroyed before the throw, and the deadline timer is cleared on every path.
+ *
+ * The transport's `headersTimeoutMs` ends at the response headers; this
+ * deadline is what stops a node that sends headers and then stalls the body
+ * from holding the reader open. `timeoutMs` defaults to
+ * {@link DEFAULT_CLIENT_BODY_TIMEOUT_MS}.
+ */
+async function readBoundedBytes(res, maxBytes, timeoutMs = constants_1.DEFAULT_CLIENT_BODY_TIMEOUT_MS) {
     const chunks = [];
     let total = 0;
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ResponseTimeoutError(timeoutMs)), timeoutMs);
+    });
+    const iterator = res.body[Symbol.asyncIterator]();
     try {
-        for await (const chunk of res.body) {
-            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        for (;;) {
+            // `Promise.race` subscribes to both, so neither the deadline nor a read
+            // that rejects once the stream is destroyed goes unhandled.
+            const step = await Promise.race([iterator.next(), deadline]);
+            if (step.done)
+                break;
+            const buf = Buffer.isBuffer(step.value) ? step.value : Buffer.from(step.value);
             total += buf.length;
             if (total > maxBytes) {
                 throw new ResponseTooLargeError(maxBytes);
@@ -52,10 +84,13 @@ async function readBoundedBytes(res, maxBytes) {
         res.destroy();
         throw err;
     }
-    return Buffer.concat(chunks);
+    finally {
+        clearTimeout(timer);
+    }
+    return Buffer.concat(chunks, total);
 }
-/** Read a bounded response body and parse it as JSON. */
-async function readBoundedJson(res, maxBytes) {
-    const bytes = await readBoundedBytes(res, maxBytes);
+/** Read a bounded, deadlined response body and parse it as JSON. */
+async function readBoundedJson(res, maxBytes, timeoutMs = constants_1.DEFAULT_CLIENT_BODY_TIMEOUT_MS) {
+    const bytes = await readBoundedBytes(res, maxBytes, timeoutMs);
     return JSON.parse(bytes.toString('utf8'));
 }

package/dist/cjs/node/index.js

@@ -14,7 +14,7 @@
  * a node via `NodeClient`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = exports.didWebToUrl = exports.createDidWebResolver = exports.ResponseTooLargeError = exports.readBoundedJson = exports.readBoundedBytes = exports.trimTrailingSlashes = exports.NodeClientError = exports.NodeClient = exports.verifyNodeRecordEnvelope = exports.DEFAULT_MAX_RATE_LIMIT_ENTRIES = exports.DEFAULT_WRITE_RATE_LIMIT = exports.createRateLimiter = exports.BlobHashMismatchError = exports.createNodeApp = void 0;
+exports.DEFAULT_DID_DOC_MAX_BYTES = exports.DEFAULT_WRITE_RESPONSE_MAX_BYTES = exports.DEFAULT_LOG_MAX_BYTES = exports.DEFAULT_HEAD_MAX_BYTES = exports.DEFAULT_CLIENT_MAX_REDIRECTS = exports.DEFAULT_BLOB_BODY_TIMEOUT_MS = exports.DEFAULT_CLIENT_BODY_TIMEOUT_MS = exports.DEFAULT_CLIENT_TIMEOUT_MS = exports.NODE_BLOBS_PATH = exports.NODE_SYNC_PUSH_PATH = exports.NODE_RECORDS_PATH = exports.NODE_LOG_PATH = exports.NODE_HEAD_PATH = exports.SHA256_HEX = exports.OWNER_ACTION_BLOB_PIN = exports.NODE_MODES = exports.OWNER_AUTH_MAX_AGE_MS = exports.OWNER_AUTH_HEADERS = exports.JSON_BODY_LIMIT = exports.MAX_SYNC_BATCH = exports.DEFAULT_MAX_BLOB_BYTES = exports.MAX_LOG_LIMIT = exports.DEFAULT_LOG_LIMIT = exports.DEFAULT_PORT = exports.DEFAULT_APP_NAMESPACE = exports.DEFAULT_SERVICE_TYPE = exports.DEFAULT_WELL_KNOWN_PATH = exports.PROTOCOL_VERSION = exports.didWebToUrl = exports.createDidWebResolver = exports.ResponseTimeoutError = exports.ResponseTooLargeError = exports.readBoundedJson = exports.readBoundedBytes = exports.trimTrailingSlashes = exports.NodeClientError = exports.NodeClient = exports.verifyNodeRecordEnvelope = exports.DEFAULT_MAX_RATE_LIMIT_ENTRIES = exports.DEFAULT_WRITE_RATE_LIMIT = exports.createRateLimiter = exports.BlobHashMismatchError = exports.createNodeApp = void 0;
 // ── Express app factory ───────────────────────────────────────────────────────
 var nodeApp_1 = require("./nodeApp");
 Object.defineProperty(exports, "createNodeApp", { enumerable: true, get: function () { return nodeApp_1.createNodeApp; } });
@@ -37,6 +37,7 @@ var httpFetch_1 = require("./httpFetch");
 Object.defineProperty(exports, "readBoundedBytes", { enumerable: true, get: function () { return httpFetch_1.readBoundedBytes; } });
 Object.defineProperty(exports, "readBoundedJson", { enumerable: true, get: function () { return httpFetch_1.readBoundedJson; } });
 Object.defineProperty(exports, "ResponseTooLargeError", { enumerable: true, get: function () { return httpFetch_1.ResponseTooLargeError; } });
+Object.defineProperty(exports, "ResponseTimeoutError", { enumerable: true, get: function () { return httpFetch_1.ResponseTimeoutError; } });
 // ── did:web verification-method resolver ───────────────────────────────────────
 var didWebResolver_1 = require("./didWebResolver");
 Object.defineProperty(exports, "createDidWebResolver", { enumerable: true, get: function () { return didWebResolver_1.createDidWebResolver; } });
@@ -64,6 +65,8 @@ Object.defineProperty(exports, "NODE_RECORDS_PATH", { enumerable: true, get: fun
 Object.defineProperty(exports, "NODE_SYNC_PUSH_PATH", { enumerable: true, get: function () { return constants_1.NODE_SYNC_PUSH_PATH; } });
 Object.defineProperty(exports, "NODE_BLOBS_PATH", { enumerable: true, get: function () { return constants_1.NODE_BLOBS_PATH; } });
 Object.defineProperty(exports, "DEFAULT_CLIENT_TIMEOUT_MS", { enumerable: true, get: function () { return constants_1.DEFAULT_CLIENT_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DEFAULT_CLIENT_BODY_TIMEOUT_MS", { enumerable: true, get: function () { return constants_1.DEFAULT_CLIENT_BODY_TIMEOUT_MS; } });
+Object.defineProperty(exports, "DEFAULT_BLOB_BODY_TIMEOUT_MS", { enumerable: true, get: function () { return constants_1.DEFAULT_BLOB_BODY_TIMEOUT_MS; } });
 Object.defineProperty(exports, "DEFAULT_CLIENT_MAX_REDIRECTS", { enumerable: true, get: function () { return constants_1.DEFAULT_CLIENT_MAX_REDIRECTS; } });
 Object.defineProperty(exports, "DEFAULT_HEAD_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_HEAD_MAX_BYTES; } });
 Object.defineProperty(exports, "DEFAULT_LOG_MAX_BYTES", { enumerable: true, get: function () { return constants_1.DEFAULT_LOG_MAX_BYTES; } });

package/dist/cjs/node/nodeClient.js

@@ -9,8 +9,9 @@
  * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
  * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Every
- * response body is read with a hard byte ceiling, so a node cannot stream an
- * unbounded body into the caller.
+ * response body is read with a hard byte ceiling AND a whole-body deadline, so
+ * a node can neither stream an unbounded body into the caller nor hold it by
+ * stalling after the headers (`ResponseTimeoutError`, which is transient).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeClient = exports.NodeClientError = void 0;
@@ -54,6 +55,8 @@ class NodeClient {
         this.baseUrl = trimTrailingSlashes(options.baseUrl);
         this.fetch = options.fetch;
         this.headersTimeoutMs = options.headersTimeoutMs ?? constants_1.DEFAULT_CLIENT_TIMEOUT_MS;
+        this.bodyTimeoutMs = options.bodyTimeoutMs ?? constants_1.DEFAULT_CLIENT_BODY_TIMEOUT_MS;
+        this.blobBodyTimeoutMs = options.blobBodyTimeoutMs ?? constants_1.DEFAULT_BLOB_BODY_TIMEOUT_MS;
         this.maxRedirects = options.maxRedirects ?? constants_1.DEFAULT_CLIENT_MAX_REDIRECTS;
         this.headMaxBytes = options.headMaxBytes ?? constants_1.DEFAULT_HEAD_MAX_BYTES;
         this.logMaxBytes = options.logMaxBytes ?? constants_1.DEFAULT_LOG_MAX_BYTES;
@@ -75,7 +78,7 @@ class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${constants_1.NODE_HEAD_PATH} responded HTTP ${res.status}`, res.status);
         }
-        const body = await (0, httpFetch_1.readBoundedJson)(res, this.headMaxBytes);
+        const body = await (0, httpFetch_1.readBoundedJson)(res, this.headMaxBytes, this.bodyTimeoutMs);
         const obj = (typeof body === 'object' && body !== null ? body : {});
         return {
             seq: typeof obj.seq === 'number' ? obj.seq : null,
@@ -100,7 +103,7 @@ class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${constants_1.NODE_LOG_PATH} responded HTTP ${res.status}`, res.status);
         }
-        const body = await (0, httpFetch_1.readBoundedJson)(res, this.logMaxBytes);
+        const body = await (0, httpFetch_1.readBoundedJson)(res, this.logMaxBytes, this.bodyTimeoutMs);
         const records = body.records;
         if (!Array.isArray(records)) {
             throw new NodeClientError(`node ${constants_1.NODE_LOG_PATH} returned no records array`, res.status);
@@ -129,7 +132,7 @@ class NodeClient {
             headers: { 'Content-Type': 'application/json' },
             body: Buffer.from(JSON.stringify(envelope), 'utf8'),
         }));
-        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes);
+        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${constants_1.NODE_RECORDS_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
@@ -151,7 +154,7 @@ class NodeClient {
             headers: { 'Content-Type': 'application/json' },
             body: Buffer.from(JSON.stringify({ records: envelopes }), 'utf8'),
         }));
-        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes);
+        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${constants_1.NODE_SYNC_PUSH_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
@@ -175,7 +178,7 @@ class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${constants_1.NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}`, res.status);
         }
-        return (0, httpFetch_1.readBoundedBytes)(res, this.blobMaxBytes);
+        return (0, httpFetch_1.readBoundedBytes)(res, this.blobMaxBytes, this.blobBodyTimeoutMs);
     }
     /**
      * Pin a content-addressed blob with an owner-signed authorization
@@ -194,7 +197,7 @@ class NodeClient {
             },
             body: bytes,
         }));
-        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes);
+        const body = await (0, httpFetch_1.readBoundedJson)(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${constants_1.NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);

package/dist/esm/node/constants.js

@@ -70,6 +70,14 @@ export const NODE_SYNC_PUSH_PATH = '/sync/push';
 export const NODE_BLOBS_PATH = '/blobs';
 /** Default time-to-first-byte deadline for a NodeClient request (ms). */
 export const DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/**
+ * Default deadline for reading a whole JSON response body (head, log page,
+ * write result, `did.json`) once its headers have arrived (ms). The headers
+ * deadline above ends at the headers; this one stops a peer that then stalls.
+ */
+export const DEFAULT_CLIENT_BODY_TIMEOUT_MS = 15000;
+/** Default deadline for reading a whole fetched blob body (up to {@link DEFAULT_MAX_BLOB_BYTES}) (ms). */
+export const DEFAULT_BLOB_BODY_TIMEOUT_MS = 60000;
 /** Default redirect budget for a NodeClient request (each re-validated upstream). */
 export const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
 /** Default bounded read for a `/oxy/head` response (tiny JSON). */

package/dist/esm/node/didWebResolver.js

@@ -18,7 +18,7 @@
  */
 import { didDocumentSchema, } from '@oxy.so/contracts';
 import { readBoundedJson } from './httpFetch.js';
-import { DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';
+import { DEFAULT_CLIENT_BODY_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';
 /**
  * Map a `did:web` DID to its `did.json` URL, or `null` when `did` is not a
  * well-formed `did:web` identifier.
@@ -87,6 +87,7 @@ export function createDidWebResolver(fetch, options = {}) {
     const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
     const maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
     const maxBytes = options.maxBytes ?? DEFAULT_DID_DOC_MAX_BYTES;
+    const bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_CLIENT_BODY_TIMEOUT_MS;
     return {
         async resolve(subjectDid) {
             const url = didWebToUrl(subjectDid);
@@ -99,7 +100,7 @@ export function createDidWebResolver(fetch, options = {}) {
                     res.destroy();
                     return null;
                 }
-                const body = await readBoundedJson(res, maxBytes);
+                const body = await readBoundedJson(res, maxBytes, bodyTimeoutMs);
                 const parsed = didDocumentSchema.safeParse(body);
                 if (!parsed.success) {
                     return null;

package/dist/esm/node/httpFetch.js

@@ -9,13 +9,14 @@
  * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Either way
  * the SSRF/transport policy stays in the injected implementation, and the
- * bounded body read (the cap that stops a malicious node streaming forever)
- * stays here, close to the parsing.
+ * bounded body read (the byte cap and the body deadline that stop a malicious
+ * node streaming forever or stalling mid-body) stays here, close to the parsing.
  *
  * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
  * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
  * and `Buffer` is a `Uint8Array`.
  */
+import { DEFAULT_CLIENT_BODY_TIMEOUT_MS } from './constants.js';
 /** Thrown when a response body exceeds the caller's byte ceiling. */
 export class ResponseTooLargeError extends Error {
     constructor(maxBytes) {
@@ -25,16 +26,46 @@ export class ResponseTooLargeError extends Error {
     }
 }
 /**
- * Read a response body into a single buffer, aborting (and destroying the
- * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
- * node that streams an unbounded body.
+ * Thrown when a response body does not end within the caller's deadline — a
+ * peer that sent its headers and then stalled or trickled the body. Unlike
+ * {@link ResponseTooLargeError} this says nothing about the peer's data, only
+ * that this attempt ran out of time: a caller treats it as transient and retries.
  */
-export async function readBoundedBytes(res, maxBytes) {
+export class ResponseTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`response body did not end within ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'ResponseTimeoutError';
+    }
+}
+/**
+ * Read a response body into a single buffer, at most `maxBytes` and within
+ * `timeoutMs` for the WHOLE body (from the call until the stream ends). Past
+ * the cap it throws {@link ResponseTooLargeError}, past the deadline
+ * {@link ResponseTimeoutError}; on either, or a stream error, the stream is
+ * destroyed before the throw, and the deadline timer is cleared on every path.
+ *
+ * The transport's `headersTimeoutMs` ends at the response headers; this
+ * deadline is what stops a node that sends headers and then stalls the body
+ * from holding the reader open. `timeoutMs` defaults to
+ * {@link DEFAULT_CLIENT_BODY_TIMEOUT_MS}.
+ */
+export async function readBoundedBytes(res, maxBytes, timeoutMs = DEFAULT_CLIENT_BODY_TIMEOUT_MS) {
     const chunks = [];
     let total = 0;
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ResponseTimeoutError(timeoutMs)), timeoutMs);
+    });
+    const iterator = res.body[Symbol.asyncIterator]();
     try {
-        for await (const chunk of res.body) {
-            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        for (;;) {
+            // `Promise.race` subscribes to both, so neither the deadline nor a read
+            // that rejects once the stream is destroyed goes unhandled.
+            const step = await Promise.race([iterator.next(), deadline]);
+            if (step.done)
+                break;
+            const buf = Buffer.isBuffer(step.value) ? step.value : Buffer.from(step.value);
             total += buf.length;
             if (total > maxBytes) {
                 throw new ResponseTooLargeError(maxBytes);
@@ -46,10 +77,13 @@ export async function readBoundedBytes(res, maxBytes) {
         res.destroy();
         throw err;
     }
-    return Buffer.concat(chunks);
+    finally {
+        clearTimeout(timer);
+    }
+    return Buffer.concat(chunks, total);
 }
-/** Read a bounded response body and parse it as JSON. */
-export async function readBoundedJson(res, maxBytes) {
-    const bytes = await readBoundedBytes(res, maxBytes);
+/** Read a bounded, deadlined response body and parse it as JSON. */
+export async function readBoundedJson(res, maxBytes, timeoutMs = DEFAULT_CLIENT_BODY_TIMEOUT_MS) {
+    const bytes = await readBoundedBytes(res, maxBytes, timeoutMs);
     return JSON.parse(bytes.toString('utf8'));
 }

package/dist/esm/node/index.js

@@ -21,8 +21,8 @@ export { verifyNodeRecordEnvelope } from './verifyRecord.js';
 // ── HTTP client ────────────────────────────────────────────────────────────────
 export { NodeClient, NodeClientError, trimTrailingSlashes } from './nodeClient.js';
 // ── Injected transport contract + bounded readers ──────────────────────────────
-export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch.js';
+export { readBoundedBytes, readBoundedJson, ResponseTooLargeError, ResponseTimeoutError, } from './httpFetch.js';
 // ── did:web verification-method resolver ───────────────────────────────────────
 export { createDidWebResolver, didWebToUrl } from './didWebResolver.js';
 // ── Node-protocol shape constants ──────────────────────────────────────────────
-export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';
+export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_BODY_TIMEOUT_MS, DEFAULT_BLOB_BODY_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants.js';

package/dist/esm/node/nodeClient.js

@@ -8,11 +8,12 @@
  * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
  * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Every
- * response body is read with a hard byte ceiling, so a node cannot stream an
- * unbounded body into the caller.
+ * response body is read with a hard byte ceiling AND a whole-body deadline, so
+ * a node can neither stream an unbounded body into the caller nor hold it by
+ * stalling after the headers (`ResponseTimeoutError`, which is transient).
  */
 import { readBoundedBytes, readBoundedJson } from './httpFetch.js';
-import { DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_MAX_BLOB_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, NODE_BLOBS_PATH, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, OWNER_AUTH_HEADERS, } from './constants.js';
+import { DEFAULT_BLOB_BODY_TIMEOUT_MS, DEFAULT_CLIENT_BODY_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_MAX_BLOB_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, NODE_BLOBS_PATH, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, OWNER_AUTH_HEADERS, } from './constants.js';
 /** A non-2xx node response (or a node that returned a malformed body). */
 export class NodeClientError extends Error {
     constructor(message, status, reason) {
@@ -49,6 +50,8 @@ export class NodeClient {
         this.baseUrl = trimTrailingSlashes(options.baseUrl);
         this.fetch = options.fetch;
         this.headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+        this.bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_CLIENT_BODY_TIMEOUT_MS;
+        this.blobBodyTimeoutMs = options.blobBodyTimeoutMs ?? DEFAULT_BLOB_BODY_TIMEOUT_MS;
         this.maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
         this.headMaxBytes = options.headMaxBytes ?? DEFAULT_HEAD_MAX_BYTES;
         this.logMaxBytes = options.logMaxBytes ?? DEFAULT_LOG_MAX_BYTES;
@@ -70,7 +73,7 @@ export class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${NODE_HEAD_PATH} responded HTTP ${res.status}`, res.status);
         }
-        const body = await readBoundedJson(res, this.headMaxBytes);
+        const body = await readBoundedJson(res, this.headMaxBytes, this.bodyTimeoutMs);
         const obj = (typeof body === 'object' && body !== null ? body : {});
         return {
             seq: typeof obj.seq === 'number' ? obj.seq : null,
@@ -95,7 +98,7 @@ export class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${NODE_LOG_PATH} responded HTTP ${res.status}`, res.status);
         }
-        const body = await readBoundedJson(res, this.logMaxBytes);
+        const body = await readBoundedJson(res, this.logMaxBytes, this.bodyTimeoutMs);
         const records = body.records;
         if (!Array.isArray(records)) {
             throw new NodeClientError(`node ${NODE_LOG_PATH} returned no records array`, res.status);
@@ -124,7 +127,7 @@ export class NodeClient {
             headers: { 'Content-Type': 'application/json' },
             body: Buffer.from(JSON.stringify(envelope), 'utf8'),
         }));
-        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${NODE_RECORDS_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
@@ -146,7 +149,7 @@ export class NodeClient {
             headers: { 'Content-Type': 'application/json' },
             body: Buffer.from(JSON.stringify({ records: envelopes }), 'utf8'),
         }));
-        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${NODE_SYNC_PUSH_PATH} responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);
@@ -170,7 +173,7 @@ export class NodeClient {
             res.destroy();
             throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}`, res.status);
         }
-        return readBoundedBytes(res, this.blobMaxBytes);
+        return readBoundedBytes(res, this.blobMaxBytes, this.blobBodyTimeoutMs);
     }
     /**
      * Pin a content-addressed blob with an owner-signed authorization
@@ -189,7 +192,7 @@ export class NodeClient {
             },
             body: bytes,
         }));
-        const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+        const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
         if (res.status < 200 || res.status >= 300) {
             const reason = readError(body);
             throw new NodeClientError(`node ${NODE_BLOBS_PATH}/:hash responded HTTP ${res.status}${reason ? ` (${reason})` : ''}`, res.status, reason);

package/dist/types/node/constants.d.ts

@@ -68,6 +68,14 @@ export declare const NODE_SYNC_PUSH_PATH = "/sync/push";
 export declare const NODE_BLOBS_PATH = "/blobs";
 /** Default time-to-first-byte deadline for a NodeClient request (ms). */
 export declare const DEFAULT_CLIENT_TIMEOUT_MS = 8000;
+/**
+ * Default deadline for reading a whole JSON response body (head, log page,
+ * write result, `did.json`) once its headers have arrived (ms). The headers
+ * deadline above ends at the headers; this one stops a peer that then stalls.
+ */
+export declare const DEFAULT_CLIENT_BODY_TIMEOUT_MS = 15000;
+/** Default deadline for reading a whole fetched blob body (up to {@link DEFAULT_MAX_BLOB_BYTES}) (ms). */
+export declare const DEFAULT_BLOB_BODY_TIMEOUT_MS = 60000;
 /** Default redirect budget for a NodeClient request (each re-validated upstream). */
 export declare const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
 /** Default bounded read for a `/oxy/head` response (tiny JSON). */

package/dist/types/node/didWebResolver.d.ts

@@ -22,6 +22,8 @@ import { type NodeFetch } from './httpFetch';
 export interface DidWebResolverOptions {
     /** Time-to-first-byte deadline for the `did.json` fetch (ms). */
     headersTimeoutMs?: number;
+    /** Whole-body read deadline for the `did.json`, once its headers arrived (ms). */
+    bodyTimeoutMs?: number;
     /** Redirect budget for the `did.json` fetch (each re-validated by the transport). */
     maxRedirects?: number;
     /** Bounded read ceiling for the fetched `did.json`. */

package/dist/types/node/httpFetch.d.ts

@@ -9,8 +9,8 @@
  * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Either way
  * the SSRF/transport policy stays in the injected implementation, and the
- * bounded body read (the cap that stops a malicious node streaming forever)
- * stays here, close to the parsing.
+ * bounded body read (the byte cap and the body deadline that stop a malicious
+ * node streaming forever or stalling mid-body) stays here, close to the parsing.
  *
  * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
  * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
@@ -51,10 +51,27 @@ export declare class ResponseTooLargeError extends Error {
     constructor(maxBytes: number);
 }
 /**
- * Read a response body into a single buffer, aborting (and destroying the
- * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
- * node that streams an unbounded body.
+ * Thrown when a response body does not end within the caller's deadline — a
+ * peer that sent its headers and then stalled or trickled the body. Unlike
+ * {@link ResponseTooLargeError} this says nothing about the peer's data, only
+ * that this attempt ran out of time: a caller treats it as transient and retries.
  */
-export declare function readBoundedBytes(res: NodeFetchResponse, maxBytes: number): Promise<Buffer>;
-/** Read a bounded response body and parse it as JSON. */
-export declare function readBoundedJson(res: NodeFetchResponse, maxBytes: number): Promise<unknown>;
+export declare class ResponseTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Read a response body into a single buffer, at most `maxBytes` and within
+ * `timeoutMs` for the WHOLE body (from the call until the stream ends). Past
+ * the cap it throws {@link ResponseTooLargeError}, past the deadline
+ * {@link ResponseTimeoutError}; on either, or a stream error, the stream is
+ * destroyed before the throw, and the deadline timer is cleared on every path.
+ *
+ * The transport's `headersTimeoutMs` ends at the response headers; this
+ * deadline is what stops a node that sends headers and then stalls the body
+ * from holding the reader open. `timeoutMs` defaults to
+ * {@link DEFAULT_CLIENT_BODY_TIMEOUT_MS}.
+ */
+export declare function readBoundedBytes(res: NodeFetchResponse, maxBytes: number, timeoutMs?: number): Promise<Buffer>;
+/** Read a bounded, deadlined response body and parse it as JSON. */
+export declare function readBoundedJson(res: NodeFetchResponse, maxBytes: number, timeoutMs?: number): Promise<unknown>;

package/dist/types/node/index.d.ts

@@ -20,9 +20,9 @@ export { verifyNodeRecordEnvelope } from './verifyRecord';
 export type { NodeVerifyResult, NodeVerifyRejectionReason } from './verifyRecord';
 export { NodeClient, NodeClientError, trimTrailingSlashes } from './nodeClient';
 export type { NodeClientOptions, NodeHead, NodeLogPage, NodeWriteResult, NodeBlobPutResult, NodeBlobPinAuth, } from './nodeClient';
-export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch';
+export { readBoundedBytes, readBoundedJson, ResponseTooLargeError, ResponseTimeoutError, } from './httpFetch';
 export type { NodeFetch, NodeFetchInit, NodeFetchResponse } from './httpFetch';
 export { createDidWebResolver, didWebToUrl } from './didWebResolver';
 export type { DidWebResolverOptions } from './didWebResolver';
-export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants';
+export { PROTOCOL_VERSION, DEFAULT_WELL_KNOWN_PATH, DEFAULT_SERVICE_TYPE, DEFAULT_APP_NAMESPACE, DEFAULT_PORT, DEFAULT_LOG_LIMIT, MAX_LOG_LIMIT, DEFAULT_MAX_BLOB_BYTES, MAX_SYNC_BATCH, JSON_BODY_LIMIT, OWNER_AUTH_HEADERS, OWNER_AUTH_MAX_AGE_MS, NODE_MODES, OWNER_ACTION_BLOB_PIN, SHA256_HEX, NODE_HEAD_PATH, NODE_LOG_PATH, NODE_RECORDS_PATH, NODE_SYNC_PUSH_PATH, NODE_BLOBS_PATH, DEFAULT_CLIENT_TIMEOUT_MS, DEFAULT_CLIENT_BODY_TIMEOUT_MS, DEFAULT_BLOB_BODY_TIMEOUT_MS, DEFAULT_CLIENT_MAX_REDIRECTS, DEFAULT_HEAD_MAX_BYTES, DEFAULT_LOG_MAX_BYTES, DEFAULT_WRITE_RESPONSE_MAX_BYTES, DEFAULT_DID_DOC_MAX_BYTES, } from './constants';
 export type { NodeMode } from './constants';

package/dist/types/node/nodeClient.d.ts

@@ -8,8 +8,9 @@
  * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
  * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Every
- * response body is read with a hard byte ceiling, so a node cannot stream an
- * unbounded body into the caller.
+ * response body is read with a hard byte ceiling AND a whole-body deadline, so
+ * a node can neither stream an unbounded body into the caller nor hold it by
+ * stalling after the headers (`ResponseTimeoutError`, which is transient).
  */
 import type { SignedRecordEnvelope } from '@oxy.so/contracts';
 import { type NodeFetch } from './httpFetch';
@@ -63,6 +64,10 @@ export interface NodeClientOptions {
     fetch: NodeFetch;
     /** Time-to-first-byte deadline per request (ms). */
     headersTimeoutMs?: number;
+    /** Whole-body read deadline for a JSON response, once its headers arrived (ms). */
+    bodyTimeoutMs?: number;
+    /** Whole-body read deadline for a fetched blob (ms). */
+    blobBodyTimeoutMs?: number;
     /** Redirect budget per request (each re-validated by the transport). */
     maxRedirects?: number;
     /** Bounded read ceiling for a `/oxy/head` response. */
@@ -86,6 +91,8 @@ export declare class NodeClient {
     private readonly baseUrl;
     private readonly fetch;
     private readonly headersTimeoutMs;
+    private readonly bodyTimeoutMs;
+    private readonly blobBodyTimeoutMs;
     private readonly maxRedirects;
     private readonly headMaxBytes;
     private readonly logMaxBytes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/protocol",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Oxy Protocol — the app-agnostic base substrate: signed-record envelope, canonical JSON, signature/verification, and platform crypto. Reused by any Oxy app to decentralize its own content.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -132,7 +132,7 @@
   },
   "dependencies": {
     "@noble/curves": "^1.9.7",
-    "@oxy.so/contracts": "^5.0.0",
+    "@oxy.so/contracts": "^5.4.0",
     "zod": "^3.25.64"
   },
   "peerDependencies": {

package/src/__tests__/httpFetch.test.ts

@@ -0,0 +1,49 @@
+import { PassThrough } from 'node:stream';
+import {
+  type NodeFetchResponse,
+  readBoundedBytes,
+  ResponseTimeoutError,
+  ResponseTooLargeError,
+} from '../node/httpFetch';
+
+function streamResponse(): { stream: PassThrough; res: NodeFetchResponse } {
+  const stream = new PassThrough();
+  return {
+    stream,
+    res: { status: 200, headers: {}, body: stream, destroy: () => stream.destroy() },
+  };
+}
+
+describe('readBoundedBytes', () => {
+  it('reads a body that ends within its limits', async () => {
+    const { stream, res } = streamResponse();
+    const pending = readBoundedBytes(res, 8, 1_000);
+    stream.write('ab');
+    stream.end('cd');
+    expect((await pending).toString()).toBe('abcd');
+  });
+
+  it('throws ResponseTooLargeError one byte past the cap and destroys the stream', async () => {
+    const { stream, res } = streamResponse();
+    const pending = readBoundedBytes(res, 3, 1_000);
+    stream.write('abcd');
+    await expect(pending).rejects.toBeInstanceOf(ResponseTooLargeError);
+    expect(stream.destroyed).toBe(true);
+  });
+
+  it('throws ResponseTimeoutError for a body that stalls and destroys the stream', async () => {
+    jest.useFakeTimers();
+    try {
+      const { stream, res } = streamResponse();
+      const pending = readBoundedBytes(res, 1_024, 5_000);
+      stream.write('{"partial":');
+      const settled = expect(pending).rejects.toBeInstanceOf(ResponseTimeoutError);
+      await jest.advanceTimersByTimeAsync(5_000);
+      await settled;
+      expect(stream.destroyed).toBe(true);
+      expect(jest.getTimerCount()).toBe(0);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+});

package/src/node/constants.ts

@@ -89,6 +89,16 @@ export const NODE_BLOBS_PATH = '/blobs';
 /** Default time-to-first-byte deadline for a NodeClient request (ms). */
 export const DEFAULT_CLIENT_TIMEOUT_MS = 8_000;
 
+/**
+ * Default deadline for reading a whole JSON response body (head, log page,
+ * write result, `did.json`) once its headers have arrived (ms). The headers
+ * deadline above ends at the headers; this one stops a peer that then stalls.
+ */
+export const DEFAULT_CLIENT_BODY_TIMEOUT_MS = 15_000;
+
+/** Default deadline for reading a whole fetched blob body (up to {@link DEFAULT_MAX_BLOB_BYTES}) (ms). */
+export const DEFAULT_BLOB_BODY_TIMEOUT_MS = 60_000;
+
 /** Default redirect budget for a NodeClient request (each re-validated upstream). */
 export const DEFAULT_CLIENT_MAX_REDIRECTS = 1;
 

package/src/node/didWebResolver.ts

@@ -25,6 +25,7 @@ import {
 import type { ResolvedVerificationMethods, VerificationMethodResolver } from '../identity/resolver';
 import { type NodeFetch, readBoundedJson } from './httpFetch';
 import {
+  DEFAULT_CLIENT_BODY_TIMEOUT_MS,
   DEFAULT_CLIENT_MAX_REDIRECTS,
   DEFAULT_CLIENT_TIMEOUT_MS,
   DEFAULT_DID_DOC_MAX_BYTES,
@@ -34,6 +35,8 @@ import {
 export interface DidWebResolverOptions {
   /** Time-to-first-byte deadline for the `did.json` fetch (ms). */
   headersTimeoutMs?: number;
+  /** Whole-body read deadline for the `did.json`, once its headers arrived (ms). */
+  bodyTimeoutMs?: number;
   /** Redirect budget for the `did.json` fetch (each re-validated by the transport). */
   maxRedirects?: number;
   /** Bounded read ceiling for the fetched `did.json`. */
@@ -124,6 +127,7 @@ export function createDidWebResolver(
   const headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
   const maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
   const maxBytes = options.maxBytes ?? DEFAULT_DID_DOC_MAX_BYTES;
+  const bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_CLIENT_BODY_TIMEOUT_MS;
 
   return {
     async resolve(subjectDid: string): Promise<ResolvedVerificationMethods | null> {
@@ -137,7 +141,7 @@ export function createDidWebResolver(
           res.destroy();
           return null;
         }
-        const body = await readBoundedJson(res, maxBytes);
+        const body = await readBoundedJson(res, maxBytes, bodyTimeoutMs);
         const parsed = didDocumentSchema.safeParse(body);
         if (!parsed.success) {
           return null;

package/src/node/httpFetch.ts

@@ -9,14 +9,16 @@
  * Oxy supplies an adapter over `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Either way
  * the SSRF/transport policy stays in the injected implementation, and the
- * bounded body read (the cap that stops a malicious node streaming forever)
- * stays here, close to the parsing.
+ * bounded body read (the byte cap and the body deadline that stop a malicious
+ * node streaming forever or stalling mid-body) stays here, close to the parsing.
  *
  * A Node `IncomingMessage` (what `safeFetch` returns) satisfies
  * {@link NodeFetchResponse.body} directly — it is an `AsyncIterable<Buffer>`,
  * and `Buffer` is a `Uint8Array`.
  */
 
+import { DEFAULT_CLIENT_BODY_TIMEOUT_MS } from './constants';
+
 /** Per-request options the client passes to the injected transport. */
 export interface NodeFetchInit {
   /** HTTP method (`GET` / `POST` / `PUT`). */
@@ -58,16 +60,49 @@ export class ResponseTooLargeError extends Error {
 }
 
 /**
- * Read a response body into a single buffer, aborting (and destroying the
- * stream) the moment it exceeds `maxBytes`. The bound is the defence against a
- * node that streams an unbounded body.
+ * Thrown when a response body does not end within the caller's deadline — a
+ * peer that sent its headers and then stalled or trickled the body. Unlike
+ * {@link ResponseTooLargeError} this says nothing about the peer's data, only
+ * that this attempt ran out of time: a caller treats it as transient and retries.
+ */
+export class ResponseTimeoutError extends Error {
+  constructor(public readonly timeoutMs: number) {
+    super(`response body did not end within ${timeoutMs} ms`);
+    this.name = 'ResponseTimeoutError';
+  }
+}
+
+/**
+ * Read a response body into a single buffer, at most `maxBytes` and within
+ * `timeoutMs` for the WHOLE body (from the call until the stream ends). Past
+ * the cap it throws {@link ResponseTooLargeError}, past the deadline
+ * {@link ResponseTimeoutError}; on either, or a stream error, the stream is
+ * destroyed before the throw, and the deadline timer is cleared on every path.
+ *
+ * The transport's `headersTimeoutMs` ends at the response headers; this
+ * deadline is what stops a node that sends headers and then stalls the body
+ * from holding the reader open. `timeoutMs` defaults to
+ * {@link DEFAULT_CLIENT_BODY_TIMEOUT_MS}.
  */
-export async function readBoundedBytes(res: NodeFetchResponse, maxBytes: number): Promise<Buffer> {
+export async function readBoundedBytes(
+  res: NodeFetchResponse,
+  maxBytes: number,
+  timeoutMs: number = DEFAULT_CLIENT_BODY_TIMEOUT_MS,
+): Promise<Buffer> {
   const chunks: Buffer[] = [];
   let total = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new ResponseTimeoutError(timeoutMs)), timeoutMs);
+  });
+  const iterator = res.body[Symbol.asyncIterator]();
   try {
-    for await (const chunk of res.body) {
-      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    for (;;) {
+      // `Promise.race` subscribes to both, so neither the deadline nor a read
+      // that rejects once the stream is destroyed goes unhandled.
+      const step = await Promise.race([iterator.next(), deadline]);
+      if (step.done) break;
+      const buf = Buffer.isBuffer(step.value) ? step.value : Buffer.from(step.value);
       total += buf.length;
       if (total > maxBytes) {
         throw new ResponseTooLargeError(maxBytes);
@@ -77,12 +112,18 @@ export async function readBoundedBytes(res: NodeFetchResponse, maxBytes: number)
   } catch (err) {
     res.destroy();
     throw err;
+  } finally {
+    clearTimeout(timer);
   }
-  return Buffer.concat(chunks);
+  return Buffer.concat(chunks, total);
 }
 
-/** Read a bounded response body and parse it as JSON. */
-export async function readBoundedJson(res: NodeFetchResponse, maxBytes: number): Promise<unknown> {
-  const bytes = await readBoundedBytes(res, maxBytes);
+/** Read a bounded, deadlined response body and parse it as JSON. */
+export async function readBoundedJson(
+  res: NodeFetchResponse,
+  maxBytes: number,
+  timeoutMs: number = DEFAULT_CLIENT_BODY_TIMEOUT_MS,
+): Promise<unknown> {
+  const bytes = await readBoundedBytes(res, maxBytes, timeoutMs);
   return JSON.parse(bytes.toString('utf8'));
 }

package/src/node/index.ts

@@ -48,7 +48,12 @@ export type {
 } from './nodeClient';
 
 // ── Injected transport contract + bounded readers ──────────────────────────────
-export { readBoundedBytes, readBoundedJson, ResponseTooLargeError } from './httpFetch';
+export {
+  readBoundedBytes,
+  readBoundedJson,
+  ResponseTooLargeError,
+  ResponseTimeoutError,
+} from './httpFetch';
 export type { NodeFetch, NodeFetchInit, NodeFetchResponse } from './httpFetch';
 
 // ── did:web verification-method resolver ───────────────────────────────────────
@@ -78,6 +83,8 @@ export {
   NODE_SYNC_PUSH_PATH,
   NODE_BLOBS_PATH,
   DEFAULT_CLIENT_TIMEOUT_MS,
+  DEFAULT_CLIENT_BODY_TIMEOUT_MS,
+  DEFAULT_BLOB_BODY_TIMEOUT_MS,
   DEFAULT_CLIENT_MAX_REDIRECTS,
   DEFAULT_HEAD_MAX_BYTES,
   DEFAULT_LOG_MAX_BYTES,

package/src/node/nodeClient.ts

@@ -8,13 +8,16 @@
  * the protocol package never depends on `@oxy.so/core`. Oxy supplies an adapter
  * over `@oxy.so/core/server`'s `safeFetch` (HTTPS-only, DNS-pinned, private-IP
  * denylist, bounded redirects); a test supplies an in-process stub. Every
- * response body is read with a hard byte ceiling, so a node cannot stream an
- * unbounded body into the caller.
+ * response body is read with a hard byte ceiling AND a whole-body deadline, so
+ * a node can neither stream an unbounded body into the caller nor hold it by
+ * stalling after the headers (`ResponseTimeoutError`, which is transient).
  */
 
 import type { SignedRecordEnvelope } from '@oxy.so/contracts';
 import { type NodeFetch, type NodeFetchInit, readBoundedBytes, readBoundedJson } from './httpFetch';
 import {
+  DEFAULT_BLOB_BODY_TIMEOUT_MS,
+  DEFAULT_CLIENT_BODY_TIMEOUT_MS,
   DEFAULT_CLIENT_MAX_REDIRECTS,
   DEFAULT_CLIENT_TIMEOUT_MS,
   DEFAULT_HEAD_MAX_BYTES,
@@ -87,6 +90,10 @@ export interface NodeClientOptions {
   fetch: NodeFetch;
   /** Time-to-first-byte deadline per request (ms). */
   headersTimeoutMs?: number;
+  /** Whole-body read deadline for a JSON response, once its headers arrived (ms). */
+  bodyTimeoutMs?: number;
+  /** Whole-body read deadline for a fetched blob (ms). */
+  blobBodyTimeoutMs?: number;
   /** Redirect budget per request (each re-validated by the transport). */
   maxRedirects?: number;
   /** Bounded read ceiling for a `/oxy/head` response. */
@@ -129,6 +136,8 @@ export class NodeClient {
   private readonly baseUrl: string;
   private readonly fetch: NodeFetch;
   private readonly headersTimeoutMs: number;
+  private readonly bodyTimeoutMs: number;
+  private readonly blobBodyTimeoutMs: number;
   private readonly maxRedirects: number;
   private readonly headMaxBytes: number;
   private readonly logMaxBytes: number;
@@ -139,6 +148,8 @@ export class NodeClient {
     this.baseUrl = trimTrailingSlashes(options.baseUrl);
     this.fetch = options.fetch;
     this.headersTimeoutMs = options.headersTimeoutMs ?? DEFAULT_CLIENT_TIMEOUT_MS;
+    this.bodyTimeoutMs = options.bodyTimeoutMs ?? DEFAULT_CLIENT_BODY_TIMEOUT_MS;
+    this.blobBodyTimeoutMs = options.blobBodyTimeoutMs ?? DEFAULT_BLOB_BODY_TIMEOUT_MS;
     this.maxRedirects = options.maxRedirects ?? DEFAULT_CLIENT_MAX_REDIRECTS;
     this.headMaxBytes = options.headMaxBytes ?? DEFAULT_HEAD_MAX_BYTES;
     this.logMaxBytes = options.logMaxBytes ?? DEFAULT_LOG_MAX_BYTES;
@@ -162,7 +173,7 @@ export class NodeClient {
       res.destroy();
       throw new NodeClientError(`node ${NODE_HEAD_PATH} responded HTTP ${res.status}`, res.status);
     }
-    const body = await readBoundedJson(res, this.headMaxBytes);
+    const body = await readBoundedJson(res, this.headMaxBytes, this.bodyTimeoutMs);
     const obj = (typeof body === 'object' && body !== null ? body : {}) as Record<string, unknown>;
     return {
       seq: typeof obj.seq === 'number' ? obj.seq : null,
@@ -188,7 +199,7 @@ export class NodeClient {
       res.destroy();
       throw new NodeClientError(`node ${NODE_LOG_PATH} responded HTTP ${res.status}`, res.status);
     }
-    const body = await readBoundedJson(res, this.logMaxBytes);
+    const body = await readBoundedJson(res, this.logMaxBytes, this.bodyTimeoutMs);
     const records = (body as { records?: unknown }).records;
     if (!Array.isArray(records)) {
       throw new NodeClientError(`node ${NODE_LOG_PATH} returned no records array`, res.status);
@@ -222,7 +233,7 @@ export class NodeClient {
         body: Buffer.from(JSON.stringify(envelope), 'utf8'),
       }),
     );
-    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
     if (res.status < 200 || res.status >= 300) {
       const reason = readError(body);
       throw new NodeClientError(
@@ -258,7 +269,7 @@ export class NodeClient {
         body: Buffer.from(JSON.stringify({ records: envelopes }), 'utf8'),
       }),
     );
-    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
     if (res.status < 200 || res.status >= 300) {
       const reason = readError(body);
       throw new NodeClientError(
@@ -293,7 +304,7 @@ export class NodeClient {
         res.status,
       );
     }
-    return readBoundedBytes(res, this.blobMaxBytes);
+    return readBoundedBytes(res, this.blobMaxBytes, this.blobBodyTimeoutMs);
   }
 
   /**
@@ -320,7 +331,7 @@ export class NodeClient {
         body: bytes,
       }),
     );
-    const body = await readBoundedJson(res, this.writeResponseMaxBytes);
+    const body = await readBoundedJson(res, this.writeResponseMaxBytes, this.bodyTimeoutMs);
     if (res.status < 200 || res.status >= 300) {
       const reason = readError(body);
       throw new NodeClientError(