livybolt 0.1.0

package/src/lib/crypto/seed-store.js

@@ -0,0 +1,164 @@
+// Seed at rest — seal/unlock a BIP-39 mnemonic as a NIP-49 `ncryptsec`.
+//
+// Per-survey keys derive from the agent's ONE seed (see ./survey-key.ts), so the
+// seed — not the account-0 private key — is what must rest at rest. NIP-49
+// encrypts a secret of 16/32 bytes; a BIP-39 mnemonic's *entropy* is exactly that
+// (16 bytes for 12 words, 32 for 24), and round-trips back to the mnemonic. So we
+// seal the entropy with the literal NIP-49 primitive (scrypt + XChaCha20-Poly1305)
+// and reconstruct the words on unlock.
+//
+// CAVEAT: the resulting `ncryptsec` encodes seed ENTROPY, not a signing `nsec`.
+// The seed words are the canonical portable backup; this blob is an
+// at-rest/transport encoding. To stop a generic Nostr tool from silently
+// importing it as a private key, the entropy is prefixed with a magic tag before
+// encryption (see SEED_BLOB_HEADER): the decrypted payload is then MAGIC‖entropy
+// (21 or 37 bytes), never a 32-byte secp256k1 key, so a foreign NIP-49 tool
+// rejects it on length instead of deriving a wrong-but-usable key. The tag also
+// lets `restore --ncryptsec` reject a foreign blob loudly rather than misreading
+// arbitrary 32-byte plaintext as seed entropy.
+//
+// Isomorphic (nostr-tools + @scure/bip39 only) so the same code runs in the
+// browser, the CLI, and tests — and can later ride into a shared `livybolt-core`.
+
+import { encrypt as nip49Encrypt, decrypt as nip49Decrypt } from 'nostr-tools/nip49'
+import { validateWords } from 'nostr-tools/nip06'
+import * as bip39 from '@scure/bip39'
+// The `.js` suffix is required by @scure/bip39's package exports (v2.x).
+import { wordlist } from '@scure/bip39/wordlists/english.js'
+
+// NIP-49 scrypt work factor (log2 N). 16 is the common default; the CLI uses it.
+const DEFAULT_LOGN = 16
+
+// Self-identifying tags prepended to the entropy before NIP-49 encryption:
+// ASCII magic + a 1-byte format version. Bump the version if the payload
+// layout ever changes. Their length (5) keeps the tagged payload off the
+// 16/32-byte entropy sizes, so a tagged blob can never be mistaken for a bare
+// nsec or bare entropy. Two DISTINCT tags keep the two secrets apart: a
+// master-seed backup ("LVYS") can never be imported as a pairing view blob
+// ("LVYV") and vice versa — the unlock functions reject a cross-tag blob
+// loudly instead of quietly restoring the wrong hierarchy.
+const SEED_BLOB_HEADER = new Uint8Array([0x4c, 0x56, 0x59, 0x53, 0x01]) // "LVYS" v1
+const VIEW_BLOB_HEADER = new Uint8Array([0x4c, 0x56, 0x59, 0x56, 0x01]) // "LVYV" v1
+
+                                                                                        
+
+export class SeedStoreError extends Error {
+           code                    
+  constructor(code                    , message         ) {
+    super(message ?? code)
+    this.name = 'SeedStoreError'
+    this.code = code
+  }
+}
+
+/**
+ * Seal a BIP-39 mnemonic into a NIP-49 `ncryptsec` of its entropy. The password
+ * is required to open it again.
+ */
+export function sealSeed(mnemonic        , password        , logN         = DEFAULT_LOGN)         {
+  return sealTagged(SEED_BLOB_HEADER, mnemonic, password, logN)
+}
+
+/**
+ * Open a NIP-49 `ncryptsec` (of seed entropy) back into the BIP-39 mnemonic. A
+ * wrong password (or a corrupt blob) fails AEAD authentication → `bad_password`.
+ */
+export function unlockSeed(ncryptsec        , password        )         {
+  return unlockTagged(
+    SEED_BLOB_HEADER,
+    ncryptsec,
+    password,
+    'this ncryptsec is not a Livybolt seed backup (missing format tag) — restore from your seed words instead'
+  )
+}
+
+/**
+ * Seal the VIEW seed (a 12-word view mnemonic — see ./view-key.ts) as the
+ * pairing blob `livybolt pair` renders. Distinct tag from the master backup, so
+ * neither blob can be imported as the other. The blob is a durable, portable
+ * credential — no nonce, TTL, or device binding by design: it stays valid
+ * until view-seed rotation, and a user may keep it in a password manager to
+ * pair future browsers without the CLI machine.
+ */
+export function sealViewSeed(
+  viewMnemonic        ,
+  password        ,
+  logN         = DEFAULT_LOGN
+)         {
+  return sealTagged(VIEW_BLOB_HEADER, viewMnemonic, password, logN)
+}
+
+/** Open a pairing blob back into the view mnemonic (browser import path). */
+export function unlockViewSeed(ncryptsec        , password        )         {
+  return unlockTagged(
+    VIEW_BLOB_HEADER,
+    ncryptsec,
+    password,
+    'this ncryptsec is not a Livybolt pairing blob (missing view tag) — export one with `livybolt pair`'
+  )
+}
+
+function sealTagged(
+  header            ,
+  mnemonic        ,
+  password        ,
+  logN        
+)         {
+  const words = mnemonic.trim()
+  if (!words) throw new SeedStoreError('empty', 'a non-empty mnemonic is required')
+  if (!password) throw new SeedStoreError('empty', 'a non-empty password is required')
+  if (!validateWords(words)) {
+    throw new SeedStoreError('invalid_words', 'not a valid BIP-39 mnemonic')
+  }
+  const entropy = bip39.mnemonicToEntropy(words, wordlist)
+  // Tag the entropy so the blob is self-identifying (see the headers above).
+  const tagged = new Uint8Array(header.length + entropy.length)
+  tagged.set(header, 0)
+  tagged.set(entropy, header.length)
+  return nip49Encrypt(tagged, password, logN)
+}
+
+function unlockTagged(
+  header            ,
+  ncryptsec        ,
+  password        ,
+  untaggedMessage        
+)         {
+  if (!password) throw new SeedStoreError('empty', 'a non-empty password is required')
+  let payload            
+  try {
+    payload = nip49Decrypt(ncryptsec.trim(), password)
+  } catch {
+    throw new SeedStoreError(
+      'bad_password',
+      'could not decrypt — wrong password or corrupt ncryptsec'
+    )
+  }
+  // NIP-49 is authenticated (XChaCha20-Poly1305), so a successful decrypt means
+  // the password was correct. If the plaintext lacks the expected tag it is NOT
+  // this kind of Livybolt blob — a foreign ncryptsec (e.g. a raw nsec), a pre-tag
+  // blob, or the OTHER Livybolt blob kind. Reject it loudly rather than feeding
+  // arbitrary bytes to entropyToMnemonic.
+  if (!hasHeader(header, payload)) {
+    throw new SeedStoreError('untagged', untaggedMessage)
+  }
+  const entropy = payload.subarray(header.length)
+  let mnemonic        
+  try {
+    mnemonic = bip39.entropyToMnemonic(entropy, wordlist)
+  } catch {
+    throw new SeedStoreError('bad_password', 'decrypted payload is not valid seed entropy')
+  }
+  if (!validateWords(mnemonic)) {
+    throw new SeedStoreError('bad_password', 'decrypted payload is not a valid seed')
+  }
+  return mnemonic
+}
+
+function hasHeader(header            , payload            )          {
+  if (payload.length <= header.length) return false
+  for (let i = 0; i < header.length; i++) {
+    if (payload[i] !== header[i]) return false
+  }
+  return true
+}

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

@@ -0,0 +1,97 @@
+// Per-survey decryption keypair, DERIVED from the agent's one seed.
+//
+// Today an encrypted survey's decryption key is random (see
+// ./recipient-key.ts `generateRecipientKeypair`) and lives only in the local
+// vault — lose the vault and the responses are unrecoverable even though you
+// "still have your seed." This module removes that footgun: every survey key is
+// a deterministic function of the seed at a NIP-06 account index, so the seed
+// words are the single backup and the vault becomes a rebuildable cache.
+//
+// Account 0 is RESERVED for the agent identity (see ./agent-identity.ts).
+// Surveys derive at account n >= 1, so a survey decryption key can never collide
+// with the identity key. These derived keys are app-internal encryption keypairs
+// (they receive NIP-44-sealed responses); they are NOT Nostr identities and must
+// never sign public Nostr events — that is what keeps NIP-06's "prefer a single
+// nsec" identity guidance inapplicable here. We use the BIP-32/SLIP-44 (coin
+// 1237) derivation math NIP-06 documents, nothing more.
+//
+// Isomorphic (nostr-tools only) so the same code runs in the browser, the CLI,
+// and tests — and, later, the extracted livybolt-core shared by the native clients.
+
+import { getPublicKey } from 'nostr-tools/pure'
+import * as nip19 from 'nostr-tools/nip19'
+import { privateKeyFromSeedWords, validateWords } from 'nostr-tools/nip06'
+                                                       
+
+/** Account index reserved for the agent identity — never a survey. */
+export const IDENTITY_ACCOUNT_INDEX = 0
+/** First valid survey account index (surveys start here, n >= 1). */
+export const FIRST_SURVEY_ACCOUNT_INDEX = 1
+/** Highest valid account index — NIP-06 derives a hardened path, so the index
+ *  must fit the BIP-32 hardened range (< 2^31). */
+export const MAX_SURVEY_ACCOUNT_INDEX = 0x7fffffff
+
+/** A survey's decryption keypair plus the account index it derives from. */
+                                                                
+                                                                  
+                      
+ 
+
+                                                                                               
+
+export class SurveyKeyError extends Error {
+           code                    
+  constructor(code                    , message         ) {
+    super(message ?? code)
+    this.name = 'SurveyKeyError'
+    this.code = code
+  }
+}
+
+/**
+ * Derive survey n's decryption keypair from the agent's BIP-39 seed at NIP-06
+ * account index n (n >= 1). Deterministic: the same mnemonic + index always
+ * yields the same key, which is what makes the seed a complete backup.
+ *
+ * @param mnemonic BIP-39 seed words — the canonical backup.
+ * @param accountIndex NIP-06 account index; must be an integer >= 1 (0 is the
+ *   reserved identity account).
+ * @param passphrase Optional BIP-39 passphrase (the "25th word"); must match
+ *   whatever the identity was derived with.
+ */
+export function deriveSurveyKeypair(
+  mnemonic        ,
+  accountIndex        ,
+  passphrase         
+)                       {
+  const words = mnemonic.trim()
+  if (!words) throw new SurveyKeyError('empty')
+  if (!Number.isInteger(accountIndex)) {
+    throw new SurveyKeyError('invalid_index', 'account index must be an integer')
+  }
+  if (accountIndex < FIRST_SURVEY_ACCOUNT_INDEX) {
+    throw new SurveyKeyError(
+      'reserved_index',
+      `account ${accountIndex} is reserved for the identity; surveys start at ${FIRST_SURVEY_ACCOUNT_INDEX}`
+    )
+  }
+  if (accountIndex > MAX_SURVEY_ACCOUNT_INDEX) {
+    throw new SurveyKeyError(
+      'invalid_index',
+      `account ${accountIndex} exceeds the BIP-32 hardened range (max ${MAX_SURVEY_ACCOUNT_INDEX})`
+    )
+  }
+  if (!validateWords(words)) {
+    throw new SurveyKeyError('invalid_words', 'not a valid BIP-39 mnemonic')
+  }
+
+  const privkey = privateKeyFromSeedWords(words, passphrase, accountIndex)
+  const pubkeyHex = getPublicKey(privkey)
+  return {
+    accountIndex,
+    privkey,
+    pubkeyHex,
+    nsec: nip19.nsecEncode(privkey),
+    npub: nip19.npubEncode(pubkeyHex),
+  }
+}

package/src/lib/crypto/token-vault.js

@@ -0,0 +1,116 @@
+// Token Vault — a per-agent, encrypted list of the surveys an agent owns.
+//
+// Each entry pairs a survey with the credentials needed to (a) CLAIM it into an
+// account later (`ownerToken`) and (b) READ its encrypted responses now
+// (`surveyDecryptSecret` — the per-survey Survey Decrypt Key secret). Bundling
+// the decrypt secret here is what makes the agent-native read/analyze loop work:
+// unlock the identity once, open the vault, and every survey's responses become
+// readable.
+//
+// Entries are sealed individually TO the Agent Identity Key's pubkey (see
+// ./envelope.ts). Two deliberate properties follow:
+//   • APPEND needs only the pubkey — rolling a new survey in never requires
+//     unlocking the identity (no password).
+//   • READ needs the private key — only an unlocked identity can open the vault.
+//
+// The vault is the *lock's contents*; the Agent Identity Key is the *lock*. They
+// stay separate from the Survey Decrypt Keys the entries carry. Isomorphic
+// (envelope.ts + nostr-tools only); the node-only file store lives in
+// scripts/token-vault-store.mjs.
+
+// Explicit `.ts` extension: this module is also loaded directly by the raw-node
+// CLI/smoke scripts (Node's type-stripper resolves relative TS imports only with
+// the extension). `allowImportingTsExtensions` keeps tsc happy; bundler/vitest
+// resolution is unaffected.
+import { sealEnvelope, openEnvelope, isEnvelope,               } from './envelope.js'
+
+                                  
+                                                       
+                  
+                                                                              
+                                                                             
+                                                                              
+                                                                  
+                     
+                                                                                  
+                                                                              
+                              
+                                                                                 
+                                                                           
+                                                                             
+                      
+ 
+
+                                                     
+                                                         
+                 
+ 
+
+                                              
+
+export class VaultError extends Error {
+           code                
+  constructor(code                , message         ) {
+    super(message ?? code)
+    this.name = 'VaultError'
+    this.code = code
+  }
+}
+
+/**
+ * Seal one entry to the identity pubkey. Takes only a PUBLIC key — appending to
+ * the vault never needs the identity's secret (no unlock/password).
+ */
+export async function sealVaultEntry(
+  input                 ,
+  identityPubkeyHex        
+)                    {
+  const entry             = { ...input, addedAt: new Date().toISOString() }
+  return sealEnvelope(JSON.stringify(entry), [identityPubkeyHex])
+}
+
+/** Open one sealed entry with the identity private key. */
+export async function openVaultEntry(
+  envelope          ,
+  identityPrivkey            
+)                      {
+  // openEnvelope throws EnvelopeError (e.g. not_a_recipient) — let it propagate.
+  const json = await openEnvelope(envelope, identityPrivkey)
+  let parsed         
+  try {
+    parsed = JSON.parse(json)
+  } catch {
+    throw new VaultError('malformed_entry', 'entry is not valid JSON')
+  }
+  if (!isVaultEntry(parsed)) {
+    throw new VaultError(
+      'malformed_entry',
+      'entry needs a surveyId and either an ownerToken (legacy) or a surveyIndex (derived)'
+    )
+  }
+  return parsed
+}
+
+/** Open an entire vault (array of sealed envelopes) in order. */
+export async function openVault(
+  envelopes            ,
+  identityPrivkey            
+)                        {
+  const out               = []
+  for (const env of envelopes) out.push(await openVaultEntry(env, identityPrivkey))
+  return out
+}
+
+/** A vault is stored as an array of these sealed envelopes. */
+export function isVaultEnvelope(value         )                    {
+  return isEnvelope(value)
+}
+
+function isVaultEntry(value         )                      {
+  if (typeof value !== 'object' || value === null) return false
+  const e = value                           
+  if (typeof e.surveyId !== 'string') return false
+  // A legacy entry is keyed by its ownerToken; a derived (rebuilt) entry by its
+  // surveyIndex. Exactly one is required — an entry with neither is malformed.
+  return typeof e.ownerToken === 'string' || typeof e.surveyIndex === 'number'
+}

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

@@ -0,0 +1,98 @@
+// View-seed hierarchy — the browser's read-only root, derived ONE-WAY from the
+// master seed.
+//
+// The dashboard must decrypt responses without ever holding the master seed
+// (see docs/plans/2026-07-02-001-feat-view-seed-web-dashboard-plan.md). This
+// module is the split: a VIEW SEED is computed from the master mnemonic via
+// HKDF with a domain-separation tag, and per-survey VIEW KEYS derive from it at
+// the SAME NIP-06 account index as the survey's encryption key. One-way by
+// construction: view seed → view keys is derivable; view seed → master is not.
+// Same-index derivation is what makes browser rediscovery and seed-only
+// recovery free — one scan algorithm, two hierarchies.
+//
+// The HKDF input is the BIP-39 *seed* (mnemonicToSeed of words + optional
+// passphrase), not the raw entropy: the passphrase ("25th word") must change
+// the view hierarchy exactly as it changes every other derived key, and the
+// passphrase never touches the entropy. The 16-byte HKDF output becomes a
+// 12-word view MNEMONIC, so downstream derivation reuses the canonical NIP-06
+// `privateKeyFromSeedWords` unchanged (and the view seed seals/transports via
+// the same NIP-49 machinery as the master, under its own blob tag).
+//
+// View keys are app-internal encryption keypairs (they receive NIP-44-sealed
+// CEK wraps); they are NOT Nostr identities and must never sign public Nostr
+// events — the same rule as ./survey-key.ts.
+//
+// Isomorphic (nostr-tools + @scure/bip39 + @noble/hashes only) so the same
+// code runs in the browser, the CLI, and tests.
+
+import { hkdf } from '@noble/hashes/hkdf.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+import { validateWords } from 'nostr-tools/nip06'
+import * as bip39 from '@scure/bip39'
+// The `.js` suffix is required by @scure/bip39's package exports (v2.x).
+import { wordlist } from '@scure/bip39/wordlists/english.js'
+// Explicit `.ts` extension: this module is also loaded directly by the raw-node
+// CLI scripts (`livybolt pair`, `livybolt create`) — Node's type-stripper resolves
+// relative TS imports only with the extension (same rule as ./token-vault.ts).
+import {
+  deriveSurveyKeypair,
+  SurveyKeyError,
+                            
+} from './survey-key.js'
+
+/** HKDF domain-separation tag. Bump the version if the derivation ever changes
+ *  — existing view seeds would rotate, master-derived keys would not. */
+export const VIEW_SEED_TAG = 'lightsurvey/view-seed/v1'
+
+/** A survey's view keypair plus the account index it derives from. Shape-
+ *  identical to the encryption keypair — same envelope seam, different root. */
+                                                     
+
+                                                                                             
+
+export class ViewKeyError extends Error {
+           code                  
+  constructor(code                  , message         ) {
+    super(message ?? code)
+    this.name = 'ViewKeyError'
+    this.code = code
+  }
+}
+
+/**
+ * Derive the view seed (a 12-word mnemonic) one-way from the master mnemonic.
+ * Deterministic: the same master words + passphrase always yield the same view
+ * seed, so the 12 master words remain the single canonical backup — the view
+ * seed needs none of its own.
+ *
+ * @param mnemonic Master BIP-39 seed words.
+ * @param passphrase Optional BIP-39 passphrase; must match whatever the
+ *   identity/survey keys were derived with (it changes the view seed too).
+ */
+export function deriveViewSeed(mnemonic        , passphrase         )         {
+  const words = mnemonic.trim()
+  if (!words) throw new ViewKeyError('empty', 'a non-empty mnemonic is required')
+  if (!validateWords(words)) {
+    throw new ViewKeyError('invalid_words', 'not a valid BIP-39 mnemonic')
+  }
+  const masterSeed = bip39.mnemonicToSeedSync(words, passphrase)
+  const tag = new TextEncoder().encode(VIEW_SEED_TAG)
+  const viewEntropy = hkdf(sha256, masterSeed, undefined, tag, 16)
+  return bip39.entropyToMnemonic(viewEntropy, wordlist)
+}
+
+/**
+ * Derive survey n's VIEW keypair from the view seed at NIP-06 account index n
+ * (n >= 1, account 0 reserved — mirroring the encryption hierarchy so the two
+ * stay index-parallel). Runs the same guards and math as
+ * `deriveSurveyKeypair`, just over the view seed.
+ */
+export function deriveViewKeypair(viewSeed        , accountIndex        )                     {
+  try {
+    return deriveSurveyKeypair(viewSeed, accountIndex)
+  } catch (e) {
+    // Re-type so callers of this module handle one error surface.
+    if (e instanceof SurveyKeyError) throw new ViewKeyError(e.code, e.message)
+    throw e
+  }
+}