keychat-save 1.4.3 → 1.6.0

package/README.md

@@ -83,6 +83,56 @@ 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
+
+# Publish identifiers for everything already on chain — see below
+keychat-save keycloud catalog
+```
+
+### Listing without downloading
+
+Metadata travels in its own encrypted push, separate from the file. A listing
+therefore costs kilobytes: names, sizes and image thumbnails are read without
+moving a single file body, and the bodies are fetched only when you open one.
+
+Anything uploaded before that split has its metadata sealed inside its own body,
+so listing it the old way meant downloading it. `keycloud catalog` fixes that in
+one small transaction: it publishes the identifiers you already hold locally —
+names, sizes, hashes, and your RepoChain snapshots too — encrypted to your key.
+Any device with that key then lists your whole history for a few KB. Cataloguing
+51 items cost 2 Compute.
+
+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

@@ -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,14 @@ 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
+  keycloud catalog              Publish identifiers for everything already on
+                                chain, so any device can list it without
+                                downloading a single file
+
   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.3",
+  "version": "1.6.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

@@ -49,7 +49,7 @@ 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 '../src/wallet/spent-ledger.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
@@ -115,6 +115,41 @@ async function releaseLedgerAfterFailure (address) {
   }
 }
 
+/**
+ * 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) {
   const res = await fetch(`${BRIDGE}/api/broadcast`, {
     method: 'POST',
@@ -398,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)
@@ -454,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)
@@ -529,6 +598,20 @@ async function publish (scriptHex, k, address, lockingScript, { dry = false } =
     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 ... ')
   let ftx
   try {
@@ -657,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}` : ''))
@@ -750,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
@@ -796,6 +879,293 @@ 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'
+// v2 SPLITS METADATA OUT OF THE FILE'S CIPHERTEXT.
+//
+//   v1  [KCLD, 01, pub, encrypt(meta + bytes),            ts]
+//   v2  [KCLD, 02, pub, encrypt(meta), encrypt(bytes),    ts]
+//
+// v1 sealed the filename INSIDE the file's own ciphertext, so listing what you
+// own meant fetching and decrypting every byte you had ever uploaded — ten
+// 10 MB files is a 100 MB download to draw ten labels. A file browser is not
+// buildable on that.
+//
+// In v2 the meta push is a few hundred bytes plus an optional thumbnail, so the
+// bridge can index and serve it alone and the client renders a whole grid
+// without touching a single file body. The bytes are fetched only when someone
+// opens something.
+//
+// BOTH PUSHES STAY ENCRYPTED to the owner's key. Filenames never appear in
+// plaintext on chain — the point is that only the holder of the key learns
+// anything, and a filename is often the most revealing part of a file.
+//
+// v1 files stay readable: cloudGet accepts either shape.
+const CLOUD_VERSION_V1 = '01'
+const CLOUD_VERSION = '02'
+// 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
+
+const MIME_BY_EXT = {
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+  '.webp': 'image/webp', '.heic': 'image/heic', '.tiff': 'image/tiff', '.bmp': 'image/bmp',
+  '.pdf': 'application/pdf', '.txt': 'text/plain', '.md': 'text/markdown',
+  '.json': 'application/json', '.csv': 'text/csv', '.zip': 'application/zip',
+  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.mp3': 'audio/mpeg', '.wav': 'audio/wav'
+}
+const mimeFor = name => MIME_BY_EXT[path.extname(name).toLowerCase()] || 'application/octet-stream'
+
+/**
+ * A 256px JPEG preview, base64, for the file grid to render without ever
+ * fetching the original — the same reason Finder feels instant.
+ *
+ * Uses `sips`, which ships with macOS, rather than adding an image dependency
+ * to a package whose only dep is @bsv/sdk. Every failure path returns null and
+ * the grid falls back to a type icon: a missing thumbnail must never be able to
+ * fail an upload.
+ */
+function makeThumb (abs, mime) {
+  if (!mime.startsWith('image/')) return null
+  const tmp = path.join(TMP, `kcthumb-${Math.random().toString(36).slice(2)}.jpg`)
+  try {
+    sh('sips', ['-Z', '256', '-s', 'format', 'jpeg', '-s', 'formatOptions', '60', abs, '--out', tmp],
+      { stdio: 'ignore' })
+    const b = fs.readFileSync(tmp)
+    // Sanity bound: a "thumbnail" bigger than this is not a thumbnail, and it
+    // would bloat the very push that exists to stay small.
+    return b.length > 64 * 1024 ? null : b.toString('base64')
+  } catch {
+    return null
+  } finally {
+    try { fs.unlinkSync(tmp) } catch { /* never existed */ }
+  }
+}
+
+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 name = path.basename(abs)
+  const mime = mimeFor(name)
+  const thumb = makeThumb(abs, mime)
+  const meta = {
+    v: 2,
+    kind: 'file',
+    name,
+    size: bytes.length,
+    sha256: sha,
+    mime,
+    at: Math.floor(Date.now() / 1000),
+    ...(thumb ? { thumb } : {})
+  }
+  console.log(`${name}  ${(bytes.length / 1048576).toFixed(2)} MB  ${mime}` +
+    (thumb ? `  thumb ${(Buffer.byteLength(thumb, 'base64') / 1024).toFixed(1)} KB` : ''))
+  console.log(`sha256   ${sha}`)
+
+  process.stdout.write('encrypting ... ')
+  const t = Date.now()
+  const pub = PublicKey.fromString(pubHex)
+  // TWO PUSHES. The meta push is what the bridge indexes and the file grid
+  // reads; the file push is fetched only when someone opens the file. Both are
+  // sealed to the same key — a filename is often the most revealing part of a
+  // file, so it never travels in plaintext.
+  const metaCipher = EncryptedMessage.encrypt(
+    Array.from(Buffer.from(JSON.stringify(meta), 'utf8')), k, pub
+  )
+  const fileCipher = EncryptedMessage.encrypt(Array.from(bytes), k, pub)
+  console.log(`${((Date.now() - t) / 1000).toFixed(1)}s  ` +
+    `meta ${(metaCipher.length / 1024).toFixed(1)} KB, file ${(fileCipher.length / 1048576).toFixed(2)} MB`)
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0')
+  const scriptHex = buildOpReturn(
+    [CLOUD_PREFIX, CLOUD_VERSION, pubHex, hex(metaCipher), hex(fileCipher), 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`)
+
+  // BOTH SHAPES. v1 sealed meta and bytes in one ciphertext; v2 splits them so
+  // the meta can be indexed and listed without moving the file. Files uploaded
+  // before the split must keep opening — the version byte says which is which.
+  const dec = p => Buffer.from(EncryptedMessage.decrypt(Array.from(Buffer.from(p, 'hex')), k))
+  let meta, bytes
+  if (parts[1] === CLOUD_VERSION_V1) {
+    ({ meta, tar: bytes } = unframePayload(dec(parts[3])))
+  } else {
+    meta = JSON.parse(dec(parts[3]).toString('utf8'))
+    bytes = dec(parts[4])
+  }
+
+  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}`)
+}
+
+/**
+ * Publish a CATALOG: one small transaction carrying identifiers for things
+ * already on chain.
+ *
+ * The backfill problem: everything uploaded before the v2 split sealed its
+ * metadata inside its own body, so listing a v1 item means downloading it —
+ * 34 MB to read a repo name. The bridge cannot help, because it cannot decrypt.
+ * Re-uploading to get v2 metadata would cost thousands of Compute.
+ *
+ * Arash's fix, and it is the right one: send the IDENTIFIERS as their own
+ * delta. We already hold every name, size and hash in the local indexes
+ * (repos.json, keycloud.json) — the expensive part was only ever getting them
+ * back OUT of chain. One catalog transaction publishes the lot, encrypted to
+ * the same key, and any device can then list a full history without moving a
+ * single body.
+ *
+ * Shipped AS a KCLD v2 envelope on purpose: the bridge already indexes those
+ * and serves their meta push, so this needs no new prefix, no new endpoint and
+ * no new indexer. `kind: 'catalog'` tells a reader to merge the entries rather
+ * than render a file.
+ */
+async function cloudCatalog ({ dry = false } = {}) {
+  const k = key()
+  const address = k.toPublicKey().toAddress()
+  const pubHex = k.toPublicKey().toString()
+  const lockingScript = new P2PKH().lock(address)
+
+  const read = f => { try { return JSON.parse(fs.readFileSync(path.join(CONFIG_DIR, f), 'utf8')) } catch { return [] } }
+  const entries = []
+  for (const r of read('repos.json')) {
+    if (!r.txid) continue
+    entries.push({ t: r.txid, k: 'repo', n: r.repo, h: r.head, s: r.tarSize ?? null, a: r.at ?? null, c: r.cost ?? null })
+  }
+  for (const f of read(CLOUD_INDEX)) {
+    if (!f.txid) continue
+    entries.push({ t: f.txid, k: 'file', n: f.name, m: f.mime ?? null, s: f.size ?? null, a: f.at ?? null, c: f.cost ?? null })
+  }
+  if (!entries.length) throw new Error('nothing to catalog — repos.json and keycloud.json are both empty')
+
+  const meta = { v: 2, kind: 'catalog', at: Math.floor(Date.now() / 1000), count: entries.length, entries }
+  const body = Buffer.from(JSON.stringify(meta), 'utf8')
+  console.log(`catalog  ${entries.length} entries  ${(body.length / 1024).toFixed(1)} KB`)
+  for (const kind of ['repo', 'file']) {
+    const n = entries.filter(e => e.k === kind).length
+    if (n) console.log(`  ${n} ${kind}${n === 1 ? '' : 's'}`)
+  }
+
+  process.stdout.write('encrypting ... ')
+  const pub = PublicKey.fromString(pubHex)
+  const metaCipher = EncryptedMessage.encrypt(Array.from(body), k, pub)
+  // The file push is deliberately empty-but-present: a catalog has no body, and
+  // keeping the six-push shape means every existing v2 reader parses it without
+  // a special case.
+  const fileCipher = EncryptedMessage.encrypt(Array.from(Buffer.alloc(0)), k, pub)
+  console.log(`meta ${(metaCipher.length / 1024).toFixed(1)} KB`)
+  const timestamp = Math.floor(Date.now() / 1000).toString(16).padStart(8, '0')
+  const scriptHex = buildOpReturn(
+    [CLOUD_PREFIX, CLOUD_VERSION, pubHex, hex(metaCipher), hex(fileCipher), timestamp])
+
+  const res = await publishWithRetry(scriptHex, k, address, lockingScript, { dry })
+  if (dry) {
+    console.log(`\n--dry: nothing broadcast\n  payload ${res.txid}`)
+    return
+  }
+  console.log(`\nCATALOG ${entries.length} entries -> ${res.txid}  (${res.cost} Compute)`)
+}
+
+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 {}
@@ -828,3 +1198,26 @@ 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()
+  if (sub === 'catalog') return cloudCatalog({ dry })
+  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')
+  console.log('  keychat-save keycloud catalog            publish identifiers for existing on-chain items')
+  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 }