keychat-save 1.4.2 → 1.5.0

package/README.md

@@ -83,6 +83,40 @@ A bundle carries only committed history. It misses uncommitted work, gitignored
 and `node_modules` — which means a restore depends on the npm registry still serving every package
 at the same version. Packages get unpublished. RepoChain carries the lot.
 
+## KeyCloud — files on chain
+
+`save` handles text and **RepoChain** handles repositories. **KeyCloud** puts a single file on
+chain in one transaction, sealed to your own key. Nobody else can read it, including us.
+
+```bash
+# Upload — one file, one transaction
+keychat-save keycloud put ~/Documents/passport.pdf
+
+# Fetch it back anywhere your identity key is. sha256 is verified before
+# anything is written to disk.
+keychat-save keycloud get <txid> ~/Downloads
+
+# What you have uploaded from this machine
+keychat-save keycloud list
+```
+
+Bytes are encrypted directly — never base64, which would add 33% to the size and therefore 33% to
+the cost. The file's sha256 travels with it and is checked on the way back, so a truncated fetch
+fails loudly instead of writing a corrupt file.
+
+### What it costs
+
+Storage is priced like permanence, at the 100 sats/KB mining floor:
+
+| File | Cost |
+|------|------|
+| 1 MB | ~200 Compute |
+| 10 MB | ~2,000 Compute |
+| 100 MB | ~20,000 Compute (0.1 BSV) |
+
+`put` refuses anything over 95 MB rather than spend on a transaction no miner will accept — miner
+policy caps a single transaction at 100 MB.
+
 ## How it works
 
 Content is sealed with your identity key (ECIES) and broadcast as a transaction on BSV via

package/check-generated.mjs

@@ -18,3 +18,30 @@ if (!readFileSync(new URL('./index.mjs', import.meta.url), 'utf8').includes('100
   console.error('Without it an underpaid save is accepted, never mined, and lost hours later.')
   process.exit(1)
 }
+
+// EVERY RELATIVE IMPORT MUST RESOLVE INSIDE THE PACKAGE.
+//
+// 1.4.3 SHIPPED WITH REPOCHAIN COMPLETELY DEAD. repo.mjs imported
+// './spent-ledger-fs.js' and '../src/wallet/spent-ledger.js' — neither was in
+// the package — so every `keychat-save repo ...` exited with ERR_MODULE_NOT_FOUND
+// before doing anything. The two guards above both passed: repo.mjs WAS
+// generated and index.mjs DID have the floor guard. Nothing checked that the
+// package could actually load.
+for (const f of ['repo.mjs', 'index.mjs', 'spent-ledger.js', 'spent-ledger-fs.js']) {
+  let body
+  try { body = readFileSync(new URL(`./${f}`, import.meta.url), 'utf8') } catch { continue }
+  for (const m of body.matchAll(/from\s+'(\.[^']+)'/g)) {
+    try {
+      readFileSync(new URL(m[1], new URL(`./${f}`, import.meta.url)), 'utf8')
+    } catch {
+      console.error(`${f} imports '${m[1]}', which is not in the package.`)
+      console.error('That is what shipped broken in 1.4.3 — the CLI cannot even load.')
+      process.exit(1)
+    }
+  }
+}
+
+// And the guard the other two could not give: actually LOAD the modules. A
+// syntax error in the generated file (a bad cut point produces one) passes
+// every textual check above and still bricks the CLI.
+await import('./repo.mjs')

package/index.mjs

@@ -75,8 +75,8 @@ async function getUnspent (address) {
 // The bridge answers in its own shape when our node can serve the tx:
 //     { outputs: [ { satoshis, script, index } ] }
 // When it CANNOT — the node is pruned with no -txindex, so getrawtransaction fails for
-// any confirmed tx in a discarded block — the web proxy falls back to WhatsOnChain and
-// returns WoC's body untouched:
+// any confirmed tx in a discarded block — the bridge falls through to GorillaPool and
+// the body comes back in the other shape:
 //     { vout: [ { value, n, scriptPubKey: { hex } } ] }
 //
 // Callers looked only at `tx.outputs`, so on the WoC shape they iterated an empty array
@@ -259,6 +259,33 @@ async function cmdSave (label, body) {
   }
   console.log(`  Fee:  ${sum - changeSats} sats / ${rawHex.length / 2} bytes = ${rate.toFixed(2)} sats/KB`)
 
+  // FRESH READ, IN THE SAME COMMAND, IMMEDIATELY BEFORE THE BROADCAST.
+  //
+  // Everything above planned against the getUnspent call at the top of this
+  // function, and that snapshot is now as old as building and signing took.
+  // Another writer on the same key — the KeyChat web app, a second terminal,
+  // a repo snapshot — can have taken an input in that window. Broadcasting
+  // anyway produces a tx that is accepted by some peers, never mined, and gone
+  // hours later: exactly the silent-loss failure the fee floor above guards
+  // against, arriving by a different route.
+  //
+  // THE CHAIN IS THE LEDGER. The bridge verifies every outpoint against the
+  // node's chainstate with include_mempool=true — "is this usable for a new tx
+  // right now" — so anything another writer has already BROADCAST is absent
+  // from this response. No reservation table, no shared state: just look again
+  // before committing.
+  const fresh = await getUnspent(address)
+  const live = new Set(fresh.map(u => `${u.txid}:${u.vout}`))
+  const gone = picked.filter(u => !live.has(`${u.txid}:${u.vout}`))
+  if (gone.length) {
+    throw new Error(
+      `${gone.length} of ${picked.length} input(s) were spent while this save was ` +
+      `being built (first: ${gone[0].txid.slice(0, 16)}…:${gone[0].vout}). ` +
+      `NOT broadcast — it would have been a dead double-spend. Re-run; the ` +
+      `picker will take fresh coins.`
+    )
+  }
+
   const txid = await broadcast(rawHex)
 
   // Prepend new entry to local saves index
@@ -449,6 +476,12 @@ if (cmd === 'init') {
   // RepoChain — whole git repositories on chain, not just session text.
   const { runRepo } = await import('./repo.mjs')
   await runRepo(args)
+} else if (cmd === 'keycloud') {
+  // KeyCloud — a single file on chain, sealed to your own key. Shares repo.mjs
+  // because it shares publish(): the funding-tx pattern, the 100 sats/KB floor,
+  // the self-marker, and the pre-broadcast chain re-read.
+  const { runKeycloud } = await import('./repo.mjs')
+  await runKeycloud(args)
 } else {
   console.log(`keychat-save — Save to BSV blockchain via KeyChat (keychat.pro)
 
@@ -469,6 +502,11 @@ REPOCHAIN — whole git repositories:
   repo estimate <path>          Size and cost, broadcasts nothing
   repo list                     Snapshots taken from this machine
 
+KEYCLOUD — files on chain, sealed to your own key:
+  keycloud put <file>           Upload one file in a single transaction
+  keycloud get <txid> <dest>    Fetch it back (sha256 verified before writing)
+  keycloud list                 Files uploaded from this machine
+
   Each snapshot is ONE transaction. A delta continues the chain automatically and
   carries the ordered txids of every ancestor, so a single txid restores everything.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keychat-save",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Save sessions, files and whole git repositories to the BSV blockchain via KeyChat",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/avaziri93/keychat-save"
+    "url": "git+https://github.com/avaziri93/keychat-save.git"
   },
   "homepage": "https://keychat.pro",
   "scripts": {

package/repo.mjs

@@ -48,6 +48,14 @@ import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { installFileLedger } from './spent-ledger-fs.js'
+import { markSpentOutpoints, withoutSpent, pruneConfirmed, rebuildFromNode } from './spent-ledger.js'
+
+// Share one spent-ledger with keychat-save and every other Node writer on this
+// machine. A repo snapshot and a session save draw from the SAME wallet; a
+// snapshot can spend many seconds building a multi-MB tx, and without this a
+// save started in that window picks the same inputs and dies as a double-spend.
+installFileLedger()
 
 const CONFIG_DIR = path.join(os.homedir(), '.keychat')
 const WIF_PATH = path.join(CONFIG_DIR, 'identity.wif')
@@ -75,14 +83,71 @@ function key () {
 }
 
 // ── bridge ───────────────────────────────────────────────────────
-async function getUnspent (address) {
+async function getUnspent (address, { skipLedger = false } = {}) {
   const res = await fetch(`${BRIDGE}/api/address/${address}/unspent`)
   if (!res.ok) throw new Error(`unspent ${res.status}`)
-  return (await res.json()).map(u => ({
+  const mapped = (await res.json()).map(u => ({
     txid: u.tx_hash || u.txid,
     vout: u.tx_pos ?? u.vout,
     satoshis: u.value ?? u.satoshis
   }))
+  if (skipLedger) return mapped
+  // The node says what exists; the ledger only subtracts coins another writer
+  // has already claimed. Prune each load so it stays the size of what is in
+  // flight rather than growing forever.
+  pruneConfirmed(mapped)
+  return withoutSpent(mapped)
+}
+
+/**
+ * A snapshot that never reached the network still holds its coins. Re-derive
+ * from a fresh node scan rather than un-marking by hand — the node is
+ * authoritative at this moment, and a hand-rolled release can be wrong in the
+ * direction that double-spends. Failure path only.
+ */
+async function releaseLedgerAfterFailure (address) {
+  try {
+    const fresh = await getUnspent(address, { skipLedger: true })
+    const r = rebuildFromNode(fresh)
+    console.warn(`  ledger rebuilt from node: ${r.released} released, ${r.dropped} dropped`)
+  } catch (err) {
+    console.warn(`  could not rebuild ledger: ${err.message}`)
+  }
+}
+
+/**
+ * Thrown when an input we signed was taken before we broadcast. Distinct type
+ * so the caller can rebuild on fresh coins instead of shipping a dead tx.
+ */
+class StaleInputsError extends Error {}
+
+/**
+ * LAST READ BEFORE BROADCAST — are the coins we just signed still ours?
+ *
+ * publish() reads /unspent once at the top and then does real work: planning,
+ * building and signing, tens of seconds for a multi-MB payload. Any other
+ * writer on this key can take an input in that window — most obviously the
+ * browser, whose spent-ledger lives in localStorage and cannot see this
+ * file-backed one. Nothing looked again, so a snapshot could be signed against
+ * coins that were already gone and broadcast dead. That is how 811d165c lost
+ * two of its 76 inputs.
+ *
+ * THE CHAIN IS THE LEDGER HERE, not local state. The bridge's /unspent verifies
+ * every outpoint against the node's chainstate with include_mempool=true —
+ * "is this usable for a new tx right now" — so anything another writer has
+ * BROADCAST is already absent from this response. That is the same read Compute
+ * History reconstructs the whole wallet from. No reservation table needed.
+ *
+ * skipLedger: true is REQUIRED. markSpentOutpoints(picked) has already claimed
+ * these coins in our own ledger, so the filtered view would report every one of
+ * them missing and this check would fire on every single save.
+ *
+ * Returns the outpoints that are gone; empty means clear to broadcast.
+ */
+async function staleInputs (address, picked) {
+  const fresh = await getUnspent(address, { skipLedger: true })
+  const live = new Set(fresh.map(u => `${u.txid}:${u.vout}`))
+  return picked.filter(u => !live.has(`${u.txid}:${u.vout}`))
 }
 
 async function broadcast (rawHex) {
@@ -103,24 +168,36 @@ async function broadcast (rawHex) {
 // 68 MB of hex in the live web server to satisfy a restore is not worth it. A query
 // string makes its isTxBody regex miss, so the request passes straight through.
 //
-// But that same regex miss also skips its WhatsOnChain fallback, which is the only
-// second source we have once a tx is mined. So fall back to the plain path on
-// failure — retrievability beats keeping the proxy cache tidy.
+// The plain path is still tried on failure — retrievability beats keeping the
+// proxy cache tidy. (It used to also carry the proxy's WhatsOnChain fallback;
+// that was removed 2026-08-28, so the third source below is now the only
+// second opinion once a tx is mined.)
 async function getRawHex (txid) {
   // Three sources, in order of sovereignty:
   //   1. bridge ?raw=1  — our node, bypassing the web proxy's forever-cache.
-  //   2. bridge plain   — same node, but with the proxy's WoC fallback behind it.
-  //   3. WoC direct     — last resort, and it earns its place: our node is PRUNED
-  //      with no -txindex, so getrawtransaction CANNOT return a confirmed tx at
-  //      all. Every mined snapshot is therefore unfetchable from us, and with
-  //      only the first two sources a rate-limited proxy made the whole delta
-  //      chain unreplayable — which breaks restore, not just new deltas.
-  // 429 gets a backoff rather than being treated as absence; hammering a closed
-  // limiter is what turned a transient failure into a hard one.
+  //   2. bridge plain   — same node; the bridge itself falls through to GP.
+  //   3. GorillaPool raw — last resort, and it earns its place: our node is
+  //      PRUNED with no -txindex, so getrawtransaction CANNOT return a
+  //      confirmed tx at all. Every mined snapshot is unfetchable from us
+  //      directly, and without a third source a rate-limited proxy made the
+  //      whole delta chain unreplayable — which breaks restore, not just new
+  //      deltas.
+  //
+  // WAS WhatsOnChain until 2026-08-28. WoC TRUNCATES LARGE SCRIPTS, and this
+  // function fetches repo snapshots — the multi-MB transactions most likely to
+  // be cut short. A truncated body does not error; it decrypts to garbage or
+  // fails a hash check, so the failure surfaces as a corrupt restore rather
+  // than a fetch error. It also throttled at ~3 req/s, and the responses that
+  // lost were the biggest ones. GP serves the same transactions whole and
+  // faster — measured: a 4.8 MB snapshot in 3.4s.
+  //
+  // GP returns raw BYTES, so convert rather than reading text as hex.
+  // 429 still gets a backoff rather than being treated as absence; hammering a
+  // closed limiter is what turned a transient failure into a hard one.
   const urls = [
     `${BRIDGE}/api/tx/${txid}/hex?raw=1`,
     `${BRIDGE}/api/tx/${txid}/hex`,
-    `https://api.whatsonchain.com/v1/bsv/main/tx/${txid}/hex`
+    `https://ordinals.gorillapool.io/api/tx/${txid}/raw`
   ]
   let wait = 500
   for (let attempt = 0; attempt < 3; attempt++) {
@@ -129,6 +206,15 @@ async function getRawHex (txid) {
       try { res = await fetch(url) } catch { continue }
       if (res.status === 429) { await new Promise(r => setTimeout(r, wait)); continue }
       if (!res.ok) continue
+      // GP's /raw returns BINARY tx bytes, not hex text. Reading it with
+      // .text() yields mojibake that fails the hex test below, so the source
+      // would silently never work — a fallback that is present but dead is
+      // worse than no fallback, because nothing tells you.
+      if (url.endsWith('/raw')) {
+        const h = Buffer.from(await res.arrayBuffer()).toString('hex')
+        if (h && /^[0-9a-f]+$/i.test(h)) return h
+        continue
+      }
       const ct = res.headers.get('content-type') || ''
       const data = ct.includes('json') ? await res.json() : await res.text()
       const h = (typeof data === 'string' ? data.replace(/"/g, '').trim() : data.hex)
@@ -137,7 +223,7 @@ async function getRawHex (txid) {
     wait = Math.min(wait * 4, 8000)
     await new Promise(r => setTimeout(r, wait))
   }
-  throw new Error(`cannot fetch raw tx ${txid} from node, bridge or WoC`)
+  throw new Error(`cannot fetch raw tx ${txid} from node, bridge or GorillaPool`)
 }
 
 // ── OP_RETURN ────────────────────────────────────────────────────
@@ -347,6 +433,29 @@ function planFunding (utxos, target) {
 // delta small enough to skip it has nothing to lose.
 const DIRECT_MAX_INPUTS = 60
 
+/**
+ * publish(), retried on fresh coins if an input was taken mid-build.
+ *
+ * Re-entering publish() re-reads /unspent from the top, so the rebuild plans
+ * against the current chain rather than the snapshot that just went stale. The
+ * payload script is unchanged — only the funding is re-planned — so a retry
+ * costs a rebuild and a re-sign, never a different snapshot.
+ *
+ * Bounded at 3 attempts. If coins are being taken out from under us that
+ * persistently, something else is wrong and looping would just burn fees.
+ */
+async function publishWithRetry (scriptHex, k, address, lockingScript, opts = {}) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return await publish(scriptHex, k, address, lockingScript, opts)
+    } catch (err) {
+      if (!(err instanceof StaleInputsError) || attempt >= 3) throw err
+      console.log(`\n  ${err.message}`)
+      console.log(`  rebuilding on fresh coins (attempt ${attempt + 1}/3) ...\n`)
+    }
+  }
+}
+
 /** Broadcast one OP_RETURN payload, funding it whichever way is cheaper. */
 async function publish (scriptHex, k, address, lockingScript, { dry = false } = {}) {
   const opReturn = Script.fromHex(scriptHex)
@@ -403,6 +512,17 @@ async function publish (scriptHex, k, address, lockingScript, { dry = false } =
     console.log(`payload tx    ${(bytes / 1024).toFixed(1)} KB, ${n} inputs, ` +
       `fee ${fee} sats = ${fee / SATS_PER_COMPUTE} Compute (single tx, ${rate.toFixed(2)} sats/KB)`)
     if (dry) return { txid: tx.id('hex'), funding: null, cost: fee / SATS_PER_COMPUTE, dry: true }
+    // Same fresh read as the two-tx path below. This path claims nothing in the
+    // ledger, so the inputs are simply the ones we built with.
+    process.stdout.write('re-checking inputs ... ')
+    const goneDirect = await staleInputs(address, utxos.slice(0, n))
+    if (goneDirect.length) {
+      console.log(`${goneDirect.length} of ${n} TAKEN`)
+      throw new StaleInputsError(
+        `${goneDirect.length} input(s) were spent while this tx was being built ` +
+        `(first: ${goneDirect[0].txid.slice(0, 16)}…:${goneDirect[0].vout})`)
+    }
+    console.log(`${n}/${n} still live`)
     process.stdout.write('broadcasting ... ')
     const txid = await broadcast(tx.toHex())
     console.log(txid)
@@ -431,6 +551,11 @@ async function publish (scriptHex, k, address, lockingScript, { dry = false } =
   const fundingValue = payloadFee + SELF_MARKER_SATS
   const { picked, sum: fsum, need } = planFunding(utxos, fundingValue)
   const fundFee = need - fundingValue
+  // Claim the inputs before signing. A multi-MB payload can spend tens of
+  // seconds in sign(), and any save started in that window would otherwise
+  // pick the very same coins. Released below on every path that does not
+  // broadcast the funding tx.
+  markSpentOutpoints(picked)
   console.log(`payload tx    ${(payloadBytes / 1048576).toFixed(2)} MB, ` +
     `fee ${payloadFee} sats = ${payloadFee / SATS_PER_COMPUTE} Compute`)
   console.log(`funding tx    ${picked.length} inputs, fee ${fundFee} sats`)
@@ -458,18 +583,49 @@ async function publish (scriptHex, k, address, lockingScript, { dry = false } =
 
   // Both must clear the floor BEFORE either goes out. Broadcasting the funding tx and
   // then discovering the payload is underpaid strands the fee in a spent output.
-  assertFeeRate(fundTx, fundFee, 'funding tx')
-  // Miner receives the funding value MINUS the marker — check the floor against
-  // what the miner actually gets, not against what the tx consumes.
-  assertFeeRate(payTx, fundingValue - SELF_MARKER_SATS, 'payload tx')
+  try {
+    assertFeeRate(fundTx, fundFee, 'funding tx')
+    // Miner receives the funding value MINUS the marker — check the floor against
+    // what the miner actually gets, not against what the tx consumes.
+    assertFeeRate(payTx, fundingValue - SELF_MARKER_SATS, 'payload tx')
+  } catch (err) {
+    await releaseLedgerAfterFailure(address)
+    throw err
+  }
 
   if (dry) {
+    // Nothing goes to the network on a dry run, so the coins are still ours.
+    await releaseLedgerAfterFailure(address)
     return { txid: payTx.id('hex'), funding: fundTx.id('hex'), cost: (fundingValue + fundFee) / SATS_PER_COMPUTE, dry: true }
   }
+  // FRESH READ, IN THE SAME COMMAND, IMMEDIATELY BEFORE THE BROADCAST.
+  // Everything above this line is planning against a snapshot that is now as
+  // old as the signing took. Ask the chain once more before committing.
+  process.stdout.write('re-checking inputs ... ')
+  const gone = await staleInputs(address, picked)
+  if (gone.length) {
+    console.log(`${gone.length} of ${picked.length} TAKEN`)
+    await releaseLedgerAfterFailure(address)
+    throw new StaleInputsError(
+      `${gone.length} input(s) were spent while this tx was being built ` +
+      `(first: ${gone[0].txid.slice(0, 16)}…:${gone[0].vout})`)
+  }
+  console.log(`${picked.length}/${picked.length} still live`)
+
   process.stdout.write('broadcasting funding tx ... ')
-  const ftx = await broadcast(fundTx.toHex())
+  let ftx
+  try {
+    ftx = await broadcast(fundTx.toHex())
+  } catch (err) {
+    // Funding never left, so `picked` is still ours.
+    await releaseLedgerAfterFailure(address)
+    throw err
+  }
   console.log(ftx)
   process.stdout.write('broadcasting payload tx ... ')
+  // Deliberately NO release if the payload fails: the funding tx is already on
+  // the network, so `picked` is genuinely spent. Releasing here would hand the
+  // picker coins that are gone — the one direction that double-spends.
   const ptx = await broadcast(payTx.toHex())
   console.log(ptx)
   return { txid: ptx, funding: ftx, cost: (fundingValue + fundFee) / SATS_PER_COMPUTE }
@@ -584,7 +740,7 @@ async function backup (repoPath, { dry = false } = {}) {
     sha256: sha, manifestRoot, tarSize: tar.length, at: Math.floor(Date.now() / 1000)
   }
   const scriptHex = sealPayload(meta, tar, k, pubHex)
-  const res = await publish(scriptHex, k, address, lockingScript, { dry })
+  const res = await publishWithRetry(scriptHex, k, address, lockingScript, { dry })
   if (dry) {
     console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}` +
       (res.funding ? `\n  funding ${res.funding}` : ''))
@@ -677,7 +833,7 @@ async function delta (repoPath, baseTxid, { dry = false } = {}) {
     manifestRoot: curM.root, tarSize: tar.length, at: Math.floor(Date.now() / 1000)
   }
   const scriptHex = sealPayload(meta, tar, k, pubHex)
-  const res = await publish(scriptHex, k, address, lockingScript, { dry })
+  const res = await publishWithRetry(scriptHex, k, address, lockingScript, { dry })
   if (dry) {
     console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}`)
     return
@@ -723,6 +879,145 @@ async function restore (txid, dest) {
   console.log(`restored to ${path.join(dest, name)}`)
 }
 
+// ── KeyCloud ─────────────────────────────────────────────────────
+// ONE FILE, ONE TRANSACTION, SEALED TO YOUR OWN KEY.
+//
+// KeyCloud is personal storage, not messaging: the file is encrypted to the
+// wallet's OWN public key, so only this identity can ever read it back. It
+// reuses publish() wholesale — the funding-tx pattern, the 100 sats/KB floor,
+// the self-marker, and the pre-broadcast chain re-read — because a second copy
+// of that machinery is precisely how getTx and getRawTxHex drifted apart.
+//
+// KCLD, NOT KSAV OR KREP. A distinct prefix keeps files out of `load` (which
+// would otherwise decrypt every upload into saves.json and then carry it in
+// every future bootstrap table) and out of `repo list`. Same reason KREP was
+// split from KSAV in the first place.
+//
+// RAW BYTES. The file is framed and encrypted directly, never base64 — that
+// 33% tax is real money here: at 100 sats/KB a 10 MB file is ~2,000 Compute,
+// so base64 alone would cost ~660 Compute extra per upload.
+//
+// SIZE. Single tx up to the miner policy ceiling — GorillaPool and TAAL both
+// publish maxtxsizepolicy=100,000,000, and 33.87 MB repo snapshots already go
+// on chain whole this way. Our own bitcoind runs maxscriptsizepolicy=6000000
+// and will not relay past 6 MB itself; ARC carries those and the node picks
+// them up when mined. Above the ceiling the file must be chunked — see the
+// KACH chunk+manifest format in src/messages/attachment.js, whose receive side
+// already exists. put refuses rather than guessing, so nothing is spent on a
+// transaction no miner will accept.
+const CLOUD_PREFIX = '4b434c44' // "KCLD"
+const CLOUD_INDEX = 'keycloud.json'
+// Policy ceiling for a single transaction. The payload is the whole tx, so this
+// is deliberately conservative against the published 100 MB: envelope, ECIES
+// overhead and the funding input all sit inside the same limit.
+const CLOUD_MAX_SINGLE_TX = 95 * 1024 * 1024
+
+function recordCloudFile (rec) {
+  const idx = path.join(CONFIG_DIR, CLOUD_INDEX)
+  let all = []
+  try { all = JSON.parse(fs.readFileSync(idx, 'utf8')) } catch {}
+  all.push(rec)
+  fs.writeFileSync(idx, JSON.stringify(all, null, 2), 'utf8')
+}
+
+/** Upload one file to chain, sealed to this wallet's own key. */
+async function cloudPut (filePath, { dry = false } = {}) {
+  if (!filePath) throw new Error('usage: keycloud put <file>')
+  const abs = path.resolve(filePath)
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
+    throw new Error(`not a file: ${abs}`)
+  }
+  const k = key()
+  const address = k.toPublicKey().toAddress()
+  const pubHex = k.toPublicKey().toString()
+  const lockingScript = new P2PKH().lock(address)
+
+  const bytes = fs.readFileSync(abs)
+  if (bytes.length > CLOUD_MAX_SINGLE_TX) {
+    throw new Error(
+      `${(bytes.length / 1048576).toFixed(1)} MB exceeds the ${CLOUD_MAX_SINGLE_TX / 1048576} MB ` +
+      `single-transaction ceiling. Chunked upload (KACH manifest) is not wired into this ` +
+      `command yet — nothing was spent.`)
+  }
+  const sha = createHash('sha256').update(bytes).digest('hex')
+  const meta = {
+    v: 1,
+    kind: 'file',
+    name: path.basename(abs),
+    size: bytes.length,
+    sha256: sha,
+    at: Math.floor(Date.now() / 1000)
+  }
+  console.log(`${meta.name}  ${(bytes.length / 1048576).toFixed(2)} MB`)
+  console.log(`sha256   ${sha}`)
+
+  process.stdout.write('encrypting ... ')
+  const t = Date.now()
+  const cipher = EncryptedMessage.encrypt(
+    Array.from(framePayload(meta, bytes)), k, PublicKey.fromString(pubHex)
+  )
+  console.log(`${((Date.now() - t) / 1000).toFixed(1)}s`)
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0')
+  const scriptHex = buildOpReturn([CLOUD_PREFIX, VERSION, pubHex, hex(cipher), timestamp])
+
+  const res = await publishWithRetry(scriptHex, k, address, lockingScript, { dry })
+  if (dry) {
+    console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}` +
+      (res.funding ? `\n  funding ${res.funding}` : ''))
+    return
+  }
+  recordCloudFile({ txid: res.txid, funding: res.funding, ...meta, cost: res.cost })
+  console.log(`\nKEYCLOUD ${meta.name} -> ${res.txid}`)
+  console.log(`get with: keychat-save keycloud get ${res.txid} <dest>`)
+}
+
+/**
+ * Fetch one KCLD file back and write it to dest.
+ *
+ * Verifies the sha256 recorded at upload before writing anything. That check is
+ * not ceremony: getRawHex falls through to a third party for anything our
+ * pruned node cannot serve, and a TRUNCATED body does not error — it decrypts
+ * to garbage. The hash is what turns that into a failure instead of a corrupt
+ * file on disk.
+ */
+async function cloudGet (txid, dest) {
+  if (!/^[0-9a-f]{64}$/.test(txid || '')) throw new Error('usage: keycloud get <txid> <dest>')
+  const k = key()
+  const pubHex = k.toPublicKey().toString()
+  const rawHex = await getRawHex(txid)
+  const tx = Transaction.fromHex(rawHex)
+  let parts = null
+  for (const o of tx.outputs) {
+    const s = o.lockingScript.toHex()
+    if (s.startsWith('006a') || s.startsWith('6a')) { parts = extractParts(s); break }
+  }
+  if (!parts || parts[0] !== CLOUD_PREFIX) throw new Error(`${txid} is not a KCLD keycloud transaction`)
+  if (parts[2] !== pubHex) throw new Error(`${txid} is not encrypted to this identity`)
+  const plain = Buffer.from(EncryptedMessage.decrypt(Array.from(Buffer.from(parts[3], 'hex')), k))
+  const { meta, tar: bytes } = unframePayload(plain)
+
+  const got = createHash('sha256').update(bytes).digest('hex')
+  if (meta.sha256 && got !== meta.sha256) {
+    throw new Error(`sha256 mismatch — expected ${meta.sha256}, got ${got}. NOT written.`)
+  }
+  // A bare directory means "put it back under its own name".
+  let out = path.resolve(dest || '.')
+  if (fs.existsSync(out) && fs.statSync(out).isDirectory()) out = path.join(out, meta.name)
+  fs.writeFileSync(out, bytes)
+  console.log(`${meta.name}  ${(bytes.length / 1048576).toFixed(2)} MB  sha256 ok`)
+  console.log(`wrote ${out}`)
+}
+
+function cloudList () {
+  let all = []
+  try { all = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, CLOUD_INDEX), 'utf8')) } catch {}
+  if (!all.length) return console.log('no keycloud files recorded locally')
+  for (const r of all.sort((a, b) => b.at - a.at)) {
+    console.log(`${new Date(r.at * 1000).toISOString().slice(0, 10)}  ${String(r.name).padEnd(28)} ` +
+      `${(r.size / 1048576).toFixed(2)} MB  ${r.cost}C  ${r.txid}`)
+  }
+}
+
 function list () {
   let all = []
   try { all = JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, 'repos.json'), 'utf8')) } catch {}
@@ -755,3 +1050,24 @@ export async function runRepo (argv) {
   console.log('  keychat-save repo list')
   process.exitCode = 1
 }
+
+/**
+ * CLI entry for the keycloud commands, called from index.mjs.
+ *
+ * Shares this module with runRepo on purpose: KeyCloud uses the same publish()
+ * — funding-tx pattern, 100 sats/KB floor, self-marker, pre-broadcast chain
+ * re-read. A separate module would mean a second copy of that machinery.
+ */
+export async function runKeycloud (argv) {
+  const [sub, ...rest] = argv
+  const dry = rest.includes('--dry')
+  const args = rest.filter(x => !x.startsWith('--'))
+  if (sub === 'put') return cloudPut(args[0], { dry })
+  if (sub === 'get') return cloudGet(args[0], args[1])
+  if (sub === 'list') return cloudList()
+  console.log('usage:')
+  console.log('  keychat-save keycloud put  <file> [--dry]   one tx, sealed to your own key')
+  console.log('  keychat-save keycloud get  <txid> <dest>')
+  console.log('  keychat-save keycloud list')
+  process.exitCode = 1
+}

package/spent-ledger-fs.js

@@ -0,0 +1,49 @@
+// File-backed store for the shared spent-ledger, for every Node entry point:
+// the bot, keychat-save, keychat-repo.
+//
+// The browser keeps its ledger in localStorage; Node has no localStorage (and
+// the bot's shim discards writes), so anything running outside a browser must
+// install this before it spends.
+//
+// WHAT SHARING THIS FILE BUYS
+// Every Node process on one machine reads and writes the same ledger, so a
+// repo snapshot cannot pick the coin a session save just claimed, and neither
+// can pick one the other is mid-broadcast on. That is the "failed saves while
+// the app is also sending" case: two writers, one wallet, one pool.
+//
+// WHERE IT STOPS
+// A browser cannot write to ~/.keychat, so the app's ledger and this one are
+// separate stores. Contention BETWEEN the app and a CLI is still arbitrated by
+// the node alone — which is sufficient there only because a person switching
+// between the app and a terminal takes seconds, against a measured node lag of
+// 10-65ms. It is the sub-100ms machine-speed case that needs a ledger, and
+// that only ever happens within one process or between two Node ones.
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { setLedgerBackend } from './spent-ledger.js'
+
+const LEDGER = process.env.KC_SPENT_LEDGER ||
+  path.join(os.homedir(), '.keychat', 'spent-ledger.json')
+
+export const fileBackend = {
+  read () {
+    try { return JSON.parse(fs.readFileSync(LEDGER, 'utf8')) } catch { return {} }
+  },
+  // Temp file + rename: a crash mid-write must not leave truncated JSON, since
+  // a failed parse falls back to {} and would silently un-spend everything.
+  write (m) {
+    fs.mkdirSync(path.dirname(LEDGER), { recursive: true })
+    const tmp = `${LEDGER}.${process.pid}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(m))
+    fs.renameSync(tmp, LEDGER)
+  }
+}
+
+/** Point the shared ledger at the filesystem. Call once, before any spend. */
+export function installFileLedger () {
+  setLedgerBackend(fileBackend)
+  return LEDGER
+}
+
+export const LEDGER_PATH = LEDGER

package/spent-ledger.js

@@ -0,0 +1,195 @@
+// Durable spent-ledger for every KeyChat picker.
+//
+// THE PROBLEM IT SOLVES
+// Two sends fired back-to-back spend the same coin. Measured on 2026-08-28
+// against the bot, which sends twice per reply (the message, then the self-CC
+// copy 0.1ms later): our own node takes 10-65ms to report the first tx's
+// inputs as spent. The second send asks "what can I spend?" inside that
+// window, gets a stale-but-honest answer, and because every Compute piece is
+// exactly 500 sats and the picker is largest-first, it deterministically picks
+// THE SAME COIN. Two txs spending one input; the network keeps one, the other
+// dies silently.
+//
+// The client hits the same thing on any paired flow — delete then
+// re-introduce, accept then auto-reply — which is what caused the 2026-06-02
+// "intros not broadcasting" incident.
+//
+// No amount of node-side correctness fixes this. The node is not wrong, it is
+// BEHIND, and we ask faster than any index can update.
+//
+// THE FIX
+// Record the spend locally AT PICK TIME, before the tx is even signed. The
+// next pick reads this ledger, not the network, so the race has nowhere to
+// happen. This replaces the old in-memory recentlySpent map, whose TTL was an
+// arbitrary constant (10s in the client, 60s on the bot) tuned against a lag
+// nobody had measured — and which was lost entirely on reload or restart.
+//
+// DIRECTIONALITY — this file may only ever REMOVE coins from the pool.
+// Nothing enters the pool from here; the node decides what exists and what is
+// confirmed. A stale flag costs one coin, which is recoverable. Resurrecting a
+// coin the chain has already seen spent is a double-spend, which is not.
+//
+// The ONE way a flag is cleared is rebuildFromNode(), and only after a
+// broadcast FAILED — see that function for why it must never run on success.
+//
+// STORAGE IS INJECTABLE AND MUST BE SYNCHRONOUS. Async storage (IndexedDB)
+// would re-open the very window this closes: the write has to land before the
+// next pick reads. Browser uses localStorage; the bot installs a file-backed
+// store at boot, because its localStorage shim discards writes.
+
+const KEY = 'keychat-spent-ledger'
+
+const localStorageBackend = {
+  read () {
+    try { return JSON.parse(localStorage.getItem(KEY) || '{}') } catch { return {} }
+  },
+  write (m) {
+    try { localStorage.setItem(KEY, JSON.stringify(m)) } catch { /* quota — see prune note */ }
+  }
+}
+
+// A Web Worker has NO localStorage. The send worker imports sendMessage, so it
+// reaches this module — and a backend that silently discards writes there would
+// be WORSE than the in-memory map this replaced, which at least worked inside
+// the worker's own session. So when there is no localStorage, fall back to
+// memory rather than to nothing.
+//
+// The worker still echoes its spentOutpoints to the main thread, which mirrors
+// them into the durable ledger (see workers/send-worker.js) — that is what
+// makes a worker send visible to the next main-thread send. This fallback only
+// has to cover picks made back-to-back INSIDE one worker.
+function makeMemoryBackend () {
+  let store = {}
+  return { read: () => store, write: (m) => { store = m } }
+}
+
+function defaultBackend () {
+  try {
+    if (typeof localStorage === 'undefined') return makeMemoryBackend()
+    // Availability is not the same as usability — Safari private mode throws
+    // on setItem rather than on access. Probe once, at load.
+    const probe = '__kc_ledger_probe__'
+    localStorage.setItem(probe, '1')
+    localStorage.removeItem(probe)
+    return localStorageBackend
+  } catch {
+    return makeMemoryBackend()
+  }
+}
+
+let backend = defaultBackend()
+
+/**
+ * Install a different synchronous store. The bot calls this with an fs-backed
+ * implementation before importing anything that spends. Must expose
+ * read(): object and write(object): void, both synchronous.
+ */
+export function setLedgerBackend (b) { backend = b }
+
+const op = (txid, vout) => `${txid}:${vout}`
+
+/**
+ * Mark outpoints spent so no picker hands them out again. Call at PICK time,
+ * not after broadcast — the whole point is to beat the node, and a
+ * post-broadcast write is already too late for the very next send.
+ */
+export function markSpentOutpoints (utxos) {
+  const m = backend.read()
+  const ts = Math.floor(Date.now() / 1000)
+  for (const u of utxos) m[op(u.txid, u.vout)] = ts
+  backend.write(m)
+}
+
+/** True if the ledger has recorded this outpoint as spent. */
+export function isSpentOutpoint (txid, vout) {
+  return backend.read()[op(txid, vout)] !== undefined
+}
+
+/**
+ * Filter a node-supplied UTXO list down to what the ledger still considers
+ * unspent. One read for the whole list rather than per-entry.
+ */
+export function withoutSpent (utxos) {
+  const m = backend.read()
+  // FAST PATH — nothing claimed means nothing to filter, so do no work at all.
+  // This runs on every getUnspent, which the balance poll calls every 5s, on
+  // the main thread, against a wallet that can hold tens of thousands of
+  // UTXOs. Building a key string per UTXO there stalls the tab; the ledger
+  // meanwhile is empty or holds a handful of in-flight outpoints. Cost must
+  // scale with the LEDGER, not the wallet.
+  if (isEmpty(m)) return utxos
+  return utxos.filter(u => m[op(u.txid, u.vout)] === undefined)
+}
+
+// Emptiness without allocating an Object.keys array.
+function isEmpty (m) {
+  for (const _k in m) return false
+  return true
+}
+
+/**
+ * Drop entries the node no longer lists — they are confirmed spent, gone from
+ * /unspent forever, and their flags are dead weight. Runs on every load so the
+ * ledger stays the size of what is actually in flight (a handful of outpoints)
+ * rather than growing for the life of the wallet.
+ *
+ * SAFE ON THE SUCCESS PATH, unlike rebuildFromNode: this only ever forgets
+ * coins the node has already dropped, so it cannot hand a spent coin back to
+ * the picker. It never touches an entry the node still lists — that is exactly
+ * the in-flight case the ledger exists to remember.
+ *
+ * Writes only when something actually changed, so the common no-op load costs
+ * one read.
+ */
+export function pruneConfirmed (nodeUtxos) {
+  const m = backend.read()
+  // Same reasoning as withoutSpent: with an empty ledger there is nothing to
+  // prune, and building a Set over every UTXO the wallet owns to discover that
+  // is the expensive way to do nothing.
+  if (isEmpty(m)) return 0
+  const live = new Set(nodeUtxos.map(u => op(u.txid, u.vout)))
+  let removed = 0
+  for (const k of Object.keys(m)) {
+    if (!live.has(k)) { delete m[k]; removed++ }
+  }
+  if (removed) backend.write(m)
+  return removed
+}
+
+/**
+ * Re-derive the ledger from a FRESH scan of the node's UTXO set.
+ *
+ * Anything the node still lists is un-marked; anything it no longer lists is
+ * dropped, since a confirmed spend is gone from /unspent forever and its flag
+ * is dead weight. So one call both releases the coins a failed send stranded
+ * AND keeps the ledger from growing over the wallet's lifetime.
+ *
+ * CALL THIS ONLY AFTER A BROADCAST FAILED. On the success path the node is
+ * still 10-65ms behind and WOULD list the inputs we just legitimately spent —
+ * rebuilding there hands them back to the picker and re-creates the exact
+ * double-spend this module exists to prevent. Failure is the only moment we
+ * know the node's view is the correct one.
+ *
+ * Clearing both cases is safe because the picker's pool IS the node's list and
+ * this ledger only subtracts from it: a coin the node has dropped cannot be
+ * picked whether or not we remember it. The one residual is a coin from an
+ * earlier SUCCESSFUL send the node has not caught up on — which is why this is
+ * failure-only, and why the failing broadcast's own round-trip (~86ms observed
+ * between paired sends, against 10-65ms of node lag) is what covers it.
+ *
+ * `nodeUtxos` must come from the node, not from any cache.
+ */
+export function rebuildFromNode (nodeUtxos) {
+  const live = new Set(nodeUtxos.map(u => op(u.txid, u.vout)))
+  const m = backend.read()
+  let released = 0   // node still lists it -> our send never landed, give it back
+  let dropped = 0    // node no longer lists it -> confirmed spent, flag is dead
+  for (const k of Object.keys(m)) {
+    if (live.has(k)) released++; else dropped++
+    delete m[k]
+  }
+  backend.write(m)
+  return { released, dropped }
+}
+
+export function ledgerSize () { return Object.keys(backend.read()).length }