livybolt 0.1.0

package/scripts/vault-read.mjs

@@ -0,0 +1,118 @@
+// `livybolt vault read --survey <id>` — pull a survey's responses and decrypt them
+// locally through the VaultDecryptor seam.
+//
+//   1. Unlock the identity (password if encrypted) and open the vault.
+//   2. Find the entry for <id> → ownerToken + surveyDecryptSecret.
+//   3. GET /api/surveys/:id/responses with the owner Bearer token.
+//   4. Open each encrypted envelope with the per-survey decrypt key.
+//
+// The decrypt secret lives only in the local vault; the server never holds a
+// key that can open the envelopes it stored.
+
+import { AgentIdentityError, agentIdentityFromSeedWords } from '../src/lib/crypto/agent-identity.js'
+import { deriveSurveyKeypair } from '../src/lib/crypto/survey-key.js'
+import { openVault, VaultError } from '../src/lib/crypto/token-vault.js'
+import { readStore } from './agent-identity-store.mjs'
+import { seedMnemonicFromRecord, surveyPrivkeyForEntry, SeedUnlockError } from './seed-unlock.mjs'
+import { resolveIdentityPassword } from './cli-prompt.mjs'
+import { signNip98Token } from '../src/lib/nip98.js'
+import { readVault } from './token-vault-store.mjs'
+import { fetchResponses, DEFAULT_HOST } from './livybolt-api.mjs'
+import { rawNsecVaultDecryptor, decryptResponses } from './vault-decrypt.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 === '--password') flags.password = argv[++i]
+    else if (a === '--host') flags.host = argv[++i]
+    else if (a === '--since') flags.since = argv[++i]
+    else if (a === '--json') flags.json = true
+    else fail(`unknown argument: ${a}`)
+  }
+  return flags
+}
+
+const resolvePassword = (flags) => resolveIdentityPassword(flags, fail)
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  if (!flags.survey) fail('usage: livybolt vault read --survey <id>')
+
+  const rec = readStore()
+  if (!rec) fail('no identity. Run: livybolt id new')
+
+  // Unlock the seed once: derive the identity key (to open the vault) and, for
+  // derived surveys, the per-survey decrypt key (from the stored account index).
+  const mnemonic = await seedMnemonicFromRecord(rec, () => resolvePassword(flags))
+  const { privkey } = agentIdentityFromSeedWords(mnemonic)
+
+  const entries = await openVault(readVault(), privkey)
+  const entry = entries.find((e) => e.surveyId === flags.survey)
+  if (!entry) fail(`survey ${flags.survey} not found in the vault.`)
+
+  // Authenticate the read with NIP-98 signed by the survey key (no owner token);
+  // fall back to the legacy owner token only when the entry carries no key.
+  const host = flags.host ?? DEFAULT_HOST
+  const surveyPrivkey = surveyPrivkeyForEntry(entry, mnemonic)
+  const authorization = surveyPrivkey
+    ? await signNip98Token(
+        `${host}/api/surveys/${encodeURIComponent(entry.surveyId)}/responses`,
+        'GET',
+        surveyPrivkey
+      )
+    : undefined
+
+  const result = await fetchResponses({
+    host,
+    surveyId: entry.surveyId,
+    ownerToken: entry.ownerToken,
+    authorization,
+    since: flags.since,
+  })
+
+  // Legacy surveys carry the nsec directly; derived surveys re-derive it from
+  // the seed + stored account index.
+  const decryptSecret =
+    entry.surveyDecryptSecret ??
+    (typeof entry.surveyIndex === 'number'
+      ? deriveSurveyKeypair(mnemonic, entry.surveyIndex).nsec
+      : null)
+
+  let rows = result.responses ?? []
+  if (decryptSecret) {
+    rows = await decryptResponses(rows, rawNsecVaultDecryptor(decryptSecret))
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ...result, responses: rows }, null, 2))
+    return
+  }
+
+  console.log(`survey:   ${result.survey?.title ?? entry.surveyId}`)
+  console.log(`collected:${result.totals?.collected ?? rows.length}  locked:${result.totals?.locked ?? 0}`)
+  console.log('')
+  for (const r of rows) {
+    const mark = r.encrypted ? (r.decrypted ? '🔓' : '🔒') : '·'
+    console.log(`${mark} #${r.ordinal} ${r.submittedAt}`)
+    console.log(`   ${JSON.stringify(r.data)}`)
+  }
+  console.log('')
+  console.log(`count=${rows.length}`)
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).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}`)
+    console.error(`error: ${err.message}`)
+    process.exit(1)
+  })
+}

package/scripts/vault-rebuild.mjs

@@ -0,0 +1,121 @@
+// `livybolt vault rebuild` — recover the vault from the seed alone (foundation U5).
+//
+// The server is accountless, so recovery works like restoring an HD wallet:
+// derive survey n's key at account n, ask the server to resolve its
+// encryption_pubkey (GET /surveys?encryption_pubkey=…, foundation U3), and on a
+// hit re-seal a {surveyId, surveyIndex} vault entry. Because reads now use NIP-98
+// signed by the survey key (foundation U4), a rebuilt entry needs no owner token
+// — the seed alone restores read access. Stop after `gap` consecutive misses.
+//
+// Only DERIVED surveys are recoverable. Legacy random-key surveys are not
+// re-derivable from the seed.
+
+import { deriveSurveyKeypair } from '../src/lib/crypto/survey-key.js'
+import { rediscoverSurveys } from '../src/lib/read/rediscover.js'
+import { agentIdentityFromSeedWords } from '../src/lib/crypto/agent-identity.js'
+import { sealVaultEntry, openVault } from '../src/lib/crypto/token-vault.js'
+import { readStore } from './agent-identity-store.mjs'
+import { readVault, appendVaultEnvelope } from './token-vault-store.mjs'
+import { seedMnemonicFromRecord } from './seed-unlock.mjs'
+import { resolveIdentityPassword } from './cli-prompt.mjs'
+import { lookupSurveyByPubkey, DEFAULT_HOST } from './livybolt-api.mjs'
+import { setNextIndex } from './survey-index-store.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 === '--gap') flags.gap = Number(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
+}
+
+/**
+ * Gap-limit scan: derive account n, look it up, collect hits, stop after
+ * `gapLimit` consecutive misses (HD-wallet gap limit — a gap wider than the
+ * limit truncates the scan). Pure: `lookup(pubkeyHex) => descriptor | null`.
+ * Returns every hit (`found`), the subset not already vaulted (`toAdd`), and the
+ * next free index.
+ *
+ * The scan itself lives in src/lib/read/rediscover.ts (shared with the
+ * dashboard, which runs it over VIEW pubkeys); this wrapper binds it to the
+ * encryption hierarchy and adds the vault-idempotence split.
+ */
+export async function scanForSurveys({
+  mnemonic,
+  lookup,
+  gapLimit = 20,
+  existingSurveyIds = new Set(),
+}) {
+  const { found: hits, nextIndex } = await rediscoverSurveys({
+    derivePubkey: (n) => deriveSurveyKeypair(mnemonic, n).pubkeyHex,
+    lookup,
+    gapLimit,
+  })
+  const found = hits.map((h) => ({ surveyId: h.surveyId, index: h.accountIndex }))
+  const toAdd = found.filter((h) => !existingSurveyIds.has(h.surveyId))
+  return { found, toAdd, nextIndex }
+}
+
+export async function main(argv) {
+  const flags = parseFlags(argv)
+  const gapLimit = Number.isInteger(flags.gap) && flags.gap > 0 ? flags.gap : 20
+  const host = flags.host ?? DEFAULT_HOST
+
+  const rec = readStore()
+  if (!rec) fail('no identity. Run: livybolt id new')
+  const mnemonic = await seedMnemonicFromRecord(rec, () => resolveIdentityPassword(flags, fail))
+  const identity = agentIdentityFromSeedWords(mnemonic)
+
+  // Read the existing vault so the rebuild is additive and idempotent. A missing
+  // vault reads as [] (nothing to preserve); a CORRUPT or undecryptable one must
+  // ABORT — swallowing it would treat the vault as empty and re-append every
+  // survey, or overwrite a vault we simply failed to read.
+  let existingSurveyIds = new Set()
+  const existing = readVault()
+  if (existing.length > 0) {
+    const entries = await openVault(existing, identity.privkey)
+    existingSurveyIds = new Set(entries.map((e) => e.surveyId))
+  }
+
+  // A network error (not a 404) must abort the scan, not look like a miss that
+  // could prematurely hit the gap limit and truncate recovery.
+  const lookup = (pubkeyHex) => lookupSurveyByPubkey({ host, encryptionPubkey: pubkeyHex })
+
+  const { found, toAdd, nextIndex } = await scanForSurveys({
+    mnemonic,
+    lookup,
+    gapLimit,
+    existingSurveyIds,
+  })
+
+  for (const hit of toAdd) {
+    const env = await sealVaultEntry(
+      { surveyId: hit.surveyId, surveyIndex: hit.index },
+      identity.pubkeyHex
+    )
+    appendVaultEnvelope(env)
+  }
+  setNextIndex(nextIndex)
+
+  console.log(`found=${found.length} added=${toAdd.length} next_index=${nextIndex}`)
+  console.error(
+    'Note: only DERIVED surveys are recoverable from the seed. Legacy random-key ' +
+      'surveys are not re-derivable — restore their vault.json copy to read them.'
+  )
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv.slice(2)).catch((err) => {
+    console.error(`error: ${err.message}`)
+    process.exit(1)
+  })
+}

package/src/lib/crypto/agent-identity.js

@@ -0,0 +1,85 @@
+// Agent Identity Key — a per-agent Nostr keypair an agent provisions CLIENT-SIDE.
+//
+// This is the agent's stable *name* (`npub`) and the future *lock* on its token
+// vault (and, later, a *signer* for linking into a dashboard account). It is
+// generated and held entirely on the client — the server never sees the secret.
+//
+// It is DISTINCT from the Survey Decrypt Key (see ./recipient-key.ts): that key
+// decrypts one survey's *response contents*; this key is an *identity*. The two
+// are functionally separate and must never be conflated. This module deliberately
+// does not import recipient-key — they share only the secp256k1 + nostr-tools
+// primitives, nothing else.
+//
+// Built on a NIP-06 seed (BIP-39 mnemonic → HD-derived key, account index 0,
+// path m/44'/1237'/0'/0/0) so the *seed words* are the canonical backup and
+// purpose-isolated subkeys remain possible later. Seed-at-rest encryption lives
+// in ./seed-store.ts (NIP-49 of the BIP-39 entropy). Like ./recipient-key.ts this
+// is isomorphic (nostr-tools only) so the same code runs in the browser, the CLI,
+// and tests.
+
+import { getPublicKey } from 'nostr-tools/pure'
+import * as nip19 from 'nostr-tools/nip19'
+import { generateSeedWords, validateWords, privateKeyFromSeedWords } from 'nostr-tools/nip06'
+
+// NIP-06 account index. The identity is account 0; per-survey keys derive at
+// account n (see ./survey-key.ts).
+const DEFAULT_ACCOUNT_INDEX = 0
+
+                                
+                                                                           
+                                                               
+                    
+                                                   
+                     
+                                                                             
+                   
+                                                                         
+              
+                                                                              
+              
+ 
+
+                                                              
+
+export class AgentIdentityError extends Error {
+           code                        
+  constructor(code                        , message         ) {
+    super(message ?? code)
+    this.name = 'AgentIdentityError'
+    this.code = code
+  }
+}
+
+/** Generate a fresh identity from a new BIP-39 seed. */
+export function generateAgentIdentity()                {
+  return agentIdentityFromSeedWords(generateSeedWords())
+}
+
+/**
+ * Restore (or derive) an identity from BIP-39 seed words — the canonical,
+ * recoverable path. Deterministic: the same mnemonic always yields the same key.
+ */
+export function agentIdentityFromSeedWords(
+  mnemonic        ,
+  passphrase         ,
+  accountIndex         = DEFAULT_ACCOUNT_INDEX
+)                {
+  const words = mnemonic.trim()
+  if (!words) throw new AgentIdentityError('empty')
+  if (!validateWords(words)) {
+    throw new AgentIdentityError('invalid_words', 'not a valid BIP-39 mnemonic')
+  }
+  const privkey = privateKeyFromSeedWords(words, passphrase, accountIndex)
+  return fromPrivkey(privkey, words)
+}
+
+function fromPrivkey(privkey            , seedWords         )                {
+  const pubkeyHex = getPublicKey(privkey)
+  return {
+    seedWords,
+    privkey,
+    pubkeyHex,
+    nsec: nip19.nsecEncode(privkey),
+    npub: nip19.npubEncode(pubkeyHex),
+  }
+}

package/src/lib/crypto/envelope.js

@@ -0,0 +1,253 @@
+// End-to-end encrypted response envelope.
+//
+// The server is content-blind: it stores and serves this object without ever
+// holding a key that can open it. Encryption happens in the respondent's
+// browser; decryption happens in the owner's browser.
+//
+// Scheme (envelope / hybrid encryption):
+//   1. The response plaintext is encrypted once with a fresh random 256-bit
+//      content-encryption key (CEK) under AES-256-GCM (an AEAD — ciphertext is
+//      tamper-evident).
+//   2. The CEK is wrapped to each recipient's secp256k1 pubkey with NIP-44 v2.
+//      A single ephemeral keypair per envelope provides the sender side of the
+//      ECDH (respondents are anonymous and hold no identity key); the shared
+//      `epk` lets each recipient re-derive their conversation key.
+//
+// Wrapping the small CEK per-recipient (rather than re-encrypting the bulk) is
+// what makes recovery contacts cheap: add a recipient = add one wrapped key.
+//
+// Isomorphic: depends only on Web Crypto (`globalThis.crypto.subtle`) and
+// nostr-tools, both available in modern browsers and Node ≥ 20.
+
+import * as nip44 from 'nostr-tools/nip44'
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure'
+
+export const ENVELOPE_VERSION = 1         
+/** Cap on response plaintext, matching the adopted roadmap. */
+export const MAX_PLAINTEXT_BYTES = 64 * 1024
+
+const ALG = 'AES-256-GCM'         
+const HEX64 = /^[0-9a-f]{64}$/
+
+                             
+                                                         
+            
+                                                                     
+            
+ 
+
+                           
+           
+                 
+                                                                       
+             
+                                          
+            
+                                                                   
+            
+                    
+ 
+
+                               
+                   
+                              
+                         
+                        
+                         
+                     
+                    
+
+export class EnvelopeError extends Error {
+           code                   
+  constructor(code                   , message         ) {
+    super(message ?? code)
+    this.name = 'EnvelopeError'
+    this.code = code
+  }
+}
+
+const subtle = ()               => {
+  const c = globalThis.crypto
+  if (!c?.subtle) throw new EnvelopeError('decrypt_failed', 'Web Crypto unavailable')
+  return c.subtle
+}
+
+/**
+ * UTF-8 encode onto a plain `ArrayBuffer`. `TextEncoder` returns
+ * `Uint8Array<ArrayBufferLike>`, which lib.dom's `BufferSource` (Web Crypto)
+ * rejects because it permits `SharedArrayBuffer`; re-homing onto a fresh
+ * `ArrayBuffer` satisfies the type without an `any` cast.
+ */
+function utf8(s        )                          {
+  const enc = new TextEncoder().encode(s)
+  const out = new Uint8Array(enc.length)
+  out.set(enc)
+  return out
+}
+
+/** Additional authenticated data: binds the ciphertext to its version + alg. */
+function aad(version        )                          {
+  return utf8(`lightsurvey/envelope/${version}/${ALG}`)
+}
+
+export async function sealEnvelope(
+  plaintext        ,
+  recipientPubkeys          
+)                    {
+  if (!Array.isArray(recipientPubkeys) || recipientPubkeys.length === 0) {
+    throw new EnvelopeError('no_recipients')
+  }
+  for (const pk of recipientPubkeys) {
+    if (typeof pk !== 'string' || !HEX64.test(pk)) {
+      throw new EnvelopeError('invalid_recipient_pubkey', `not an x-only hex pubkey: ${pk}`)
+    }
+  }
+  const recipients = [...new Set(recipientPubkeys)]
+
+  const plaintextBytes = utf8(plaintext)
+  if (plaintextBytes.length > MAX_PLAINTEXT_BYTES) {
+    throw new EnvelopeError(
+      'plaintext_too_large',
+      `${plaintextBytes.length} bytes exceeds ${MAX_PLAINTEXT_BYTES}`
+    )
+  }
+
+  // 1. Bulk encryption under a fresh CEK.
+  const cek = globalThis.crypto.getRandomValues(new Uint8Array(32))
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))
+  const aesKey = await subtle().importKey('raw', cek, 'AES-GCM', false, ['encrypt'])
+  const ctBuf = await subtle().encrypt(
+    { name: 'AES-GCM', iv, additionalData: aad(ENVELOPE_VERSION) },
+    aesKey,
+    plaintextBytes
+  )
+
+  // 2. Wrap the CEK to each recipient with one shared ephemeral keypair.
+  const esk = generateSecretKey()
+  const epk = getPublicKey(esk)
+  const cekB64 = bytesToBase64(cek)
+  const keys               = recipients.map((pk) => ({
+    pk,
+    wk: nip44.encrypt(cekB64, nip44.getConversationKey(esk, pk)),
+  }))
+
+  return {
+    v: ENVELOPE_VERSION,
+    alg: ALG,
+    epk,
+    iv: bytesToBase64(iv),
+    ct: bytesToBase64(new Uint8Array(ctBuf)),
+    keys,
+  }
+}
+
+/**
+ * The decryption seam. Opening an envelope needs exactly one capability: a
+ * NIP-44 v2 decrypt of the per-recipient wrapped key. Modelling that as an
+ * interface lets the bulk AES-GCM step stay in one place while the key-unwrap
+ * is provided by either a raw private key (here) or a remote signer such as a
+ * NIP-46 bunker (which exposes `nip44_decrypt` but never the key itself).
+ */
+                                 
+                                                                                    
+                         
+     
+                                                                          
+                                                                              
+     
+                                                                       
+ 
+
+/**
+ * Raw-private-key backend for the {@link VaultDecryptor} seam. The key lives in
+ * memory and performs the NIP-44 unwrap directly. The bunker backend (deferred)
+ * implements the same interface by delegating to the remote signer.
+ */
+export function rawNsecDecryptor(recipientPrivkey            )                 {
+  return {
+    pubkey: getPublicKey(recipientPrivkey),
+    async nip44Decrypt(peerPubkey        , ciphertext        )                  {
+      const convKey = nip44.getConversationKey(recipientPrivkey, peerPubkey)
+      return nip44.decrypt(ciphertext, convKey)
+    },
+  }
+}
+
+/**
+ * Open an envelope through the {@link VaultDecryptor} seam. The decryptor
+ * supplies the NIP-44 unwrap of the CEK; the AES-256-GCM bulk decrypt is done
+ * here so there is exactly one copy of it regardless of key backend.
+ */
+export async function openEnvelopeWith(
+  envelope          ,
+  decryptor                
+)                  {
+  if (!isEnvelope(envelope)) throw new EnvelopeError('malformed_envelope')
+  if (envelope.v !== ENVELOPE_VERSION) {
+    throw new EnvelopeError('unsupported_version', `envelope version ${envelope.v}`)
+  }
+
+  const entry = envelope.keys.find((k) => k.pk === decryptor.pubkey)
+  if (!entry) throw new EnvelopeError('not_a_recipient')
+
+  try {
+    const cek = base64ToBytes(await decryptor.nip44Decrypt(envelope.epk, entry.wk))
+    if (cek.length !== 32) throw new Error('bad CEK length')
+
+    const aesKey = await subtle().importKey('raw', cek, 'AES-GCM', false, ['decrypt'])
+    const ptBuf = await subtle().decrypt(
+      { name: 'AES-GCM', iv: base64ToBytes(envelope.iv), additionalData: aad(envelope.v) },
+      aesKey,
+      base64ToBytes(envelope.ct)
+    )
+    return new TextDecoder().decode(ptBuf)
+  } catch (err) {
+    if (err instanceof EnvelopeError) throw err
+    throw new EnvelopeError('decrypt_failed', err instanceof Error ? err.message : undefined)
+  }
+}
+
+export async function openEnvelope(
+  envelope          ,
+  recipientPrivkey            
+)                  {
+  return openEnvelopeWith(envelope, rawNsecDecryptor(recipientPrivkey))
+}
+
+export function isEnvelope(value         )                    {
+  if (typeof value !== 'object' || value === null) return false
+  const e = value                           
+  return (
+    typeof e.v === 'number' &&
+    e.alg === ALG &&
+    typeof e.epk === 'string' &&
+    typeof e.iv === 'string' &&
+    typeof e.ct === 'string' &&
+    Array.isArray(e.keys) &&
+    e.keys.every(
+      (k) =>
+        typeof k === 'object' &&
+        k !== null &&
+        typeof (k              ).pk === 'string' &&
+        typeof (k              ).wk === 'string'
+    )
+  )
+}
+
+// ── base64 (isomorphic; handles up to 64 KiB without call-stack blowup) ───────
+
+function bytesToBase64(bytes            )         {
+  let binary = ''
+  const CHUNK = 0x8000
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK))
+  }
+  return btoa(binary)
+}
+
+function base64ToBytes(b64        )                          {
+  const binary = atob(b64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}

package/src/lib/crypto/recipient-key.js

@@ -0,0 +1,111 @@
+// Recipient (decryption) keypair for encrypted surveys.
+//
+// The owner of an encrypted survey holds a secp256k1 keypair. Responses are
+// sealed to its pubkey (the survey's `encryption_pubkey`); only the matching
+// private key can open them. For email/passkey/anonymous owners the keypair is
+// generated in the browser and the secret is shown ONCE as an `nsec` for
+// backup — it never reaches the server, so losing it is permanent data loss.
+// NIP-07/NIP-46 signers are the power-user path (handled elsewhere).
+//
+// This module is the pure key-handling core: generation, bech32 encoding, and
+// robust parsing of an owner-pasted secret (nsec or hex) back into bytes. It is
+// isomorphic (nostr-tools only) so the same code runs in the browser and tests.
+
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure'
+import * as nip19 from 'nostr-tools/nip19'
+
+const HEX64 = /^[0-9a-fA-F]{64}$/
+// Shape of a bech32 string (`<hrp>1<data>`) — used to tell "wrong kind of key"
+// (e.g. an npub pasted as a secret) apart from outright garbage.
+const BECH32_SHAPE = /^[a-z]+1[02-9ac-hj-np-z]+$/
+
+                                   
+                                                   
+                     
+                                                                        
+                   
+                                                      
+              
+                                             
+              
+ 
+
+                                                                        
+
+export class RecipientKeyError extends Error {
+           code                       
+  constructor(code                       , message         ) {
+    super(message ?? code)
+    this.name = 'RecipientKeyError'
+    this.code = code
+  }
+}
+
+export function generateRecipientKeypair()                   {
+  const privkey = generateSecretKey()
+  const pubkeyHex = getPublicKey(privkey)
+  return {
+    privkey,
+    pubkeyHex,
+    nsec: nip19.nsecEncode(privkey),
+    npub: nip19.npubEncode(pubkeyHex),
+  }
+}
+
+/**
+ * Parse an owner-supplied decryption secret — either an `nsec` or raw 64-char
+ * hex — into the private key bytes and derived pubkey. Throws RecipientKeyError
+ * with a specific `code` rather than leaking bech32/parse internals to the UI.
+ */
+export function parseRecipientSecret(input        )   
+                     
+                   
+  {
+  const trimmed = input.trim()
+  if (!trimmed) throw new RecipientKeyError('empty')
+
+  let privkey            
+  if (HEX64.test(trimmed)) {
+    privkey = hexToBytes32(trimmed.toLowerCase())
+  } else if (BECH32_SHAPE.test(trimmed)) {
+    const decoded = decodeBech32(trimmed)
+    if (decoded.type !== 'nsec') throw new RecipientKeyError('wrong_type', `got ${decoded.type}`)
+    privkey = decoded.data
+  } else {
+    throw new RecipientKeyError('malformed', 'expected an nsec or 64-char hex secret')
+  }
+
+  return { privkey, pubkeyHex: getPublicKey(privkey) }
+}
+
+/**
+ * Parse a recovery-contact pubkey — either an `npub` or raw 64-char hex — into
+ * x-only lowercase hex. Rejects nsec/other bech32 with `wrong_type` so a pasted
+ * secret can never be silently stored as a recipient.
+ */
+export function parsePubkey(input        )         {
+  const trimmed = input.trim()
+  if (!trimmed) throw new RecipientKeyError('empty')
+
+  if (HEX64.test(trimmed)) return trimmed.toLowerCase()
+  if (BECH32_SHAPE.test(trimmed)) {
+    const decoded = decodeBech32(trimmed)
+    if (decoded.type !== 'npub') throw new RecipientKeyError('wrong_type', `got ${decoded.type}`)
+    return decoded.data
+  }
+  throw new RecipientKeyError('malformed', 'expected an npub or 64-char hex pubkey')
+}
+
+function decodeBech32(value        )                                  {
+  try {
+    return nip19.decode(value)
+  } catch {
+    throw new RecipientKeyError('malformed', 'not valid bech32')
+  }
+}
+
+function hexToBytes32(hex        )             {
+  const bytes = new Uint8Array(32)
+  for (let i = 0; i < 32; i++) bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16)
+  return bytes
+}