quadqr-js 1.0.2 → 1.2.0

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]\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  --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) {
@@ -26,6 +29,14 @@ function parse(argv) {
     else if (token === "--version") flags.version = argv[++i];
     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 +44,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 +76,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,19 +101,43 @@ async function main() {
 
     const options = {
       ecc: flags.ecc || "M",
+      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
-    });
+    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}, ECC ${code.eccLevel}).`);
     return;
   }
@@ -73,7 +145,7 @@ async function main() {
   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 +160,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;

package/dist/esm/benchmark.js

@@ -11,6 +11,7 @@ import {
   encodeBytes,
   decodeMatrix,
   getVersionInfo,
+  compressPayload,
   MAX_VERSION
 } from "./quadqr.js";
 
@@ -103,6 +104,85 @@ export function compareCapacity(version, ecc = "M") {
   };
 }
 
+
+/** Calculate the smallest QuadQR and standard QR versions for a payload size. */
+export function calculateCapacityPlan(options = {}) {
+  const ecc = normalizeEcc(options.ecc ?? "M");
+  let sourceBytes;
+  const hasConcretePayload = options.payload instanceof Uint8Array || typeof options.payload === "string";
+  if (options.payload instanceof Uint8Array) sourceBytes = options.payload;
+  else if (typeof options.payload === "string") sourceBytes = new TextEncoder().encode(options.payload);
+  else sourceBytes = new Uint8Array(Math.max(0, Math.floor(options.payloadBytes ?? 0)));
+
+  const requestedCompression = options.compression ?? "none";
+  const signed = Boolean(options.signed);
+  const keyIdBytes = options.keyId ? new TextEncoder().encode(String(options.keyId)).length : 0;
+  const envelopeHeaderBytes = 16;
+  const signingBytes = signed ? 64 + keyIdBytes + (options.embedPublicKey ? 32 : 0) : 0;
+  let compression = requestedCompression;
+  let storedBytes = sourceBytes.length;
+  let compressed = false;
+
+  if (requestedCompression !== "none" && hasConcretePayload) {
+    const candidate = compressPayload(sourceBytes);
+    if (requestedCompression === "lz" || candidate.length < sourceBytes.length - 2) {
+      storedBytes = candidate.length;
+      compressed = true;
+      compression = "lz";
+    } else {
+      compression = "none";
+    }
+  } else if (requestedCompression !== "none" && !hasConcretePayload) {
+    compression = "unknown";
+  }
+
+  const needsEnvelope = signed || compressed || requestedCompression === "lz";
+  const encodedBytes = storedBytes + (needsEnvelope ? envelopeHeaderBytes + signingBytes : 0);
+  const extensionOverheadBytes = encodedBytes - storedBytes;
+
+  let quadqrVersion = null;
+  let quadqrInfo = null;
+  for (let version = 1; version <= MAX_VERSION; version++) {
+    const info = getVersionInfo(version, { ecc });
+    if (encodedBytes <= info.capacityBytes) {
+      quadqrVersion = version;
+      quadqrInfo = info;
+      break;
+    }
+  }
+
+  const standard = STANDARD_QR_BYTE_CAPACITY[ecc];
+  let standardQrVersion = null;
+  for (let version = 1; version <= MAX_VERSION; version++) {
+    if (sourceBytes.length <= standard[version - 1]) {
+      standardQrVersion = version;
+      break;
+    }
+  }
+
+  return {
+    ecc,
+    sourceBytes: sourceBytes.length,
+    encodedBytes,
+    storedBytes,
+    extensionOverheadBytes,
+    compression,
+    compressed,
+    signed,
+    quadqrVersion,
+    quadqrSize: quadqrInfo?.size ?? null,
+    quadqrCapacityBytes: quadqrInfo?.capacityBytes ?? null,
+    remainingBytes: quadqrInfo ? quadqrInfo.capacityBytes - encodedBytes : null,
+    utilizationPercent: quadqrInfo ? encodedBytes / quadqrInfo.capacityBytes * 100 : null,
+    standardQrVersion,
+    standardQrSize: standardQrVersion ? 21 + 4 * (standardQrVersion - 1) : null,
+    matrixWidthSavingsPercent: quadqrInfo && standardQrVersion
+      ? (1 - quadqrInfo.size / (21 + 4 * (standardQrVersion - 1))) * 100
+      : null,
+    note: "Compression is measured only when concrete payload bytes are provided. Byte-count-only estimates cannot predict compression gain."
+  };
+}
+
 export function buildCapacityComparison(options = {}) {
   const ecc = normalizeEcc(options.ecc ?? "M");
   const versions = options.versions ?? Array.from({ length: MAX_VERSION }, (_, i) => i + 1);

package/dist/esm/node.js

@@ -10,7 +10,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { deflateSync, inflateSync } from "node:zlib";
 import { webcrypto } from "node:crypto";
 
-import { renderToImageData, scanImageData } from "./quadqr.js";
+import { renderToImageData, renderToSVG, scanImageData } from "./quadqr.js";
 
 if (!globalThis.crypto) globalThis.crypto = webcrypto;
 
@@ -242,6 +242,18 @@ export async function savePNG(codeOrMatrix, filename, options = {}) {
   return { filename, bytes: png.length };
 }
 
+/** Render a QuadQR code/matrix directly to an SVG string. */
+export function toSVG(codeOrMatrix, options = {}) {
+  return renderToSVG(codeOrMatrix, options);
+}
+
+/** Render a QuadQR code/matrix and save it as SVG. */
+export async function saveSVG(codeOrMatrix, filename, options = {}) {
+  const svg = toSVG(codeOrMatrix, options);
+  await writeFile(filename, svg, "utf8");
+  return { filename, bytes: Buffer.byteLength(svg, "utf8") };
+}
+
 async function decodeWithOptionalSharp(buffer) {
   try {
     const { default: sharp } = await import("sharp");