feat: bunker client mode — connect to remote signer via BUNKER_URI, full round-trip tested (324 tests)

Author: TheCryptoDonkey

src/bunker-context.ts

@@ -0,0 +1,115 @@
+/**
+ * BunkerContext — an IdentityContext-compatible interface backed by a NIP-46 bunker.
+ *
+ * Instead of holding the secret key locally, all signing is delegated to a
+ * remote bunker via encrypted Nostr relay messages.
+ *
+ * Usage:
+ *   BUNKER_URI=bunker://pk?relay=wss://...
+ *   or
+ *   BUNKER_URI=bunker://pk?relay=wss://...&secret=clienthex
+ */
+
+import { BunkerSigner } from 'nostr-tools/nip46'
+import { useWebSocketImplementation, SimplePool } from 'nostr-tools/pool'
+import { generateSecretKey, getPublicKey } from 'nostr-tools/pure'
+import { npubEncode } from 'nostr-tools/nip19'
+import WebSocket from 'ws'
+import type { Event as NostrEvent, EventTemplate } from 'nostr-tools'
+import type { PublicIdentity, SignFn } from './types.js'
+
+useWebSocketImplementation(WebSocket)
+
+export interface BunkerConfig {
+  pubkey: string
+  relay: string
+  secret?: string  // client secret key hex
+}
+
+/** Parse a bunker:// URI */
+export function parseBunkerUri(uri: string): BunkerConfig {
+  // bunker://<pubkey>?relay=<url>&secret=<hex>
+  const url = new URL(uri)
+  const pubkey = url.hostname || url.pathname.replace('//', '')
+  const relay = url.searchParams.get('relay')
+  const secret = url.searchParams.get('secret') ?? undefined
+  if (!pubkey || !relay) {
+    throw new Error('Invalid bunker URI: missing pubkey or relay')
+  }
+  return { pubkey, relay, secret }
+}
+
+export class BunkerContext {
+  private signer: BunkerSigner
+  private pool: SimplePool
+  private pubkeyHex: string | undefined
+  private clientSk: Uint8Array
+
+  private constructor(signer: BunkerSigner, pool: SimplePool, clientSk: Uint8Array) {
+    this.signer = signer
+    this.pool = pool
+    this.clientSk = clientSk
+  }
+
+  /** Connect to a remote bunker. Blocks until the connection is established. */
+  static async connect(uri: string, timeoutMs = 15_000): Promise<BunkerContext> {
+    const config = parseBunkerUri(uri)
+    const clientSk = config.secret
+      ? Buffer.from(config.secret, 'hex')
+      : generateSecretKey()
+    const pool = new SimplePool()
+
+    const signer = BunkerSigner.fromBunker(
+      clientSk,
+      { pubkey: config.pubkey, relays: [config.relay], secret: null },
+      { pool },
+    )
+
+    // Connect and verify
+    await signer.connect()
+    await signer.ping()
+
+    const ctx = new BunkerContext(signer, pool, clientSk)
+    ctx.pubkeyHex = await signer.getPublicKey()
+    return ctx
+  }
+
+  /** The remote identity's npub */
+  get activeNpub(): string {
+    return npubEncode(this.pubkeyHex!)
+  }
+
+  /** The remote identity's hex pubkey */
+  get activePublicKeyHex(): string {
+    return this.pubkeyHex!
+  }
+
+  /** Sign an event via the remote bunker */
+  getSigningFunction(): SignFn {
+    return async (template: EventTemplate): Promise<NostrEvent> => {
+      return this.signer.signEvent(template) as unknown as NostrEvent
+    }
+  }
+
+  /** List identities — bunker mode only has one (the remote key) */
+  listIdentities(): PublicIdentity[] {
+    return [{ npub: this.activeNpub, purpose: 'bunker', index: 0 }]
+  }
+
+  /** NIP-44 encrypt via the remote bunker */
+  async nip44Encrypt(recipientPubkey: string, plaintext: string): Promise<string> {
+    return this.signer.nip44Encrypt(recipientPubkey, plaintext)
+  }
+
+  /** NIP-44 decrypt via the remote bunker */
+  async nip44Decrypt(senderPubkey: string, ciphertext: string): Promise<string> {
+    return this.signer.nip44Decrypt(senderPubkey, ciphertext)
+  }
+
+  /** Clean up */
+  destroy(): void {
+    this.signer.close()
+    this.pool.destroy()
+    this.clientSk.fill(0)
+  }
+}

src/cli.ts

@@ -182,6 +182,7 @@ Modes:
 Environment:
   NOSTR_SECRET_KEY              nsec, hex, or BIP-39 mnemonic
   NOSTR_SECRET_KEY_FILE         Path to secret key file
+  BUNKER_URI / BUNKER_URI_FILE  bunker:// URI (use INSTEAD of secret key)
   NOSTR_RELAYS                  Comma-separated relay URLs
   NWC_URI / NWC_URI_FILE        Nostr Wallet Connect URI
   TOR_PROXY                     SOCKS5h proxy URL

src/config.ts

@@ -42,12 +42,19 @@ export function loadConfig(): BrayConfig {
   const keyEnvVar = process.env.NOSTR_SECRET_KEY
   let secretKey: string
 
+  const bunkerUri = process.env.BUNKER_URI ?? process.env.BUNKER_URI_FILE
+    ? (process.env.BUNKER_URI_FILE ? readSecretFile(process.env.BUNKER_URI_FILE) : process.env.BUNKER_URI)
+    : undefined
+
   if (keyFilePath) {
     secretKey = readSecretFile(keyFilePath)
   } else if (keyEnvVar) {
     secretKey = keyEnvVar
+  } else if (bunkerUri) {
+    // Bunker mode — no local secret needed
+    secretKey = ''
   } else {
-    throw new Error('No secret key provided: set NOSTR_SECRET_KEY or NOSTR_SECRET_KEY_FILE')
+    throw new Error('No secret key provided: set NOSTR_SECRET_KEY, NOSTR_SECRET_KEY_FILE, or BUNKER_URI')
   }
 
   const secretFormat = detectKeyFormat(secretKey)
@@ -82,11 +89,14 @@ export function loadConfig(): BrayConfig {
   delete process.env.NOSTR_SECRET_KEY_FILE
   delete process.env.NWC_URI
   delete process.env.NWC_URI_FILE
+  delete process.env.BUNKER_URI
+  delete process.env.BUNKER_URI_FILE
 
   return {
     secretKey,
     secretFormat,
     relays,
+    bunkerUri: bunkerUri ?? undefined,
     nwcUri,
     torProxy,
     allowClearnetWithTor,

src/index.ts

@@ -19,13 +19,22 @@ const pool = new RelayPool({
   defaultRelays: config.relays,
 })
 const nip65 = new Nip65Manager(pool, config.relays)
-const ctx = new IdentityContext(config.secretKey, config.secretFormat)
-export const deps = { ctx, pool, nip65, nwcUri: config.nwcUri }
 
-// Clear secret references from config — strings are immutable so originals
-// persist until GC, but removing references allows earlier collection
+// Connect to bunker or use local key
+let ctx: IdentityContext | import('./bunker-context.js').BunkerContext
+if (config.bunkerUri) {
+  const { BunkerContext } = await import('./bunker-context.js')
+  ctx = await BunkerContext.connect(config.bunkerUri)
+  console.error(`Connected to bunker — signing as ${ctx.activeNpub}`)
+} else {
+  ctx = new IdentityContext(config.secretKey, config.secretFormat)
+}
+
+export const deps = { ctx: ctx as any, pool, nip65, nwcUri: config.nwcUri }
+
 ;(config as any).secretKey = ''
 ;(config as any).nwcUri = undefined
+;(config as any).bunkerUri = undefined
 
 // Load master identity relay list
 const masterRelays = await nip65.loadForIdentity(ctx.activeNpub)

src/types.ts

@@ -37,6 +37,7 @@ export interface BrayConfig {
   readonly secretKey: string
   readonly secretFormat: 'nsec' | 'hex' | 'mnemonic'
   readonly relays: string[]
+  readonly bunkerUri?: string
   readonly nwcUri?: string
   readonly torProxy?: string
   readonly allowClearnetWithTor: boolean

test/bunker-round-trip.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Bunker round-trip test — server + client via our test relay.
+ *
+ * 1. Start in-memory relay
+ * 2. Start bunker server (holds the key)
+ * 3. Connect bunker client
+ * 4. Sign an event via the bunker
+ * 5. Verify the signature
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { verifyEvent } from 'nostr-tools/pure'
+import { startRelay } from '../src/serve.js'
+import { startBunker } from '../src/bunker.js'
+import { IdentityContext } from '../src/context.js'
+import { BunkerContext } from '../src/bunker-context.js'
+
+const TEST_NSEC = 'nsec1cxymst7yntfnvt4vkztk54q9muks6n77dn7qyhjpcvlxtkc6hy2s0364r8'
+
+let relay: ReturnType<typeof startRelay>
+let bunkerServer: ReturnType<typeof startBunker>
+let ctx: IdentityContext
+
+describe('bunker round-trip', () => {
+  beforeAll(() => {
+    // Start test relay
+    relay = startRelay({ port: 19648, quiet: true })
+
+    // Start bunker server with local context
+    ctx = new IdentityContext(TEST_NSEC, 'nsec')
+    bunkerServer = startBunker({
+      ctx,
+      relays: [relay.url],
+      quiet: true,
+    })
+  })
+
+  afterAll(() => {
+    bunkerServer.close()
+    ctx.destroy()
+    relay.close()
+  })
+
+  it('bunker server starts and returns a URI', () => {
+    expect(bunkerServer.url).toMatch(/^bunker:\/\//)
+    expect(bunkerServer.pubkey).toMatch(/^[0-9a-f]{64}$/)
+    expect(bunkerServer.npub).toMatch(/^npub1/)
+  })
+
+  it('client connects to bunker and gets public key', async () => {
+    const client = await BunkerContext.connect(bunkerServer.url)
+    expect(client.activeNpub).toBe(ctx.activeNpub)
+    expect(client.activePublicKeyHex).toBe(ctx.activePublicKeyHex)
+    client.destroy()
+  }, 15_000)
+
+  it('client signs an event via the bunker', async () => {
+    const client = await BunkerContext.connect(bunkerServer.url)
+    const sign = client.getSigningFunction()
+
+    const event = await sign({
+      kind: 1,
+      created_at: Math.floor(Date.now() / 1000),
+      tags: [],
+      content: 'signed via bunker!',
+    })
+
+    expect(event.kind).toBe(1)
+    expect(event.content).toBe('signed via bunker!')
+    expect(event.pubkey).toBe(ctx.activePublicKeyHex)
+    expect(verifyEvent(event)).toBe(true)
+
+    client.destroy()
+  }, 15_000)
+
+  it('client lists identities', async () => {
+    const client = await BunkerContext.connect(bunkerServer.url)
+    const list = client.listIdentities()
+    expect(list.length).toBe(1)
+    expect(list[0].purpose).toBe('bunker')
+    client.destroy()
+  }, 15_000)
+})