fractal-pqc 0.3.0 → 0.3.2

package/README.md

@@ -1,5 +1,11 @@
 # fractal-pqc
 
+> ⚠️ **Reference toolkit — NOT for production custody of real funds (yet).** It is
+> **unaudited**, **key-path-only**, proven on **signet (not mainnet)**, and its quantum
+> guarantee depends on a first-seen anchor registry that is still on the roadmap. Use it
+> for **evaluation, testnet, education, and building on** — do **not** secure real Bitcoin
+> with it until it is audited and 1.0. We say precisely what it is.
+
 A small, **runnable, test-vector-verified** reference for quantum-safe migration of a
 Bitcoin-style key. It binds a classical **secp256k1 / Taproot** key to a post-quantum
 **ML-DSA-65 (NIST FIPS-204)** key and requires a post-quantum signature to authorize —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fractal-pqc",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Runnable reference for quantum-safe migration of a Bitcoin-style key: bind secp256k1/Taproot to ML-DSA-65 (FIPS-204), derive P2TR addresses, build+sign BIP-341 key-path spends (official-vector-verified), and broadcast on testnet. Real primitives, honest scope.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
   "files": [
     "src",
     "bin",
+    "test",
     "README.md",
     "LICENSE"
   ],

package/src/index.mjs

@@ -56,4 +56,4 @@ export {
   parsePsbt, signPsbtTaprootKeyPath, finalizePsbt,
 } from "./psbt.mjs";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.2";

package/test/bip341-keypath-vector.json

@@ -0,0 +1,44 @@
+{
+  "_source": "Official BIP-341 wallet-test-vectors.json — keyPathSpending[0], input idx 4 (hashType=SIGHASH_DEFAULT). Proves taprootKeyPathSighash is Bitcoin-consensus-correct.",
+  "rawUnsignedTx": "02000000097de20cbff686da83a54981d2b9bab3586f4ca7e48f57f5b55963115f3b334e9c010000000000000000d7b7cab57b1393ace2d064f4d4a2cb8af6def61273e127517d44759b6dafdd990000000000fffffffff8e1f583384333689228c5d28eac13366be082dc57441760d957275419a418420000000000fffffffff0689180aa63b30cb162a73c6d2a38b7eeda2a83ece74310fda0843ad604853b0100000000feffffffaa5202bdf6d8ccd2ee0f0202afbbb7461d9264a25e5bfd3c5a52ee1239e0ba6c0000000000feffffff956149bdc66faa968eb2be2d2faa29718acbfe3941215893a2a3446d32acd050000000000000000000e664b9773b88c09c32cb70a2a3e4da0ced63b7ba3b22f848531bbb1d5d5f4c94010000000000000000e9aa6b8e6c9de67619e6a3924ae25696bb7b694bb677a632a74ef7eadfd4eabf0000000000ffffffffa778eb6a263dc090464cd125c466b5a99667720b1c110468831d058aa1b82af10100000000ffffffff0200ca9a3b000000001976a91406afd46bcdfd22ef94ac122aa11f241244a37ecc88ac807840cb0000000020ac9a87f5594be208f8532db38cff670c450ed2fea8fcdefcc9a663f78bab962b0065cd1d",
+  "utxosSpent": [
+    {
+      "scriptPubKey": "512053a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343",
+      "amountSats": 420000000
+    },
+    {
+      "scriptPubKey": "5120147c9c57132f6e7ecddba9800bb0c4449251c92a1e60371ee77557b6620f3ea3",
+      "amountSats": 462000000
+    },
+    {
+      "scriptPubKey": "76a914751e76e8199196d454941c45d1b3a323f1433bd688ac",
+      "amountSats": 294000000
+    },
+    {
+      "scriptPubKey": "5120e4d810fd50586274face62b8a807eb9719cef49c04177cc6b76a9a4251d5450e",
+      "amountSats": 504000000
+    },
+    {
+      "scriptPubKey": "512091b64d5324723a985170e4dc5a0f84c041804f2cd12660fa5dec09fc21783605",
+      "amountSats": 630000000
+    },
+    {
+      "scriptPubKey": "00147dd65592d0ab2fe0d0257d571abf032cd9db93dc",
+      "amountSats": 378000000
+    },
+    {
+      "scriptPubKey": "512075169f4001aa68f15bbed28b218df1d0a62cbbcf1188c6665110c293c907b831",
+      "amountSats": 672000000
+    },
+    {
+      "scriptPubKey": "5120712447206d7a5238acc7ff53fbe94a3b64539ad291c7cdbc490b7577e4b17df5",
+      "amountSats": 546000000
+    },
+    {
+      "scriptPubKey": "512077e30a5522dd9f894c3f8b8bd4c4b2cf82ca7da8a3ea6a239655c39c050ab220",
+      "amountSats": 588000000
+    }
+  ],
+  "inputIndex": 4,
+  "expectedSigHash": "4f900a0bae3f1446fd48490c2958b5a023228f01661cda3496a11da502a7f7ef"
+}

package/test/vectors.mjs

@@ -0,0 +1,234 @@
+// Real, runnable test vectors for the quantum migration envelope.
+// `npm test` (or `node test/vectors.mjs`) exercises the full flow with REAL
+// secp256k1 + ML-DSA-65 keys and prints a machine-checkable summary. No mocks.
+
+import { sha256 } from "@noble/hashes/sha2.js";
+import {
+  generateMigrationIdentity,
+  createMigrationCommitment,
+  verifyMigrationCommitment,
+  authorizeSpend,
+  verifySpend,
+  _internal,
+} from "../src/migration-envelope.mjs";
+import {
+  generateTaprootKey,
+  taprootSign,
+  taprootVerify,
+  verifiesBip340OfficialVector,
+  createTaprootPqcCommitment,
+  verifyTaprootPqcCommitment,
+} from "../src/bitcoin.mjs";
+
+let pass = 0, fail = 0;
+function check(name, cond) {
+  if (cond) { pass++; console.log(`  ✓ ${name}`); }
+  else { fail++; console.log(`  ✗ ${name}`); }
+}
+
+console.log("pqc-migration-kit — real secp256k1 + ML-DSA-65 migration envelope\n");
+
+// 1. Identity uses real key sizes.
+const id = generateMigrationIdentity();
+console.log("Key material (real):");
+console.log(`  secp256k1 pubkey : ${id.classicalPub.length} bytes (compressed)`);
+console.log(`  ML-DSA-65 pubkey : ${id.pqPublic.length} bytes (FIPS-204 Cat-3)`);
+console.log(`  ML-DSA-65 secret : ${id.pqSecret.length} bytes\n`);
+check("secp256k1 compressed pubkey is 33 bytes", id.classicalPub.length === 33);
+check("ML-DSA-65 pubkey is 1952 bytes (FIPS-204)", id.pqPublic.length === 1952);
+
+// 2. A well-formed migration commitment verifies (both signatures).
+const cert = createMigrationCommitment(id);
+const v = verifyMigrationCommitment(cert);
+console.log("\nMigration commitment:");
+console.log(`  factHash (anchorable leaf): ${cert.factHash}`);
+check("valid commitment verifies (classical + PQC both)", v.valid);
+check("  ↳ classical secp256k1 signature ok", v.classicalOk);
+check("  ↳ post-quantum ML-DSA-65 signature ok", v.pqOk);
+
+// 3. Tamper the bound PQC pubkey → commitment must fail (binding is tamper-evident).
+const tampered = { ...cert, pqPublic: cert.pqPublic.slice(0, -2) + (cert.pqPublic.endsWith("00") ? "11" : "00") };
+check("tampered PQC pubkey is rejected", verifyMigrationCommitment(tampered).valid === false);
+
+// 4. Swapping in a different classical signature → fails.
+const id2 = generateMigrationIdentity();
+const cert2 = createMigrationCommitment(id2);
+const forged = { ...cert, classicalSig: cert2.classicalSig };
+check("foreign classical signature is rejected", verifyMigrationCommitment(forged).valid === false);
+
+// 5. Post-migration spend: PQC signature authorizes a tx hash, verified against the
+//    holder's ANCHORED commitment (anchor = the factHash published first-seen on-chain).
+const anchor = cert.factHash; // as if read from the immutable on-chain anchor
+const txHash = sha256(new TextEncoder().encode("spend:send 0.5 BTC to bc1q..."));
+const spendSig = authorizeSpend(id, txHash);
+check("valid PQC spend verifies against the anchored commitment", verifySpend(cert, txHash, spendSig, { anchoredFactHash: anchor }).valid === true);
+
+// 6. Spend for a DIFFERENT tx hash must fail (signature binds the exact tx).
+const otherTx = sha256(new TextEncoder().encode("spend:send 5 BTC to attacker"));
+check("PQC spend does not replay onto another tx", verifySpend(cert, otherTx, spendSig, { anchoredFactHash: anchor }).valid === false);
+
+// 7. verifySpend fails CLOSED without an anchor (the quantum property needs the pin).
+check("verifySpend without an anchor is rejected (anchor-required)", verifySpend(cert, txHash, spendSig).reason === "anchor-required");
+
+// 8. THE quantum property, correctly modeled: an attacker who recovered the classical
+//    key (post-Shor) forges a well-formed cert re-binding the victim's classical key to
+//    the ATTACKER's OWN PQC key, then signs a spend with that PQC key. It is well-formed
+//    but its factHash ≠ the holder's anchored factHash → REJECTED at the anchor.
+const attackerId = { classicalPriv: id.classicalPriv, classicalPub: id.classicalPub, pqSecret: id2.pqSecret, pqPublic: id2.pqPublic };
+const attackerCert = createMigrationCommitment(attackerId); // victim classical pub, attacker PQC key
+const attackerSpendSig = authorizeSpend(attackerId, txHash);
+check("attacker's rebound cert is self-consistent (well-formed)", verifyMigrationCommitment(attackerCert).wellFormed === true);
+const attackerSpend = verifySpend(attackerCert, txHash, attackerSpendSig, { anchoredFactHash: anchor });
+check("classical-key attacker CANNOT spend against the anchored key (anchor-mismatch)", attackerSpend.valid === false && attackerSpend.reason === "anchor-mismatch");
+
+// 8. Determinism of canonical encoding (verifier reconstructs identical bytes).
+const a = _internal.canonical(_internal.COMMIT_DOMAIN, [id.classicalPub, id.pqPublic]);
+const b = _internal.canonical(_internal.COMMIT_DOMAIN, [id.classicalPub, id.pqPublic]);
+check("canonical encoding is deterministic", _internal.toHex(a) === _internal.toHex(b));
+
+// ── Bitcoin Taproot (BIP-340 Schnorr) — real, consensus-correct ────────────────
+console.log("\nBitcoin Taproot (BIP-340 Schnorr):");
+
+// 9. Our Schnorr verifier accepts the OFFICIAL BIP-340 test vector → Bitcoin-correct.
+check("official BIP-340 test vector verifies (Bitcoin consensus-correct)", verifiesBip340OfficialVector() === true);
+
+// 10. Real Taproot sign/verify roundtrip with x-only 32-byte key.
+const tap = generateTaprootKey();
+check("Taproot x-only pubkey is 32 bytes", tap.xOnlyPub.length === 32);
+const tapMsg = sha256(new TextEncoder().encode("taproot sighash placeholder"));
+const tapSig = taprootSign(tap.secretKey, tapMsg);
+check("Taproot Schnorr sign/verify roundtrip", taprootVerify(tapSig, tapMsg, tap.xOnlyPub) === true);
+check("Taproot Schnorr rejects a tampered message", taprootVerify(tapSig, sha256(new TextEncoder().encode("other")), tap.xOnlyPub) === false);
+
+// 11. Taproot → PQC quantum-recovery commitment (P2QRH-style), dual-signed.
+const pqId = generateMigrationIdentity();
+const btcCert = createTaprootPqcCommitment(tap, pqId);
+const bv = verifyTaprootPqcCommitment(btcCert);
+console.log(`  recovery commitment factHash: ${btcCert.factHash}`);
+check("Taproot→PQC recovery commitment verifies (Schnorr + ML-DSA-65)", bv.valid === true);
+check("  ↳ Taproot Schnorr side ok", bv.taprootOk === true);
+check("  ↳ ML-DSA-65 side ok", bv.pqOk === true);
+const btcTampered = { ...btcCert, pqPublic: btcCert.pqPublic.slice(0, -2) + (btcCert.pqPublic.endsWith("00") ? "11" : "00") };
+check("tampered PQC key in recovery commitment is rejected", verifyTaprootPqcCommitment(btcTampered).valid === false);
+
+// ── Bitcoin addresses + transactions (real, official-vector-checked) ───────────
+console.log("\nBitcoin addresses + transactions:");
+const { segwitDecode, segwitEncode } = await import("../src/bech32.mjs");
+const { taprootTweakOutputKey, p2trAddress, p2wpkhAddress } = await import("../src/address.mjs");
+const bx = await import("../src/tx.mjs");
+const { schnorr } = await import("@noble/curves/secp256k1.js");
+const hx = (h) => Uint8Array.from(Buffer.from(h, "hex"));
+const hex = (b) => Buffer.from(b).toString("hex");
+
+// bech32m — official BIP-350 P2TR vector round-trips.
+const trAddr = "bc1p0xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqzk5jj0";
+const trDec = segwitDecode("bc", trAddr);
+check("BIP-350 P2TR address decodes to witver 1 / 32-byte program", trDec?.version === 1 && trDec.program.length === 32);
+check("BIP-350 P2TR address re-encodes identically (bech32m)", segwitEncode("bc", 1, trDec.program) === trAddr);
+// bech32 — official BIP-173 P2WPKH v0 program.
+const wpDec = segwitDecode("bc", "BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4");
+check("BIP-173 P2WPKH v0 program = 751e76e8…33bd6", wpDec && hex(wpDec.program) === "751e76e8199196d454941c45d1b3a323f1433bd6");
+
+// BIP-341 official test vector: internal key → tweaked output key → address.
+const internalP = hx("d6889cb081036e0faefa3a35157ad71086b123b2b144b649798b494c300a961d");
+check("BIP-341 taproot tweak → official output key", hex(taprootTweakOutputKey(internalP)) === "53a1f6e454df1aa2776a2814a721372d6258050de330b3c6d10ee8f4e0dda343");
+check("BIP-341 P2TR address = official bc1p2wsldez…59h4z5", p2trAddress(internalP, "bc") === "bc1p2wsldez5mud2yam29q22wgfh9439spgduvct83k3pm50fcxa5dps59h4z5");
+
+// Serialization + txid vs the Bitcoin GENESIS coinbase (consensus ground truth).
+const genesisRaw = hx("01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000");
+check("genesis coinbase txid (serialization + txid correct)",
+  hex(bx._internal.rev(bx._internal.dsha(genesisRaw))) === "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b");
+
+// Real key-path P2TR spend: tweaked private key pubkey == output key, and the Schnorr
+// signature over the BIP-341 sighash verifies against that output key.
+const spend = generateTaprootKey();
+const { privKey, outputXOnly } = bx.taprootTweakPrivateKey(spend.secretKey);
+check("tweaked private key's pubkey equals the tweaked output key", hex(schnorr.getPublicKey(privKey)) === hex(outputXOnly));
+const spk = bx.p2trScriptPubKey(outputXOnly);
+const tx = { version: 2, locktime: 0, inputs: [{ txid: "aa".repeat(32), vout: 0 }], outputs: [{ valueSats: 9000, scriptPubKey: spk }] };
+const sigHex = bx.signTaprootKeyPath(tx, 0, spend.secretKey, [10000], [spk]);
+const sighash = bx.taprootKeyPathSighash(tx, 0, [10000], [spk]);
+check("key-path spend signature verifies against the Taproot output key", taprootVerify(hx(sigHex), sighash, outputXOnly) === true);
+check("signed P2TR tx serializes (segwit) and yields a txid", typeof bx.txid(tx) === "string" && bx.serializeSegwit(tx).length > 0);
+console.log(`  demo P2TR address: ${p2trAddress(spend.xOnlyPub, "tb")}`);
+
+// THE consensus proof: the BIP-341 key-path sighash matches the OFFICIAL vector byte-for-byte.
+const { readFileSync } = await import("node:fs");
+const { fileURLToPath } = await import("node:url");
+const { dirname, join } = await import("node:path");
+const here = dirname(fileURLToPath(import.meta.url));
+const V = JSON.parse(readFileSync(join(here, "bip341-keypath-vector.json"), "utf8"));
+function parseRawTx(raw) {
+  const b = hx(raw); let p = 0;
+  const u32 = () => { const v = new DataView(b.buffer, b.byteOffset + p, 4).getUint32(0, true); p += 4; return v; };
+  const rd = (n) => { const s = b.slice(p, p + n); p += n; return s; };
+  const vi = () => { const f = b[p++]; if (f < 0xfd) return f; if (f === 0xfd) { const v = new DataView(b.buffer, b.byteOffset + p, 2).getUint16(0, true); p += 2; return v; } if (f === 0xfe) { const v = u32(); return v; } const v = new DataView(b.buffer, b.byteOffset + p, 8).getBigUint64(0, true); p += 8; return Number(v); };
+  const version = u32(); const nin = vi(); const inputs = [];
+  for (let i = 0; i < nin; i++) { const prev = rd(32); const vout = u32(); const sl = vi(); rd(sl); const sequence = u32(); inputs.push({ txid: hex(Uint8Array.from(prev).reverse()), vout, sequence }); }
+  const nout = vi(); const outputs = [];
+  for (let i = 0; i < nout; i++) { const lo = new DataView(b.buffer, b.byteOffset + p, 4).getUint32(0, true); const hiv = new DataView(b.buffer, b.byteOffset + p + 4, 4).getUint32(0, true); p += 8; const valueSats = BigInt(hiv) * 0x100000000n + BigInt(lo); const sl = vi(); outputs.push({ valueSats, scriptPubKey: rd(sl) }); }
+  const locktime = u32(); return { version, locktime, inputs, outputs };
+}
+const otx = parseRawTx(V.rawUnsignedTx);
+check("BIP-341 vector tx round-trips our serializer", hex(bx.serializeLegacy(otx)) === V.rawUnsignedTx);
+const oSig = bx.taprootKeyPathSighash(otx, V.inputIndex, V.utxosSpent.map((u) => BigInt(u.amountSats)), V.utxosSpent.map((u) => hx(u.scriptPubKey)));
+check("BIP-341 key-path sighash MATCHES the OFFICIAL vector (consensus-correct)", hex(oSig) === V.expectedSigHash);
+
+// ── Fees + PSBT (BIP-174) — funded P2TR spend end-to-end ───────────────────────
+console.log("\nFees + PSBT (funded P2TR spend):");
+const fees = await import("../src/fees.mjs");
+const psbtMod = await import("../src/psbt.mjs");
+check("P2TR vsize 1-in/1-out ≈ 111 vB", fees.estimateP2trVsize(1, 1) === 111);
+check("P2TR vsize 1-in/2-out ≈ 154 vB", fees.estimateP2trVsize(1, 2) === 154);
+const uTxos = [{ txid: "ab".repeat(32), vout: 0, valueSats: 100000 }];
+const sel = fees.selectCoins(uTxos, 60000, 8);
+check("coin selection conserves value (in = target + fee + change)", 100000 === 60000 + sel.fee + sel.changeSats);
+const spk2 = bx.p2trScriptPubKey(outputXOnly);
+const outs = [{ valueSats: 60000, scriptPubKey: spk2 }];
+if (sel.hasChange) outs.push({ valueSats: sel.changeSats, scriptPubKey: spk2 });
+const ftx = { version: 2, locktime: 0, inputs: sel.inputs.map((u) => ({ txid: u.txid, vout: u.vout, sequence: 0xffffffff })), outputs: outs };
+const meta = sel.inputs.map(() => ({ witnessUtxo: { valueSats: 100000, scriptPubKey: spk2 }, tapInternalKey: spend.xOnlyPub }));
+const psbt = psbtMod.createPsbt(ftx, meta);
+const parsed = psbtMod.parsePsbt(psbtMod.serializePsbt(psbt));
+check("PSBT serialize→parse round-trips (magic + input/output counts)", parsed.magicOk && parsed.tx.inputs.length === ftx.inputs.length && parsed.tx.outputs.length === outs.length);
+check("PSBT base64 carries the BIP-174 magic", psbtMod.serializePsbtBase64(psbt).startsWith("cHNidP8"));
+psbtMod.signPsbtTaprootKeyPath(psbt, [spend.secretKey]);
+const fin = psbtMod.finalizePsbt(psbt);
+const fsighash = bx.taprootKeyPathSighash(ftx, 0, [100000], [spk2]);
+check("finalized PSBT witness sig verifies against the output key", taprootVerify(psbt.inputs[0].tapKeySig, fsighash, outputXOnly) === true);
+check("finalized PSBT yields a broadcastable tx (hex + txid)", typeof fin.hex === "string" && fin.hex.length > 0 && typeof fin.txid === "string");
+
+// Regression: red-team fixes (fees false-insufficient, PSBT key-control, trailing bytes).
+check("fees: fundable changeless spend is NOT falsely rejected", (() => {
+  const r = fees.selectCoins([{ txid: "aa".repeat(32), vout: 0, valueSats: 10454 }], 10000, 1);
+  return r.hasChange === false && r.changeSats === 0 && r.fee >= 111;
+})());
+check("PSBT signer refuses a key that doesn't control the input", (() => {
+  const B = generateTaprootKey();
+  const p2 = psbtMod.createPsbt(ftx, meta);
+  try { psbtMod.signPsbtTaprootKeyPath(p2, [B.secretKey]); return false; } catch { return true; }
+})());
+check("PSBT parser rejects trailing bytes", (() => {
+  const ser = psbtMod.serializePsbt(psbtMod.createPsbt(ftx, meta));
+  try { psbtMod.parsePsbt(new Uint8Array([...ser, 1, 2, 3])); return false; } catch { return true; }
+})());
+
+// ── Testnet broadcaster (offline dry-run — no network) ─────────────────────────
+console.log("\nTestnet broadcaster (dry-run):");
+const addrMod = await import("../src/address.mjs");
+const bcast = await import("../src/broadcast.mjs");
+// addressToScriptPubKey inverts p2trAddress: derive addr → decode back to the same spk.
+const rtSpk = addrMod.addressToScriptPubKey(addrMod.p2trAddress(spend.xOnlyPub, "tb"), "tb");
+check("addressToScriptPubKey(p2trAddress(k)) == p2trScriptPubKey(tweak(k))", hex(rtSpk) === hex(bx.p2trScriptPubKey(outputXOnly)));
+// Full build+sign path with provided UTXOs + fee rate → dry-run, no network call.
+const destAddr = addrMod.p2trAddress(generateTaprootKey().xOnlyPub, "tb");
+const dry = await bcast.sendP2trKeyPath({
+  internalPriv: spend.secretKey, to: destAddr, amountSats: 50000, network: "tb",
+  feeRate: 2, utxos: [{ txid: "ab".repeat(32), vout: 0, valueSats: 100000 }], broadcast: false,
+});
+check("send-testnet dry-run builds a signed tx (not broadcast)", dry.broadcasted === false && typeof dry.hex === "string" && dry.hex.length > 0);
+check("send-testnet dry-run conserves value (in = amount + fee + change)", 100000 === 50000 + dry.fee + dry.changeSats);
+check("send-testnet dry-run yields an explorer link for the txid", dry.explorer.includes(dry.txid));
+
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);