nappup 2.3.10 → 2.3.11

package/README.md

@@ -76,7 +76,10 @@ export DOTENV_PRIVATE_KEY_NAPPUP="$(nappup env keygen)"
 
 `env keygen` writes only the generated 64-character lowercase hex key to standard output, writes a reminder to standard error, and never reads or modifies `.env`. Store the result in a secret manager; nappup cannot recover it.
 
-Because encryption itself requires only the public key, the following command can safely replace the Nostr secret without receiving the private key:
+Encrypting a replacement requires only `DOTENV_PUBLIC_KEY_NAPPUP`. The command
+below receives the **new Nostr credential** (a secret key or bunker URL), but does
+not require `DOTENV_PRIVATE_KEY_NAPPUP`, the separate **dotenv decryption key**.
+It does not need to decrypt or know the previous Nostr credential:
 
 ```bash
 nappup env set NOSTR_SECRET_KEY
@@ -89,6 +92,39 @@ Existing plaintext values are encrypted automatically when used. If an explicit
 
 Use `DOTENV_CONFIG_PATH` to select a different dotenv file. The private key must come from the process environment or CLI and is rejected if stored inside that file.
 
+### Local development and shared credentials
+
+To use a checkout instead of the registry package:
+
+```bash
+cd /path/to/nappup
+npm link
+cd /path/to/app
+npm link nappup --no-save --package-lock=false
+```
+
+The second command links the app dependency and its local CLI to the global link.
+Projects that use nappup at runtime can keep a registry dependency for reproducible
+installs; local CLI-only projects may rely entirely on the link. `npm ci` removes
+local links, so repeat the second command afterward. When switching Node/npm
+installations, repeat both commands to register the checkout under the new global
+prefix as well.
+
+A link shares code, not credentials: `.env` still defaults to the current working
+directory. To use one existing encrypted identity across projects, export an
+absolute path to its dotenv file in the shells running nappup:
+
+```bash
+export DOTENV_CONFIG_PATH="/absolute/path/to/shared/nappup.env"
+nappup env set NOSTR_SECRET_KEY
+```
+
+Choose an existing file to retain its identity, or set the desired credential once
+in a new file. Supply the matching `DOTENV_PRIVATE_KEY_NAPPUP` if that file uses a
+custom encryption key. Changing credentials in a shared file affects every project
+using it; existing project `.env` files are not automatically merged or migrated.
+A process-level `NOSTR_SECRET_KEY` still takes precedence over the file.
+
 ### Examples
 
 Upload the current directory to the main channel:
@@ -142,7 +178,22 @@ await publishApp(fileList, signer, {
 Rejected uploads use `NappupError`, with a stable code from
 `NAPPUP_ERROR_CODES`. The original error is retained as `cause`, and some
 errors include structured `details`, so applications can show their own
-recovery instructions without matching CLI-oriented message text:
+recovery instructions without matching CLI-oriented message text.
+
+For terminal destination failures, `error.details.failures` contains
+`{ destination, filename?, reason }` entries. `reason` retains the original error,
+including HTTP `status`, `retryable`, `retryAfterMs`, or relay `category` when
+available. Native causes and aggregated errors remain available for diagnostics.
+Signer failures are normalized to `NAPPUP_SIGNER_LOCKED` or `NAPPUP_SIGNER_DENIED`,
+including when nested inside an aggregate.
+
+A file succeeds when at least one destination confirms a copy (each chunk for
+IRFS). Failures of extra replicas are logged without emitting a terminal error.
+Publishing the app manifest still requires a confirmed copy. Display recovery
+instructions for rejected operations; use specific destination guidance only
+when it applies to all blocking failures. Different files may succeed on
+different servers.
+
 
 ```js
 import publishApp, { NAPPUP_ERROR_CODES } from 'nappup'

package/bin/nappup/helpers.js

@@ -90,13 +90,14 @@ function parseEnvArgs (args) {
 function hiddenQuestion (query, { input, output }) {
   return new Promise((resolve, reject) => {
     const wasRaw = Boolean(input.isRaw)
-    const wasPaused = input.isPaused?.() ?? false
+    const wasFlowing = input.readableFlowing === true
     let value = ''
 
     function cleanup () {
       input.off('keypress', onKeypress)
       input.setRawMode(wasRaw)
-      if (wasPaused) input.pause()
+      // An untouched TTY has readableFlowing === null, not isPaused() === true.
+      if (!wasFlowing) input.pause()
     }
 
     function onKeypress (text, key = {}) {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/44billion/nappup.git"
   },
   "license": "MIT",
-  "version": "2.3.10",
+  "version": "2.3.11",
   "description": "Nostr App Uploader",
   "type": "module",
   "scripts": {

package/src/errors.js

@@ -75,14 +75,27 @@ const SIGNER_DENIED_PATTERNS = [
   /sign(?:ing)? request (?:rejected|denied)/i
 ]
 
-// Walks the cause chain looking for signer-level failures such as a locked
-// vault or a rejected signing prompt. Returns a NAPPUP_* code or null.
+// Traverses native error trees without looping through cycles or unbounded causes.
+function * errorTree (error, seen = new Set(), depth = 0) {
+  if (!error || typeof error !== 'object' || seen.has(error) || depth >= 12) return
+  seen.add(error)
+  yield error
+  yield * errorTree(error.cause, seen, depth + 1)
+  if (Array.isArray(error.errors)) {
+    for (const child of error.errors) yield * errorTree(child, seen, depth + 1)
+  }
+}
+
+// Classifies original signer failures, not diagnostic text from servers or aggregates.
 export function classifySignerError (error) {
-  let current = error
-  for (let depth = 0; current && depth < 6; depth++) {
+  for (const current of errorTree(error)) {
     if (current.name === 'NotAllowedError' || current.code === 'DENIED_BY_USER') {
       return NAPPUP_ERROR_CODES.SIGNER_DENIED
     }
+    if (current.code === NAPPUP_ERROR_CODES.SIGNER_LOCKED || current.code === NAPPUP_ERROR_CODES.SIGNER_DENIED) {
+      return current.code
+    }
+    if (Array.isArray(current.errors) || current.category || current.code === 'BLOSSOM_HTTP_ERROR') continue
     const message = typeof current.message === 'string' ? current.message : ''
     if (SIGNER_LOCKED_PATTERNS.some(pattern => pattern.test(message))) {
       return NAPPUP_ERROR_CODES.SIGNER_LOCKED
@@ -90,20 +103,46 @@ export function classifySignerError (error) {
     if (SIGNER_DENIED_PATTERNS.some(pattern => pattern.test(message))) {
       return NAPPUP_ERROR_CODES.SIGNER_DENIED
     }
-    current = current.cause
   }
   return null
 }
 
+// Retains only failures of files with no confirmed Blossom copy.
+export function blossomUploadError (failedFiles) {
+  const failures = failedFiles.flatMap(file => (file.errors ?? []).map(({ server, error }) => ({
+    filename: file.filename, destination: server, reason: error
+  })))
+  return new NappupError(NAPPUP_ERROR_CODES.BLOSSOM_UPLOAD_FAILED,
+    `${failedFiles.length} file(s) failed to upload to Blossom`, {
+      cause: new AggregateError(failures.map(failure => failure.reason), 'Blossom destinations failed'),
+      details: {
+        failedFileCount: failedFiles.length,
+        filenames: failedFiles.map(file => file.filename).filter(Boolean),
+        failures
+      }
+    })
+}
+
+// Exposes destination failures consistently across Blossom and relay publication.
+function failureDetails (error) {
+  if (error?.details?.failures) return error.details
+  const failures = []
+  for (const current of errorTree(error)) {
+    if (!Array.isArray(current.failures)) continue
+    for (const { relay, reason } of current.failures) {
+      failures.push({ destination: relay, reason, ...(error?.details?.filename ? { filename: error.details.filename } : {}) })
+    }
+  }
+  return failures.length ? { ...error.details, failures } : error?.details
+}
+
 // Ensures every error crossing nappup's public API has a documented code.
 export function normalizeNappupError (error) {
+  const details = failureDetails(error)
   if (typeof error?.code === 'string' && error.code.startsWith('NAPPUP_')) {
-    const signerCode = classifySignerError(error)
-    if (signerCode && signerCode !== error.code) {
-      return new NappupError(signerCode, error.message, {
-        cause: error.cause,
-        details: error.details
-      })
+    const code = classifySignerError(error) ?? error.code
+    if (code !== error.code || details !== error.details) {
+      return new NappupError(code, error.message, { cause: error.cause, details })
     }
     return error
   }
@@ -111,12 +150,12 @@ export function normalizeNappupError (error) {
     return new NappupError(
       NAPPUP_ERROR_CODES.UPLOAD_CANCELLED,
       error?.message || 'Upload cancelled',
-      { cause: error }
+      { cause: error, details }
     )
   }
   return new NappupError(
     classifySignerError(error) ?? NAPPUP_ERROR_CODES.UPLOAD_FAILED,
     error?.message || 'Upload failed',
-    { cause: error }
+    { cause: error, details }
   )
 }

package/src/index.js

@@ -8,7 +8,7 @@ import { extractHtmlMetadata, findAppIcon, findIndexFile } from '#helpers/app-me
 import { getBlossomServers, healthCheckServers, uploadFilesToBlossom } from '#services/blossom-upload.js'
 import { uploadBinaryDataChunks } from '#services/irfs-upload.js'
 import { uploadSiteManifest } from '#services/site-manifest.js'
-import { NappupError, NAPPUP_ERROR_CODES, normalizeNappupError, classifySignerError } from '#errors.js'
+import { NappupError, NAPPUP_ERROR_CODES, normalizeNappupError, blossomUploadError } from '#errors.js'
 
 export { NappupError, NAPPUP_ERROR_CODES } from '#errors.js'
 
@@ -215,7 +215,7 @@ async function publishApp (fileList, nostrSigner, {
         shouldReupload,
         log
       })
-      if (failedFiles.length) throw new Error(`Blossom upload failed for ${mediaName}`)
+      if (failedFiles.length) throw blossomUploadError(failedFiles)
       return { rootHash: uploadedFiles[0].sha256, mimeType, size: blob.size }
     }
 
@@ -300,21 +300,7 @@ async function publishApp (fileList, nostrSigner, {
       shouldReupload,
       log
     })
-    if (failedFiles.length) {
-      const signerError = failedFiles
-        .flatMap(failed => failed.errors ?? [])
-        .map(failed => failed.error)
-        .find(error => classifySignerError(error))
-      const details = {
-        failedFileCount: failedFiles.length,
-        filenames: failedFiles.map(failed => failed.filename).filter(Boolean)
-      }
-      throw new NappupError(
-        NAPPUP_ERROR_CODES.BLOSSOM_UPLOAD_FAILED,
-        `${failedFiles.length} file(s) failed to upload to Blossom`,
-        signerError ? { cause: signerError, details } : { details }
-      )
-    }
+    if (failedFiles.length) throw blossomUploadError(failedFiles)
 
     for (const uploaded of uploadedFiles) {
       const metadata = {

package/src/services/blossom-upload.js

@@ -6,9 +6,11 @@ import { classifySignerError } from '#errors.js'
 
 const DEFAULT_HEALTH_CHECK_TIMEOUT_MS = 5000
 const DEFAULT_EXISTENCE_CHECK_TIMEOUT_MS = 5000
+const DEFAULT_UPLOAD_TIMEOUT_MS = 60000
+const MAX_RETRY_WAIT_MS = 60000
 
 // Bounds browser fetches whose native network timeout can take minutes.
-async function fetchWithTimeout (url, options, timeoutMs) {
+async function fetchWithTimeout (url, options, timeoutMs, consume = response => response) {
   const controller = new AbortController()
   let timedOut = false
   const timeoutId = setTimeout(() => {
@@ -16,9 +18,12 @@ async function fetchWithTimeout (url, options, timeoutMs) {
     controller.abort()
   }, timeoutMs)
   try {
-    return await fetch(url, { ...options, signal: controller.signal })
+    const response = await fetch(url, { ...options, signal: controller.signal })
+    return await consume(response)
   } catch (error) {
-    if (timedOut) throw new Error(`request timed out after ${timeoutMs}ms`)
+    if (timedOut) {
+      throw Object.assign(new Error(`request timed out after ${timeoutMs}ms`, { cause: error }), { category: 'timeout' })
+    }
     throw error
   } finally {
     clearTimeout(timeoutId)
@@ -104,12 +109,42 @@ export async function computeFileHash (file) {
   return bytesToBase16(hash.digest())
 }
 
+// Retry-After is advisory timing; X-Reason is diagnostic text, never policy.
+function retryAfterMs (value) {
+  if (!value) return 0
+  const text = value.trim()
+  if (/^\d+$/.test(text)) return Number(text) * 1000
+  const date = Date.parse(text)
+  return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0
+}
+
+async function readUploadResponse (response) {
+  if (response.status !== 200 && response.status !== 201) {
+    const status = response.status
+    const reason = response.headers.get('X-Reason') || response.statusText || 'No error message provided'
+    const error = new Error(`upload returned an error (${status}): ${reason}`)
+    error.code = 'BLOSSOM_HTTP_ERROR'
+    error.status = status
+    error.retryable = [408, 425, 429].includes(status) || (status >= 500 && status <= 599 && ![501, 505].includes(status))
+    error.retryAfterMs = retryAfterMs(response.headers.get('Retry-After'))
+    await response.body?.cancel().catch(() => {})
+    throw error
+  }
+  try {
+    return await response.json()
+  } catch (cause) {
+    if (!(cause instanceof SyntaxError)) throw cause
+    const error = new Error('upload returned an invalid JSON blob descriptor', { cause })
+    error.retryable = false
+    throw error
+  }
+}
+
 /**
- * Uploads a single file to a single blossom server with retry+backoff.
+ * Uploads a single file to a single blossom server with bounded retry+backoff.
  * Returns { success: true, descriptor } or { success: false, error }.
  */
-async function uploadFileToServer (serverUrl, signer, file, fileHash, mimeType, { shouldReupload, log, maxRetries = 5 }) {
-  // Check if already uploaded
+async function uploadFileToServer (serverUrl, signer, file, fileHash, mimeType, { shouldReupload, log, maxRetries = 5, uploadTimeoutMs }) {
   if (!shouldReupload) {
     try {
       const checkResponse = await fetchWithTimeout(
@@ -117,9 +152,7 @@ async function uploadFileToServer (serverUrl, signer, file, fileHash, mimeType,
         { method: 'HEAD' },
         DEFAULT_EXISTENCE_CHECK_TIMEOUT_MS
       )
-      if (checkResponse.ok) {
-        return { success: true, alreadyExists: true }
-      }
+      if (checkResponse.ok) return { success: true, alreadyExists: true }
     } catch (error) {
       log(`Could not check whether ${fileHash} exists on ${serverUrl}; uploading it anyway: ${error?.message ?? error}`)
     }
@@ -129,36 +162,36 @@ async function uploadFileToServer (serverUrl, signer, file, fileHash, mimeType,
   for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
       if (attempt > 0) {
-        log(`Retrying upload to ${serverUrl} (attempt ${attempt + 1}/${maxRetries + 1})`)
+        log(`Retrying upload to ${serverUrl} in ${pause}ms (attempt ${attempt + 1}/${maxRetries + 1})`)
         await new Promise(resolve => setTimeout(resolve, pause))
-        pause += 2000
       }
       const authorization = await createAuthHeader(signer, (evt) => {
         evt.tags.push(['t', 'upload'])
         evt.tags.push(['x', fileHash])
       })
-      const response = await fetch(`${serverUrl}/upload`, {
-        method: 'PUT',
-        headers: { 'Content-Type': mimeType, Authorization: authorization },
-        body: file.stream(),
-        duplex: 'half'
-      })
-      if (response.status >= 300) {
-        const reason = response.headers.get('X-Reason') || response.statusText
-        throw new Error(`upload returned an error (${response.status}): ${reason}`)
+      const headers = { 'Content-Type': mimeType, 'X-SHA-256': fileHash, Authorization: authorization }
+      // Browsers own Content-Length. A native Blob/File gives fetch its size;
+      // Node's file-like streaming adapter needs the known length explicitly.
+      if (globalThis.process?.versions?.node && Number.isSafeInteger(file.size) && file.size >= 0) {
+        headers['Content-Length'] = String(file.size)
       }
-      const descriptor = await response.json()
+      const isBlob = typeof Blob !== 'undefined' && file instanceof Blob
+      const descriptor = await fetchWithTimeout(`${serverUrl}/upload`, {
+        method: 'PUT', headers,
+        body: isBlob ? file : file.stream(),
+        ...(isBlob ? {} : { duplex: 'half' }),
+        redirect: 'manual'
+      }, uploadTimeoutMs, readUploadResponse)
       return { success: true, descriptor }
-    } catch (err) {
-      if (classifySignerError(err)) {
-        // Signer-level failures (locked vault, rejected prompt) are not
-        // transient upload errors: retrying would just re-prompt or fail
-        // again, so surface them immediately.
-        return { success: false, error: err }
+    } catch (error) {
+      if (classifySignerError(error) || error.name === 'AbortError' || error.retryable === false || attempt === maxRetries) {
+        return { success: false, error }
       }
-      if (attempt === maxRetries) {
-        return { success: false, error: err }
+      if (error.retryAfterMs > MAX_RETRY_WAIT_MS) {
+        log(`${serverUrl}: Retry-After exceeds the ${MAX_RETRY_WAIT_MS}ms automatic wait budget; retry in a later operation`)
+        return { success: false, error }
       }
+      pause = Math.max(1000 + attempt * 2000, error.retryAfterMs || 0)
     }
   }
   return { success: false, error: new Error('Max retries exceeded') }
@@ -180,6 +213,7 @@ export async function uploadFilesToBlossom ({
   signer,
   shouldReupload = false,
   maxRetries = 5,
+  uploadTimeoutMs = DEFAULT_UPLOAD_TIMEOUT_MS,
   log = () => {}
 }) {
   const normalizedServers = [...new Set(servers.flatMap(server => {
@@ -207,7 +241,7 @@ export async function uploadFilesToBlossom ({
     for (let i = 0; i < fileInfos.length; i++) {
       const info = fileInfos[i]
       log(`Uploading ${info.filename} to ${serverUrl}`)
-      const result = await uploadFileToServer(serverUrl, signer, info.file, info.sha256, info.mimeType, { shouldReupload, log, maxRetries })
+      const result = await uploadFileToServer(serverUrl, signer, info.file, info.sha256, info.mimeType, { shouldReupload, log, maxRetries, uploadTimeoutMs })
 
       if (result.success) {
         fileServerResults[i].successCount++
@@ -218,7 +252,7 @@ export async function uploadFilesToBlossom ({
         }
       } else {
         fileServerResults[i].errors.push({ server: serverUrl, error: result.error })
-        log(`${info.filename}: Failed to upload to ${serverUrl}: ${result.error?.message ?? result.error}`)
+        log(`${info.filename}: Failed to upload to ${serverUrl} (${info.mimeType}, ${info.file.size} bytes): ${result.error?.message ?? result.error}`)
       }
     }
   })

package/src/services/irfs-upload.js

@@ -168,6 +168,12 @@ export async function throttledSendEvent (event, relays, {
   }
   const maybeSuccessfulRelays = relays.length - noRetryErrors.length
   const hasReachedMaxRetries = retries > maxRetries
+  // Exhausted replication attempts cannot invalidate an already confirmed copy.
+  const confirmedRelays = relays.length - noRetryErrors.length - rateLimitErrors.length
+  if (hasReachedMaxRetries && confirmedRelays >= minSuccessfulRelays) {
+    log(`Replication retries exhausted; the required confirmations are already satisfied:\n${rateLimitErrors.map(formatRelayFailure).join('\n')}`)
+    return { pause }
+  }
   if (
     hasReachedMaxRetries ||
     maybeSuccessfulRelays < minSuccessfulRelays