kinetex 1.4.0 → 1.5.0

package/dist/cjs/response.js

@@ -296,6 +296,37 @@ function readWithAbort(reader, signal) {
 function normaliseOnExceed(mode) {
     return mode === "truncate" || mode === "abort" ? mode : "throw";
 }
+/**
+ * The single size-limit policy, shared by the buffering reader and the
+ * streaming one.
+ *
+ * Both had the same four decisions — when to fire `onExceedCallback`, when to
+ * throw, how much of the crossing chunk to keep, when to stop — written out
+ * twice. They drifted: the streaming version cancelled with `"size limit"` where
+ * the buffered one used `"size limit exceeded"`, which is the kind of difference
+ * that only matters in a log nobody diffs.
+ *
+ * `makeError` is supplied by the caller because the two entry points raise
+ * different public classes (`ResponseSizeLimitError` here,
+ * `SizeLimitError` from `types.ts` via `core.ts`). Both carry the code
+ * `"ESIZELIMIT"`, but they are different classes with different prototypes and
+ * collapsing them is a breaking change, so each keeps its own.
+ */
+export function limitAction(chunk, bytesRead, limit, onExceed, makeError) {
+    const newTotal = bytesRead + chunk.byteLength;
+    if (newTotal <= limit.maxBytes)
+        return { kind: "keep" };
+    limit.onExceedCallback?.(newTotal, limit.maxBytes);
+    if (onExceed === "throw")
+        throw makeError(newTotal, limit.maxBytes);
+    if (onExceed === "truncate") {
+        const remaining = limit.maxBytes - bytesRead;
+        // `remaining > 0` always holds here: `newTotal > maxBytes` with a
+        // non-negative chunk length implies `bytesRead < maxBytes`.
+        return { kind: "truncate", chunk: chunk.slice(0, remaining) };
+    }
+    return { kind: "stop" };
+}
 /**
  * Read a ReadableStream with a hard size limit.
  *
@@ -328,31 +359,35 @@ export async function readBodyWithLimit(stream, url, limit, signal) {
                 }
                 break;
             }
-            const newTotal = bytesRead + value.byteLength;
-            if (newTotal > limit.maxBytes) {
-                limit.onExceedCallback?.(newTotal, limit.maxBytes);
-                if (onExceed === "throw") {
-                    await reader.cancel("size limit exceeded");
-                    throw new ResponseSizeLimitError(newTotal, limit.maxBytes, url);
-                }
-                if (onExceed === "abort") {
-                    await reader.cancel("size limit exceeded");
-                    break;
-                }
-                if (onExceed === "truncate") {
-                    const remaining = limit.maxBytes - bytesRead;
-                    if (remaining > 0) {
-                        chunks.push(value.slice(0, remaining));
-                        bytesRead += remaining;
-                    }
-                    break;
-                }
+            let action;
+            try {
+                action = limitAction(value, bytesRead, limit, onExceed, (n, max) => new ResponseSizeLimitError(n, max, url));
+            }
+            catch (err) {
+                await reader.cancel("size limit exceeded");
+                throw err;
+            }
+            if (action.kind === "stop") {
+                await reader.cancel("size limit exceeded");
+                break;
+            }
+            if (action.kind === "truncate") {
+                chunks.push(action.chunk);
+                bytesRead += action.chunk.byteLength;
+                break;
             }
             chunks.push(value);
             bytesRead += value.byteLength;
         }
     }
     finally {
+        // Cancel before releasing when bailing out, so the unread remainder of the
+        // body is discarded rather than left buffered on a released lock. The loop
+        // already cancels on every abort it observes; this covers the race where the
+        // signal fired between the last read and the loop exiting.
+        if (signal?.aborted) {
+            await reader.cancel("aborted").catch(() => { });
+        }
         reader.releaseLock();
     }
     return concatUint8Arrays(chunks);
@@ -413,6 +448,13 @@ function detectBOM(bytes) {
  * @returns The decoded string.
  * @throws {ResponseDecodeError} If decoding fails even with lenient fallback.
  */
+/**
+ * Decode a response body to a string.
+ *
+ * `url` is optional: it is only used to name the originating URL on a
+ * `ResponseDecodeError`, and requiring every caller to thread one through just
+ * to decode a body it already has in hand made the third parameter a formality.
+ */
 export function decodeBody(bytes, charset, url) {
     const detected = detectBOM(bytes);
     const resolved = detected ?? resolveCharset(charset);
@@ -427,7 +469,7 @@ export function decodeBody(bytes, charset, url) {
             return new TextDecoder(resolved, { fatal: false }).decode(data);
         }
         catch (err2) {
-            throw new ResponseDecodeError(String(err2), resolved, url);
+            throw new ResponseDecodeError(String(err2), resolved, url ?? "<unknown url>");
         }
     }
 }
@@ -464,6 +506,13 @@ function createSizeLimitedDecompression(stream, encoding, maxDecompressedSize =
  */
 export function decompressStream(stream, encoding) {
     const normalized = encoding.trim().toLowerCase();
+    // An empty body carrying a Content-Encoding is an ordinary response — an
+    // empty 204, an empty error body — and every decoder here rejects it,
+    // `DecompressionStream("gzip")` and node:zlib alike, with `Z_BUF_ERROR:
+    // unexpected end of file` because there is no frame to parse. Without this
+    // check the client turned a normal empty reply into an exception. zstd
+    // happened to tolerate it on Node 22, which made the defect look
+    // runtime-specific when it was encoding-independent and had always been there.
     // ── Brotli (br) ──────────────────────────────────────────────────────────
     // WHATWG DecompressionStream does NOT support brotli in any current runtime.
     // On Node.js we use node:zlib.createBrotliDecompress() via a stream adapter.
@@ -488,17 +537,100 @@ export function decompressStream(stream, encoding) {
         // CompressionFormat is a browser type, we normalize to it
         // Type assertion is safe as we validated the encoding above
         const format = normalized;
-        const ds = new DecompressionStream(format);
-        // DecompressionStream and TransformStream have compatible pipeThrough signatures
-        // in all modern runtimes, but TypeScript doesn't recognize this type compatibility
-        // Type assertion is safe here as we've validated the format above
-        return stream.pipeThrough(ds);
+        // Constructed here, inside this `try`, so an unrecognised format still
+        // throws synchronously and falls through to the pass-through below. Built
+        // lazily inside the stream it would throw from `start()`, where nothing
+        // catches it, and an unknown encoding would surface as an unhandled
+        // TypeError instead of the raw bytes.
+        const decoder = new DecompressionStream(format);
+        return decodeUnlessEmpty(stream, decoder);
     }
     catch {
         // Unsupported format — return raw (caller sent Accept-Encoding conservatively)
         return stream;
     }
 }
+/**
+ * Decodes `source`, or yields nothing at all when `source` is empty.
+ *
+ * `DecompressionStream("gzip")` rejects a zero-byte stream with the same
+ * `Z_BUF_ERROR: unexpected end of file` the node:zlib decoders raise, because
+ * there is no frame to parse. An empty body carrying `Content-Encoding` is an
+ * ordinary response — an empty 204, an empty error body — so it must produce
+ * nothing rather than fail. zstd happened to tolerate this on Node 22, which
+ * made the defect look runtime-specific when it was encoding-independent.
+ *
+ * The decoder is constructed on the first non-empty chunk rather than up front,
+ * because that is the only point at which emptiness is known and this has to
+ * stay synchronous. Only the chunk that was already in flight is held, so a
+ * streaming body still streams.
+ */
+function decodeUnlessEmpty(source, decoder) {
+    const reader = source.getReader();
+    return new ReadableStream({
+        async start(controller) {
+            // A source may hand over zero-length chunks before its real payload, or
+            // instead of one — counting the chunk rather than its bytes would send an
+            // empty body to the decoder and get `Z_BUF_ERROR` back. So: read until
+            // something with bytes arrives, or the source ends.
+            let first = null;
+            for (;;) {
+                const next = await reader
+                    .read()
+                    .catch(() => ({ done: true, value: undefined }));
+                if (next.done || next.value.byteLength > 0) {
+                    first = next;
+                    break;
+                }
+            }
+            if (first.done) {
+                // Nothing to decode: an empty body carrying a Content-Encoding is an
+                // ordinary response, not a malformed one.
+                controller.close();
+                return;
+            }
+            // Re-hydrate the peeked chunk in front of the rest of the source, then
+            // let `pipeThrough` do the piping. Doing the write/read interleaving by
+            // hand deadlocked on backpressure: a TransformStream's `write()` does not
+            // settle until its readable queue drains, and nothing was reading yet.
+            const rehydrated = new ReadableStream({
+                start(c) {
+                    c.enqueue(first.value);
+                },
+                async pull(c) {
+                    const next = await reader.read();
+                    if (next.done)
+                        c.close();
+                    else
+                        c.enqueue(next.value);
+                },
+                cancel(reason) {
+                    void reader.cancel(reason).catch(() => undefined);
+                },
+            });
+            const out = rehydrated.pipeThrough(decoder);
+            const pump = out.getReader();
+            void (async () => {
+                try {
+                    for (;;) {
+                        const chunk = await pump.read();
+                        if (chunk.done) {
+                            controller.close();
+                            return;
+                        }
+                        controller.enqueue(chunk.value);
+                    }
+                }
+                catch (err) {
+                    controller.error(err);
+                }
+            })();
+        },
+        cancel(reason) {
+            void reader.cancel(reason).catch(() => undefined);
+        },
+    });
+}
 /**
  * Decompress a brotli-encoded ReadableStream.
  * Uses node:zlib on Node.js. Returns the stream unchanged on other runtimes.
@@ -554,6 +686,14 @@ function nodeZlibDecompressStream(stream, create) {
     // can land in that window — an immediately-aborted request is the common
     // case, not an edge one. Remember it and apply it once the reader exists.
     let cancelRequested = false;
+    // A zero-byte source is a legitimate response — an empty 204, an empty error
+    // body — and it carries a Content-Encoding header like any other. Every
+    // zlib decoder rejects it (`Z_BUF_ERROR: unexpected end of file`), so
+    // without this the client turned an ordinary empty reply into an exception.
+    // zstd happened to tolerate it on Node 22 only, which is why this went
+    // unnoticed: the failure looked runtime-specific and was actually encoding-
+    // independent, and had been there for gzip, deflate and br the whole time.
+    let sawBytes = false;
     return new ReadableStream({
         async start(controller) {
             // Dynamic import so non-Node runtimes never load node:zlib
@@ -589,9 +729,24 @@ function nodeZlibDecompressStream(stream, create) {
                 while (true) {
                     const { done, value } = await reader.read();
                     if (done) {
+                        // Nothing was ever fed to the decoder, so there is no frame to
+                        // parse and nothing to fail on. Close with what we have: nothing.
+                        if (!sawBytes) {
+                            if (!settled) {
+                                settled = true;
+                                controller.close();
+                            }
+                            br.destroy();
+                            break;
+                        }
                         br.end();
                         break;
                     }
+                    // Count bytes, not chunks: a source may hand over a zero-length
+                    // chunk and then close, which is still an empty body. Counting the
+                    // chunk instead let exactly that case reach the decoder and fail.
+                    if (value.byteLength > 0)
+                        sawBytes = true;
                     br.write(value);
                 }
             }
@@ -1334,9 +1489,9 @@ export function extractServerTiming(headers) {
 // ============================================================================
 // §14  UTILITIES
 // ============================================================================
-async function readBodyBytes(response, url, options) {
+function readBodyBytes(response, url, options) {
     if (!response.body)
-        return new Uint8Array(0);
+        return Promise.resolve(new Uint8Array(0));
     const headers = normalizeHeaders(response.headers);
     let stream = response.body;
     // Decompression
@@ -1350,33 +1505,11 @@ async function readBodyBytes(response, url, options) {
     if (options.sizeLimit) {
         return readBodyWithLimit(stream, url, options.sizeLimit, options.signal);
     }
-    const reader = stream.getReader();
-    const chunks = [];
-    try {
-        while (true) {
-            if (options.signal?.aborted) {
-                throw new DOMException("Response reading aborted", "AbortError");
-            }
-            const { done, value } = await readWithAbort(reader, options.signal);
-            if (done) {
-                // See readWithAbort: an aborted read also resolves as done.
-                if (options.signal?.aborted) {
-                    throw new DOMException("Response reading aborted", "AbortError");
-                }
-                break;
-            }
-            chunks.push(value);
-        }
-    }
-    finally {
-        // Cancel before releasing when we are bailing out, so the unread remainder
-        // of the body is discarded rather than left buffered on a released lock.
-        if (options.signal?.aborted) {
-            await reader.cancel("aborted").catch(() => { });
-        }
-        reader.releaseLock();
-    }
-    return concatUint8Arrays(chunks);
+    // No configured limit is the same read with an unreachable one. `newTotal`
+    // can never exceed `Infinity`, so the limit policy never engages and
+    // `onExceedCallback` never fires — which is exactly the previous behaviour,
+    // minus a second copy of the read loop to keep in step with the first.
+    return readBodyWithLimit(stream, url, { maxBytes: Infinity }, options.signal);
 }
 function applySizeLimit(stream, url, limit, signal) {
     const onExceed = normaliseOnExceed(limit.onExceed);
@@ -1403,27 +1536,21 @@ function applySizeLimit(stream, url, limit, signal) {
                         controller.close();
                         break;
                     }
-                    const newTotal = bytesRead + value.byteLength;
-                    if (newTotal > limit.maxBytes) {
-                        limit.onExceedCallback?.(newTotal, limit.maxBytes);
-                        if (onExceed === "throw") {
-                            await reader.cancel("size limit");
-                            controller.error(new ResponseSizeLimitError(newTotal, limit.maxBytes, url));
-                            return;
-                        }
-                        if (onExceed === "abort") {
-                            await reader.cancel("size limit");
-                            controller.close();
-                            return;
-                        }
-                        if (onExceed === "truncate") {
-                            const remaining = limit.maxBytes - bytesRead;
-                            if (remaining > 0)
-                                controller.enqueue(value.slice(0, remaining));
-                            controller.close();
-                            await reader.cancel("size limit");
-                            return;
-                        }
+                    let action;
+                    try {
+                        action = limitAction(value, bytesRead, limit, onExceed, (n, max) => new ResponseSizeLimitError(n, max, url));
+                    }
+                    catch (err) {
+                        await reader.cancel("size limit exceeded");
+                        controller.error(err);
+                        return;
+                    }
+                    if (action.kind !== "keep") {
+                        if (action.kind === "truncate")
+                            controller.enqueue(action.chunk);
+                        controller.close();
+                        await reader.cancel("size limit exceeded");
+                        return;
                     }
                     bytesRead += value.byteLength;
                     controller.enqueue(value);

package/dist/cjs/socks5.js

@@ -397,6 +397,11 @@ async function withRetry(fn, maxRetries, delayMs) {
     }
     throw lastError;
 }
+// Deliberately kept local. This module has no imports at all, so it can be
+// loaded on its own in restricted runtimes where a relative import of
+// `utils.ts` would pull the whole package graph in with it. `sleep(ms)` with
+// no signal is the one shape that cannot diverge from the shared copy — it
+// resolves after `ms` and attaches nothing.
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }

package/dist/cjs/utils.js

@@ -668,7 +668,7 @@ function isBlockedIPv6(b) {
  * @param allowedSchemes - Allowed URL schemes
  * @returns True if URL is safe
  */
-export function isSafeURL(url, allowedSchemes = ["http", "https"]) {
+export function isSafeURL(url, allowedSchemes = ["http", "https"], options = {}) {
     try {
         const parsed = typeof url === "string" ? new URL(url) : url;
         const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
@@ -680,25 +680,31 @@ export function isSafeURL(url, allowedSchemes = ["http", "https"]) {
         if (FORBIDDEN_SCHEMES.has(scheme)) {
             return false;
         }
-        let host = parsed.hostname.toLowerCase();
-        const isV6Literal = host.startsWith("[") && host.endsWith("]");
-        if (isV6Literal)
-            host = host.slice(1, -1);
-        // Block loopback hostnames (including *.localhost subdomains)
-        if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0")
-            return false;
-        // Block private/reserved IPs (SSRF prevention) — numeric comparison over
-        // expanded bytes so every IPv6 spelling and numeric IPv4 form is covered.
-        if (isV6Literal || host.includes(":")) {
-            const v6 = parseIPv6Host(host);
-            // Unparseable IPv6 literal → reject defensively
-            if (v6 === null || isBlockedIPv6(v6))
-                return false;
-        }
-        else {
-            const v4 = parseIPv4Host(host);
-            if (v4 !== null && isBlockedIPv4(v4))
+        // `allowPrivateNetwork` relaxes *only* the address checks below. Scheme,
+        // path traversal, hostname length, URL length and port validation are not
+        // about where the socket lands, so they still apply — otherwise opting in to
+        // a loopback fixture would also silently opt in to `file:` and `../`.
+        if (!options.allowPrivateNetwork) {
+            let host = parsed.hostname.toLowerCase();
+            const isV6Literal = host.startsWith("[") && host.endsWith("]");
+            if (isV6Literal)
+                host = host.slice(1, -1);
+            // Block loopback hostnames (including *.localhost subdomains)
+            if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0")
                 return false;
+            // Block private/reserved IPs (SSRF prevention) — numeric comparison over
+            // expanded bytes so every IPv6 spelling and numeric IPv4 form is covered.
+            if (isV6Literal || host.includes(":")) {
+                const v6 = parseIPv6Host(host);
+                // Unparseable IPv6 literal → reject defensively
+                if (v6 === null || isBlockedIPv6(v6))
+                    return false;
+            }
+            else {
+                const v4 = parseIPv4Host(host);
+                if (v4 !== null && isBlockedIPv4(v4))
+                    return false;
+            }
         }
         // Check for suspicious patterns (path traversal)
         if (parsed.hostname.includes("..") || parsed.pathname.includes("..")) {
@@ -723,6 +729,35 @@ export function isSafeURL(url, allowedSchemes = ["http", "https"]) {
         return false;
     }
 }
+/**
+ * True when a literal IPv4/IPv6 address falls in a blocked range.
+ *
+ * The same decision `isSafeURL` makes about a hostname, applied to an address
+ * that has already been resolved. Kept separate from `isSafeURL` because the two
+ * answer different questions: `isSafeURL` reads what the caller wrote, this
+ * reads what the resolver returned. Both are needed — see
+ * `createPinnedLookup` in `core.ts`, which is the only thing that stops a
+ * hostname that resolves to a private address from being dialled.
+ *
+ * IPv4 literals are accepted in every form a resolver can return (dotted-quad
+ * and numeric); anything unparseable is treated as blocked, so an address this
+ * cannot understand fails closed rather than open.
+ */
+export function isBlockedAddress(address) {
+    const host = address.trim().toLowerCase();
+    if (host.startsWith("[") && host.endsWith("]"))
+        return true;
+    if (host === "" || host === "localhost" || host.endsWith(".localhost"))
+        return true;
+    if (host.includes(":")) {
+        const v6 = parseIPv6Host(host);
+        return v6 === null || isBlockedIPv6(v6);
+    }
+    // A resolver returns dotted-quad, but `parseIPv4Host` also accepts the
+    // numeric spellings, and a non-IP string must not be read as "safe".
+    const v4 = parseIPv4Host(host);
+    return v4 === null || isBlockedIPv4(v4);
+}
 /**
  * Check if a URL is absolute (has a scheme).
  *
@@ -868,7 +903,7 @@ export function formatError(error) {
  * another, so the function whose entire job is to turn an error into a string
  * threw instead, taking the `catch` that was logging it down with it.
  */
-function safeStringify(value) {
+export function safeStringify(value, circularMarker = "[Circular]") {
     const seen = new Set();
     try {
         return (JSON.stringify(value, (_key, v) => {
@@ -876,7 +911,7 @@ function safeStringify(value) {
                 return v.toString();
             if (typeof v === "object" && v !== null) {
                 if (seen.has(v))
-                    return "[Circular]";
+                    return circularMarker;
                 seen.add(v);
             }
             return v;
@@ -946,12 +981,12 @@ export function perfNow() {
  */
 export function sleep(ms, signal) {
     if (signal?.aborted) {
-        return Promise.reject(_abortError());
+        return Promise.reject(abortError());
     }
     return new Promise((resolve, reject) => {
         const onAbort = () => {
             clearTimeout(timer);
-            reject(_abortError());
+            reject(abortError());
         };
         const timer = setTimeout(() => {
             signal?.removeEventListener("abort", onAbort); // cleanup on normal completion
@@ -1017,6 +1052,50 @@ export function toUint8Array(data) {
  * @param bytes The buffer to encode.
  * @returns Base64-encoded string.
  */
+/**
+ * SHA-256 of a string or byte array, as lowercase hex.
+ *
+ * The `ArrayBuffer` slice is not optional. `crypto.subtle.digest` takes an
+ * `ArrayBuffer`, and a `Uint8Array`'s `.buffer` is the whole backing store —
+ * pass it directly and a view that starts partway into a larger buffer gets
+ * hashed from offset zero, hashing the wrong bytes. Three copies of this
+ * function existed and one of them made exactly that mistake.
+ */
+/**
+ * Copy `headers`, replacing the value of any name in `sensitive` with `mask`.
+ *
+ * The comparison is case-insensitive because HTTP header names are, and the
+ * caller's set is folded once here rather than at each call site — which is
+ * what `noUncheckedIndexedAccess` makes expensive elsewhere, where every
+ * consumer ends up writing `headers["x"] ?? headers["X"]` to find a header that
+ * was only ever stored under one spelling.
+ *
+ * `mask` is a parameter rather than a constant because four call sites already
+ * disagreed on it: the logger and the lifecycle hooks wrote `"***"`, the
+ * logging interceptor wrote `"**REDACTED**"`, and the HAR recorder wrote
+ * `"***REDACTED***"`. Those strings are observable in log output, so unifying
+ * them is a behaviour change and is deliberately not made here — but they are
+ * now in one function, so a future decision to converge is a one-line edit.
+ */
+/** True when `name` is one of `sensitive`, compared case-insensitively. */
+export function isSensitiveHeader(name, sensitive) {
+    return sensitive.has(name.toLowerCase());
+}
+export function redactHeaders(headers, sensitive, mask) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        out[k] = isSensitiveHeader(k, sensitive) ? mask : v;
+    }
+    return out;
+}
+export async function sha256Hex(data) {
+    const raw = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const buf = raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength);
+    const hash = await crypto.subtle.digest("SHA-256", buf);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
 export function uint8ArrayToBase64(bytes) {
     // Process in 3-byte (24-bit) aligned chunks to avoid padding issues mid-stream.
     // 3 × 2¹³ = 24 576 bytes per chunk — keeps individual strings small.
@@ -1094,7 +1173,7 @@ export function mergeSignals(...signals) {
     const abort = () => {
         for (const s of validSignals)
             s.removeEventListener("abort", abort);
-        controller.abort(_abortError());
+        controller.abort(abortError());
     };
     for (const s of validSignals)
         s.addEventListener("abort", abort, { once: true });
@@ -1149,11 +1228,20 @@ export function randomBytes(byteCount) {
         .join("");
 }
 // Cross-runtime error creation: DOMException may not exist in all runtimes.
-function _abortError() {
+/**
+ * A platform-shaped abort rejection: a `DOMException` named `AbortError` where
+ * one exists, and a plain `Error` carrying the same name where it does not.
+ *
+ * `message` is a parameter because two callers need different text for the same
+ * event, and they had each written this function. It is deliberately not
+ * `AbortError` from `types.ts`: that is a `KinetexError` with code `EABORT`, a
+ * different and equally deliberate contract used by the request pipeline.
+ */
+export function abortError(message = "Aborted") {
     if (typeof DOMException !== "undefined") {
-        return new DOMException("Aborted", "AbortError");
+        return new DOMException(message, "AbortError");
     }
-    const err = new Error("Aborted");
+    const err = new Error(message);
     err.name = "AbortError";
     return err;
 }

package/dist/cjs/ws.js

@@ -19,11 +19,40 @@
  */
 // FIX (H6): remote WS payloads are untrusted — parsed JSON dispatched to
 // listeners is stripped of prototype-pollution keys (see sanitizeParsedJSON).
-import { sanitizeParsedJSON } from "./utils.js";
+import { sanitizeParsedJSON, isValidHeaderName, isValidHeaderValue } from "./utils.js";
 // ============================================================================
 // §2  ERRORS
 // ============================================================================
 /** WebSocket connection or protocol error. */
+/**
+ * Reject a handshake header that cannot be represented as one.
+ *
+ * `client.ws()` builds an `authorization` header straight from the configured
+ * bearer token or API key and hands it to a `WSClient`, and `WSClient` applies
+ * it through the runtime's `setHeader` — with no validation anywhere on that
+ * path. The HTTP pipeline does validate: `mergeHeaders` runs
+ * `isValidHeaderName` / `isValidHeaderValue` and refuses control characters. A
+ * WebSocket configured through `client.ws()` therefore skipped the one check
+ * that stops a token containing `\r\n` from splitting into a second header on
+ * the handshake.
+ *
+ * Checked in the constructor rather than at connect time so the error names the
+ * configuration that is wrong, and so it cannot be reached by adding a header
+ * later — `_headers` is assigned once and never mutated.
+ */
+function validateHandshakeHeaders(headers) {
+    if (!headers)
+        return;
+    for (const [name, value] of Object.entries(headers)) {
+        if (!isValidHeaderName(name)) {
+            throw new WSError(`Invalid WebSocket handshake header name: ${JSON.stringify(name)}`);
+        }
+        if (!isValidHeaderValue(value)) {
+            throw new WSError(`Invalid value for WebSocket handshake header ${JSON.stringify(name)}: ` +
+                "must be a string of printable characters with no control characters");
+        }
+    }
+}
 export class WSError extends Error {
     /** Machine-readable error code for WebSocket errors. */
     code = "EWSCONNECT";
@@ -191,6 +220,7 @@ export class WSClient {
         this._url = cfg.url;
         this._protocols = cfg.protocols;
         this._headers = cfg.headers;
+        validateHandshakeHeaders(cfg.headers);
         this._maxReconnects = cfg.maxReconnects ?? 10;
         this._reconnectBaseMs = cfg.reconnectBaseMs ?? 1_000;
         this._reconnectMaxMs = cfg.reconnectMaxMs ?? 30_000;
@@ -990,7 +1020,18 @@ export class WSClient {
     }
     /** Buffer an outgoing message and track bytes for backpressure. */
     _bufferMessage(data, byteLen) {
-        if (this._bufferMessages && !this._aborted) {
+        if (!this._bufferMessages) {
+            // With buffering switched off, a send made while the socket is not OPEN
+            // had nowhere to go: the buffer branch was skipped and nothing was sent.
+            // `send()` returns void, so there was no return value to inspect either
+            // — the message vanished with no error and no callback, which is data
+            // loss the application cannot distinguish from a delivered message.
+            if (!this._aborted) {
+                this._cbError?.(new WSError(`WebSocket message dropped: the socket is not open and bufferMessages is disabled (${byteLen} bytes). Reconnect, or enable bufferMessages to queue sends made while reconnecting.`));
+            }
+            return;
+        }
+        if (!this._aborted) {
             const evicted = this._buffer.length >= this._maxBufferSize ? this._buffer.shift() : undefined;
             if (evicted !== undefined) {
                 this._bufferedBytes -=