fix: defer writeHead to prevent Content-Length truncation in payment rewriter (#161)

* fix: defer writeHead in payment response rewriter to prevent Content-Length truncation

@hono/node-server's responseViaCache sets Content-Length from the
original body size and calls writeHead before res.end. When the payment
response rewriter intercepts res.end and swaps in a larger rewritten
body (with full x402/mpp challenge data), the Content-Length already on
the wire reflects the original smaller body. The client reads only that
many bytes, truncating the JSON and causing a parse error.

Fix: defer writeHead until res.end fires, then update Content-Length to
match the (potentially rewritten) body before flushing both. For SSE
(res.write before res.end), the deferred writeHead flushes at the first
write call — no Content-Length conflict since SSE doesn't use the
responseViaCache path.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add writeHead deferral tests for JSON and SSE response paths

Tests installPaymentResponseRewriter by simulating @hono/node-server's
exact call patterns:
- JSON path: writeHead(status, {Content-Length}) then end(body)
- SSE path: writeHead(status, headers) then write(chunk)... then end()

Coverage:
- Content-Length updated to match rewritten body size
- Content-Length preserved when no rewrite occurs (no challenge, non-matching body)
- writeHead(status, statusMessage, headers) three-arg form
- end() without writeHead (implicit headers)
- Buffer body handling
- Hook restoration after end()
- SSE: writeHead flushed on first write, not duplicated
- SSE: payment error chunks rewritten, normal chunks unchanged
- SSE: only error chunk rewritten in multi-chunk stream
- Content-Length === actual body byte length invariant

Also exports installPaymentResponseRewriter for direct unit testing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: badjer

packages/atxp-express/src/atxpExpress.ts

@@ -165,9 +165,11 @@ export function atxpExpress(args: ATXPArgs): Router {
  * Old clients: see JSON-RPC error with code -30402 → Branch 1 matches
  * New clients: see JSON-RPC error with code -30402 + full error.data → x402/mpp works
  */
-function installPaymentResponseRewriter(res: Response, logger: import("@atxp/common").Logger): void {
+/** @internal Exported for testing only. */
+export function installPaymentResponseRewriter(res: Response, logger: import("@atxp/common").Logger): void {
   const origEnd = res.end;
   const origWrite = res.write;
+  const origWriteHead = res.writeHead;
 
   // Rewrite helper shared by both res.write and res.end hooks.
   // tryRewritePaymentResponse handles both SSE (data: lines) and plain JSON.
@@ -183,9 +185,30 @@ function installPaymentResponseRewriter(res: Response, logger: import("@atxp/com
     return tryRewritePaymentResponse(body, challenge, logger) ?? chunk;
   }
 
+  // Defer writeHead until res.end so we can update Content-Length after
+  // rewriting the body. @hono/node-server's responseViaCache sets
+  // Content-Length from the original (pre-rewrite) body size, then calls
+  // writeHead before end. Without deferring, the client receives the
+  // original Content-Length but the rewritten (larger) body, causing
+  // JSON truncation.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let deferredWriteHead: any[] | null = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  res.writeHead = function writeHeadDeferred(this: Response, ...args: any[]): any {
+    deferredWriteHead = args;
+    return this;
+  } as any;
+
+  function flushWriteHead(self: Response): void {
+    if (!deferredWriteHead) return;
+    (origWriteHead as any).apply(self, deferredWriteHead);
+    deferredWriteHead = null;
+  }
+
   // Hook res.write for SSE streaming responses.
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   res.write = function writeWithPaymentRewrite(this: Response, ...args: any[]): any {
+    flushWriteHead(this);
     args[0] = rewriteChunk(args[0]);
     return (origWrite as any).apply(this, args);
   } as any;
@@ -195,7 +218,31 @@ function installPaymentResponseRewriter(res: Response, logger: import("@atxp/com
   res.end = function endWithPaymentRewrite(this: Response, ...args: any[]): any {
     res.end = origEnd;
     res.write = origWrite;
+    res.writeHead = origWriteHead;
     args[0] = rewriteChunk(args[0]);
+
+    // Update Content-Length in deferred writeHead to match the rewritten body.
+    if (deferredWriteHead) {
+      const newBody = args[0];
+      if (newBody != null) {
+        const newLength = typeof newBody === 'string'
+          ? Buffer.byteLength(newBody)
+          : Buffer.isBuffer(newBody)
+            ? newBody.length
+            : undefined;
+        if (newLength !== undefined) {
+          // writeHead(statusCode, headers) or writeHead(statusCode, statusMessage, headers)
+          const headersIdx = typeof deferredWriteHead[1] === 'string' ? 2 : 1;
+          const headers = deferredWriteHead[headersIdx];
+          if (headers && typeof headers === 'object') {
+            headers['Content-Length'] = newLength;
+          }
+        }
+      }
+      (origWriteHead as any).apply(this, deferredWriteHead);
+      deferredWriteHead = null;
+    }
+
     return (origEnd as any).apply(this, args);
   } as any;
 }