livybolt 0.1.0

package/scripts/livybolt-api.mjs

@@ -0,0 +1,253 @@
+// Pure HTTP client for the Livybolt API. Every function takes an injectable
+// `fetchImpl` (defaults to global fetch) so the create/resume/read flows are
+// unit-testable without a network. No filesystem, no argv — see livybolt.mjs and
+// survey-create.mjs for the CLI wrappers that wire these to disk and stdout.
+
+export const DEFAULT_HOST = process.env.LIVYBOLT_HOST ?? 'https://livybolt.com'
+
+/** Abort a request that hangs — a stuck server must not freeze the CLI, above
+ *  all the vault-rebuild scan loop, which fires one request per account index.
+ *  AbortSignal.timeout uses an unref'd timer, so it never keeps the process up. */
+const REQUEST_TIMEOUT_MS = 30_000
+const withTimeout = (init = {}) => ({ ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) })
+
+export class LivyApiError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message)
+    this.name = 'LivyApiError'
+    this.status = status
+    this.body = body
+  }
+}
+
+/** Parse `L402 macaroon="…", invoice="…"` into its parts. */
+export function parseL402Challenge(header) {
+  if (!header) return null
+  const macaroon = header.match(/macaroon="([^"]+)"/)?.[1]
+  const invoice = header.match(/invoice="([^"]+)"/)?.[1]
+  if (!macaroon || !invoice) return null
+  return { macaroon, invoice }
+}
+
+async function readJson(res) {
+  try {
+    return await res.json()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Phase 1 of two-phase create: POST the survey body with no payment and capture
+ * the L402 challenge (macaroon + invoice + sats breakdown). The caller persists
+ * these and pays the invoice out of band.
+ *
+ * Returns { macaroon, invoice, breakdown } on the expected 402, or throws.
+ */
+export async function requestCreate({ host = DEFAULT_HOST, body, fetchImpl = fetch }) {
+  const res = await fetchImpl(`${host}/api/surveys`, withTimeout({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  }))
+
+  if (res.status === 402) {
+    const challenge = parseL402Challenge(res.headers.get('WWW-Authenticate'))
+    if (!challenge) {
+      throw new LivyApiError('402 without a parseable L402 challenge', { status: 402 })
+    }
+    const payload = await readJson(res)
+    return { ...challenge, breakdown: payload?.breakdown ?? null }
+  }
+
+  const payload = await readJson(res)
+  throw new LivyApiError(
+    `unexpected status ${res.status} from create (expected 402 challenge)`,
+    { status: res.status, body: payload }
+  )
+}
+
+/**
+ * Phase 2 of two-phase create: re-POST the same body with the L402 credential
+ * (macaroon:preimage) to redeem the paid invoice and mint the survey.
+ *
+ * Returns the created-survey JSON ({ surveyId, slug, publicUrl, viewPubkey, … }).
+ */
+export async function resumeCreate({
+  host = DEFAULT_HOST,
+  body,
+  macaroon,
+  preimage,
+  fetchImpl = fetch,
+}) {
+  const res = await fetchImpl(`${host}/api/surveys`, withTimeout({
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `L402 ${macaroon}:${preimage}`,
+    },
+    body: JSON.stringify(body),
+  }))
+
+  const payload = await readJson(res)
+  if (res.status === 201) return payload
+  throw new LivyApiError(`create resume failed (status ${res.status})`, {
+    status: res.status,
+    body: payload,
+  })
+}
+
+/**
+ * Phase 1 of two-phase unlock: POST the unlock request with a NIP-98
+ * `authorization` header (signed by the survey key, payload-bound to {count})
+ * but no L402 credential, and capture the L402 challenge (macaroon + invoice).
+ * NIP-98 authenticates ownership; the L402 credential is carried separately in
+ * `X-Unlock-Authorization` so it never shadows the auth header.
+ *
+ * Returns { macaroon, invoice, breakdown } on the expected 402, or throws.
+ */
+export async function requestUnlock({
+  host = DEFAULT_HOST,
+  surveyId,
+  authorization,
+  count,
+  fetchImpl = fetch,
+}) {
+  if (!authorization) {
+    throw new LivyApiError('unlock requires a NIP-98 authorization header (no owner token exists)')
+  }
+  const res = await fetchImpl(`${host}/api/surveys/${encodeURIComponent(surveyId)}/unlock`, withTimeout({
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: authorization },
+    body: JSON.stringify({ count }),
+  }))
+
+  if (res.status === 402) {
+    const challenge = parseL402Challenge(res.headers.get('WWW-Authenticate'))
+    if (!challenge) {
+      throw new LivyApiError('402 without a parseable L402 challenge', { status: 402 })
+    }
+    const payload = await readJson(res)
+    return {
+      ...challenge,
+      breakdown: payload
+        ? {
+            unlock_count: payload.unlock_count,
+            sats_per_unlock: payload.sats_per_unlock,
+            total_sats: payload.total_sats,
+          }
+        : null,
+    }
+  }
+
+  const payload = await readJson(res)
+  throw new LivyApiError(
+    `unexpected status ${res.status} from unlock (expected 402 challenge)`,
+    { status: res.status, body: payload }
+  )
+}
+
+/**
+ * Phase 2 of two-phase unlock: re-POST with a FRESH NIP-98 `authorization`
+ * (payment happens out of band, so the phase-1 signature has expired by resume
+ * time) plus the L402 credential in `X-Unlock-Authorization`. Promotes the N
+ * oldest locked responses to `unlocked` (FIFO).
+ *
+ * Returns { unlocked, ids } (or { unlocked: 0, message } when nothing is locked).
+ */
+export async function resumeUnlock({
+  host = DEFAULT_HOST,
+  surveyId,
+  authorization,
+  count,
+  macaroon,
+  preimage,
+  fetchImpl = fetch,
+}) {
+  if (!authorization) {
+    throw new LivyApiError('unlock requires a NIP-98 authorization header (no owner token exists)')
+  }
+  const res = await fetchImpl(`${host}/api/surveys/${encodeURIComponent(surveyId)}/unlock`, withTimeout({
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: authorization,
+      'X-Unlock-Authorization': `L402 ${macaroon}:${preimage}`,
+    },
+    body: JSON.stringify({ count }),
+  }))
+
+  const payload = await readJson(res)
+  if (res.status === 200) return payload
+  throw new LivyApiError(`unlock resume failed (status ${res.status})`, {
+    status: res.status,
+    body: payload,
+  })
+}
+
+/** Fetch a survey's prepaid-pool balance (NIP-98 authorization, or owner Bearer). */
+export async function fetchBalance({
+  host = DEFAULT_HOST,
+  surveyId,
+  ownerToken,
+  authorization,
+  fetchImpl = fetch,
+}) {
+  const res = await fetchImpl(
+    `${host}/api/surveys/${encodeURIComponent(surveyId)}/balance`,
+    withTimeout({ headers: { Authorization: authorization ?? `Bearer ${ownerToken}` } })
+  )
+
+  const payload = await readJson(res)
+  if (res.status === 200) return payload
+  throw new LivyApiError(`fetch balance failed (status ${res.status})`, {
+    status: res.status,
+    body: payload,
+  })
+}
+
+/** Fetch a survey's responses with the owner Bearer token. */
+export async function fetchResponses({
+  host = DEFAULT_HOST,
+  surveyId,
+  ownerToken,
+  authorization,
+  since,
+  fetchImpl = fetch,
+}) {
+  const url = new URL(`${host}/api/surveys/${encodeURIComponent(surveyId)}/responses`)
+  if (since) url.searchParams.set('since', since)
+
+  const res = await fetchImpl(url.toString(), withTimeout({
+    headers: { Authorization: authorization ?? `Bearer ${ownerToken}` },
+  }))
+
+  const payload = await readJson(res)
+  if (res.status === 200) return payload
+  throw new LivyApiError(`fetch responses failed (status ${res.status})`, {
+    status: res.status,
+    body: payload,
+  })
+}
+
+/**
+ * Resolve a survey from its (public) encryption_pubkey via the lookup endpoint
+ * (foundation U3). Returns the public descriptor on 200, null on 404, and throws
+ * on any other status — so a recovery scan aborts on a real error rather than
+ * mistaking it for a miss. Used by `livybolt vault rebuild`.
+ */
+export async function lookupSurveyByPubkey({
+  host = DEFAULT_HOST,
+  encryptionPubkey,
+  fetchImpl = fetch,
+}) {
+  const url = new URL(`${host}/api/surveys`)
+  url.searchParams.set('encryption_pubkey', encryptionPubkey)
+  const res = await fetchImpl(url.toString(), withTimeout())
+  if (res.status === 404) return null
+  if (res.status === 200) return readJson(res)
+  throw new LivyApiError(`survey lookup failed (status ${res.status})`, {
+    status: res.status,
+    body: await readJson(res),
+  })
+}

package/scripts/livybolt.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// Livybolt — accountless, self-custody, end-to-end-encrypted surveys over Lightning.
+//
+// A thin router over the focused subcommand scripts. Each subcommand is its own
+// module (testable in isolation); this just dispatches argv and inherits stdio.
+//
+//   livybolt id      new | show | export | restore | unlock  (agent-identity.mjs)
+//   livybolt create  <survey.json>                            (survey-create.mjs)
+//   livybolt create  --resume <handle> --preimage <hex>       (survey-create.mjs)
+//   livybolt balance --survey <id>                            (balance.mjs)
+//   livybolt unlock  --survey <id> --count <n>                (unlock.mjs)
+//   livybolt unlock  --resume <handle> --preimage <hex>       (unlock.mjs)
+//   livybolt vault   add | list                               (token-vault.mjs)
+//   livybolt vault   read --survey <id>                       (vault-read.mjs)
+//   livybolt pair                                             (pair.mjs)
+//
+// Host defaults to https://livybolt.com (override LIVYBOLT_HOST or --host).
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+// The subcommands import `.ts` crypto modules directly, relying on Node's
+// type-stripping. That emits two unconditional warnings to stderr that would
+// otherwise clutter every command — silence just those, nothing else.
+const QUIET = ['--disable-warning=ExperimentalWarning', '--disable-warning=MODULE_TYPELESS_PACKAGE_JSON']
+const run = (script, args) =>
+  spawnSync(process.execPath, [...QUIET, join(here, script), ...args], { stdio: 'inherit' })
+
+function usage(code = 0) {
+  console.log(`livybolt — accountless surveys over Lightning
+
+Commands:
+  livybolt id <new|show|export|restore|unlock> [flags]   manage your self-custody key
+  livybolt create <survey.json>                          phase 1: get an invoice + handle
+  livybolt create --resume <handle> --preimage <hex>     phase 2: mint after paying
+  livybolt balance --survey <id> [--json]                prepaid-pool accounting
+  livybolt unlock --survey <id> --count <n>              phase 1: invoice to unlock N overage
+  livybolt unlock --resume <handle> --preimage <hex>     phase 2: unlock after paying
+  livybolt vault add --survey <id> --token <tok>         roll a survey into the vault
+  livybolt vault list [--password <pw>]                  list vaulted surveys
+  livybolt vault read --survey <id> [--json]             pull + decrypt responses
+  livybolt vault rebuild [--gap <n>] [--password <pw>]   recover the vault from the seed
+  livybolt pair [--no-qr]                                pair a browser dashboard (view seed QR)
+
+Host: $LIVYBOLT_HOST or --host (default https://livybolt.com)`)
+  process.exit(code)
+}
+
+const [command, ...rest] = process.argv.slice(2)
+
+let result
+switch (command) {
+  case 'id':
+    result = run('agent-identity.mjs', rest)
+    break
+  case 'create':
+    result = run('survey-create.mjs', rest)
+    break
+  case 'unlock':
+    result = run('unlock.mjs', rest)
+    break
+  case 'balance':
+    result = run('balance.mjs', rest)
+    break
+  case 'pair':
+    result = run('pair.mjs', rest)
+    break
+  case 'vault': {
+    const [sub, ...vrest] = rest
+    if (sub === 'read') result = run('vault-read.mjs', vrest)
+    else if (sub === 'rebuild') result = run('vault-rebuild.mjs', vrest)
+    else if (sub === 'add' || sub === 'list') result = run('token-vault.mjs', [sub, ...vrest])
+    else {
+      console.error(`error: unknown vault command: ${sub ?? '(none)'} (add | list | read | rebuild)`)
+      process.exit(1)
+    }
+    break
+  }
+  case 'help':
+  case '--help':
+  case '-h':
+  case undefined:
+    usage(0)
+    break
+  default:
+    console.error(`error: unknown command: ${command}`)
+    usage(1)
+}
+
+process.exit(result?.status ?? 0)

package/scripts/pair.mjs

@@ -0,0 +1,116 @@
+// `livybolt pair` — provision a browser dashboard with the VIEW seed.
+//
+//   1. Unlock the identity (master seed) locally.
+//   2. Derive the view seed — one-way, read-only hierarchy (view-key.ts).
+//   3. Choose a PAIRING password (distinct from the identity password: the
+//      browser must never learn a credential that opens anything but this blob).
+//   4. Seal the view seed as a tagged NIP-49 blob ("LVYV" — cannot be imported
+//      as a master seed, and a master backup cannot be imported as this).
+//   5. Render as a QR code + copyable string. The dashboard scans/pastes it and
+//      prompts for the pairing password.
+//
+// The blob is ciphertext only — the raw view seed never crosses a screen, a
+// QR, or a clipboard. It is also a DURABLE, PORTABLE credential: not
+// single-use, not expiring, not device-bound. It stays valid until view-seed
+// rotation, so a user may store the string in a password manager and pair any
+// future browser from it without this machine. Do not "harden" it with
+// nonces, TTLs, or one-time codes — the password is the gate; rotation is the
+// revocation.
+//
+// Master seed exposure: none. Only the derived view seed leaves this process,
+// and only encrypted. A compromised blob + password yields read access only —
+// rotatable, no identity, no creation authority.
+
+import qrcode from 'qrcode-terminal'
+import { sealViewSeed } from '../src/lib/crypto/seed-store.js'
+import { loadViewSeed } from './seed-unlock.mjs'
+import { readStore } from './agent-identity-store.mjs'
+import { resolveIdentityPassword, promptHidden } 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 === '--password') flags.password = argv[++i]
+    else if (a === '--pair-password') flags.pairPassword = argv[++i]
+    else if (a === '--no-qr') flags.noQr = true
+    else if (a.startsWith('--')) fail(`unknown argument: ${a}`)
+    else flags._.push(a)
+  }
+  return flags
+}
+
+/**
+ * Build the pairing blob: unlock → derive view seed → seal under the pairing
+ * password. Pure of terminal I/O so tests exercise the real path.
+ */
+export async function buildPairBlob({ resolvePassword, pairPassword }) {
+  if (!pairPassword) throw new Error('a pairing password is required')
+  const viewSeed = await loadViewSeed({ resolvePassword })
+  return sealViewSeed(viewSeed, pairPassword)
+}
+
+/** Resolve the NEW pairing password: flag, else interactive double prompt. */
+async function resolvePairPassword(flags) {
+  if (flags.pairPassword != null) return flags.pairPassword
+  if (!process.stdin.isTTY) {
+    fail('no pairing password. Pass --pair-password or run interactively.')
+  }
+  const first = await promptHidden('Choose a pairing password (the browser will ask for it once): ')
+  if (!first) fail('the pairing password must not be empty.')
+  const second = await promptHidden('Repeat the pairing password: ')
+  if (first !== second) fail('pairing passwords did not match.')
+  return first
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (!readStore()) {
+    fail('no identity found. Run `livybolt id new` first.')
+  }
+
+  // Track the identity password (when one is used) so we can refuse a pairing
+  // password that duplicates it — the browser must never receive a credential
+  // that also opens the local seed store (KTD-4).
+  let identityPassword
+  const resolvePassword = async () => {
+    identityPassword = await resolveIdentityPassword(flags, fail)
+    return identityPassword
+  }
+
+  // Unlock + derive first (identity prompt, when the store is encrypted),
+  // then choose the pairing password, then seal.
+  const viewSeed = await loadViewSeed({ resolvePassword })
+  const pairPassword = await resolvePairPassword(flags)
+  if (identityPassword !== undefined && pairPassword === identityPassword) {
+    fail('the pairing password must be different from your identity password.')
+  }
+  const blob = sealViewSeed(viewSeed, pairPassword)
+
+  console.log('Pairing blob (view seed, encrypted with your pairing password):')
+  console.log('')
+  console.log(blob)
+  console.log('')
+  if (!flags.noQr) {
+    // The QR encodes exactly the string above — one canonical encoding.
+    qrcode.generate(blob, { small: true })
+    console.log('')
+  }
+  console.log('On the dashboard: scan the QR (or paste the string), then enter')
+  console.log('the pairing password. The blob is reusable for future devices —')
+  console.log('you may keep it in a password manager. It grants READ access')
+  console.log('only, and view-seed rotation revokes it everywhere.')
+}
+
+// Run when invoked directly (node scripts/pair.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/pending-store.mjs

@@ -0,0 +1,70 @@
+// Local at-rest store for in-flight (created-but-unpaid) surveys. Between
+// `livybolt create` (phase 1: POST → 402 challenge) and `livybolt create --resume`
+// (phase 2: pay → redeem), the macaroon, invoice, the survey body, and the
+// freshly minted Survey Decrypt Key secret must survive process exit. They live
+// here, one file per handle, until resume succeeds and deletes the file.
+//
+// The Survey Decrypt Key secret is a real key at rest → dir 0700, files 0600.
+// Default: ~/.livybolt/pending/<handle>.json (shares LIVYBOLT_IDENTITY_HOME).
+
+import { join } from 'node:path'
+import {
+  mkdirSync,
+  writeFileSync,
+  readFileSync,
+  existsSync,
+  chmodSync,
+  rmSync,
+  readdirSync,
+} from 'node:fs'
+import { storeHome } from './agent-identity-store.mjs'
+
+export function pendingDir() {
+  return join(storeHome(), 'pending')
+}
+
+export function pendingPath(handle) {
+  return join(pendingDir(), `${handle}.json`)
+}
+
+export function writePending(handle, record) {
+  const dir = pendingDir()
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const path = pendingPath(handle)
+  writeFileSync(path, JSON.stringify(record, null, 2) + '\n', { mode: 0o600 })
+  chmodSync(path, 0o600)
+  return path
+}
+
+export class PendingStoreError extends Error {
+  constructor(code, message) {
+    super(message ?? code)
+    this.name = 'PendingStoreError'
+    this.code = code
+  }
+}
+
+export function readPending(handle) {
+  const path = pendingPath(handle)
+  if (!existsSync(path)) return null
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'))
+  } catch {
+    // A partially-written or corrupt handle file → fail loud and named, not a
+    // raw SyntaxError that hides which pending create is broken.
+    throw new PendingStoreError('corrupt', `pending survey "${handle}" at ${path} is not valid JSON`)
+  }
+}
+
+export function deletePending(handle) {
+  const path = pendingPath(handle)
+  if (existsSync(path)) rmSync(path)
+}
+
+export function listPending() {
+  const dir = pendingDir()
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.slice(0, -'.json'.length))
+}

package/scripts/seed-unlock.mjs

@@ -0,0 +1,111 @@
+// Unlock the agent's seed from the local identity store, and derive keys from it.
+//
+// The v2 store (see ./agent-identity-store.mjs) holds the SEED — plaintext words
+// (`secretKind: seed-plaintext`) or a NIP-49 ncryptsec of the BIP-39 entropy
+// (`secretKind: seed-entropy-nip49`). This module is the single seam that turns
+// the stored seed back into:
+//   - the mnemonic            (seedMnemonicFromRecord / loadSeedMnemonic)
+//   - the identity, account 0 (identityFromRecord — what the vault decryptors need)
+//   - a per-survey key, n>=1  (deriveSurveyKeyForIndex — the foundation-U2 seam)
+//
+// `resolvePassword` is an async fn the caller supplies; it is invoked ONLY when
+// the store is encrypted, so a plaintext store never triggers a prompt.
+
+import { agentIdentityFromSeedWords } from '../src/lib/crypto/agent-identity.js'
+import { unlockSeed } from '../src/lib/crypto/seed-store.js'
+import { deriveSurveyKeypair } from '../src/lib/crypto/survey-key.js'
+import { deriveViewSeed, deriveViewKeypair } from '../src/lib/crypto/view-key.js'
+import { parseRecipientSecret } from '../src/lib/crypto/recipient-key.js'
+import { readStore, storePath } from './agent-identity-store.mjs'
+
+export class SeedUnlockError extends Error {
+  constructor(code, message) {
+    super(message ?? code)
+    this.name = 'SeedUnlockError'
+    this.code = code
+  }
+}
+
+// Recover the seed mnemonic from a store record.
+export async function seedMnemonicFromRecord(rec, resolvePassword) {
+  if (!rec) {
+    throw new SeedUnlockError(
+      'no_identity',
+      `no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`
+    )
+  }
+  if (rec.secretKind === 'seed-plaintext') {
+    if (!rec.seedWords) {
+      throw new SeedUnlockError('corrupt_store', 'seed-plaintext store is missing its seedWords')
+    }
+    return rec.seedWords
+  }
+  if (rec.secretKind === 'seed-entropy-nip49') {
+    if (!rec.ncryptsec) {
+      throw new SeedUnlockError(
+        'corrupt_store',
+        'seed-entropy-nip49 store is missing its ncryptsec'
+      )
+    }
+    if (typeof resolvePassword !== 'function') {
+      throw new SeedUnlockError(
+        'no_resolver',
+        'a password resolver is required to open an encrypted seed store'
+      )
+    }
+    return unlockSeed(rec.ncryptsec, await resolvePassword())
+  }
+  throw new SeedUnlockError(
+    'unsupported_store',
+    `unrecognized identity store (secretKind=${rec.secretKind ?? 'none'}) — likely an old (pre-v2) store; re-provision with \`livybolt id new\``
+  )
+}
+
+// The agent identity (account 0, including privkey) recovered from the stored seed.
+// This is what the vault decryptors need: the vault entries are sealed to the
+// identity pubkey, so opening them requires the identity privkey.
+export async function identityFromRecord(rec, resolvePassword) {
+  return agentIdentityFromSeedWords(await seedMnemonicFromRecord(rec, resolvePassword))
+}
+
+// Read the store and recover the mnemonic.
+export async function loadSeedMnemonic({ resolvePassword } = {}) {
+  return seedMnemonicFromRecord(readStore(), resolvePassword)
+}
+
+// Derive survey n's keypair from the stored seed (n >= 1). The seam foundation
+// plan U2 (`livybolt create`) calls instead of generating a random key.
+export async function deriveSurveyKeyForIndex(index, { resolvePassword } = {}) {
+  return deriveSurveyKeypair(await loadSeedMnemonic({ resolvePassword }), index)
+}
+
+// Derive BOTH of survey n's keypairs — encryption (survey hierarchy) and view
+// (view hierarchy, same index) — from ONE unlock, so `livybolt create` registers
+// the pair without prompting for the password twice.
+export async function deriveSurveyKeysForIndex(index, { resolvePassword } = {}) {
+  const mnemonic = await loadSeedMnemonic({ resolvePassword })
+  return {
+    encryption: deriveSurveyKeypair(mnemonic, index),
+    view: deriveViewKeypair(deriveViewSeed(mnemonic), index),
+  }
+}
+
+// The view seed (a 12-word view mnemonic) recovered from the stored seed —
+// what `livybolt pair` seals into the pairing blob.
+export async function loadViewSeed({ resolvePassword } = {}) {
+  return deriveViewSeed(await loadSeedMnemonic({ resolvePassword }))
+}
+
+// The survey's private key for a vault entry, for signing NIP-98 read/unlock
+// auth: derived from the seed (derived surveys carry `surveyIndex`) or parsed
+// from the stored secret (legacy random-key surveys). Returns null when neither
+// is present (the caller falls back to the legacy owner token).
+export function surveyPrivkeyForEntry(entry, mnemonic) {
+  if (typeof entry.surveyIndex === 'number') {
+    return deriveSurveyKeypair(mnemonic, entry.surveyIndex).privkey
+  }
+  if (entry.surveyDecryptSecret) {
+    return parseRecipientSecret(entry.surveyDecryptSecret).privkey
+  }
+  return null
+}