fix(container): whitespace transport-resistance (issue #1)

A .pbf.json pasted into an email body / reflowed by a text transport could break
two ways, both now fixed + locked with tests:
- strict crc32_encoded rejected whitespace the glyph payload ignores -> compute it
  over the CANONICAL payload (data with [CR/LF/TAB/SPACE] stripped). Clean
  containers are byte-for-byte unchanged (backward-compatible); only transport-
  injected whitespace is tolerated.
- JSON forbids raw newlines inside strings (a hard line-wrap of the long data
  line) -> lenient parse: strip raw control whitespace and retry on parse failure.
  Applied to decodeFromContainer AND the decodeText router (web + Node CLI path).

Decode strips canonical whitespace before decoding (default decode does not ignore
it). Integrity intact: genuine non-whitespace corruption is still rejected (crc32
of the original bytes, post-decode). Adds 8 JS transport tests (A-G + router +
corruption-still-caught) and a transport-mangle case to the parameterized
test/test_container, so every executable inherits the guard.

Author: pmarreck

docs/plans/2026-06-26-printable-binary-file-container-design.md

@@ -181,3 +181,29 @@ Drop a file or paste below — auto-detects ENCODE vs DECODE.
 **Recommendation:** A — it makes decode unmistakable (directly answers the
 issue), and the metadata panel + container option are equally expressible in B.
 Awaiting Peter's pick before building index.html.
+
+## Transport resistance (whitespace) — added 2026-06-27
+The container must survive being pasted into email bodies / reflowed by text
+transports that inject whitespace. Empirically (test/js + test/test_container):
+- Whitespace BETWEEN JSON tokens (reindent, CRLF, trailing spaces) was always
+  fine — `JSON.parse` ignores it.
+- Whitespace landing INSIDE `data` originally broke decode two ways, both fixed:
+  1. **strict `crc32_encoded`** rejected any byte change, even whitespace the
+     glyph payload is indifferent to → **fix:** `crc32_encoded` is computed over
+     the *canonical* payload (data with `[\r\n\t ]` stripped). The default
+     encoding emits none of those, so clean containers' checksum is UNCHANGED
+     (backward-compatible); only transport-injected whitespace is tolerated.
+  2. **JSON forbids a raw newline inside a string** (a hard line-wrap of the long
+     `data` line) → **fix:** a lenient parse — on `JSON.parse` failure, strip raw
+     control whitespace (`[\r\n\t]`, never legitimate in our metadata strings or
+     the glyph payload) and retry.
+- Decode strips the canonical whitespace from `data` before `decode()` (default
+  decode does NOT ignore whitespace; that is opt-in `-S`). **Integrity is intact:
+  a genuine non-whitespace corruption is still rejected** (crc32 of the original
+  bytes, checked post-decode).
+
+**Required of EVERY impl** (the "all executables" goal): canonicalize the payload
+(`strip [\r\n\t ]`) for the `crc32_encoded` check + before decoding, and parse
+leniently (hand-rolled C/Lua parsers get this free by skipping whitespace while
+scanning `data`; strict parsers like JS `JSON.parse` / Zig `std.json` need the
+strip-and-retry fallback). `test/test_container` enforces this per impl.

js/printable_binary.js

@@ -676,12 +676,35 @@ class PrintableBinary {
    * @param {{filename?:string, modified_ms?:number, created_ms?:number, mode?:string, owner?:string, group?:string}} [meta]
    * @returns {object} the container
    */
+  /**
+   * Strip transport-injected whitespace from an encoded payload. The default
+   * encoding emits no literal spaces/tabs/CR/LF (all are glyph'd), so a clean
+   * payload is unchanged; this only removes whitespace a text transport (email
+   * wrap, reflow) added — making the container as whitespace-tolerant as raw
+   * printable-binary while keeping crc integrity intact for real corruption.
+   */
+  _canonicalPayload(data) {
+    return String(data).replace(/[\r\n\t ]/g, '');
+  }
+
+  /**
+   * JSON.parse with a transport-tolerant fallback: a hard line-wrap can inject a
+   * raw newline into the long `data` string, which JSON forbids unescaped inside
+   * a string literal. On a parse failure, strip raw control whitespace (never
+   * legitimate in our short metadata strings nor in the glyph payload) and retry.
+   */
+  _parseLenient(text) {
+    try { return JSON.parse(text); }
+    catch (_e) { return JSON.parse(String(text).replace(/[\r\n\t]/g, '')); }
+  }
+
+
   encodeToContainer(bytes, meta = {}) {
     if (!(bytes instanceof Uint8Array)) {
       throw new Error("encodeToContainer expects a Uint8Array");
     }
     const data = this.encode(bytes);
-    const dataBytes = sharedTextEncoder.encode(data);
+    const dataBytes = sharedTextEncoder.encode(this._canonicalPayload(data));
     const container = {
       format: "printable-binary-file",
       version: 1,
@@ -709,7 +732,7 @@ class PrintableBinary {
    * @returns {{ bytes: Uint8Array, meta: object }}
    */
   decodeFromContainer(input) {
-    const c = typeof input === "string" ? JSON.parse(input) : input;
+    const c = typeof input === "string" ? this._parseLenient(input) : input;
     if (!c || typeof c !== "object") {
       throw new Error("Container must be a JSON object or JSON string");
     }
@@ -719,13 +742,14 @@ class PrintableBinary {
     if (typeof c.data !== "string") {
       throw new Error("Container 'data' must be a string");
     }
+    const cleanData = this._canonicalPayload(c.data);
     if (c.crc32_encoded !== undefined && c.crc32_encoded !== null) {
-      const got = this.crc32hex(sharedTextEncoder.encode(c.data));
+      const got = this.crc32hex(sharedTextEncoder.encode(cleanData));
       if (got !== String(c.crc32_encoded).toLowerCase()) {
         throw new Error(`Container crc32_encoded mismatch (got ${got}, expected ${c.crc32_encoded}) — 'data' is corrupted`);
       }
     }
-    const bytes = this.decode(c.data);
+    const bytes = this.decode(cleanData);
     if (c.byte_length !== undefined && c.byte_length !== null && bytes.length !== c.byte_length) {
       throw new Error(`Container byte_length mismatch (decoded ${bytes.length}, expected ${c.byte_length})`);
     }
@@ -756,7 +780,7 @@ class PrintableBinary {
     const trimmed = String(text).trim();
     if (trimmed.startsWith('{')) {
       let parsed = null;
-      try { parsed = JSON.parse(trimmed); } catch (_e) { parsed = null; }
+      try { parsed = this._parseLenient(trimmed); } catch (_e) { parsed = null; }
       if (parsed && parsed.format === 'printable-binary-file') {
         const { bytes, meta } = this.decodeFromContainer(parsed);
         return { bytes, filename: meta.filename || 'decoded.bin', meta, kind: 'container' };

test/js/test_printable_binary.js

@@ -374,6 +374,38 @@ console.log('\n--- decodeText (decode-mode router) Tests ---');
   assert(threw, "decodeText: corrupt container is rejected");
 }
 
+// --- Container transport-resistance (whitespace) Tests, issue #1 ---
+console.log('\n--- Container transport-resistance (whitespace) Tests ---');
+{
+  const bytes = new Uint8Array([0,1,2,9,10,13,32,65,66,67,0x7b,34,92,128,200,255]);
+  const container = encoder.encodeToContainer(bytes, { filename: "t.bin", modified_ms: 123 });
+  const json = JSON.stringify(container, null, 2);
+  const eq = (a) => Array.from(a).length === bytes.length && Array.from(a).every((b,i)=>b===bytes[i]);
+  const insertEvery = (s,n,sep)=>Array.from(s).map((ch,i)=>(i>0&&i%n===0)?sep+ch:ch).join('');
+  const decOk = (label, text) => {
+    try { const {bytes:out}=encoder.decodeFromContainer(text); assert(eq(out), label); }
+    catch(e){ assert(false, label + ' (threw: ' + e.message.slice(0,45) + ')'); }
+  };
+
+  decOk("transport A: reindented JSON structure", json.replace(/\n/g,'\n   ').replace(/: /g,'  :  '));
+  decOk("transport B: CRLF line endings", json.replace(/\n/g,'\r\n'));
+  decOk("transport C: trailing spaces per line", json.split('\n').map(l=>l+'   ').join('\n'));
+  { const c=JSON.parse(json); c.data=insertEvery(c.data,4,' ');  decOk("transport D: spaces inside data (escaped)", JSON.stringify(c)); }
+  { const c=JSON.parse(json); c.data=insertEvery(c.data,8,'\n'); decOk("transport E: newlines inside data (escaped)", JSON.stringify(c)); }
+  decOk("transport F: raw spaces injected into data", json.replace(/("data": ".{8})/, '$1   '));
+  decOk("transport G: raw newline wrapped into data", json.replace(/("data": ".{8})/, '$1\n'));
+
+  // the decode-mode router (web UI + Node CLI path) must be transport-resistant too
+  { const m = json.replace(/("data": ")/, "$1\n   "); const r = encoder.decodeText(m);
+    assert(r.kind === "container" && eq(r.bytes), "transport: decodeText routes a mangled container (not misread as raw)"); }
+
+  // integrity preserved: a GENUINE (non-whitespace) corruption must STILL be rejected
+  let threw=false;
+  try { const c=JSON.parse(json); c.data=c.data.slice(0,-3)+'AzQ'; encoder.decodeFromContainer(JSON.stringify(c)); }
+  catch(_e){ threw=true; }
+  assert(threw, "transport: genuine (non-whitespace) corruption still rejected");
+}
+
 console.log('Test Summary:');
 console.log(`Total tests: ${testCount}`);
 console.log(`Passed: ${passCount}`);

test/test_container

@@ -34,5 +34,11 @@ if cmp -s "$TMP/orig.bin" "$TMP/restored.bin"; then ok "round-trip bytes identic
 sed 's/\("data": *"\)/\1ZZZ/' "$TMP/orig.pbf.json" > "$TMP/corrupt.pbf.json"
 if "$IMPL" -d -C "$TMP/corrupt.pbf.json" > /dev/null 2>&1; then bad "corrupt container rejected (nonzero exit)"; else ok "corrupt container rejected (nonzero exit)"; fi
 
+# 6. transport resistance: inject a raw newline + spaces INTO the data value (as an
+# email wrap/reflow would). The glyph payload is whitespace-agnostic, so decode must
+# still recover the original bytes (canonicalize + lenient JSON parse).
+awk '{ sub(/"data": "/, "&\n   ") } 1' "$TMP/orig.pbf.json" > "$TMP/wrapped.pbf.json"
+if "$IMPL" -d -C "$TMP/wrapped.pbf.json" > "$TMP/restored2.bin" 2>/dev/null && cmp -s "$TMP/orig.bin" "$TMP/restored2.bin"; then ok "transport-mangled container still decodes (whitespace-resistant)"; else bad "transport-mangled container still decodes (whitespace-resistant)"; fi
+
 echo "container CLI test [$IMPL]: $pass passed, $fail failed"
 [ "$fail" -eq 0 ]