quadqr-js 1.0.2 → 1.3.0

package/SPECIFICATION.md

@@ -0,0 +1,337 @@
+# QuadQR Technical Specification
+
+## Status
+
+QuadQR is an experimental RGBW matrix symbology. Normal mode uses 4-state RGBW cells, while the optional **High Density Mode** is experimental and uses the 16-state Triangle16 physical layout. It is not ISO/IEC QR Code and is not intended to be decoded by standard QR readers.
+
+The physical matrix format remains **QuadQR Format v5**. Normal application data is always treated simply as UTF-8 text or arbitrary bytes. Compression, signatures, encryption, rendering, and diagnostics are optional features layered around that stable matrix codec.
+
+For exact matrix geometry and Reed-Solomon framing, see [`FORMAT.md`](./FORMAT.md).
+
+## 1. Layer model
+
+```text
+Application bytes / UTF-8 text
+        │
+        ├─ optional compression metadata (internal)
+        ├─ optional Ed25519 signature metadata (internal)
+        ├─ optional Secure Payload v1 (AES-256-GCM)
+        │
+        └─ QuadQR Format v5
+             ├─ protected header
+             ├─ CRC-32
+             ├─ GF(256) Reed-Solomon Spectrum ECC
+             ├─ spectral-spatial interleaving
+             └─ normal RGBW or High Density Triangle16 matrix
+```
+
+There is deliberately **no public payload-type registry**. Applications do not select URL, JSON, contact, Wi-Fi, or other semantic types. They encode text or bytes and interpret that data themselves.
+
+## 2. Physical cell alphabet
+
+Data modules use exactly four states:
+
+| State | Bits | Internal value |
+|---|---|---:|
+| Red | `00` | 0 |
+| Green | `01` | 1 |
+| Blue | `10` | 2 |
+| White | `11` | 3 |
+
+Structural black is separate from the data alphabet. One encoded byte maps to exactly four RGBW data cells.
+
+### High Density Mode
+
+When `highDensity: true` is selected, each payload module has a fixed `/` diagonal and two independently classified RGBW regions. This creates 16 states and 4 raw bits per body cell. The protected header stays solid-color at 2 bits per cell for robust bootstrap recovery, then header flag bit 6 tells the decoder that the ECC/body stream uses Triangle16 packing. Scanner sampling uses two points well inside the triangles and excludes the diagonal boundary.
+
+## 3. Matrix sizing
+
+```text
+size = 21 + 4 × (version - 1)
+version = 1..40
+```
+
+Three 7×7 finder patterns are always present. Version 1 has the legacy QuadQR 5×5 bottom-right alignment marker. Versions 2–40 use the distributed alignment schedule defined in `FORMAT.md`.
+
+## 4. Format v5 header flags
+
+The protected Format v5 header uses:
+
+```text
+bit 0      UTF-8 text flag
+bits 1..2  ECC profile id
+bit 3      Secure Payload v1 envelope
+bit 4      internal payload-extension metadata present
+bit 5      signed-payload hint
+bit 6      High Density Mode flag
+bit 7      reserved
+```
+
+Bit 4 is an implementation/interoperability hint used only when compression or signing requires metadata. It is not a user-selectable payload mode.
+
+## 5. Spectrum ECC
+
+The field remains:
+
+```text
+GF(2^8) = GF(256)
+primitive polynomial = 0x11d
+```
+
+Version 2+ parity profiles:
+
+| Profile | Parity bytes/block | Correctable unknown byte errors/block |
+|---|---:|---:|
+| L | 12 | 6 |
+| M | 24 | 12 |
+| Q | 36 | 18 |
+| H | 48 | 24 |
+
+The decoder retains per-cell color confidence. Low-confidence bytes can be promoted to known erasures, allowing Reed-Solomon recovery to use the existing parity budget more efficiently.
+
+## 6. Internal payload extension envelope
+
+Compression and signing require a small amount of metadata. QuadQR stores that metadata in an **internal extension envelope** only when needed. Applications should normally use `encodeText()`, `encodeBytes()`, `encodeSignedText()`, or `encodeSignedBytes()` and never construct this envelope themselves.
+
+Current envelope magic:
+
+```text
+QPX1
+```
+
+Fixed header size: **16 bytes**.
+
+| Offset | Size | Field |
+|---:|---:|---|
+| 0 | 4 | ASCII magic `QPX1` |
+| 4 | 1 | Extension version (`2`; decoder also accepts legacy `1`) |
+| 5 | 1 | Flags |
+| 6 | 1 | Compression ID |
+| 7 | 1 | Signature algorithm ID |
+| 8 | 4 | Original application payload length, big-endian |
+| 12 | 1 | Signing key-ID length (v2); legacy signer-label length in v1 |
+| 13 | 1 | Optional embedded public-key length |
+| 14 | 1 | Signature length |
+| 15 | 1 | Reserved (`0`) |
+
+Variable bytes follow as:
+
+```text
+keyId || optionalPublicKey || signature || storedPayload
+```
+
+Envelope flags currently use:
+
+```text
+bit 0  signed
+bit 1  compressed
+bit 2  public key embedded
+```
+
+The envelope contains no semantic content type. The Format v5 text flag still determines whether the recovered application payload should be decoded as UTF-8 text.
+
+## 7. Compression
+
+Compression IDs:
+
+```text
+0 = none
+1 = QuadQR portable LZ
+```
+
+The portable LZ stream is an LZSS-style format with groups of up to eight tokens. Each group begins with one flag byte. A flag bit of `0` means a one-byte literal. A flag bit of `1` means a two-byte back-reference:
+
+```text
+12-bit offset: 1..4095 bytes
+4-bit length: stored value + 3, therefore 3..18 bytes
+```
+
+Public compression modes are:
+
+```text
+none
+auto
+lz
+```
+
+`compression: "auto"` uses compression only when it meaningfully reduces payload size. When it does not help and the payload is not signed, QuadQR stores the original payload directly with **no extension-envelope overhead**.
+
+Compression occurs before signing, encryption, and Format v5 ECC.
+
+## 8. Signed QuadQR
+
+Signature algorithm ID `1` is **Ed25519**.
+
+Signed payloads in extension v2 store:
+
+```text
+optional compact key ID
+64-byte Ed25519 signature
+optional 32-byte raw Ed25519 public key only when explicitly requested
+```
+
+The normal production profile does **not** embed the public key. The signature covers:
+
+```text
+16-byte extension header
+|| key ID
+|| optional embedded public key
+|| stored payload bytes
+```
+
+The signature field itself is excluded from the signed message.
+
+The private Ed25519 key is used only by the issuer to create signatures and must never be embedded in a QuadQR. Verification uses a trusted public key supplied externally by the application, server, certificate, or trusted-key registry. The optional key ID is only an identifier that helps the verifier select the correct trusted public key.
+
+For compatibility or self-contained integrity checks, implementations may set `embedPublicKey: true`. A signature verified only against a key embedded in the same QuadQR proves integrity and key possession, but does not establish a trusted signer identity. Such verification should be reported separately from verification against an external trust anchor.
+
+Legacy extension v1 symbols used a signer label and embedded public key. Decoders may continue to read and verify those symbols for backward compatibility.
+
+## 9. Secure + signed composition
+
+When compression, signing, and encryption are combined, QuadQR uses:
+
+```text
+application payload
+→ optional compression
+→ optional Ed25519 signature metadata
+→ AES-256-GCM Secure Payload v1
+→ Format v5 ECC/matrix
+```
+
+After scanning:
+
+```text
+Format v5 decode
+→ AES-GCM authentication/decryption
+→ internal compression/signature metadata processing
+→ application payload
+→ optional Ed25519 signature verification
+```
+
+This keeps signature metadata confidential when encryption is enabled while preserving offline verification after decryption.
+
+## 10. Text and binary APIs
+
+Text and bytes are first-class without semantic payload types:
+
+- `encodeText()` / `decodeMatrix().text` for UTF-8 text;
+- `encodeBytes()` for arbitrary bytes;
+- `encodeUint8Array()` / `decodeUint8Array()` as explicit byte-oriented convenience APIs.
+
+Compression works on both text and byte payloads through the same `compression` option.
+
+## 11. Rendering profiles
+
+Rendering does not modify the encoded matrix.
+
+### Screen mode
+
+Uses the normal RGBW palette and permits:
+
+```text
+classic
+soft
+depth
+inset
+```
+
+### Print mode
+
+`mode: "print"` applies conservative defaults:
+
+- minimum quiet zone of 4 modules unless explicitly overridden;
+- print-safe darker RGB primaries;
+- Classic solid-module rendering by default;
+- physical-size guidance through `getPrintGuidance()`.
+
+Recommended general-purpose starting module size is **0.40 mm/module**. Real printer, paper, ink/toner, lamination, lighting, and camera validation remains necessary for production deployments.
+
+## 12. Logo safety
+
+Logos are rendering overlays and never modify Format v5 data structures.
+
+`size: "auto"` estimates a conservative logo ratio from:
+
+- ECC profile;
+- encoded utilization;
+- version 1 compact-profile penalty;
+- clear-background usage;
+- screen vs print mode.
+
+`findMaxSafeLogoSize()` can empirically search the largest decodable logo size when an ImageData-like logo is available. Generated symbols should still be verified after final rendering.
+
+## 13. Scanner diagnostics
+
+Successful image scans expose normalized diagnostic fields including:
+
+```text
+confidence
+geometryConfidence
+calibrationConfidence
+structureConfidence
+eccUtilization
+correctedErrors
+erasureSymbols
+```
+
+With `debug: true`, the scanner can also report stage state, geometry candidates, finder/vision passes, latest sampled matrix, confidence matrix, color-normalization method, and the failed stage when decoding does not complete.
+
+Debug output is diagnostic evidence, not a cryptographic assurance score.
+
+## 14. Scanability score and torture testing
+
+`runImageStressTest()` and `assessScanability()` use deterministic synthetic distortions to estimate robustness against:
+
+- blur;
+- low brightness;
+- high exposure;
+- uneven shadow;
+- contrast loss;
+- perspective distortion;
+- JPEG-like quantization/block artifacts;
+- downscaling.
+
+Current rating bands:
+
+```text
+90–100  Excellent
+75–89   Good
+50–74   Risky
+0–49    Likely unscannable
+```
+
+These scores are regression/testing aids. They do not replace validation with real phone cameras, printers, displays, paper stocks, lighting conditions, and physical damage.
+
+## 15. Capacity planning
+
+Capacity is determined from the actual Format v5 layout, protected header, CRC, and Spectrum ECC plan. Compression can reduce stored payload bytes, while signatures and encryption add metadata bytes before the matrix codec.
+
+The benchmark helper can report:
+
+- minimum QuadQR version;
+- encoded bytes;
+- remaining capacity;
+- utilization;
+- approximate same-letter standard QR byte-mode version.
+
+When only a payload byte count is known, `compression: "auto"` cannot predict the gain because compressibility depends on the actual bytes.
+
+Standard QR comparisons use the same **nominal ECC letter only**. QuadQR and ISO QR recovery strengths are not equivalent and should not be presented as such.
+
+## 16. Compatibility principles
+
+Implementations should follow these rules:
+
+1. Keep RGBW mapping exactly `R=00, G=01, B=10, W=11`.
+2. Keep GF(256) Spectrum ECC and its errors+erasures behavior.
+3. Preserve Format v5 decoding for normal and Secure Payload symbols.
+4. Keep application semantics outside the QuadQR codec. Do not require a growing content-type registry.
+5. Treat compression/signature metadata as internal transport metadata, not a separate user payload mode.
+6. Treat `keyId` only as an identifier. Signer trust comes from an external trusted public-key binding.
+7. Keep rendering effects out of structural finder/timing/alignment/calibration modules.
+8. Validate public format changes with both matrix and rendered-image scanner tests.
+
+## 17. Reference implementation
+
+The JavaScript implementation in this repository is the current reference implementation. Public entry points are documented under `docs/` and exercised by `tests/self-test.js` and `tests/package-test.js`.

package/bin/quadqr.js

@@ -1,18 +1,21 @@
 #!/usr/bin/env node
 
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import process from "node:process";
 import {
   bytesToHex,
   decryptDecoded,
   encodeSecureText,
+  encodeSignedText,
   encodeText,
-  generateRaw256Key
+  generateRaw256Key,
+  generateSigningKeyPair,
+  verifyDecodedSignature
 } from "../dist/index.js";
-import { savePNG, scanFile } from "../dist/node.js";
+import { savePNG, saveSVG, scanFile } from "../dist/node.js";
 
 function help() {
-  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png] [--ecc M] [--version auto|1..40]\n  quadqr encode <text> --password <password> [-o file.png]\n  quadqr encode <text> --key <64-hex-key> [-o file.png]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>]\n  quadqr keygen\n\nOptions:\n  -o, --output <file>       Output PNG path (default: quadqr.png)\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --module-size <px>        PNG module size (default: 12)\n  --quiet-zone <modules>    PNG quiet zone (default: 4)\n  -h, --help                Show help\n`);
+  console.log(`QuadQR CLI\n\nUsage:\n  quadqr encode <text> [-o file.png|file.svg] [--ecc M] [--version auto|1..40] [--high-density]\n  quadqr encode <text> [--compression auto]\n  quadqr encode <text> --sign-key signing-key.json [--key-id issuer-main]\n  quadqr encode <text> --password <password> [-o file.png|file.svg]\n  quadqr decode <file.png> [--password <password> | --key <64-hex-key>] [--verify-key signing-key.json] [--debug]\n  quadqr keygen\n  quadqr signkeygen [-o signing-key.json]\n\nOptions:\n  -o, --output <file>       Output PNG/SVG path, or signing-key JSON for signkeygen\n  --ecc <L|M|Q|H>          ECC profile (default: M)\n  --version <auto|1..40>    Symbol version (default: auto)\n  --compression <mode>      none|auto|lz (default: auto)\n  --high-density            Enable experimental Triangle16 High Density Mode\n  --sign-key <file>         Sign using a signkeygen JSON bundle\n  --key-id <id>             Override the signing key ID stored in the QuadQR\n  --embed-public-key        Also embed the public key for untrusted/self-contained checks\n  --verify-key <file>       Verify a signed QuadQR with a trusted key bundle\n  --password <text>         Encrypt/decrypt with password mode\n  --key <hex>               Encrypt/decrypt with raw 256-bit key mode\n  --print                   Use the print-safe render profile\n  --image-size <px>         Exact square output size (default: 720)\n  --module-size <px>        Legacy pixels-per-module sizing\n  --quiet-zone <modules>    Quiet zone in modules (default: 4)\n  --debug                   Emit scanner diagnostics to stderr on decode\n  -h, --help                Show help\n`);
 }
 
 function parse(argv) {
@@ -24,8 +27,17 @@ function parse(argv) {
     else if (token === "-o" || token === "--output") flags.output = argv[++i];
     else if (token === "--ecc") flags.ecc = argv[++i];
     else if (token === "--version") flags.version = argv[++i];
+    else if (token === "--high-density") flags.highDensity = true;
     else if (token === "--password") flags.password = argv[++i];
     else if (token === "--key") flags.key = argv[++i];
+    else if (token === "--compression") flags.compression = argv[++i];
+    else if (token === "--sign-key") flags.signKey = argv[++i];
+    else if (token === "--key-id") flags.keyId = argv[++i];
+    else if (token === "--embed-public-key") flags.embedPublicKey = true;
+    else if (token === "--verify-key") flags.verifyKey = argv[++i];
+    else if (token === "--print") flags.print = true;
+    else if (token === "--debug") flags.debug = true;
+    else if (token === "--image-size") flags.imageSize = Number(argv[++i]);
     else if (token === "--module-size") flags.moduleSize = Number(argv[++i]);
     else if (token === "--quiet-zone") flags.quietZone = Number(argv[++i]);
     else args.push(token);
@@ -33,6 +45,25 @@ function parse(argv) {
   return { args, flags };
 }
 
+function bytesToBase64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+
+function base64ToBytes(value, label) {
+  if (typeof value !== "string" || !value) throw new Error(`${label} is missing from signing key bundle.`);
+  return new Uint8Array(Buffer.from(value, "base64"));
+}
+
+async function readSigningBundle(filename) {
+  const parsed = JSON.parse(await readFile(filename, "utf8"));
+  if (parsed.algorithm && parsed.algorithm !== "Ed25519") throw new Error(`Unsupported signing algorithm ${parsed.algorithm}.`);
+  return {
+    privateKey: parsed.privateKeyPkcs8 ? base64ToBytes(parsed.privateKeyPkcs8, "privateKeyPkcs8") : null,
+    publicKey: base64ToBytes(parsed.publicKeyRaw || parsed.publicKeyBytes, "publicKeyRaw"),
+    keyId: parsed.keyId || null
+  };
+}
+
 async function main() {
   const { args, flags } = parse(process.argv.slice(2));
   if (flags.help || !args.length) {
@@ -46,6 +77,24 @@ async function main() {
     return;
   }
 
+  if (command === "signkeygen") {
+    const pair = await generateSigningKeyPair();
+    const bundle = JSON.stringify({
+      format: "quadqr-ed25519-key-v1",
+      algorithm: pair.algorithm,
+      privateKeyPkcs8: bytesToBase64(pair.privateKeyPkcs8),
+      publicKeyRaw: bytesToBase64(pair.publicKeyBytes),
+      keyId: pair.keyId
+    }, null, 2) + "\n";
+    if (flags.output) {
+      await writeFile(flags.output, bundle, { mode: 0o600 });
+      console.log(`Saved ${flags.output}. Keep the private key file secret.`);
+    } else {
+      process.stdout.write(bundle);
+    }
+    return;
+  }
+
   if (command === "encode") {
     const text = args.join(" ");
     if (!text) throw new Error("encode requires text.");
@@ -53,27 +102,52 @@ async function main() {
 
     const options = {
       ecc: flags.ecc || "M",
+      highDensity: Boolean(flags.highDensity),
+      compression: flags.compression || "auto",
       ...(flags.version && flags.version !== "auto" ? { version: Number(flags.version) } : {})
     };
-    const code = flags.password
-      ? await encodeSecureText(text, { ...options, security: { mode: "password", password: flags.password } })
+    const signingBundle = flags.signKey ? await readSigningBundle(flags.signKey) : null;
+    const signing = signingBundle ? {
+      privateKey: signingBundle.privateKey,
+      keyId: flags.keyId || signingBundle.keyId || undefined,
+      ...(flags.embedPublicKey ? { publicKey: signingBundle.publicKey, embedPublicKey: true } : {})
+    } : null;
+    const security = flags.password
+      ? { mode: "password", password: flags.password }
       : flags.key
-        ? await encodeSecureText(text, { ...options, security: { mode: "raw-key", key: flags.key } })
-        : encodeText(text, options);
+        ? { mode: "raw-key", key: flags.key }
+        : null;
+
+    let code;
+    if (security) {
+      code = await encodeSecureText(text, { ...options, security, ...(signing ? { signing } : {}) });
+    } else if (signing) {
+      code = await encodeSignedText(text, { ...options, ...signing });
+    } else {
+      code = encodeText(text, options);
+    }
 
     const output = flags.output || "quadqr.png";
-    const saved = await savePNG(code, output, {
-      moduleSize: flags.moduleSize || 12,
-      quietZone: Number.isFinite(flags.quietZone) ? flags.quietZone : 4
-    });
-    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ECC ${code.eccLevel}).`);
+    const renderOptions = {
+      quietZone: Number.isFinite(flags.quietZone) ? flags.quietZone : 4,
+      ...(flags.print ? { mode: "print" } : {}),
+      ...(Number.isFinite(flags.imageSize)
+        ? { imageSize: flags.imageSize }
+        : Number.isFinite(flags.moduleSize)
+          ? { moduleSize: flags.moduleSize }
+          : { imageSize: 720 })
+    };
+    const saved = output.toLowerCase().endsWith(".svg")
+      ? await saveSVG(code, output, renderOptions)
+      : await savePNG(code, output, renderOptions);
+    console.log(`Saved ${output} (${saved.bytes} bytes, v${code.version}, ${code.size}x${code.size}, ${code.highDensity ? "High Density experimental" : "Normal RGBW"}, ECC ${code.eccLevel}).`);
     return;
   }
 
   if (command === "decode") {
     const filename = args[0];
     if (!filename) throw new Error("decode requires an image filename.");
-    let result = await scanFile(filename);
+    let result = await scanFile(filename, flags.debug ? { debug: true } : {});
     if (result.secure) {
       if (!flags.password && !flags.key) {
         console.log(JSON.stringify({
@@ -88,6 +162,23 @@ async function main() {
       }
       result = await decryptDecoded(result, flags.password ? { password: flags.password } : { key: flags.key });
     }
+    if (result.signed && flags.verifyKey) {
+      const verifier = await readSigningBundle(flags.verifyKey);
+      result = await verifyDecodedSignature(result, { publicKey: verifier.publicKey });
+    }
+    if (flags.debug) {
+      console.error(JSON.stringify({
+        confidence: result.confidence ?? null,
+        geometryConfidence: result.geometryConfidence ?? null,
+        calibrationConfidence: result.calibrationConfidence ?? null,
+        eccUtilization: result.eccUtilization ?? null,
+        signed: Boolean(result.signed),
+        signatureVerified: result.signatureVerified ?? null,
+        signatureTrusted: result.signatureTrusted ?? null,
+        signingKeyId: result.signingKeyId ?? null,
+        diagnostics: result.diagnostics ?? null
+      }, null, 2));
+    }
     if (result.text != null) console.log(result.text);
     else process.stdout.write(Buffer.from(result.payload));
     return;