livybolt 0.1.0 → 0.1.1

package/README.md

@@ -51,4 +51,3 @@ stores ciphertext and public keys only. **Back up the seed words** printed by
 ## Docs
 
 - CLI reference: https://livybolt.com/docs/cli
-- HTTP API reference: https://livybolt.com/docs/api

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "livybolt",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "livybolt — accountless, self-custody, end-to-end-encrypted surveys over Lightning. CLI client for Livybolt (Nostr edition).",
   "type": "module",
   "bin": {
@@ -15,7 +15,8 @@
     "README.md"
   ],
   "dependencies": {
-    "nostr-tools": "^2.23.5"
+    "nostr-tools": "^2.23.5",
+    "qrcode-terminal": "^0.12.0"
   },
   "scripts": {
     "prepack": "node prepack.mjs"

package/scripts/agent-identity.mjs

@@ -138,7 +138,7 @@ async function cmdNew(flags) {
 
 function cmdShow() {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
   console.log(`npub=${rec.npub}`)
   console.log(`pubkey=${rec.pubkey}`)
   console.log(`mode=${rec.secretKind === 'seed-plaintext' ? 'plaintext' : 'encrypted'}`)
@@ -147,7 +147,7 @@ function cmdShow() {
 
 async function cmdExport(flags) {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
   // The exported blob is a NIP-49 ncryptsec of the seed entropy — restore it with
   // `restore --ncryptsec`. It is NOT a portable nsec; the seed words are the
   // canonical cross-tool backup.
@@ -183,7 +183,7 @@ async function cmdRestore(flags) {
 
 async function cmdUnlock(flags) {
   const rec = readStore()
-  if (!rec) fail(`no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`)
+  if (!rec) fail(`no identity at ${storePath()}. Run: livybolt id new`)
   const password =
     rec.secretKind === 'seed-plaintext'
       ? undefined

package/scripts/seed-unlock.mjs

@@ -31,7 +31,7 @@ export async function seedMnemonicFromRecord(rec, resolvePassword) {
   if (!rec) {
     throw new SeedUnlockError(
       'no_identity',
-      `no identity at ${storePath()}. Run: node scripts/agent-identity.mjs new`
+      `no identity at ${storePath()}. Run: livybolt id new`
     )
   }
   if (rec.secretKind === 'seed-plaintext') {

package/scripts/token-vault.mjs

@@ -38,7 +38,7 @@ function parseFlags(argv) {
 
 function requireIdentity() {
   const rec = readStore()
-  if (!rec) fail('no identity. Run: node scripts/agent-identity.mjs new')
+  if (!rec) fail('no identity. Run: livybolt id new')
   return rec
 }
 

package/src/lib/nip98.js

@@ -0,0 +1,129 @@
+// NIP-98 HTTP Auth (kind 27235) for Livybolt's owner read/unlock path.
+//
+// A client proves it holds a survey's per-survey key by signing a short-lived
+// event bound to the request, sent as `Authorization: Nostr <base64-event>`.
+// The server verifies the signature resolves to the survey's (already public)
+// `encryption_pubkey` — so the IDENTITY key signs nothing to the server, and no
+// owner-token secret needs storing. Replaces the random owner token (foundation
+// U4); the per-survey pubkey is the public encryption target, so no new
+// correlation is leaked.
+//
+// We wrap nostr-tools' nip98 primitives but supply our own freshness + URL
+// policy: nostr-tools' validateEventTimestamp has no future-skew bound and its
+// URL check is exact-host-strict (fragile behind a proxy). We bind to the
+// request PATH (which carries the surveyId + action) rather than the host.
+
+import { finalizeEvent, verifyEvent } from 'nostr-tools/pure'
+import { getToken, unpackEventFromToken, hashPayload } from 'nostr-tools/nip98'
+
+const HTTP_AUTH_KIND = 27235
+/** Max age of a NIP-98 event the server will accept (replay window). */
+export const DEFAULT_MAX_AGE_SECONDS = 60
+/** Tolerated clock skew for events dated slightly in the future. */
+const FUTURE_SKEW_SECONDS = 5
+
+                                                                                                  
+
+/**
+ * CLIENT: sign a NIP-98 `Authorization` token for (url, method[, payload]) with
+ * the survey's secret key. Returns the full header value (`Nostr <base64>`).
+ */
+export async function signNip98Token(
+  url        ,
+  method        ,
+  secretKey            ,
+  payload          
+)                  {
+  return getToken(
+    url,
+    method,
+    (event) => finalizeEvent(event, secretKey),
+    true,
+    // hashPayload runs only when payload is truthy & non-empty (nostr-tools).
+    payload                                       
+  )
+}
+
+/**
+ * SERVER: verify a NIP-98 token against the request and the expected signer
+ * SET. Binds method, request path (proxy-robust), payload hash (when a body is
+ * present), a bounded freshness window, and `event.pubkey ∈ expectedPubkeys` —
+ * a survey accepts its encryption key (CLI) or its view key (dashboard).
+ */
+export async function verifyNip98Token(params   
+               
+                
+                                                            
+              
+                                                                         
+                
+                                                               
+                                                                            
+                                             
+                        
+                                                   
+              
+ )                             {
+  const { token, method, path, body } = params
+  const maxAge = params.maxAgeSeconds ?? DEFAULT_MAX_AGE_SECONDS
+  const now = params.now ?? Math.round(Date.now() / 1000)
+
+  // No pubkey to verify against (a misconfigured row): fail closed and
+  // explicitly, rather than relying on the signer-set membership check below
+  // to coincidentally reject every signer.
+  const expected = new Set(params.expectedPubkeys.filter((p)              => !!p))
+  if (expected.size === 0) return { valid: false, reason: 'no_expected_pubkey' }
+
+  let event                                                  
+  try {
+    event = await unpackEventFromToken(token)
+  } catch {
+    return { valid: false, reason: 'malformed_token' }
+  }
+  if (!event || event.kind !== HTTP_AUTH_KIND) return { valid: false, reason: 'wrong_kind' }
+  if (!verifyEvent(event)) return { valid: false, reason: 'bad_signature' }
+
+  // Freshness: reject too-old and too-far-future (clock-skew abuse).
+  const age = now - event.created_at
+  if (age > maxAge || age < -FUTURE_SKEW_SECONDS) return { valid: false, reason: 'expired' }
+
+  const methodTag = event.tags.find((t) => t[0] === 'method')?.[1]
+  if (!methodTag || methodTag.toLowerCase() !== method.toLowerCase()) {
+    return { valid: false, reason: 'method_mismatch' }
+  }
+
+  const urlTag = event.tags.find((t) => t[0] === 'u')?.[1]
+  if (!urlTag || !pathMatches(urlTag, path)) return { valid: false, reason: 'url_mismatch' }
+
+  if (hasBody(body)) {
+    const payloadTag = event.tags.find((t) => t[0] === 'payload')?.[1]
+    if (!payloadTag || payloadTag !== hashPayload(body                           )) {
+      return { valid: false, reason: 'payload_mismatch' }
+    }
+  }
+
+  if (!expected.has(event.pubkey)) return { valid: false, reason: 'wrong_signer' }
+
+  return { valid: true, pubkey: event.pubkey }
+}
+
+function hasBody(body         )          {
+  if (body === undefined || body === null) return false
+  if (typeof body === 'object') return Object.keys(body          ).length > 0
+  return true
+}
+
+function pathMatches(urlTag        , expectedPath        )          {
+  let tagPath        
+  try {
+    tagPath = new URL(urlTag).pathname
+  } catch {
+    // The `u` tag was not an absolute URL — compare the raw path (sans query).
+    tagPath = urlTag.split('?')[0]
+  }
+  return normalizePath(tagPath) === normalizePath(expectedPath)
+}
+
+function normalizePath(p        )         {
+  return p.replace(/\/+$/, '') || '/'
+}

package/src/lib/read/fetch-responses.js

@@ -0,0 +1,104 @@
+// Authenticated response fetching — sealed envelopes only, key injected as a
+// TOKEN PROVIDER so this module never touches key material.
+//
+// The caller supplies `tokenProvider(method, url)`, which returns a full
+// `Authorization` header value (`Nostr <base64-event>` — see ../nip98.ts
+// signNip98Token). The dashboard signs with the per-survey VIEW key; the CLI
+// signs with the per-survey encryption key; this module is identical for
+// both. Responses come back as the server stores them: sealed envelopes the
+// server cannot open.
+//
+// Isomorphic (no Node built-ins, injected fetch) so the same code runs in the
+// browser, the CLI, and tests.
+
+                                                                          
+
+export class FetchResponsesError extends Error {
+           code                         
+           status         
+  constructor(code                         , message         , status         ) {
+    super(message ?? code)
+    this.name = 'FetchResponsesError'
+    this.code = code
+    this.status = status
+  }
+}
+
+/** One stored response row: `data` is a sealed envelope when `encrypted`. */
+                                 
+            
+                     
+               
+                    
+                 
+                    
+ 
+
+                                
+                  
+               
+                                 
+                             
+                           
+                                                                
+                       
+ 
+
+const DEFAULT_TIMEOUT_MS = 15_000
+
+/**
+ * Fetch one page of a survey's responses, authenticated by the injected
+ * NIP-98 token provider. The token is signed over the EXACT URL requested
+ * (query string included) — the server binds method + path.
+ */
+export async function fetchResponses(options   
+              
+                  
+                                                                           
+                                                                 
+                
+                
+                    
+                          
+ )                         {
+  const host = options.host.replace(/\/+$/, '')
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  const query = new URLSearchParams()
+  if (options.since) query.set('since', options.since)
+  if (options.limit !== undefined) query.set('limit', String(options.limit))
+  const qs = query.size > 0 ? `?${query}` : ''
+  const url = `${host}/api/surveys/${encodeURIComponent(options.surveyId)}/responses${qs}`
+
+  const token = await options.tokenProvider('GET', url)
+
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  let res          
+  try {
+    res = await fetchImpl(url, {
+      headers: { Authorization: token },
+      signal: controller.signal,
+    })
+  } catch (err) {
+    if (controller.signal.aborted) {
+      throw new FetchResponsesError('timeout', `responses fetch timed out after ${timeoutMs}ms`)
+    }
+    throw new FetchResponsesError(
+      'network',
+      `responses fetch failed: ${err instanceof Error ? err.message : String(err)}`
+    )
+  } finally {
+    clearTimeout(timer)
+  }
+
+  if (!res.ok) {
+    throw new FetchResponsesError(
+      'http_error',
+      `responses fetch failed with status ${res.status}`,
+      res.status
+    )
+  }
+  return (await res.json())                 
+}

package/src/lib/read/rediscover.js

@@ -0,0 +1,107 @@
+// Gap-limit survey rediscovery — the HD-wallet scan, hierarchy-agnostic.
+//
+// The server is accountless: nothing links surveys to an owner. Any client
+// holding a seed re-discovers its surveys the way a restored wallet finds its
+// funds — derive the pubkey at account n, ask the public lookup to resolve
+// it, stop after `gapLimit` consecutive misses. `livybolt vault rebuild` runs
+// this over ENCRYPTION pubkeys (master-seed hierarchy); the dashboard runs
+// the identical algorithm over VIEW pubkeys (view-seed hierarchy). The
+// hierarchy difference is one injected function — the key-provider seam —
+// so the scan logic exists exactly once.
+//
+// Isomorphic (no Node built-ins, injected fetch) so the same code runs in the
+// browser, the CLI, and tests.
+
+import { FIRST_SURVEY_ACCOUNT_INDEX } from '../crypto/survey-key.js'
+
+/** The public, auth-free survey descriptor the lookup endpoint returns. */
+                                   
+                  
+              
+               
+                
+                                  
+                            
+ 
+
+                                     
+                  
+                                                                            
+                      
+                              
+ 
+
+                                                 
+
+export class RediscoverError extends Error {
+           code                     
+           status         
+  constructor(code                     , message         , status         ) {
+    super(message ?? code)
+    this.name = 'RediscoverError'
+    this.code = code
+    this.status = status
+  }
+}
+
+/**
+ * Walk account indexes from FIRST_SURVEY_ACCOUNT_INDEX, resolving each derived
+ * pubkey, until `gapLimit` consecutive misses (default 20 — parity with
+ * `livybolt vault rebuild`). A hit resets the gap. Returns every hit plus the next
+ * free index (server-truth: max occupied index + 1).
+ *
+ * `lookup` must return null ONLY for a definitive miss (404). A transport or
+ * server error must throw — swallowing it as a miss could prematurely satisfy
+ * the gap limit and silently truncate rediscovery.
+ */
+export async function rediscoverSurveys(options   
+                                                                                             
+                                                
+                                                                                
+                                                                 
+                   
+ )                                                              {
+  const gapLimit = options.gapLimit ?? 20
+  const found                       = []
+  let gap = 0
+  let n = FIRST_SURVEY_ACCOUNT_INDEX
+  let maxFound = 0
+  while (gap < gapLimit) {
+    const descriptor = await options.lookup(options.derivePubkey(n))
+    if (descriptor && descriptor.surveyId) {
+      gap = 0
+      maxFound = n
+      found.push({ surveyId: descriptor.surveyId, accountIndex: n, descriptor })
+    } else {
+      gap += 1
+    }
+    n += 1
+  }
+  return { found, nextIndex: Math.max(maxFound + 1, FIRST_SURVEY_ACCOUNT_INDEX) }
+}
+
+/**
+ * Build a `lookup` over the public resolver endpoint
+ * (`GET /api/surveys?view_pubkey=` or `?encryption_pubkey=`).
+ * 404 → null (a miss); any other non-OK status → RediscoverError (abort).
+ */
+export function makeDescriptorLookup(options   
+              
+                                            
+                          
+ )                                                          {
+  const host = options.host.replace(/\/+$/, '')
+  const fetchImpl = options.fetchImpl ?? fetch
+  return async (pubkeyHex        ) => {
+    const res = await fetchImpl(`${host}/api/surveys?${options.param}=${pubkeyHex}`)
+    if (res.status === 404) return null
+    if (!res.ok) {
+      throw new RediscoverError(
+        'lookup_failed',
+        `survey lookup failed with status ${res.status}`,
+        res.status
+      )
+    }
+    return (await res.json())                    
+  }
+}