nappup 2.0.1 → 2.2.0

package/README.md

@@ -33,6 +33,7 @@ nappup [directory] [options]
 | `--main` | Publish to the **main** release channel. This is the default behavior. |
 | `--next` | Publish to the **next** release channel. Ideal for beta testing or staging builds. |
 | `--draft` | Publish to the **draft** release channel. Use this for internal testing or work-in-progress builds. |
+| `--dotenv-private-key <hex>` | Use a 32-byte hex private key to decrypt and manage encrypted credentials in `.env`. Prefer `DOTENV_PRIVATE_KEY_NAPPUP` because command-line arguments can be visible in shell history and process listings. |
 
 ## Authentication
 
@@ -47,6 +48,7 @@ Napp Up! supports multiple ways to provide your Nostr secret key:
    ```bash
    nappup -s 'bunker://<pubkey>?relay=wss://relay.example.com&secret=<token>'
    ```
+   Napp Up! creates a persistent NIP-46 client key before connecting. For URLs passed with `-s`, the latest session is stored as `LAST_CLI_BUNKER_SESSION` in the project's `.env`. A URL without `secret` is also valid when the remote signer uses its public key as the access capability.
 
 3. **Environment variable**: Set `NOSTR_SECRET_KEY` in your environment or a `.env` file (also supports `bunker://` URLs):
    ```bash
@@ -56,6 +58,37 @@ Napp Up! supports multiple ways to provide your Nostr secret key:
 
 4. **Auto-generated key**: If no key is provided, Napp Up! will generate a new keypair automatically and store it (as nsec) in your project's `.env` file for future use.
 
+When `NOSTR_SECRET_KEY` in `.env` is a bunker URL, Napp Up! adds the local client key as a `#client_key=...` URI fragment while retaining the query-string `secret` for compatibility fallback. Reconnects first use the same client key without the token and retry with the token only if necessary.
+
+Napp Up! stores `NOSTR_SECRET_KEY` and `LAST_CLI_BUNKER_SESSION` in the official dotenvx `encrypted:<base64>` format, using the compressed public key in `DOTENV_PUBLIC_KEY_NAPPUP`. The private key is selected from `--dotenv-private-key`, then `DOTENV_PRIVATE_KEY_NAPPUP` in the process environment, and finally a built-in fallback. The public key is selected from the `.env`, then the process environment, and finally derived from the selected private key.
+
+The built-in fallback makes migration automatic, but is public knowledge and therefore only hides plaintext; use an explicit private key for confidentiality. Generate one locally for storage in your secret manager with:
+
+```bash
+nappup env keygen
+```
+
+Alternatively, generate and export one directly into the current shell:
+
+```bash
+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:
+
+```bash
+nappup env set NOSTR_SECRET_KEY
+printf '%s\n' 'nsec1...' | nappup env set NOSTR_SECRET_KEY
+```
+
+The interactive form hides and confirms the value. Redirected stdin and a positional value are also accepted; the positional form emits a warning because it may be exposed through shell history or process listings. With only `DOTENV_PUBLIC_KEY_NAPPUP`, `env set` can encrypt a replacement, while commands that need an existing value fail clearly without the matching private key.
+
+Existing plaintext values are encrypted automatically when used. If an explicit private key does not match the stored public key, it becomes authoritative: recoverable values are re-encrypted and inaccessible credentials are reset with a warning naming only the affected variables. This can result in a new publisher identity or bunker client key.
+
+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.
+
 ### Examples
 
 Upload the current directory to the main channel:

package/bin/nappup/helpers.js

@@ -6,12 +6,15 @@ import mime from 'mime-types'
 import { fileTypeFromFile } from 'file-type'
 
 export function parseArgs (args) {
+  if (args[0] === 'env') return parseEnvArgs(args)
+
   let dir = null
   let sk = null
   let dTag = null
   let channel = null
   let shouldReupload = false
   let yes = false
+  let dotenvPrivateKey = null
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '-s' && args[i + 1]) {
@@ -30,19 +33,123 @@ export function parseArgs (args) {
       shouldReupload = true
     } else if (args[i] === '-y') {
       yes = true
+    } else if (args[i] === '--dotenv-private-key' && args[i + 1]) {
+      dotenvPrivateKey = args[i + 1]
+      i++
+    } else if (args[i] === '--dotenv-private-key') {
+      throw new Error('--dotenv-private-key requires a value')
     } else if (!args[i].startsWith('-') && dir === null) {
       dir = args[i]
     }
   }
 
   return {
+    command: 'upload',
     dir: path.resolve(dir ?? '.'),
     sk,
     dTag,
     channel: channel || 'main',
     shouldReupload,
-    yes
+    yes,
+    dotenvPrivateKey
+  }
+}
+
+function parseEnvArgs (args) {
+  if (args[1] === 'keygen') {
+    if (args.length !== 2) throw new Error('Expected: nappup env keygen')
+    return { command: 'env-keygen' }
+  }
+  if (args[1] !== 'set') throw new Error('Expected: nappup env set NOSTR_SECRET_KEY [value]')
+  if (args[2] !== 'NOSTR_SECRET_KEY') throw new Error('Only NOSTR_SECRET_KEY can be set')
+
+  let value = null
+  let dotenvPrivateKey = null
+  for (let i = 3; i < args.length; i++) {
+    if (args[i] === '--dotenv-private-key') {
+      if (!args[i + 1]) throw new Error('--dotenv-private-key requires a value')
+      dotenvPrivateKey = args[++i]
+    } else if (args[i] === '--') {
+      if (value !== null || !args[i + 1] || i + 2 !== args.length) throw new Error('Expected one NOSTR_SECRET_KEY value')
+      value = args[++i]
+    } else if (value === null) {
+      value = args[i]
+    } else {
+      throw new Error('Expected one NOSTR_SECRET_KEY value')
+    }
   }
+
+  return {
+    command: 'env-set',
+    name: 'NOSTR_SECRET_KEY',
+    value,
+    dotenvPrivateKey
+  }
+}
+
+function hiddenQuestion (query, { input, output }) {
+  return new Promise((resolve, reject) => {
+    const wasRaw = Boolean(input.isRaw)
+    const wasPaused = input.isPaused?.() ?? false
+    let value = ''
+
+    function cleanup () {
+      input.off('keypress', onKeypress)
+      input.setRawMode(wasRaw)
+      if (wasPaused) input.pause()
+    }
+
+    function onKeypress (text, key = {}) {
+      if (key.ctrl && key.name === 'c') {
+        cleanup()
+        output.write('\n')
+        const error = new Error('Operation cancelled by user')
+        error.code = 'ABORT_ERR'
+        reject(error)
+      } else if (key.name === 'return' || key.name === 'enter') {
+        cleanup()
+        output.write('\n')
+        resolve(value)
+      } else if (key.name === 'backspace') {
+        value = value.slice(0, -1)
+      } else if (text && !key.ctrl && !key.meta) {
+        value += text
+      }
+    }
+
+    readline.emitKeypressEvents(input)
+    input.setRawMode(true)
+    input.resume()
+    input.on('keypress', onKeypress)
+    output.write(query)
+  })
+}
+
+async function readPipedValue (input) {
+  let value = ''
+  for await (const chunk of input) {
+    value += chunk
+    if (value.length > 65536) throw new Error('NOSTR_SECRET_KEY input is too large')
+  }
+  return value.replace(/(?:\r\n|\n)$/, '')
+}
+
+export async function readEnvSetValue (args, {
+  input = process.stdin,
+  output = process.stdout,
+  errorOutput = process.stderr
+} = {}) {
+  if (args.value !== null) {
+    errorOutput.write('Warning: a plaintext value passed as an argument may be visible in shell history and process listings.\n')
+    return args.value
+  }
+  if (!input.isTTY) return readPipedValue(input)
+  if (typeof input.setRawMode !== 'function') throw new Error('Cannot hide input on this terminal')
+
+  const first = await hiddenQuestion('NOSTR_SECRET_KEY: ', { input, output })
+  const second = await hiddenQuestion('Confirm NOSTR_SECRET_KEY: ', { input, output })
+  if (first !== second) throw new Error('NOSTR_SECRET_KEY values do not match')
+  return first
 }
 
 export async function confirmArgs (args) {

package/bin/nappup/index.js

@@ -1,51 +1,85 @@
 #!/usr/bin/env node
 import path from 'node:path'
-import NostrSigner from '#services/nostr-signer.js'
 import { GENERIC_BUILD_FOLDER_NAMES } from '#helpers/app.js'
 import {
   parseArgs,
   confirmArgs,
+  readEnvSetValue,
   toFileList,
   getFiles
 } from './helpers.js'
-import toApp from '#index.js'
 
 const args = parseArgs(process.argv.slice(2))
 
-let { dTag } = args
-const { dir, sk, channel, shouldReupload } = args
-
-if (!dTag) {
-  let folderName = path.basename(dir)
-  if (GENERIC_BUILD_FOLDER_NAMES.has(folderName.toLowerCase())) {
-    const parentName = path.basename(path.dirname(dir))
-    if (parentName && parentName !== '.' && parentName !== '/' && !GENERIC_BUILD_FOLDER_NAMES.has(parentName.toLowerCase())) {
-      folderName = parentName
-    } else {
-      console.error(`Directory name "${folderName}" is a generic build folder. Please provide a d tag with -d.`)
-      process.exit(1)
-    }
+if (args.command === 'env-keygen') {
+  const { keypair } = await import('@dotenvx/primitives')
+  const { privateKey } = keypair()
+  console.error('Keep this dotenv private key secret; nappup has not stored it.')
+  process.stdout.write(`${privateKey}\n`)
+} else {
+  const dotenv = await import('#services/dotenv.js')
+  const dotenvState = dotenv.initializeDotenv({
+    privateKey: args.dotenvPrivateKey,
+    loadNostrSecretKey: args.command === 'upload' && !args.sk,
+    reconcilePrivateKey: args.command === 'upload'
+  })
+
+  if (args.command === 'env-set') {
+    const { validateNostrSecretKey } = await import('#services/nostr-secret-key.js')
+    const value = await readEnvSetValue(args)
+    validateNostrSecretKey(value)
+    dotenv.setEncryptedDotenvValue(args.name, value, {
+      filePath: dotenvState.filePath,
+      updateProcessEnv: false
+    })
+    console.log(`Set encrypted ${args.name} in ${dotenvState.filePath}`)
+  } else {
+    await upload(args, dotenvState)
   }
-  dTag = folderName
 }
-args.dTag = dTag
 
-await confirmArgs(args)
+async function upload (args, dotenvState) {
+  let { dTag } = args
+  const { dir, sk, channel, shouldReupload } = args
 
-const fileList = await toFileList(getFiles(dir), dir)
+  if (!dTag) {
+    let folderName = path.basename(dir)
+    if (GENERIC_BUILD_FOLDER_NAMES.has(folderName.toLowerCase())) {
+      const parentName = path.basename(path.dirname(dir))
+      if (parentName && parentName !== '.' && parentName !== '/' && !GENERIC_BUILD_FOLDER_NAMES.has(parentName.toLowerCase())) {
+        folderName = parentName
+      } else {
+        console.error(`Directory name "${folderName}" is a generic build folder. Please provide a d tag with -d.`)
+        process.exit(1)
+      }
+    }
+    dTag = folderName
+  }
+  args.dTag = dTag
 
-const bunkerUrl = sk?.startsWith('bunker://') ? sk : (!sk && process.env.NOSTR_SECRET_KEY?.startsWith('bunker://')) ? process.env.NOSTR_SECRET_KEY : null
+  await confirmArgs(args)
+  const fileList = await toFileList(getFiles(dir), dir)
+  const bunkerUrl = sk?.startsWith('bunker://')
+    ? sk
+    : !sk && process.env.NOSTR_SECRET_KEY?.startsWith('bunker://')
+        ? process.env.NOSTR_SECRET_KEY
+        : null
 
-let signer
-if (bunkerUrl) {
-  const { default: NostrBunkerSigner } = await import('#services/bunker-signer.js')
-  signer = await NostrBunkerSigner.create(bunkerUrl)
-} else {
-  signer = await NostrSigner.create(sk)
-}
+  let signer
+  if (bunkerUrl) {
+    const { default: NostrBunkerSigner } = await import('#services/bunker-signer.js')
+    signer = await NostrBunkerSigner.create(bunkerUrl, {
+      source: sk ? 'cli' : dotenvState.nostrSecretKeySource === 'dotenv' ? 'dotenv' : 'cli'
+    })
+  } else {
+    const { default: NostrSigner } = await import('#services/nostr-signer.js')
+    signer = await NostrSigner.create(sk)
+  }
 
-try {
-  await toApp(fileList, signer, { log: console.log.bind(console), dTag, channel, shouldReupload })
-} finally {
-  await signer.close?.()
+  try {
+    const { default: toApp } = await import('#index.js')
+    await toApp(fileList, signer, { log: console.log.bind(console), dTag, channel, shouldReupload })
+  } finally {
+    await signer.close?.()
+  }
 }

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/44billion/nappup.git"
   },
   "license": "MIT",
-  "version": "2.0.1",
+  "version": "2.2.0",
   "description": "Nostr App Uploader",
   "type": "module",
   "scripts": {
@@ -17,14 +17,14 @@
     "nappup": "bin/nappup/index.js"
   },
   "dependencies": {
+    "@dotenvx/primitives": "^2.1.0",
     "@noble/curves": "^2.0.0",
     "@noble/hashes": "^2.0.0",
     "dotenv": "^17.2.0",
     "file-type": "^21.0.0",
-    "libp2r2p": "^0.3.0",
+    "libp2r2p": "^0.9.0",
     "mime-types": "^3.0.1",
-    "nmmr": "^2.0.0",
-    "nostr-tools": "^2.23.3"
+    "nmmr": "^2.0.0"
   },
   "devDependencies": {
     "eslint": "^9.22.0",

package/src/services/bunker-session-codec.js

@@ -0,0 +1,64 @@
+import { getPublicKey } from 'libp2r2p/key'
+import { base16ToBytes } from 'libp2r2p/base16'
+import { base64UrlToBytes, bytesToBase64Url } from 'libp2r2p/base64'
+
+const HEX_32 = /^[0-9a-f]{64}$/
+const BASE64_URL = /^[A-Za-z0-9_-]+$/
+
+export function normalizeClientKey (value) {
+  if (typeof value !== 'string') throw new Error('Invalid bunker client key')
+  const normalized = value.toLowerCase()
+  if (!HEX_32.test(normalized)) throw new Error('Invalid bunker client key')
+  try {
+    getPublicKey(base16ToBytes(normalized))
+  } catch {
+    throw new Error('Invalid bunker client key')
+  }
+  return normalized
+}
+
+function normalizePubkey (value) {
+  const normalized = typeof value === 'string' ? value.toLowerCase() : ''
+  if (!HEX_32.test(normalized)) throw new Error('Invalid CLI bunker session')
+  return normalized
+}
+
+function uniqueStrings (values) {
+  return [...new Set(values.filter(value => typeof value === 'string' && value))]
+}
+
+export function encodeCliSession (session) {
+  const value = JSON.stringify({
+    remoteSignerPubkey: session.remoteSignerPubkey,
+    relays: session.relays,
+    secret: session.secret,
+    clientKey: session.clientKey
+  })
+  return bytesToBase64Url(new TextEncoder().encode(value))
+}
+
+export function decodeCliSession (encoded) {
+  if (typeof encoded !== 'string' || !BASE64_URL.test(encoded)) throw new Error('Invalid CLI bunker session')
+  const bytes = base64UrlToBytes(encoded)
+  if (bytesToBase64Url(bytes) !== encoded) throw new Error('Invalid CLI bunker session')
+
+  let value
+  try {
+    value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+  } catch {
+    throw new Error('Invalid CLI bunker session')
+  }
+
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid CLI bunker session')
+  const remoteSignerPubkey = normalizePubkey(value.remoteSignerPubkey)
+  const relays = uniqueStrings(Array.isArray(value.relays) ? value.relays : [])
+  if (!relays.length) throw new Error('Invalid CLI bunker session')
+  let secret = null
+  if (value.secret !== null) {
+    if (typeof value.secret !== 'string' || !value.secret) throw new Error('Invalid CLI bunker session')
+    secret = value.secret
+  }
+  const clientKey = normalizeClientKey(value.clientKey)
+
+  return { remoteSignerPubkey, relays, secret, clientKey }
+}

package/src/services/bunker-session.js

@@ -0,0 +1,96 @@
+import { generateSecretKey } from 'libp2r2p/key'
+import { bytesToBase16 } from 'libp2r2p/base16'
+import { toBunkerUrl } from 'libp2r2p/nip46'
+import {
+  dotenvPath,
+  DotenvDecryptionError,
+  readEncryptedDotenvValue,
+  setEncryptedDotenvValue
+} from '#services/dotenv.js'
+import {
+  decodeCliSession,
+  encodeCliSession,
+  normalizeClientKey
+} from '#services/bunker-session-codec.js'
+import { parseBunkerSessionUrl } from '#services/bunker-url.js'
+
+export const LAST_CLI_BUNKER_SESSION = 'LAST_CLI_BUNKER_SESSION'
+
+function uniqueStrings (values) {
+  return [...new Set(values.filter(value => typeof value === 'string' && value))]
+}
+
+function readCliSession (filePath, onWarning) {
+  let encoded
+  try {
+    encoded = readEncryptedDotenvValue(LAST_CLI_BUNKER_SESSION, { filePath, onWarning })
+  } catch (error) {
+    if (error instanceof DotenvDecryptionError) throw error
+    onWarning?.(`Ignoring invalid ${LAST_CLI_BUNKER_SESSION}: ${error.message}`)
+    return null
+  }
+  if (!encoded) return null
+  try {
+    return decodeCliSession(encoded)
+  } catch (error) {
+    onWarning?.(`Ignoring invalid ${LAST_CLI_BUNKER_SESSION}: ${error.message}`)
+    return null
+  }
+}
+
+function cacheMatchesInput (cache, parsed) {
+  if (!cache || cache.remoteSignerPubkey !== parsed.pointer.remoteSignerPubkey) return false
+  if (parsed.clientKey) return cache.clientKey === parsed.clientKey
+  return parsed.pointer.secret ? cache.secret === parsed.pointer.secret : true
+}
+
+export function persistBunkerSession (session) {
+  if (session.source === 'dotenv') {
+    const url = new URL(toBunkerUrl({
+      remoteSignerPubkey: session.remoteSignerPubkey,
+      relays: session.relays,
+      secret: session.secret
+    }))
+    url.hash = new URLSearchParams({ client_key: session.clientKey }).toString()
+    setEncryptedDotenvValue('NOSTR_SECRET_KEY', url.toString(), {
+      filePath: session.filePath,
+      updateProcessEnv: true
+    })
+    return
+  }
+
+  setEncryptedDotenvValue(LAST_CLI_BUNKER_SESSION, encodeCliSession(session), {
+    filePath: session.filePath,
+    updateProcessEnv: true
+  })
+}
+
+export { parseBunkerSessionUrl } from '#services/bunker-url.js'
+
+export function prepareBunkerSession (bunkerUrl, {
+  source = 'cli',
+  filePath = dotenvPath,
+  onWarning = console.warn,
+  generateClientKey = generateSecretKey
+} = {}) {
+  if (source !== 'cli' && source !== 'dotenv') throw new Error('Invalid bunker session source')
+  const parsed = parseBunkerSessionUrl(bunkerUrl)
+  const cache = source === 'cli' ? readCliSession(filePath, onWarning) : null
+  const matchingCache = cacheMatchesInput(cache, parsed) ? cache : null
+
+  let clientKey = parsed.clientKey || matchingCache?.clientKey || null
+  const reusedClientKey = Boolean(clientKey)
+  if (!clientKey) clientKey = normalizeClientKey(bytesToBase16(generateClientKey()))
+
+  const session = {
+    source,
+    filePath,
+    remoteSignerPubkey: parsed.pointer.remoteSignerPubkey,
+    relays: uniqueStrings([...parsed.pointer.relays, ...(matchingCache?.relays || [])]),
+    secret: parsed.pointer.secret || matchingCache?.secret || null,
+    clientKey,
+    reusedClientKey
+  }
+  persistBunkerSession(session)
+  return session
+}

package/src/services/bunker-signer.js

@@ -1,8 +1,69 @@
-import { generateSecretKey } from 'nostr-tools/pure'
-import { BunkerSigner, parseBunkerInput } from 'nostr-tools/nip46'
+import { BunkerSigner } from 'libp2r2p/nip46'
+import { base16ToBytes } from 'libp2r2p/base16'
 import { getRelays } from '#helpers/signer.js'
+import {
+  persistBunkerSession,
+  prepareBunkerSession
+} from '#services/bunker-session.js'
 
 const createToken = Symbol('createToken')
+const DEFAULT_CONNECT_TIMEOUT = 5_000
+const DEFAULT_REQUEST_TIMEOUT = 30_000
+
+function alreadyConnected (error) {
+  return /already connected/i.test(typeof error === 'string' ? error : error?.message || '')
+}
+
+async function closeQuietly (bunker) {
+  try {
+    await bunker?.close()
+  } catch {}
+}
+
+async function runWithDeadline (operation, timeout, timeoutMessage, onFailure) {
+  const controller = new AbortController()
+  let timer
+  const deadline = new Promise((resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(timeoutMessage)), timeout)
+  })
+  const pending = Promise.resolve().then(() => operation(controller.signal))
+
+  try {
+    return await Promise.race([pending, deadline])
+  } catch (error) {
+    controller.abort()
+    await onFailure?.()
+    await pending.catch(() => {})
+    throw error
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function openBunker (session, secret, {
+  bunkerFactory,
+  connectTimeout
+}) {
+  const bunker = bunkerFactory(base16ToBytes(session.clientKey), {
+    remoteSignerPubkey: session.remoteSignerPubkey,
+    relays: session.relays,
+    secret
+  })
+
+  await runWithDeadline(async signal => {
+    try {
+      await bunker.connect({
+        clientMetadata: { name: 'nappup' },
+        signal
+      })
+    } catch (error) {
+      if (!alreadyConnected(error)) throw error
+      await bunker.getPublicKey({ signal })
+    }
+  }, connectTimeout, 'Bunker connection timed out', () => closeQuietly(bunker))
+
+  return bunker
+}
 
 export default class NostrBunkerSigner {
   #bunker
@@ -14,28 +75,53 @@ export default class NostrBunkerSigner {
     this.#publicKey = publicKey
   }
 
-  static async create (bunkerUrl, { connectTimeout = 30_000 } = {}) {
-    const bp = await parseBunkerInput(bunkerUrl)
-    if (!bp) throw new Error('Invalid bunker URL')
-    if (bp.relays.length === 0) throw new Error('Bunker URL must include at least one relay (?relay=wss://...)')
+  static async create (bunkerUrl, {
+    source = 'cli',
+    dotenvFilePath,
+    connectTimeout = DEFAULT_CONNECT_TIMEOUT,
+    requestTimeout = DEFAULT_REQUEST_TIMEOUT,
+    onWarning = console.warn,
+    generateClientKey,
+    bunkerFactory = (clientKey, pointer) => BunkerSigner.fromBunker(clientKey, pointer)
+  } = {}) {
+    const session = prepareBunkerSession(bunkerUrl, {
+      source,
+      ...(dotenvFilePath ? { filePath: dotenvFilePath } : {}),
+      onWarning,
+      ...(generateClientKey ? { generateClientKey } : {})
+    })
 
-    const clientSk = generateSecretKey()
-    const bunker = BunkerSigner.fromBunker(clientSk, bp)
-
-    let timeoutHandle
+    let bunker
     try {
-      await Promise.race([
-        bunker.connect(),
-        new Promise((resolve, reject) => {
-          timeoutHandle = setTimeout(() => reject(new Error('Bunker connection timed out')), connectTimeout)
-        })
-      ])
-    } finally {
-      clearTimeout(timeoutHandle)
-    }
+      if (session.reusedClientKey) {
+        try {
+          bunker = await openBunker(session, null, { bunkerFactory, connectTimeout })
+        } catch (error) {
+          if (!session.secret) throw error
+          bunker = await openBunker(session, session.secret, { bunkerFactory, connectTimeout })
+        }
+      } else {
+        bunker = await openBunker(session, session.secret, { bunkerFactory, connectTimeout })
+      }
 
-    const publicKey = await bunker.getPublicKey()
-    return new this(createToken, bunker, publicKey)
+      const publicKey = await runWithDeadline(
+        signal => bunker.getPublicKey({ timeout: requestTimeout, signal }),
+        requestTimeout,
+        'Bunker public key request timed out',
+        () => closeQuietly(bunker)
+      )
+
+      session.relays = [...bunker.pointer.relays]
+      try {
+        persistBunkerSession(session)
+      } catch (error) {
+        onWarning?.(`Could not persist updated bunker session: ${error.message}`)
+      }
+      return new this(createToken, bunker, publicKey)
+    } catch (error) {
+      await closeQuietly(bunker)
+      throw error
+    }
   }
 
   getPublicKey () {

package/src/services/bunker-url.js

@@ -0,0 +1,32 @@
+import { parseBunkerUrl } from 'libp2r2p/nip46'
+import { normalizeClientKey } from '#services/bunker-session-codec.js'
+
+export function parseBunkerSessionUrl (input) {
+  let url
+  try {
+    url = new URL(input)
+  } catch {
+    throw new Error('Invalid bunker URL')
+  }
+  if (url.protocol !== 'bunker:') throw new Error('Invalid bunker URL')
+  if (url.searchParams.getAll('secret').length > 1) throw new Error('Bunker URL must not contain multiple secrets')
+  if (url.searchParams.getAll('relay').length === 0) {
+    throw new Error('Bunker URL must include at least one relay (?relay=wss://...)')
+  }
+
+  let clientKey = null
+  if (url.hash) {
+    const fragment = new URLSearchParams(url.hash.slice(1))
+    const keys = [...fragment.keys()]
+    const values = fragment.getAll('client_key')
+    if (keys.some(key => key !== 'client_key') || values.length !== 1) {
+      throw new Error('Invalid bunker URL fragment')
+    }
+    clientKey = normalizeClientKey(values[0])
+    url.hash = ''
+  }
+
+  const pointer = parseBunkerUrl(url.toString())
+  if (!pointer) throw new Error('Invalid bunker URL')
+  return { pointer, clientKey }
+}