livybolt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cozzyland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# livybolt (`livybolt`)
+
+Accountless, self-custody, **end-to-end-encrypted** surveys over Lightning.
+
+`livybolt` is the command-line client for [Livybolt](https://livybolt.com). You pay
+one Lightning invoice to create a survey, respondents answer for free, and every
+response is encrypted to a key only you hold. There are no accounts, and the server
+can never read your data.
+
+## Install
+
+```bash
+npm i -g livybolt   # installs the `livybolt` command
+livybolt --help
+```
+
+Requires **Node.js ≥ 20**.
+
+## Quick start
+
+```bash
+livybolt id new --password "<a strong passphrase>"   # self-custody key, shown once
+livybolt create survey.json                            # → Lightning invoice + handle
+#   ...pay the invoice with any wallet...
+livybolt create --resume <handle> --preimage <hex>     # → public URL, sealed to your vault
+livybolt balance --survey <id>                         # prepaid-pool accounting
+livybolt vault read --survey <id>                       # pull + decrypt responses locally
+livybolt unlock --survey <id> --count <n>              # pay to read overage responses
+```
+
+A minimal `survey.json`:
+
+```json
+{
+  "title": "Launch feedback",
+  "expected_responses": 100,
+  "per_response_sats": 50,
+  "questions": [
+    { "id": "q1", "text": "How did you hear about us?", "type": "short_text" },
+    { "id": "q2", "text": "How likely are you to recommend us?", "type": "rating" }
+  ]
+}
+```
+
+## Self-custody
+
+Your keys live only in `~/.livybolt/`. They are never sent to the server, which
+stores ciphertext and public keys only. **Back up the seed words** printed by
+`livybolt id new` — there is no recovery.
+
+## Docs
+
+- CLI reference: https://livybolt.com/docs/cli
+- HTTP API reference: https://livybolt.com/docs/api

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "livybolt",
+  "version": "0.1.0",
+  "description": "livybolt — accountless, self-custody, end-to-end-encrypted surveys over Lightning. CLI client for Livybolt (Nostr edition).",
+  "type": "module",
+  "bin": {
+    "livybolt": "scripts/livybolt.mjs"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "scripts",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "nostr-tools": "^2.23.5"
+  },
+  "scripts": {
+    "prepack": "node prepack.mjs"
+  },
+  "keywords": [
+    "survey",
+    "lightning",
+    "bitcoin",
+    "nostr",
+    "l402",
+    "end-to-end-encryption",
+    "self-custody",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://livybolt.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cozzyland/lightsurvey-nostr-edition.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/cozzyland/lightsurvey-nostr-edition/issues"
+  }
+}

package/scripts/agent-identity-store.mjs

@@ -0,0 +1,43 @@
+// Local at-rest store for the Agent Identity Key (node-only: fs/os/perms).
+//
+// Kept OUT of src/lib/crypto/agent-identity.ts on purpose — that module is
+// isomorphic (browser + node), this one touches the filesystem. The store holds
+// only public fields in the clear; the secret is the SEED — a NIP-49 `ncryptsec`
+// of the BIP-39 entropy (encrypted default, `secretKind: seed-entropy-nip49`) or,
+// with --plaintext, the bare seed words (`secretKind: seed-plaintext`, the one
+// path where the secret rests in cleartext). Storing the seed (not the account-0
+// privkey) is what lets per-survey keys derive from it. Default location:
+// ~/.livybolt/identity.json (override with LIVYBOLT_IDENTITY_HOME).
+// Dir 0700, file 0600.
+
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from 'node:fs'
+
+// v2: seed-bearing store (v1 stored the account-0 privkey, which could not derive
+// per-survey keys). Greenfield — no v1 stores exist to migrate.
+export const STORE_VERSION = 2
+
+export function storeHome() {
+  return process.env.LIVYBOLT_IDENTITY_HOME ?? join(homedir(), '.livybolt')
+}
+
+export function storePath() {
+  return join(storeHome(), 'identity.json')
+}
+
+export function readStore() {
+  const path = storePath()
+  if (!existsSync(path)) return null
+  return JSON.parse(readFileSync(path, 'utf8'))
+}
+
+export function writeStore(record) {
+  const home = storeHome()
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  const path = storePath()
+  writeFileSync(path, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 })
+  // writeFileSync only applies mode on create — force it on overwrite too.
+  chmodSync(path, 0o600)
+  return path
+}

package/scripts/agent-identity.mjs

@@ -0,0 +1,230 @@
+// Provision and manage an Agent Identity Key — entirely client-side.
+//
+// This is the executable TWIN of the canonical inline recipe (see
+// docs/reference/agent-identity.md). A code-capable agent can run this script if
+// it has the repo, or paste the equivalent ~15-line recipe; either way the
+// secret is generated and held locally and NEVER sent to the server.
+//
+// It imports the REAL isomorphic identity lib (src/lib/crypto/agent-identity.ts)
+// so the CLI and any inline reimplementation produce byte-identical keys.
+//
+// Commands:
+//   new       Generate a fresh identity. Prints npub + seed words ONCE, seals it
+//             to the local store (encrypted by default), prints the ncryptsec backup.
+//   show      Print the stored npub/pubkey (never the secret).
+//   export    Print the ncryptsec backup blob (for off-machine backup).
+//   restore   Rebuild the store from --seed "<words>" or --ncryptsec <blob>.
+//   unlock    Verify the store opens (password if encrypted); prints npub.
+//
+// Flags:
+//   --plaintext        Store the bare seed words at 0600 instead of an ncryptsec
+//                      (zero-friction for headless agents; secret rests in cleartext).
+//   --password <pw>    Password for the ncryptsec. Else LIVYBOLT_IDENTITY_PASSWORD,
+//                      else an interactive (hidden) prompt.
+//   --seed "<words>"   BIP-39 mnemonic (restore).
+//   --ncryptsec <blob> ncryptsec1… backup blob (restore).
+//
+// Store location: ~/.livybolt/identity.json (override LIVYBOLT_IDENTITY_HOME).
+//
+// Usage:
+//   node scripts/agent-identity.mjs new --password "hunter2"
+//   node scripts/agent-identity.mjs new --plaintext
+//   node scripts/agent-identity.mjs show
+//   node scripts/agent-identity.mjs export > backup.ncryptsec
+//   node scripts/agent-identity.mjs restore --seed "word1 word2 …" --password "hunter2"
+
+import {
+  generateAgentIdentity,
+  agentIdentityFromSeedWords,
+  AgentIdentityError,
+} from '../src/lib/crypto/agent-identity.js'
+import { sealSeed, unlockSeed, SeedStoreError } from '../src/lib/crypto/seed-store.js'
+import { readStore, writeStore, storePath, STORE_VERSION } from './agent-identity-store.mjs'
+import { resolveIdentityPassword } from './cli-prompt.mjs'
+
+function fail(msg) {
+  console.error(`error: ${msg}`)
+  process.exit(1)
+}
+
+// --- flag parsing (no framework) ---------------------------------------------
+function parseFlags(argv) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--plaintext') flags.plaintext = true
+    else if (a === '--password') flags.password = argv[++i]
+    else if (a === '--seed') flags.seed = argv[++i]
+    else if (a === '--ncryptsec') flags.ncryptsec = argv[++i]
+    else fail(`unknown argument: ${a}`)
+  }
+  return flags
+}
+
+async function resolvePassword(flags, purpose) {
+  const pw = await resolveIdentityPassword(flags, fail, purpose)
+  if (!pw) fail('empty password')
+  return pw
+}
+
+// --- store sealing + self-check ----------------------------------------------
+// The persisted secret is the SEED, so per-survey keys can derive from it. We
+// store the seed words (plaintext mode) or a NIP-49 ncryptsec of the BIP-39
+// entropy (encrypted default). `secretKind` tags the payload so the seed entropy
+// is never misread as an nsec.
+function sealRecord(id, { plaintext, password }) {
+  if (!id.seedWords) {
+    fail('cannot store a seed-bearing identity without seed words (use restore --seed or --ncryptsec)')
+  }
+  const base = {
+    v: STORE_VERSION,
+    npub: id.npub,
+    pubkey: id.pubkeyHex,
+    createdAt: new Date().toISOString(),
+  }
+  if (plaintext) return { ...base, secretKind: 'seed-plaintext', seedWords: id.seedWords }
+  return { ...base, secretKind: 'seed-entropy-nip49', ncryptsec: sealSeed(id.seedWords, password) }
+}
+
+// Recover the seed mnemonic from a stored record (plaintext words, or the
+// NIP-49 ncryptsec-of-entropy under the given password). Fails loud on a missing
+// or unrecognized secretKind (e.g. an old pre-v2 store) rather than silently
+// misreading the secret.
+function seedFromRecord(record, password) {
+  if (record.secretKind === 'seed-plaintext') {
+    if (!record.seedWords) fail('corrupt store: seed-plaintext record is missing seedWords')
+    return record.seedWords
+  }
+  if (record.secretKind === 'seed-entropy-nip49') {
+    return unlockSeed(record.ncryptsec, password)
+  }
+  fail(
+    `unrecognized identity store (secretKind=${record.secretKind ?? 'none'}) — ` +
+      'likely an old (pre-v2) store; re-provision with `livybolt id new`'
+  )
+}
+
+// Re-open what we just wrote and confirm the re-derived npub matches — catches a
+// mis-seal before the key is ever trusted. This is the agent's correctness oracle.
+function selfCheck(record, password) {
+  const reopened = agentIdentityFromSeedWords(seedFromRecord(record, password))
+  if (reopened.npub !== record.npub) {
+    fail('self-check FAILED: re-derived npub does not match the stored npub')
+  }
+}
+
+// --- commands ----------------------------------------------------------------
+async function cmdNew(flags) {
+  if (readStore()) {
+    fail(`an identity already exists at ${storePath()} — refusing to overwrite. Move it aside first.`)
+  }
+  const id = generateAgentIdentity()
+  const password = flags.plaintext ? null : await resolvePassword(flags, 'encrypt the new identity')
+  const record = sealRecord(id, { plaintext: flags.plaintext, password })
+  writeStore(record)
+  selfCheck(record, password)
+
+  console.error('')
+  console.error('  ⚠  BACK UP THESE SEED WORDS NOW — shown once, never sent to the server.')
+  console.error('     They are the canonical recovery for this identity.')
+  console.error(`     Stored ${flags.plaintext ? 'in CLEARTEXT (--plaintext)' : 'encrypted'} at ${storePath()} (0600).`)
+  console.error('')
+
+  console.log(`npub=${id.npub}`)
+  console.log(`pubkey=${id.pubkeyHex}`)
+  console.log(`seed_words=${id.seedWords}`)
+  if (record.ncryptsec) console.log(`ncryptsec=${record.ncryptsec}`)
+}
+
+function cmdShow() {
+  const rec = readStore()
+  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  console.log(`npub=${rec.npub}`)
+  console.log(`pubkey=${rec.pubkey}`)
+  console.log(`mode=${rec.secretKind === 'seed-plaintext' ? 'plaintext' : 'encrypted'}`)
+  console.log(`created=${rec.createdAt}`)
+}
+
+async function cmdExport(flags) {
+  const rec = readStore()
+  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  // The exported blob is a NIP-49 ncryptsec of the seed entropy — restore it with
+  // `restore --ncryptsec`. It is NOT a portable nsec; the seed words are the
+  // canonical cross-tool backup.
+  if (rec.secretKind === 'seed-entropy-nip49') {
+    console.log(rec.ncryptsec)
+    return
+  }
+  // Plaintext store: derive an encrypted seed backup on demand.
+  const password = await resolvePassword(flags, 'encrypt the backup')
+  console.log(sealSeed(rec.seedWords, password))
+}
+
+async function cmdRestore(flags) {
+  if (readStore()) {
+    fail(`an identity already exists at ${storePath()} — refusing to overwrite. Move it aside first.`)
+  }
+  let id
+  if (flags.seed) {
+    id = agentIdentityFromSeedWords(flags.seed)
+  } else if (flags.ncryptsec) {
+    const password = await resolvePassword(flags, 'open the ncryptsec')
+    // The blob is a seed-entropy ncryptsec (see cmdExport); recover the seed words.
+    id = agentIdentityFromSeedWords(unlockSeed(flags.ncryptsec, password))
+  } else {
+    fail('restore needs --seed "<words>" or --ncryptsec <blob>')
+  }
+  const password = flags.plaintext ? null : await resolvePassword(flags, 'encrypt the restored identity')
+  const record = sealRecord(id, { plaintext: flags.plaintext, password })
+  writeStore(record)
+  selfCheck(record, password)
+  console.log(`npub=${id.npub}`)
+}
+
+async function cmdUnlock(flags) {
+  const rec = readStore()
+  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  const password =
+    rec.secretKind === 'seed-plaintext'
+      ? undefined
+      : await resolvePassword(flags, 'unlock the identity')
+  const id = agentIdentityFromSeedWords(seedFromRecord(rec, password))
+  if (id.npub !== rec.npub) fail('unlock FAILED: re-derived npub does not match the stored npub')
+  console.error('unlocked OK')
+  console.log(`npub=${id.npub}`)
+}
+
+// --- main --------------------------------------------------------------------
+const [command, ...rest] = process.argv.slice(2)
+const flags = parseFlags(rest)
+
+try {
+  switch (command) {
+    case 'new':
+      await cmdNew(flags)
+      break
+    case 'show':
+      cmdShow()
+      break
+    case 'export':
+      await cmdExport(flags)
+      break
+    case 'restore':
+      await cmdRestore(flags)
+      break
+    case 'unlock':
+      await cmdUnlock(flags)
+      break
+    default:
+      fail(
+        `unknown command: ${command ?? '(none)'}\n` +
+          '  commands: new | show | export | restore | unlock\n' +
+          '  e.g. node scripts/agent-identity.mjs new --password "hunter2"'
+      )
+  }
+} catch (err) {
+  if (err instanceof AgentIdentityError || err instanceof SeedStoreError) {
+    fail(`${err.code}: ${err.message}`)
+  }
+  throw err
+}

package/scripts/balance.mjs

@@ -0,0 +1,68 @@
+// `livybolt balance --survey <id>` — show a survey's prepaid-pool accounting:
+// how many of the prepaid responses are consumed / remaining, and how many
+// overage responses are locked awaiting unlock.
+//
+// NIP-98 gated: opens the local vault to derive the survey key, signs the
+// request, then GETs the balance. No payment.
+
+import { fetchBalance, DEFAULT_HOST } from './livybolt-api.mjs'
+import { openVaultEntry } from './vault-open.mjs'
+import { signNip98Token } from '../src/lib/nip98.js'
+
+function fail(msg) {
+  console.error(`error: ${msg}`)
+  process.exit(1)
+}
+
+function parseFlags(argv) {
+  const flags = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--survey') flags.survey = argv[++i]
+    else if (a === '--host') flags.host = argv[++i]
+    else if (a === '--password') flags.password = argv[++i]
+    else if (a === '--json') flags.json = true
+    else fail(`unknown argument: ${a}`)
+  }
+  return flags
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (!flags.survey) fail('usage: livybolt balance --survey <id>')
+
+  const { entry, surveyPrivkey } = await openVaultEntry(flags.survey, flags)
+  const host = flags.host ?? DEFAULT_HOST
+  const authorization = surveyPrivkey
+    ? await signNip98Token(
+        `${host}/api/surveys/${encodeURIComponent(entry.surveyId)}/balance`,
+        'GET',
+        surveyPrivkey
+      )
+    : undefined
+  const bal = await fetchBalance({
+    host,
+    surveyId: entry.surveyId,
+    ownerToken: entry.ownerToken,
+    authorization,
+  })
+
+  if (flags.json) {
+    console.log(JSON.stringify(bal, null, 2))
+    return
+  }
+
+  console.log(`survey:    ${bal.surveyId}`)
+  console.log(`prepaid:   ${bal.prepaid_responses}`)
+  console.log(`consumed:  ${bal.consumed_responses}`)
+  console.log(`remaining: ${bal.remaining_responses}  (${bal.remaining_sats} sats of credit)`)
+  console.log(`locked:    ${bal.overage_responses}  (overage awaiting unlock)`)
+  if (bal.expires_at) console.log(`expires:   ${bal.expires_at}`)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(`error: ${err.message}`)
+    process.exit(1)
+  })
+}

package/scripts/cli-prompt.mjs

@@ -0,0 +1,38 @@
+// Shared identity-password resolution for the CLI scripts that unlock the seed.
+// Centralizes what were four byte-identical copies (agent-identity, vault-read,
+// vault-open, survey-create) so the resolution ladder lives in one place.
+
+import { createInterface } from 'node:readline'
+
+/** Read a line without echoing it (for passwords). */
+export function promptHidden(query) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    // Mute echo so the password is not displayed as it is typed.
+    rl._writeToOutput = () => {}
+    process.stdout.write(query)
+    rl.question('', (answer) => {
+      rl.close()
+      process.stdout.write('\n')
+      resolve(answer)
+    })
+  })
+}
+
+/**
+ * Resolve the identity password: --password flag, else LIVYBOLT_IDENTITY_PASSWORD,
+ * else an interactive (hidden) prompt. When there is no password and no TTY, calls
+ * `onMissing(message)` — pass the caller's fail() (which exits). `purpose` tunes
+ * the wording (e.g. 'unlock the identity', 'encrypt the new identity').
+ */
+export async function resolveIdentityPassword(flags, onMissing, purpose = 'unlock the identity') {
+  if (flags.password != null) return flags.password
+  if (process.env.LIVYBOLT_IDENTITY_PASSWORD) return process.env.LIVYBOLT_IDENTITY_PASSWORD
+  if (!process.stdin.isTTY) {
+    onMissing(
+      `no password to ${purpose}. Pass --password, set LIVYBOLT_IDENTITY_PASSWORD, or run interactively.`
+    )
+    return undefined
+  }
+  return await promptHidden(`Password to ${purpose}: `)
+}