livybolt 0.1.0

package/scripts/survey-create.mjs

@@ -0,0 +1,175 @@
+// `livybolt create` — two-phase, accountless survey creation.
+//
+//   Phase 1:  livybolt create <survey.json>
+//     1. Derive THIS survey's key PAIR from the agent seed at the next account
+//        index (deterministic; recoverable from the seed alone): the Decrypt
+//        Key (survey hierarchy) and the View Key (view hierarchy, same index —
+//        the dashboard's read recipient).
+//     2. POST the survey body (with encryption_pubkey + view_pubkey) → capture
+//        the 402 L402 challenge (macaroon + invoice + sats breakdown).
+//     3. Persist everything to a pending file (0600), keyed by a short handle.
+//     4. Print the invoice + handle. The agent pays the invoice out of band.
+//
+//   Phase 2:  livybolt create --resume <handle> --preimage <hex>
+//     5. Re-POST the body with L402 macaroon:preimage → mint the survey.
+//     6. Seal {surveyId, surveyIndex} into the local vault.
+//     7. Delete the pending file. Print the public URL.
+//
+// No private key ever leaves the machine; the server only ever sees the two
+// public keys and stores ciphertext. There is no owner token — ownership is
+// proven per-request via NIP-98 signed by a derived key.
+
+import { randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { sealVaultEntry } from '../src/lib/crypto/token-vault.js'
+import { requestCreate, resumeCreate, DEFAULT_HOST } from './livybolt-api.mjs'
+import { readStore } from './agent-identity-store.mjs'
+import { appendVaultEnvelope } from './token-vault-store.mjs'
+import { writePending, readPending, deletePending } from './pending-store.mjs'
+import { deriveSurveyKeysForIndex } from './seed-unlock.mjs'
+import { peekNextIndex, setNextIndex } from './survey-index-store.mjs'
+import { resolveIdentityPassword } from './cli-prompt.mjs'
+
+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 === '--resume') flags.resume = argv[++i]
+    else if (a === '--preimage') flags.preimage = argv[++i]
+    else if (a === '--host') flags.host = argv[++i]
+    else if (a === '--password') flags.password = argv[++i]
+    else if (a.startsWith('--')) fail(`unknown argument: ${a}`)
+    else flags._.push(a)
+  }
+  return flags
+}
+
+// Resolve the identity password to unlock the seed for derivation. Only invoked
+// for an encrypted store (a plaintext store needs no password).
+const resolvePassword = (flags) => resolveIdentityPassword(flags, fail)
+
+// The identity pubkey is the lock the vault entry is sealed to. It is a PUBLIC
+// field — reading it never needs the identity password.
+function identityPubkeyHex() {
+  const store = readStore()
+  if (!store) {
+    fail('no identity found. Run `livybolt id new` first (the vault seals to its pubkey).')
+  }
+  if (!store.pubkey) fail('identity store is missing pubkey; re-run `livybolt id`.')
+  return store.pubkey
+}
+
+async function phaseCreate(flags) {
+  const file = flags._[0]
+  if (!file) fail('usage: livybolt create <survey.json>')
+
+  let body
+  try {
+    body = JSON.parse(readFileSync(file, 'utf8'))
+  } catch (err) {
+    fail(`could not read survey JSON from ${file}: ${err.message}`)
+  }
+
+  // Derive this survey's key PAIR from the agent seed at the next account
+  // index and wire both pubkeys into the body: the encryption target and the
+  // view (dashboard read) recipient. Livybolt is E2E-only: the server only ever
+  // sees the public keys + ciphertext. The vault stores the INDEX (not a
+  // secret) — both keys re-derive from the seed.
+  //
+  // PEEK (don't consume) the index: a failed phase 1 (network/server error)
+  // must not burn the index, or repeated failures accrue permanent gaps that can
+  // eventually exceed the recovery gap-limit. We commit the index only after the
+  // request succeeds. (A concurrent create racing the same index is backstopped
+  // by the server's unique pubkey constraints → 409 on the loser.)
+  const surveyIndex = peekNextIndex()
+  const keys = await deriveSurveyKeysForIndex(surveyIndex, {
+    resolvePassword: () => resolvePassword(flags),
+  })
+  body.encryption_pubkey = keys.encryption.pubkeyHex
+  body.view_pubkey = keys.view.pubkeyHex
+
+  const host = flags.host ?? DEFAULT_HOST
+  const challenge = await requestCreate({ host, body })
+
+  // Phase 1 succeeded — now consume the index so the next create gets a fresh key.
+  setNextIndex(surveyIndex + 1)
+
+  const handle = randomBytes(5).toString('hex')
+  writePending(handle, {
+    handle,
+    host,
+    body,
+    macaroon: challenge.macaroon,
+    invoice: challenge.invoice,
+    surveyIndex,
+    breakdown: challenge.breakdown,
+    createdAt: new Date().toISOString(),
+  })
+
+  console.log(`handle:  ${handle}`)
+  if (challenge.breakdown) {
+    console.log(`total:   ${challenge.breakdown.total_sats} sats`)
+  }
+  console.log(`invoice: ${challenge.invoice}`)
+  console.log('')
+  console.log('Pay the invoice, then run:')
+  console.log(`  livybolt create --resume ${handle} --preimage <preimage-hex>`)
+}
+
+async function phaseResume(flags) {
+  const handle = flags.resume
+  const preimage = flags.preimage
+  if (!preimage) fail('usage: livybolt create --resume <handle> --preimage <hex>')
+
+  const pending = readPending(handle)
+  if (!pending) fail(`no pending survey for handle "${handle}" (already resumed, or wrong handle).`)
+
+  const created = await resumeCreate({
+    host: pending.host,
+    body: pending.body,
+    macaroon: pending.macaroon,
+    preimage,
+  })
+
+  // Roll the freshly minted survey into the vault, sealed to the identity
+  // pubkey (no password needed). The entry carries only id + index — every
+  // credential (decrypt key, view key, NIP-98 signer) re-derives from the seed.
+  const envelope = await sealVaultEntry(
+    {
+      surveyId: created.surveyId,
+      surveyIndex: pending.surveyIndex,
+    },
+    identityPubkeyHex()
+  )
+  appendVaultEnvelope(envelope)
+  deletePending(handle)
+
+  console.log('survey created ✔')
+  console.log(`surveyId:  ${created.surveyId}`)
+  console.log(`public:    ${created.publicUrl}`)
+  console.log('')
+  console.log('Sealed into your vault. Read responses with:')
+  console.log(`  livybolt vault read --survey ${created.surveyId}`)
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (flags.resume) {
+    await phaseResume(flags)
+  } else {
+    await phaseCreate(flags)
+  }
+}
+
+// Run when invoked directly (node scripts/survey-create.mjs …).
+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/survey-index-store.mjs

@@ -0,0 +1,88 @@
+// Non-secret cache of the next NIP-06 account index to derive a survey key at.
+//
+// `livybolt create` derives survey n's key at account n (see src/lib/crypto/survey-key.ts);
+// this counter remembers which index to use next so successive surveys get
+// distinct, unlinkable keys. It holds NO secret — it is a plain high-water mark.
+// Losing it is safe: `livybolt vault rebuild` (foundation U5) re-derives the surveys
+// by gap-limit scanning, and the server rejects a duplicate encryption_pubkey, so
+// a stale counter can never silently collide. Lives next to the identity store
+// (~/.livybolt, override with LIVYBOLT_IDENTITY_HOME).
+
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, existsSync, chmodSync, readFileSync } from 'node:fs'
+import { FIRST_SURVEY_ACCOUNT_INDEX } from '../src/lib/crypto/survey-key.js'
+import { storeHome } from './agent-identity-store.mjs'
+
+export class SurveyIndexError extends Error {
+  constructor(code, message) {
+    super(message ?? code)
+    this.name = 'SurveyIndexError'
+    this.code = code
+  }
+}
+
+function storePath() {
+  return join(storeHome(), 'survey-index.json')
+}
+
+/**
+ * Read the counter file. A MISSING file is the normal first-run state (start at
+ * 1). A present-but-unreadable file is CORRUPT — we must not silently treat it
+ * as missing and reset to 1, because that would re-derive an already-used survey
+ * key (a colliding encryption_pubkey). The caller decides how to react.
+ */
+function readRaw() {
+  const path = storePath()
+  if (!existsSync(path)) return { status: 'missing' }
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    return { status: 'corrupt' }
+  }
+  const next = parsed?.next
+  if (!Number.isInteger(next) || next < FIRST_SURVEY_ACCOUNT_INDEX) return { status: 'corrupt' }
+  return { status: 'ok', next }
+}
+
+/**
+ * The next index that would be allocated, without consuming it. Throws on a
+ * corrupt counter rather than silently resetting to 1 — `livybolt create` must fail
+ * loudly so it never re-derives a used key. `livybolt vault rebuild` repairs it.
+ */
+export function peekNextIndex() {
+  const r = readRaw()
+  if (r.status === 'corrupt') {
+    throw new SurveyIndexError(
+      'corrupt',
+      `survey-index counter at ${storePath()} is unreadable — refusing to reuse a key. ` +
+        'Run `livybolt vault rebuild` to rebuild it from your seed.'
+    )
+  }
+  return r.status === 'ok' ? r.next : FIRST_SURVEY_ACCOUNT_INDEX
+}
+
+/** Consume and return the next index, persisting the bumped counter. */
+export function allocateIndex() {
+  return writeNext(peekNextIndex() + 1) - 1
+}
+
+/**
+ * Set the counter so the next allocation is at least `n` — never lowers an
+ * existing higher counter. Used by `livybolt vault rebuild` after a recovery scan,
+ * so it must also REPAIR a missing or corrupt counter (it reads raw, not peek).
+ */
+export function setNextIndex(n) {
+  const r = readRaw()
+  const current = r.status === 'ok' ? r.next : FIRST_SURVEY_ACCOUNT_INDEX
+  return writeNext(Math.max(n, current))
+}
+
+function writeNext(next) {
+  const home = storeHome()
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  const path = storePath()
+  writeFileSync(path, JSON.stringify({ next }, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(path, 0o600)
+  return next
+}

package/scripts/token-vault-store.mjs

@@ -0,0 +1,52 @@
+// Local at-rest store for the Token Vault (node-only). An array of sealed
+// envelopes (see src/lib/crypto/token-vault.ts) next to the identity store.
+// Default: ~/.livybolt/vault.json (shares LIVYBOLT_IDENTITY_HOME). 0600.
+
+import { join } from 'node:path'
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from 'node:fs'
+import { storeHome } from './agent-identity-store.mjs'
+
+export class VaultStoreError extends Error {
+  constructor(code, message) {
+    super(message ?? code)
+    this.name = 'VaultStoreError'
+    this.code = code
+  }
+}
+
+export function vaultPath() {
+  return join(storeHome(), 'vault.json')
+}
+
+export function readVault() {
+  const path = vaultPath()
+  if (!existsSync(path)) return []
+  // A corrupt vault must NOT look like an empty one: returning [] (or letting a
+  // raw SyntaxError get swallowed upstream) would let appendVaultEnvelope
+  // overwrite it and `livybolt vault rebuild` re-add everything. Fail loud + typed.
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    throw new VaultStoreError('corrupt', `vault at ${path} is not valid JSON — refusing to touch it`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new VaultStoreError('corrupt', `vault at ${path} is not an array of envelopes`)
+  }
+  return parsed
+}
+
+export function writeVault(envelopes) {
+  const home = storeHome()
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  const path = vaultPath()
+  writeFileSync(path, JSON.stringify(envelopes, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(path, 0o600)
+  return path
+}
+
+export function appendVaultEnvelope(envelope) {
+  const list = readVault()
+  list.push(envelope)
+  return writeVault(list)
+}

package/scripts/token-vault.mjs

@@ -0,0 +1,94 @@
+// Roll survey ownership into, and read it back out of, the local Token Vault.
+//
+// `add`  appends a (surveyId, ownerToken, [surveyDecryptSecret]) entry sealed to
+//        the Agent Identity Key's PUBLIC key — it never needs the password.
+// `list` opens the whole vault, which DOES need the identity unlocked.
+//
+// Demonstrates the core property: an agent can keep rolling surveys in all day
+// without unlocking anything; the password is only needed to read/import later.
+//
+// Usage:
+//   node scripts/token-vault.mjs add --survey svy_1 --token lsc_abc [--secret <nsec-or-hex>]
+//   node scripts/token-vault.mjs list [--password "hunter2"]
+
+import { AgentIdentityError } from '../src/lib/crypto/agent-identity.js'
+import { sealVaultEntry, openVault, VaultError } from '../src/lib/crypto/token-vault.js'
+import { readStore } from './agent-identity-store.mjs'
+import { appendVaultEnvelope, readVault } from './token-vault-store.mjs'
+import { identityFromRecord, SeedUnlockError } from './seed-unlock.mjs'
+import { resolveIdentityPassword } from './cli-prompt.mjs'
+
+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 === '--token') flags.token = argv[++i]
+    else if (a === '--secret') flags.secret = argv[++i]
+    else if (a === '--password') flags.password = argv[++i]
+    else fail(`unknown argument: ${a}`)
+  }
+  return flags
+}
+
+function requireIdentity() {
+  const rec = readStore()
+  if (!rec) fail('no identity. Run: node scripts/agent-identity.mjs new')
+  return rec
+}
+
+async function cmdAdd(flags) {
+  if (!flags.survey || !flags.token) fail('add needs --survey <id> and --token <owner_token>')
+  const rec = requireIdentity()
+  // Append needs only the PUBLIC key — no unlock, no password.
+  const envelope = await sealVaultEntry(
+    { surveyId: flags.survey, ownerToken: flags.token, surveyDecryptSecret: flags.secret },
+    rec.pubkey
+  )
+  appendVaultEnvelope(envelope)
+  console.log(`added=${flags.survey}`)
+}
+
+async function cmdList(flags) {
+  const rec = requireIdentity()
+  // Reading the vault DOES need the identity private key, recovered from the seed.
+  const { privkey } = await identityFromRecord(rec, () => resolveIdentityPassword(flags, fail))
+
+  const entries = await openVault(readVault(), privkey)
+  for (const e of entries) {
+    console.log(
+      `entry=${e.surveyId}|${e.ownerToken ?? '-'}|secret:${e.surveyDecryptSecret ? 'yes' : 'no'}|index:${e.surveyIndex ?? '-'}`
+    )
+  }
+  console.log(`count=${entries.length}`)
+}
+
+const [command, ...rest] = process.argv.slice(2)
+const flags = parseFlags(rest)
+
+try {
+  switch (command) {
+    case 'add':
+      await cmdAdd(flags)
+      break
+    case 'list':
+      await cmdList(flags)
+      break
+    default:
+      fail(
+        `unknown command: ${command ?? '(none)'}\n` +
+          '  commands: add | list\n' +
+          '  e.g. node scripts/token-vault.mjs add --survey svy_1 --token lsc_abc'
+      )
+  }
+} catch (err) {
+  if (err instanceof AgentIdentityError) fail(`${err.code}: ${err.message}`)
+  if (err instanceof SeedUnlockError) fail(`${err.code}: ${err.message}`)
+  if (err instanceof VaultError) fail(`${err.code}: ${err.message}`)
+  throw err
+}

package/scripts/unlock.mjs

@@ -0,0 +1,148 @@
+// `livybolt unlock` — two-phase, pay-per-response unlock of overage responses.
+//
+// Responses beyond the prepaid pool are stored `locked`. Unlocking pays an
+// L402 invoice (count × unlock fee) to promote the N oldest locked responses
+// to `unlocked` (FIFO), after which `livybolt vault read` returns them.
+//
+//   Phase 1:  livybolt unlock --survey <id> --count <n>
+//     1. Open the vault → derive the survey key, sign a NIP-98 auth event
+//        (payload-bound to { count }).
+//     2. POST the unlock request → capture the 402 L402 challenge.
+//     3. Persist to a pending file (0600), keyed by a short handle.
+//        (No key material is persisted — only the L402 challenge.)
+//     4. Print the invoice + handle. Pay it out of band.
+//
+//   Phase 2:  livybolt unlock --resume <handle> --preimage <hex>
+//     5. Re-open the vault and sign a FRESH NIP-98 event (the phase-1
+//        signature expires within NIP-98's ~60s window while the invoice is
+//        being paid), then re-POST with the L402 credential in
+//        X-Unlock-Authorization → promote the locked rows.
+
+import { randomBytes } from 'node:crypto'
+import { requestUnlock, resumeUnlock, DEFAULT_HOST } from './livybolt-api.mjs'
+import { writePending, readPending, deletePending } from './pending-store.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 === '--count') flags.count = parseInt(argv[++i], 10)
+    else if (a === '--resume') flags.resume = argv[++i]
+    else if (a === '--preimage') flags.preimage = argv[++i]
+    else if (a === '--host') flags.host = argv[++i]
+    else if (a === '--password') flags.password = argv[++i]
+    else fail(`unknown argument: ${a}`)
+  }
+  return flags
+}
+
+async function phaseRequest(flags) {
+  const count = flags.count
+  if (!Number.isInteger(count) || count < 1) {
+    fail('usage: livybolt unlock --survey <id> --count <n>   (n ≥ 1)')
+  }
+
+  const { entry, surveyPrivkey } = await openVaultEntry(flags.survey, flags)
+  if (!surveyPrivkey) {
+    fail(
+      `vault entry for ${entry.surveyId} has no derivable survey key — ` +
+        'unlock authenticates with NIP-98 and needs it. Run: livybolt vault rebuild'
+    )
+  }
+  const host = flags.host ?? DEFAULT_HOST
+  const unlockUrl = `${host}/api/surveys/${encodeURIComponent(entry.surveyId)}/unlock`
+
+  const challenge = await requestUnlock({
+    host,
+    surveyId: entry.surveyId,
+    authorization: await signNip98Token(unlockUrl, 'POST', surveyPrivkey, { count }),
+    count,
+  })
+
+  const handle = randomBytes(5).toString('hex')
+  writePending(handle, {
+    handle,
+    kind: 'unlock',
+    host,
+    surveyId: entry.surveyId,
+    count,
+    macaroon: challenge.macaroon,
+    invoice: challenge.invoice,
+    breakdown: challenge.breakdown,
+    createdAt: new Date().toISOString(),
+  })
+
+  console.log(`handle:  ${handle}`)
+  if (challenge.breakdown) {
+    console.log(`unlock:  ${challenge.breakdown.unlock_count} responses`)
+    console.log(`total:   ${challenge.breakdown.total_sats} sats`)
+  }
+  console.log(`invoice: ${challenge.invoice}`)
+  console.log('')
+  console.log('Pay the invoice, then run:')
+  console.log(`  livybolt unlock --resume ${handle} --preimage <preimage-hex>`)
+}
+
+async function phaseResume(flags) {
+  const preimage = flags.preimage
+  if (!preimage) fail('usage: livybolt unlock --resume <handle> --preimage <hex>')
+
+  const pending = readPending(flags.resume)
+  if (!pending) fail(`no pending unlock for handle "${flags.resume}" (already resumed, or wrong handle).`)
+  if (pending.kind !== 'unlock') {
+    fail(`handle "${flags.resume}" is a ${pending.kind ?? 'create'} pending, not an unlock.`)
+  }
+
+  // Fresh NIP-98 signature: the pending file carries no key material, so
+  // resume re-opens the vault (prompting for the identity password again).
+  const { entry, surveyPrivkey } = await openVaultEntry(pending.surveyId, flags)
+  if (!surveyPrivkey) {
+    fail(
+      `vault entry for ${entry.surveyId} has no derivable survey key — ` +
+        'unlock authenticates with NIP-98 and needs it. Run: livybolt vault rebuild'
+    )
+  }
+  const unlockUrl = `${pending.host}/api/surveys/${encodeURIComponent(pending.surveyId)}/unlock`
+
+  const result = await resumeUnlock({
+    host: pending.host,
+    surveyId: pending.surveyId,
+    authorization: await signNip98Token(unlockUrl, 'POST', surveyPrivkey, {
+      count: pending.count,
+    }),
+    count: pending.count,
+    macaroon: pending.macaroon,
+    preimage,
+  })
+  deletePending(flags.resume)
+
+  if (result.unlocked === 0) {
+    console.log('no locked responses to unlock.')
+    return
+  }
+  console.log(`unlocked ${result.unlocked} response${result.unlocked === 1 ? '' : 's'} ✔`)
+  console.log('')
+  console.log('Read them with:')
+  console.log(`  livybolt vault read --survey ${pending.surveyId}`)
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (flags.resume) await phaseResume(flags)
+  else await phaseRequest(flags)
+}
+
+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/vault-decrypt.mjs

@@ -0,0 +1,38 @@
+// Decrypt a survey's responses locally through the VaultDecryptor seam.
+//
+// The server is content-blind: encrypted responses come back as opaque
+// envelopes. This opens them with the per-survey Survey Decrypt Key via the
+// seam in src/lib/crypto/envelope.ts. The raw-nsec backend is wired here; the
+// VaultDecryptor interface keeps alternative key backends pluggable without
+// touching this code's call shape.
+
+import { openEnvelopeWith, rawNsecDecryptor, isEnvelope } from '../src/lib/crypto/envelope.js'
+import { parseRecipientSecret } from '../src/lib/crypto/recipient-key.js'
+
+/**
+ * Build the raw-nsec VaultDecryptor for a survey's decrypt secret (nsec or
+ * 64-char hex). Returns an object satisfying the VaultDecryptor seam.
+ */
+export function rawNsecVaultDecryptor(secret) {
+  const { privkey } = parseRecipientSecret(secret)
+  return rawNsecDecryptor(privkey)
+}
+
+/**
+ * Decrypt the `responses` array from fetchResponses(). Each row whose `data` is
+ * an envelope is opened through `decryptor`; plaintext rows pass through. The
+ * decryptor is the seam — pass rawNsecVaultDecryptor(secret) for the local key
+ * backend, or any object implementing { pubkey, nip44Decrypt }.
+ */
+export async function decryptResponses(responses, decryptor) {
+  const out = []
+  for (const r of responses ?? []) {
+    if (r.encrypted && isEnvelope(r.data)) {
+      const json = await openEnvelopeWith(r.data, decryptor)
+      out.push({ ...r, data: JSON.parse(json), decrypted: true })
+    } else {
+      out.push({ ...r, decrypted: false })
+    }
+  }
+  return out
+}

package/scripts/vault-open.mjs

@@ -0,0 +1,44 @@
+// Shared helper: unlock the local identity and pull a survey's vault entry
+// plus its derived survey private key (for NIP-98 signing). Used by
+// `livybolt unlock` and `livybolt balance`.
+//
+// The identity private key opens the vault; the entry never leaves the machine.
+// Mirrors the unlock-the-identity logic in vault-read.mjs.
+
+import { agentIdentityFromSeedWords } from '../src/lib/crypto/agent-identity.js'
+import { openVault } from '../src/lib/crypto/token-vault.js'
+import { readStore } from './agent-identity-store.mjs'
+import { readVault } from './token-vault-store.mjs'
+import { seedMnemonicFromRecord, surveyPrivkeyForEntry } from './seed-unlock.mjs'
+import { resolveIdentityPassword as resolveIdentityPasswordPrompt } from './cli-prompt.mjs'
+
+function fail(msg) {
+  console.error(`error: ${msg}`)
+  process.exit(1)
+}
+
+const resolveIdentityPassword = (flags) => resolveIdentityPasswordPrompt(flags, fail)
+
+/**
+ * Open the vault with the local identity key and return the entry for
+ * `surveyId` plus its survey private key (for signing NIP-98 auth). The seed is
+ * unlocked once: the identity key opens the vault, and the survey key is derived
+ * from the same mnemonic (or parsed from a legacy stored secret). Exits with a
+ * clear error if there is no identity or the survey is not vaulted.
+ *
+ * @returns {Promise<{ entry: object, surveyPrivkey: Uint8Array | null }>}
+ */
+export async function openVaultEntry(surveyId, flags = {}) {
+  if (!surveyId) fail('a --survey <id> is required.')
+
+  const rec = readStore()
+  if (!rec) fail('no identity. Run: livybolt id new')
+
+  const mnemonic = await seedMnemonicFromRecord(rec, () => resolveIdentityPassword(flags))
+  const { privkey } = agentIdentityFromSeedWords(mnemonic)
+
+  const entries = await openVault(readVault(), privkey)
+  const entry = entries.find((e) => e.surveyId === surveyId)
+  if (!entry) fail(`survey ${surveyId} not found in the vault.`)
+  return { entry, surveyPrivkey: surveyPrivkeyForEntry(entry, mnemonic) }
+}