@kehto/services 0.5.0 → 0.6.0

package/dist/cvm-nostr-transport.d.ts

@@ -94,4 +94,4 @@ declare function createNostrCvmTransport(options?: NostrCvmTransportOptions): Cv
     dispose(): void;
 };
 
-export { type CvmRelayPool, type NostrCvmTransportOptions, createNostrCvmTransport };
+export { type CvmRelayPool, type CvmSubCloser, type NostrCvmTransportOptions, type NostrEventLike, type NostrFilterLike, createNostrCvmTransport };

package/dist/cvm-nostr-transport.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/cvm-nostr-transport.ts"],"sourcesContent":["/**\n * cvm-nostr-transport.ts — concrete ContextVM transport for NAP-CVM.\n *\n * Implements {@link CvmTransport} over Nostr, exactly as validated against live\n * ContextVM servers (e.g. Relatr):\n *\n *  - MCP JSON-RPC messages ride in kind-25910 event `content`.\n *  - Requests are CEP-4 gift-wrapped: the inner kind-25910 event is signed with\n *    the shell's ephemeral client key, NIP-44-encrypted to the server, and\n *    placed in a kind-21059 (ephemeral) / 1059 (regular) wrap signed by a fresh\n *    random key, `p`-tagged to the server. Responses arrive the same way,\n *    `p`-tagged to the client, and are correlated by the inner JSON-RPC `id`.\n *  - Discovery reads kind-11316 (server) + kind-11317 (tools) announcements.\n *\n * Shipped on a separate entry (`@kehto/services/cvm-nostr-transport`) so the\n * `nostr-tools` dependency stays out of the core `@kehto/services` bundle.\n *\n * The client key is ephemeral and shell-owned: napplets never see keys, relay\n * sockets, or NIP-44 material (NAP-CVM §Security).\n *\n * @example\n * ```ts\n * import { createNostrCvmTransport } from '@kehto/services/cvm-nostr-transport';\n * const transport = createNostrCvmTransport({\n *   defaultRelays: ['wss://relay.contextvm.org', 'wss://relay2.contextvm.org'],\n * });\n * ```\n */\n\nimport { SimplePool } from 'nostr-tools/pool';\nimport { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure';\nimport * as nip44 from 'nostr-tools/nip44';\nimport type { Event as NostrToolsEvent, Filter as NostrToolsFilter } from 'nostr-tools';\n\nimport type { CvmTransport } from './cvm-service.js';\nimport type {\n  CvmDiscoverQuery,\n  CvmRequestOptions,\n  CvmServer,\n  CvmServerRef,\n  McpMessage,\n} from './cvm-types.js';\n\n/** ContextVM unified transport event kind. */\nconst KIND_CVM = 25910;\n/** CEP-4 gift-wrap kinds: ephemeral (CEP-19) and regular. */\nconst KIND_GIFT_WRAP_EPHEMERAL = 21059;\nconst KIND_GIFT_WRAP_REGULAR = 1059;\n/** CEP-6 announcement kinds. */\nconst KIND_ANNOUNCE_SERVER = 11316;\nconst KIND_ANNOUNCE_TOOLS = 11317;\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_DISCOVER_TIMEOUT_MS = 6_000;\nconst MCP_PROTOCOL_VERSION = '2025-11-25';\nconst SEEN_WRAP_LIMIT = 512;\n\n/** Minimal signed Nostr event. */\ninterface NostrEventLike {\n  id: string;\n  pubkey: string;\n  created_at: number;\n  kind: number;\n  tags: string[][];\n  content: string;\n  sig: string;\n}\n\n/** A Nostr REQ filter (subset). */\ninterface NostrFilterLike {\n  kinds?: number[];\n  authors?: string[];\n  limit?: number;\n  ['#p']?: string[];\n  [key: string]: unknown;\n}\n\n/** Subscription handle returned by the relay pool. */\ninterface CvmSubCloser {\n  close(): void;\n}\n\n/**\n * Minimal relay-pool surface used by this transport — structurally satisfied\n * by `nostr-tools` `SimplePool`. Injectable for testing.\n */\nexport interface CvmRelayPool {\n  subscribe(\n    relays: string[],\n    filter: NostrFilterLike,\n    params: { onevent?: (event: NostrEventLike) => void; oneose?: () => void },\n  ): CvmSubCloser;\n  publish(relays: string[], event: NostrEventLike): unknown;\n}\n\n/** Options for {@link createNostrCvmTransport}. */\nexport interface NostrCvmTransportOptions {\n  /** Relays used when a server reference carries no relay hints. */\n  defaultRelays?: string[];\n  /** Default per-request timeout in milliseconds. */\n  timeoutMs?: number;\n  /** Whether to CEP-4 gift-wrap requests. Default true (most servers require it). */\n  encrypt?: boolean;\n  /** Use ephemeral (kind 21059) gift wraps when encrypting. Default true. */\n  ephemeralWrap?: boolean;\n  /** Relay pool to use. Defaults to a fresh `nostr-tools` `SimplePool`. */\n  pool?: CvmRelayPool;\n  /** Client secret key (32 bytes). Defaults to a generated ephemeral key. */\n  clientSecretKey?: Uint8Array;\n  /** Client info advertised during MCP `initialize`. */\n  clientInfo?: { name: string; version: string };\n}\n\ntype EventHandler = (server: CvmServerRef, message: McpMessage) => void;\n\ninterface PendingRequest {\n  resolve(message: McpMessage): void;\n  reject(error: Error): void;\n  timer: ReturnType<typeof setTimeout>;\n  /** The caller's original JSON-RPC id, restored on the response. */\n  originalId: string | number | undefined;\n}\n\ninterface ServerSession {\n  relays: string[];\n  initialized: boolean;\n  initializing: Promise<void> | null;\n}\n\nlet correlationCounter = 0;\nfunction nextCorrelationId(): string {\n  correlationCounter += 1;\n  return `cvm-${correlationCounter}-${getPublicKey(generateSecretKey()).slice(0, 8)}`;\n}\n\nfunction randomizedPastTimestamp(): number {\n  // NIP-59: randomize within the past two days to reduce timing metadata.\n  const jitter = Math.floor(Math.random() * 172_800);\n  return Math.floor(Date.now() / 1000) - jitter;\n}\n\nfunction tagValue(tags: string[][], name: string): string | undefined {\n  return tags.find((tag) => tag[0] === name)?.[1];\n}\n\n/** Adapt a `nostr-tools` SimplePool to the {@link CvmRelayPool} surface. */\nfunction simplePoolAdapter(sp: SimplePool): CvmRelayPool {\n  return {\n    subscribe(relays, filter, params) {\n      return sp.subscribe(relays, filter as NostrToolsFilter, {\n        onevent: params.onevent,\n        oneose: params.oneose,\n      });\n    },\n    publish(relays, event) {\n      return sp.publish(relays, event as NostrToolsEvent);\n    },\n  };\n}\n\n/**\n * Create a Nostr-backed ContextVM transport.\n *\n * @param options - Relay set, timeouts, encryption mode, and optional injected\n *   pool/keys (the injected pool + key make the transport deterministic in tests).\n * @returns A {@link CvmTransport} plus a `dispose()` to tear down subscriptions.\n */\nexport function createNostrCvmTransport(\n  options: NostrCvmTransportOptions = {},\n): CvmTransport & { dispose(): void } {\n  const defaultRelays = options.defaultRelays ?? [];\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const encrypt = options.encrypt ?? true;\n  const wrapKind = options.ephemeralWrap === false ? KIND_GIFT_WRAP_REGULAR : KIND_GIFT_WRAP_EPHEMERAL;\n  const pool: CvmRelayPool = options.pool ?? simplePoolAdapter(new SimplePool());\n  const clientSecretKey = options.clientSecretKey ?? generateSecretKey();\n  const clientPubkey = getPublicKey(clientSecretKey);\n  const clientInfo = options.clientInfo ?? { name: 'kehto-cvm', version: '1.0.0' };\n\n  const sessions = new Map<string, ServerSession>();\n  const pending = new Map<string, PendingRequest>();\n  const eventHandlers = new Set<EventHandler>();\n  const relayRefcount = new Map<string, number>();\n  const seenWraps = new Set<string>();\n  let inbound: CvmSubCloser | null = null;\n  let subscribedRelays = '';\n\n  function resolveRelays(server: CvmServerRef): string[] {\n    const relays = server.relays && server.relays.length > 0 ? server.relays : defaultRelays;\n    if (relays.length === 0) throw new Error('server not found');\n    return [...new Set(relays)];\n  }\n\n  function holdRelays(relays: string[]): void {\n    for (const url of relays) relayRefcount.set(url, (relayRefcount.get(url) ?? 0) + 1);\n    refreshSubscription();\n  }\n\n  function releaseRelays(relays: string[]): void {\n    for (const url of relays) {\n      const count = (relayRefcount.get(url) ?? 0) - 1;\n      if (count <= 0) relayRefcount.delete(url);\n      else relayRefcount.set(url, count);\n    }\n    refreshSubscription();\n  }\n\n  function refreshSubscription(): void {\n    const relays = [...relayRefcount.keys()].sort();\n    const key = relays.join(',');\n    if (key === subscribedRelays) return;\n    inbound?.close();\n    subscribedRelays = key;\n    inbound = relays.length === 0\n      ? null\n      : pool.subscribe(\n          relays,\n          { kinds: encrypt ? [KIND_GIFT_WRAP_REGULAR, KIND_GIFT_WRAP_EPHEMERAL] : [KIND_CVM], ['#p']: [clientPubkey] },\n          { onevent: handleInbound },\n        );\n  }\n\n  function rememberWrap(id: string): boolean {\n    if (seenWraps.has(id)) return false;\n    seenWraps.add(id);\n    if (seenWraps.size > SEEN_WRAP_LIMIT) {\n      const oldest = seenWraps.values().next().value;\n      if (oldest !== undefined) seenWraps.delete(oldest);\n    }\n    return true;\n  }\n\n  function handleInbound(event: NostrEventLike): void {\n    if (!rememberWrap(event.id)) return;\n    let serverPubkey: string;\n    let mcp: McpMessage;\n    try {\n      if (encrypt) {\n        const conversationKey = nip44.getConversationKey(clientSecretKey, event.pubkey);\n        const inner = JSON.parse(nip44.decrypt(event.content, conversationKey)) as NostrEventLike;\n        serverPubkey = inner.pubkey;\n        mcp = JSON.parse(inner.content) as McpMessage;\n      } else {\n        serverPubkey = event.pubkey;\n        mcp = JSON.parse(event.content) as McpMessage;\n      }\n    } catch {\n      return; // not addressed to us / undecryptable / malformed — ignore.\n    }\n\n    const id = mcp.id;\n    if (id != null && pending.has(String(id))) {\n      const entry = pending.get(String(id))!;\n      pending.delete(String(id));\n      clearTimeout(entry.timer);\n      entry.resolve({ ...mcp, id: entry.originalId });\n      return;\n    }\n    // Uncorrelated server message (notification) → fan out as a CVM event.\n    if (mcp.method !== undefined && sessions.has(serverPubkey)) {\n      const server: CvmServerRef = { pubkey: serverPubkey };\n      for (const handler of eventHandlers) handler(server, mcp);\n    }\n  }\n\n  function publishMcp(server: CvmServerRef, relays: string[], message: McpMessage): void {\n    const inner = finalizeEvent(\n      { kind: KIND_CVM, created_at: Math.floor(Date.now() / 1000), tags: [['p', server.pubkey]], content: JSON.stringify(message) },\n      clientSecretKey,\n    ) as NostrEventLike;\n    if (!encrypt) {\n      pool.publish(relays, inner);\n      return;\n    }\n    const wrapSecretKey = generateSecretKey();\n    const conversationKey = nip44.getConversationKey(wrapSecretKey, server.pubkey);\n    // Ephemeral wraps (kind 21059) are not stored; relays reject backdated\n    // ephemeral events as \"expired\", so they MUST carry a current timestamp.\n    // Regular wraps (kind 1059) are backdated per NIP-59 to blur timing metadata.\n    const createdAt =\n      wrapKind === KIND_GIFT_WRAP_EPHEMERAL ? Math.floor(Date.now() / 1000) : randomizedPastTimestamp();\n    const wrap = finalizeEvent(\n      {\n        kind: wrapKind,\n        created_at: createdAt,\n        tags: [['p', server.pubkey]],\n        content: nip44.encrypt(JSON.stringify(inner), conversationKey),\n      },\n      wrapSecretKey,\n    ) as NostrEventLike;\n    pool.publish(relays, wrap);\n  }\n\n  function sendCorrelated(\n    server: CvmServerRef,\n    relays: string[],\n    message: McpMessage,\n    timeout: number,\n  ): Promise<McpMessage> {\n    const correlationId = nextCorrelationId();\n    const originalId = message.id;\n    const outgoing: McpMessage = { ...message, id: correlationId };\n    return new Promise<McpMessage>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        pending.delete(correlationId);\n        reject(new Error('relay timeout'));\n      }, timeout);\n      pending.set(correlationId, { resolve, reject, timer, originalId });\n      try {\n        publishMcp(server, relays, outgoing);\n      } catch (err) {\n        pending.delete(correlationId);\n        clearTimeout(timer);\n        reject(err instanceof Error ? err : new Error('publish failed'));\n      }\n    });\n  }\n\n  function getSession(server: CvmServerRef): ServerSession {\n    let session = sessions.get(server.pubkey);\n    if (!session) {\n      const relays = resolveRelays(server);\n      session = { relays, initialized: false, initializing: null };\n      sessions.set(server.pubkey, session);\n      holdRelays(relays);\n    }\n    return session;\n  }\n\n  async function ensureInitialized(server: CvmServerRef, session: ServerSession, timeout: number): Promise<void> {\n    if (session.initialized) return;\n    if (session.initializing) return session.initializing;\n    session.initializing = (async () => {\n      try {\n        await sendCorrelated(\n          server,\n          session.relays,\n          {\n            jsonrpc: '2.0',\n            id: 'init',\n            method: 'initialize',\n            params: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo },\n          },\n          timeout,\n        );\n        // notifications/initialized completes the handshake; no response expected.\n        publishMcp(server, session.relays, { jsonrpc: '2.0', method: 'notifications/initialized' });\n        session.initialized = true;\n      } catch {\n        throw new Error('initialization failed');\n      } finally {\n        session.initializing = null;\n      }\n    })();\n    return session.initializing;\n  }\n\n  return {\n    async discover(query?: CvmDiscoverQuery): Promise<CvmServer[]> {\n      const relays = query?.relays && query.relays.length > 0 ? query.relays : defaultRelays;\n      if (relays.length === 0) return [];\n      const announces = new Map<string, NostrEventLike>();\n      const toolLists = new Map<string, NostrEventLike>();\n      await new Promise<void>((resolve) => {\n        const sub = pool.subscribe(\n          relays,\n          { kinds: [KIND_ANNOUNCE_SERVER, KIND_ANNOUNCE_TOOLS], limit: query?.limit ? query.limit * 4 : 100 },\n          {\n            onevent(event) {\n              if (event.kind === KIND_ANNOUNCE_SERVER) announces.set(event.pubkey, event);\n              else if (event.kind === KIND_ANNOUNCE_TOOLS) toolLists.set(event.pubkey, event);\n            },\n            oneose() { resolve(); },\n          },\n        );\n        setTimeout(() => { sub.close(); resolve(); }, DEFAULT_DISCOVER_TIMEOUT_MS);\n      });\n\n      const servers: CvmServer[] = [];\n      for (const [pubkey, event] of announces) {\n        const name = tagValue(event.tags, 'name');\n        const description = tagValue(event.tags, 'about');\n        const server: CvmServer = {\n          pubkey,\n          relays: [...relays],\n          ...(name ? { name } : {}),\n          ...(description ? { description } : {}),\n          paymentRequired: false,\n        };\n        const tools = toolLists.get(pubkey);\n        if (tools) {\n          const names = tools.tags.filter((tag) => tag[0] === 'i' && typeof tag[2] === 'string').map((tag) => tag[2]);\n          if (names.length > 0) server.capabilities = names;\n        }\n        servers.push(server);\n      }\n\n      const search = query?.search?.toLowerCase();\n      const filtered = search\n        ? servers.filter((s) => `${s.name ?? ''} ${s.description ?? ''}`.toLowerCase().includes(search))\n        : servers;\n      return query?.limit ? filtered.slice(0, query.limit) : filtered;\n    },\n\n    async request(server: CvmServerRef, message: McpMessage, requestOptions?: CvmRequestOptions): Promise<McpMessage> {\n      const session = getSession(server);\n      const timeout = requestOptions?.timeoutMs ?? timeoutMs;\n      if (requestOptions?.initialize) await ensureInitialized(server, session, timeout);\n      return sendCorrelated(server, session.relays, message, timeout);\n    },\n\n    async close(server: CvmServerRef): Promise<void> {\n      const session = sessions.get(server.pubkey);\n      if (!session) return;\n      sessions.delete(server.pubkey);\n      releaseRelays(session.relays);\n    },\n\n    onEvent(handler: EventHandler): { close(): void } {\n      eventHandlers.add(handler);\n      return {\n        close() {\n          eventHandlers.delete(handler);\n        },\n      };\n    },\n\n    dispose(): void {\n      inbound?.close();\n      inbound = null;\n      for (const entry of pending.values()) {\n        clearTimeout(entry.timer);\n        entry.reject(new Error('transport disposed'));\n      }\n      pending.clear();\n      sessions.clear();\n      relayRefcount.clear();\n      eventHandlers.clear();\n      subscribedRelays = '';\n    },\n  };\n}\n"],"mappings":";AA6BA,SAAS,kBAAkB;AAC3B,SAAS,eAAe,mBAAmB,oBAAoB;AAC/D,YAAY,WAAW;AAavB,IAAM,WAAW;AAEjB,IAAM,2BAA2B;AACjC,IAAM,yBAAyB;AAE/B,IAAM,uBAAuB;AAC7B,IAAM,sBAAsB;AAE5B,IAAM,qBAAqB;AAC3B,IAAM,8BAA8B;AACpC,IAAM,uBAAuB;AAC7B,IAAM,kBAAkB;AA0ExB,IAAI,qBAAqB;AACzB,SAAS,oBAA4B;AACnC,wBAAsB;AACtB,SAAO,OAAO,kBAAkB,IAAI,aAAa,kBAAkB,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC;AACnF;AAEA,SAAS,0BAAkC;AAEzC,QAAM,SAAS,KAAK,MAAM,KAAK,OAAO,IAAI,MAAO;AACjD,SAAO,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI,IAAI;AACzC;AAEA,SAAS,SAAS,MAAkB,MAAkC;AACpE,SAAO,KAAK,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;AAChD;AAGA,SAAS,kBAAkB,IAA8B;AACvD,SAAO;AAAA,IACL,UAAU,QAAQ,QAAQ,QAAQ;AAChC,aAAO,GAAG,UAAU,QAAQ,QAA4B;AAAA,QACtD,SAAS,OAAO;AAAA,QAChB,QAAQ,OAAO;AAAA,MACjB,CAAC;AAAA,IACH;AAAA,IACA,QAAQ,QAAQ,OAAO;AACrB,aAAO,GAAG,QAAQ,QAAQ,KAAwB;AAAA,IACpD;AAAA,EACF;AACF;AASO,SAAS,wBACd,UAAoC,CAAC,GACD;AACpC,QAAM,gBAAgB,QAAQ,iBAAiB,CAAC;AAChD,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAMA,WAAU,QAAQ,WAAW;AACnC,QAAM,WAAW,QAAQ,kBAAkB,QAAQ,yBAAyB;AAC5E,QAAM,OAAqB,QAAQ,QAAQ,kBAAkB,IAAI,WAAW,CAAC;AAC7E,QAAM,kBAAkB,QAAQ,mBAAmB,kBAAkB;AACrE,QAAM,eAAe,aAAa,eAAe;AACjD,QAAM,aAAa,QAAQ,cAAc,EAAE,MAAM,aAAa,SAAS,QAAQ;AAE/E,QAAM,WAAW,oBAAI,IAA2B;AAChD,QAAM,UAAU,oBAAI,IAA4B;AAChD,QAAM,gBAAgB,oBAAI,IAAkB;AAC5C,QAAM,gBAAgB,oBAAI,IAAoB;AAC9C,QAAM,YAAY,oBAAI,IAAY;AAClC,MAAI,UAA+B;AACnC,MAAI,mBAAmB;AAEvB,WAAS,cAAc,QAAgC;AACrD,UAAM,SAAS,OAAO,UAAU,OAAO,OAAO,SAAS,IAAI,OAAO,SAAS;AAC3E,QAAI,OAAO,WAAW,EAAG,OAAM,IAAI,MAAM,kBAAkB;AAC3D,WAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAAA,EAC5B;AAEA,WAAS,WAAW,QAAwB;AAC1C,eAAW,OAAO,OAAQ,eAAc,IAAI,MAAM,cAAc,IAAI,GAAG,KAAK,KAAK,CAAC;AAClF,wBAAoB;AAAA,EACtB;AAEA,WAAS,cAAc,QAAwB;AAC7C,eAAW,OAAO,QAAQ;AACxB,YAAM,SAAS,cAAc,IAAI,GAAG,KAAK,KAAK;AAC9C,UAAI,SAAS,EAAG,eAAc,OAAO,GAAG;AAAA,UACnC,eAAc,IAAI,KAAK,KAAK;AAAA,IACnC;AACA,wBAAoB;AAAA,EACtB;AAEA,WAAS,sBAA4B;AACnC,UAAM,SAAS,CAAC,GAAG,cAAc,KAAK,CAAC,EAAE,KAAK;AAC9C,UAAM,MAAM,OAAO,KAAK,GAAG;AAC3B,QAAI,QAAQ,iBAAkB;AAC9B,aAAS,MAAM;AACf,uBAAmB;AACnB,cAAU,OAAO,WAAW,IACxB,OACA,KAAK;AAAA,MACH;AAAA,MACA,EAAE,OAAOA,WAAU,CAAC,wBAAwB,wBAAwB,IAAI,CAAC,QAAQ,GAAG,CAAC,IAAI,GAAG,CAAC,YAAY,EAAE;AAAA,MAC3G,EAAE,SAAS,cAAc;AAAA,IAC3B;AAAA,EACN;AAEA,WAAS,aAAa,IAAqB;AACzC,QAAI,UAAU,IAAI,EAAE,EAAG,QAAO;AAC9B,cAAU,IAAI,EAAE;AAChB,QAAI,UAAU,OAAO,iBAAiB;AACpC,YAAM,SAAS,UAAU,OAAO,EAAE,KAAK,EAAE;AACzC,UAAI,WAAW,OAAW,WAAU,OAAO,MAAM;AAAA,IACnD;AACA,WAAO;AAAA,EACT;AAEA,WAAS,cAAc,OAA6B;AAClD,QAAI,CAAC,aAAa,MAAM,EAAE,EAAG;AAC7B,QAAI;AACJ,QAAI;AACJ,QAAI;AACF,UAAIA,UAAS;AACX,cAAM,kBAAwB,yBAAmB,iBAAiB,MAAM,MAAM;AAC9E,cAAM,QAAQ,KAAK,MAAY,cAAQ,MAAM,SAAS,eAAe,CAAC;AACtE,uBAAe,MAAM;AACrB,cAAM,KAAK,MAAM,MAAM,OAAO;AAAA,MAChC,OAAO;AACL,uBAAe,MAAM;AACrB,cAAM,KAAK,MAAM,MAAM,OAAO;AAAA,MAChC;AAAA,IACF,QAAQ;AACN;AAAA,IACF;AAEA,UAAM,KAAK,IAAI;AACf,QAAI,MAAM,QAAQ,QAAQ,IAAI,OAAO,EAAE,CAAC,GAAG;AACzC,YAAM,QAAQ,QAAQ,IAAI,OAAO,EAAE,CAAC;AACpC,cAAQ,OAAO,OAAO,EAAE,CAAC;AACzB,mBAAa,MAAM,KAAK;AACxB,YAAM,QAAQ,EAAE,GAAG,KAAK,IAAI,MAAM,WAAW,CAAC;AAC9C;AAAA,IACF;AAEA,QAAI,IAAI,WAAW,UAAa,SAAS,IAAI,YAAY,GAAG;AAC1D,YAAM,SAAuB,EAAE,QAAQ,aAAa;AACpD,iBAAW,WAAW,cAAe,SAAQ,QAAQ,GAAG;AAAA,IAC1D;AAAA,EACF;AAEA,WAAS,WAAW,QAAsB,QAAkB,SAA2B;AACrF,UAAM,QAAQ;AAAA,MACZ,EAAE,MAAM,UAAU,YAAY,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI,GAAG,MAAM,CAAC,CAAC,KAAK,OAAO,MAAM,CAAC,GAAG,SAAS,KAAK,UAAU,OAAO,EAAE;AAAA,MAC5H;AAAA,IACF;AACA,QAAI,CAACA,UAAS;AACZ,WAAK,QAAQ,QAAQ,KAAK;AAC1B;AAAA,IACF;AACA,UAAM,gBAAgB,kBAAkB;AACxC,UAAM,kBAAwB,yBAAmB,eAAe,OAAO,MAAM;AAI7E,UAAM,YACJ,aAAa,2BAA2B,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI,IAAI,wBAAwB;AAClG,UAAM,OAAO;AAAA,MACX;AAAA,QACE,MAAM;AAAA,QACN,YAAY;AAAA,QACZ,MAAM,CAAC,CAAC,KAAK,OAAO,MAAM,CAAC;AAAA,QAC3B,SAAe,cAAQ,KAAK,UAAU,KAAK,GAAG,eAAe;AAAA,MAC/D;AAAA,MACA;AAAA,IACF;AACA,SAAK,QAAQ,QAAQ,IAAI;AAAA,EAC3B;AAEA,WAAS,eACP,QACA,QACA,SACA,SACqB;AACrB,UAAM,gBAAgB,kBAAkB;AACxC,UAAM,aAAa,QAAQ;AAC3B,UAAM,WAAuB,EAAE,GAAG,SAAS,IAAI,cAAc;AAC7D,WAAO,IAAI,QAAoB,CAAC,SAAS,WAAW;AAClD,YAAM,QAAQ,WAAW,MAAM;AAC7B,gBAAQ,OAAO,aAAa;AAC5B,eAAO,IAAI,MAAM,eAAe,CAAC;AAAA,MACnC,GAAG,OAAO;AACV,cAAQ,IAAI,eAAe,EAAE,SAAS,QAAQ,OAAO,WAAW,CAAC;AACjE,UAAI;AACF,mBAAW,QAAQ,QAAQ,QAAQ;AAAA,MACrC,SAAS,KAAK;AACZ,gBAAQ,OAAO,aAAa;AAC5B,qBAAa,KAAK;AAClB,eAAO,eAAe,QAAQ,MAAM,IAAI,MAAM,gBAAgB,CAAC;AAAA,MACjE;AAAA,IACF,CAAC;AAAA,EACH;AAEA,WAAS,WAAW,QAAqC;AACvD,QAAI,UAAU,SAAS,IAAI,OAAO,MAAM;AACxC,QAAI,CAAC,SAAS;AACZ,YAAM,SAAS,cAAc,MAAM;AACnC,gBAAU,EAAE,QAAQ,aAAa,OAAO,cAAc,KAAK;AAC3D,eAAS,IAAI,OAAO,QAAQ,OAAO;AACnC,iBAAW,MAAM;AAAA,IACnB;AACA,WAAO;AAAA,EACT;AAEA,iBAAe,kBAAkB,QAAsB,SAAwB,SAAgC;AAC7G,QAAI,QAAQ,YAAa;AACzB,QAAI,QAAQ,aAAc,QAAO,QAAQ;AACzC,YAAQ,gBAAgB,YAAY;AAClC,UAAI;AACF,cAAM;AAAA,UACJ;AAAA,UACA,QAAQ;AAAA,UACR;AAAA,YACE,SAAS;AAAA,YACT,IAAI;AAAA,YACJ,QAAQ;AAAA,YACR,QAAQ,EAAE,iBAAiB,sBAAsB,cAAc,CAAC,GAAG,WAAW;AAAA,UAChF;AAAA,UACA;AAAA,QACF;AAEA,mBAAW,QAAQ,QAAQ,QAAQ,EAAE,SAAS,OAAO,QAAQ,4BAA4B,CAAC;AAC1F,gBAAQ,cAAc;AAAA,MACxB,QAAQ;AACN,cAAM,IAAI,MAAM,uBAAuB;AAAA,MACzC,UAAE;AACA,gBAAQ,eAAe;AAAA,MACzB;AAAA,IACF,GAAG;AACH,WAAO,QAAQ;AAAA,EACjB;AAEA,SAAO;AAAA,IACL,MAAM,SAAS,OAAgD;AAC7D,YAAM,SAAS,OAAO,UAAU,MAAM,OAAO,SAAS,IAAI,MAAM,SAAS;AACzE,UAAI,OAAO,WAAW,EAAG,QAAO,CAAC;AACjC,YAAM,YAAY,oBAAI,IAA4B;AAClD,YAAM,YAAY,oBAAI,IAA4B;AAClD,YAAM,IAAI,QAAc,CAAC,YAAY;AACnC,cAAM,MAAM,KAAK;AAAA,UACf;AAAA,UACA,EAAE,OAAO,CAAC,sBAAsB,mBAAmB,GAAG,OAAO,OAAO,QAAQ,MAAM,QAAQ,IAAI,IAAI;AAAA,UAClG;AAAA,YACE,QAAQ,OAAO;AACb,kBAAI,MAAM,SAAS,qBAAsB,WAAU,IAAI,MAAM,QAAQ,KAAK;AAAA,uBACjE,MAAM,SAAS,oBAAqB,WAAU,IAAI,MAAM,QAAQ,KAAK;AAAA,YAChF;AAAA,YACA,SAAS;AAAE,sBAAQ;AAAA,YAAG;AAAA,UACxB;AAAA,QACF;AACA,mBAAW,MAAM;AAAE,cAAI,MAAM;AAAG,kBAAQ;AAAA,QAAG,GAAG,2BAA2B;AAAA,MAC3E,CAAC;AAED,YAAM,UAAuB,CAAC;AAC9B,iBAAW,CAAC,QAAQ,KAAK,KAAK,WAAW;AACvC,cAAM,OAAO,SAAS,MAAM,MAAM,MAAM;AACxC,cAAM,cAAc,SAAS,MAAM,MAAM,OAAO;AAChD,cAAM,SAAoB;AAAA,UACxB;AAAA,UACA,QAAQ,CAAC,GAAG,MAAM;AAAA,UAClB,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC;AAAA,UACvB,GAAI,cAAc,EAAE,YAAY,IAAI,CAAC;AAAA,UACrC,iBAAiB;AAAA,QACnB;AACA,cAAM,QAAQ,UAAU,IAAI,MAAM;AAClC,YAAI,OAAO;AACT,gBAAM,QAAQ,MAAM,KAAK,OAAO,CAAC,QAAQ,IAAI,CAAC,MAAM,OAAO,OAAO,IAAI,CAAC,MAAM,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC;AAC1G,cAAI,MAAM,SAAS,EAAG,QAAO,eAAe;AAAA,QAC9C;AACA,gBAAQ,KAAK,MAAM;AAAA,MACrB;AAEA,YAAM,SAAS,OAAO,QAAQ,YAAY;AAC1C,YAAM,WAAW,SACb,QAAQ,OAAO,CAAC,MAAM,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,YAAY,EAAE,SAAS,MAAM,CAAC,IAC7F;AACJ,aAAO,OAAO,QAAQ,SAAS,MAAM,GAAG,MAAM,KAAK,IAAI;AAAA,IACzD;AAAA,IAEA,MAAM,QAAQ,QAAsB,SAAqB,gBAAyD;AAChH,YAAM,UAAU,WAAW,MAAM;AACjC,YAAM,UAAU,gBAAgB,aAAa;AAC7C,UAAI,gBAAgB,WAAY,OAAM,kBAAkB,QAAQ,SAAS,OAAO;AAChF,aAAO,eAAe,QAAQ,QAAQ,QAAQ,SAAS,OAAO;AAAA,IAChE;AAAA,IAEA,MAAM,MAAM,QAAqC;AAC/C,YAAM,UAAU,SAAS,IAAI,OAAO,MAAM;AAC1C,UAAI,CAAC,QAAS;AACd,eAAS,OAAO,OAAO,MAAM;AAC7B,oBAAc,QAAQ,MAAM;AAAA,IAC9B;AAAA,IAEA,QAAQ,SAA0C;AAChD,oBAAc,IAAI,OAAO;AACzB,aAAO;AAAA,QACL,QAAQ;AACN,wBAAc,OAAO,OAAO;AAAA,QAC9B;AAAA,MACF;AAAA,IACF;AAAA,IAEA,UAAgB;AACd,eAAS,MAAM;AACf,gBAAU;AACV,iBAAW,SAAS,QAAQ,OAAO,GAAG;AACpC,qBAAa,MAAM,KAAK;AACxB,cAAM,OAAO,IAAI,MAAM,oBAAoB,CAAC;AAAA,MAC9C;AACA,cAAQ,MAAM;AACd,eAAS,MAAM;AACf,oBAAc,MAAM;AACpB,oBAAc,MAAM;AACpB,yBAAmB;AAAA,IACrB;AAAA,EACF;AACF;","names":["encrypt"]}
+{"version":3,"sources":["../src/cvm-nostr-transport.ts"],"sourcesContent":["/**\n * cvm-nostr-transport.ts — concrete ContextVM transport for NAP-CVM.\n *\n * Implements {@link CvmTransport} over Nostr, exactly as validated against live\n * ContextVM servers (e.g. Relatr):\n *\n *  - MCP JSON-RPC messages ride in kind-25910 event `content`.\n *  - Requests are CEP-4 gift-wrapped: the inner kind-25910 event is signed with\n *    the shell's ephemeral client key, NIP-44-encrypted to the server, and\n *    placed in a kind-21059 (ephemeral) / 1059 (regular) wrap signed by a fresh\n *    random key, `p`-tagged to the server. Responses arrive the same way,\n *    `p`-tagged to the client, and are correlated by the inner JSON-RPC `id`.\n *  - Discovery reads kind-11316 (server) + kind-11317 (tools) announcements.\n *\n * Shipped on a separate entry (`@kehto/services/cvm-nostr-transport`) so the\n * `nostr-tools` dependency stays out of the core `@kehto/services` bundle.\n *\n * The client key is ephemeral and shell-owned: napplets never see keys, relay\n * sockets, or NIP-44 material (NAP-CVM §Security).\n *\n * @example\n * ```ts\n * import { createNostrCvmTransport } from '@kehto/services/cvm-nostr-transport';\n * const transport = createNostrCvmTransport({\n *   defaultRelays: ['wss://relay.contextvm.org', 'wss://relay2.contextvm.org'],\n * });\n * ```\n */\n\nimport { SimplePool } from 'nostr-tools/pool';\nimport { finalizeEvent, generateSecretKey, getPublicKey } from 'nostr-tools/pure';\nimport * as nip44 from 'nostr-tools/nip44';\nimport type { Event as NostrToolsEvent, Filter as NostrToolsFilter } from 'nostr-tools';\n\nimport type { CvmTransport } from './cvm-service.js';\nimport type {\n  CvmDiscoverQuery,\n  CvmRequestOptions,\n  CvmServer,\n  CvmServerRef,\n  McpMessage,\n} from './cvm-types.js';\n\n/** ContextVM unified transport event kind. */\nconst KIND_CVM = 25910;\n/** CEP-4 gift-wrap kinds: ephemeral (CEP-19) and regular. */\nconst KIND_GIFT_WRAP_EPHEMERAL = 21059;\nconst KIND_GIFT_WRAP_REGULAR = 1059;\n/** CEP-6 announcement kinds. */\nconst KIND_ANNOUNCE_SERVER = 11316;\nconst KIND_ANNOUNCE_TOOLS = 11317;\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\nconst DEFAULT_DISCOVER_TIMEOUT_MS = 6_000;\nconst MCP_PROTOCOL_VERSION = '2025-11-25';\nconst SEEN_WRAP_LIMIT = 512;\n\n/** Minimal signed Nostr event. */\nexport interface NostrEventLike {\n  id: string;\n  pubkey: string;\n  created_at: number;\n  kind: number;\n  tags: string[][];\n  content: string;\n  sig: string;\n}\n\n/** A Nostr REQ filter (subset). */\nexport interface NostrFilterLike {\n  kinds?: number[];\n  authors?: string[];\n  limit?: number;\n  ['#p']?: string[];\n  [key: string]: unknown;\n}\n\n/** Subscription handle returned by the relay pool. */\nexport interface CvmSubCloser {\n  close(): void;\n}\n\n/**\n * Minimal relay-pool surface used by this transport — structurally satisfied\n * by `nostr-tools` `SimplePool`. Injectable for testing.\n */\nexport interface CvmRelayPool {\n  subscribe(\n    relays: string[],\n    filter: NostrFilterLike,\n    params: { onevent?: (event: NostrEventLike) => void; oneose?: () => void },\n  ): CvmSubCloser;\n  publish(relays: string[], event: NostrEventLike): unknown;\n}\n\n/** Options for {@link createNostrCvmTransport}. */\nexport interface NostrCvmTransportOptions {\n  /** Relays used when a server reference carries no relay hints. */\n  defaultRelays?: string[];\n  /** Default per-request timeout in milliseconds. */\n  timeoutMs?: number;\n  /** Whether to CEP-4 gift-wrap requests. Default true (most servers require it). */\n  encrypt?: boolean;\n  /** Use ephemeral (kind 21059) gift wraps when encrypting. Default true. */\n  ephemeralWrap?: boolean;\n  /** Relay pool to use. Defaults to a fresh `nostr-tools` `SimplePool`. */\n  pool?: CvmRelayPool;\n  /** Client secret key (32 bytes). Defaults to a generated ephemeral key. */\n  clientSecretKey?: Uint8Array;\n  /** Client info advertised during MCP `initialize`. */\n  clientInfo?: { name: string; version: string };\n}\n\ntype EventHandler = (server: CvmServerRef, message: McpMessage) => void;\n\ninterface PendingRequest {\n  resolve(message: McpMessage): void;\n  reject(error: Error): void;\n  timer: ReturnType<typeof setTimeout>;\n  /** The caller's original JSON-RPC id, restored on the response. */\n  originalId: string | number | undefined;\n}\n\ninterface ServerSession {\n  relays: string[];\n  initialized: boolean;\n  initializing: Promise<void> | null;\n}\n\nlet correlationCounter = 0;\nfunction nextCorrelationId(): string {\n  correlationCounter += 1;\n  return `cvm-${correlationCounter}-${getPublicKey(generateSecretKey()).slice(0, 8)}`;\n}\n\nfunction randomizedPastTimestamp(): number {\n  // NIP-59: randomize within the past two days to reduce timing metadata.\n  const jitter = Math.floor(Math.random() * 172_800);\n  return Math.floor(Date.now() / 1000) - jitter;\n}\n\nfunction tagValue(tags: string[][], name: string): string | undefined {\n  return tags.find((tag) => tag[0] === name)?.[1];\n}\n\n/** Adapt a `nostr-tools` SimplePool to the {@link CvmRelayPool} surface. */\nfunction simplePoolAdapter(sp: SimplePool): CvmRelayPool {\n  return {\n    subscribe(relays, filter, params) {\n      return sp.subscribe(relays, filter as NostrToolsFilter, {\n        onevent: params.onevent,\n        oneose: params.oneose,\n      });\n    },\n    publish(relays, event) {\n      return sp.publish(relays, event as NostrToolsEvent);\n    },\n  };\n}\n\n/**\n * Create a Nostr-backed ContextVM transport.\n *\n * @param options - Relay set, timeouts, encryption mode, and optional injected\n *   pool/keys (the injected pool + key make the transport deterministic in tests).\n * @returns A {@link CvmTransport} plus a `dispose()` to tear down subscriptions.\n */\nexport function createNostrCvmTransport(\n  options: NostrCvmTransportOptions = {},\n): CvmTransport & { dispose(): void } {\n  const defaultRelays = options.defaultRelays ?? [];\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const encrypt = options.encrypt ?? true;\n  const wrapKind = options.ephemeralWrap === false ? KIND_GIFT_WRAP_REGULAR : KIND_GIFT_WRAP_EPHEMERAL;\n  const pool: CvmRelayPool = options.pool ?? simplePoolAdapter(new SimplePool());\n  const clientSecretKey = options.clientSecretKey ?? generateSecretKey();\n  const clientPubkey = getPublicKey(clientSecretKey);\n  const clientInfo = options.clientInfo ?? { name: 'kehto-cvm', version: '1.0.0' };\n\n  const sessions = new Map<string, ServerSession>();\n  const pending = new Map<string, PendingRequest>();\n  const eventHandlers = new Set<EventHandler>();\n  const relayRefcount = new Map<string, number>();\n  const seenWraps = new Set<string>();\n  let inbound: CvmSubCloser | null = null;\n  let subscribedRelays = '';\n\n  function resolveRelays(server: CvmServerRef): string[] {\n    const relays = server.relays && server.relays.length > 0 ? server.relays : defaultRelays;\n    if (relays.length === 0) throw new Error('server not found');\n    return [...new Set(relays)];\n  }\n\n  function holdRelays(relays: string[]): void {\n    for (const url of relays) relayRefcount.set(url, (relayRefcount.get(url) ?? 0) + 1);\n    refreshSubscription();\n  }\n\n  function releaseRelays(relays: string[]): void {\n    for (const url of relays) {\n      const count = (relayRefcount.get(url) ?? 0) - 1;\n      if (count <= 0) relayRefcount.delete(url);\n      else relayRefcount.set(url, count);\n    }\n    refreshSubscription();\n  }\n\n  function refreshSubscription(): void {\n    const relays = [...relayRefcount.keys()].sort();\n    const key = relays.join(',');\n    if (key === subscribedRelays) return;\n    inbound?.close();\n    subscribedRelays = key;\n    inbound = relays.length === 0\n      ? null\n      : pool.subscribe(\n          relays,\n          { kinds: encrypt ? [KIND_GIFT_WRAP_REGULAR, KIND_GIFT_WRAP_EPHEMERAL] : [KIND_CVM], ['#p']: [clientPubkey] },\n          { onevent: handleInbound },\n        );\n  }\n\n  function rememberWrap(id: string): boolean {\n    if (seenWraps.has(id)) return false;\n    seenWraps.add(id);\n    if (seenWraps.size > SEEN_WRAP_LIMIT) {\n      const oldest = seenWraps.values().next().value;\n      if (oldest !== undefined) seenWraps.delete(oldest);\n    }\n    return true;\n  }\n\n  function handleInbound(event: NostrEventLike): void {\n    if (!rememberWrap(event.id)) return;\n    let serverPubkey: string;\n    let mcp: McpMessage;\n    try {\n      if (encrypt) {\n        const conversationKey = nip44.getConversationKey(clientSecretKey, event.pubkey);\n        const inner = JSON.parse(nip44.decrypt(event.content, conversationKey)) as NostrEventLike;\n        serverPubkey = inner.pubkey;\n        mcp = JSON.parse(inner.content) as McpMessage;\n      } else {\n        serverPubkey = event.pubkey;\n        mcp = JSON.parse(event.content) as McpMessage;\n      }\n    } catch {\n      return; // not addressed to us / undecryptable / malformed — ignore.\n    }\n\n    const id = mcp.id;\n    if (id != null && pending.has(String(id))) {\n      const entry = pending.get(String(id))!;\n      pending.delete(String(id));\n      clearTimeout(entry.timer);\n      entry.resolve({ ...mcp, id: entry.originalId });\n      return;\n    }\n    // Uncorrelated server message (notification) → fan out as a CVM event.\n    if (mcp.method !== undefined && sessions.has(serverPubkey)) {\n      const server: CvmServerRef = { pubkey: serverPubkey };\n      for (const handler of eventHandlers) handler(server, mcp);\n    }\n  }\n\n  function publishMcp(server: CvmServerRef, relays: string[], message: McpMessage): void {\n    const inner = finalizeEvent(\n      { kind: KIND_CVM, created_at: Math.floor(Date.now() / 1000), tags: [['p', server.pubkey]], content: JSON.stringify(message) },\n      clientSecretKey,\n    ) as NostrEventLike;\n    if (!encrypt) {\n      pool.publish(relays, inner);\n      return;\n    }\n    const wrapSecretKey = generateSecretKey();\n    const conversationKey = nip44.getConversationKey(wrapSecretKey, server.pubkey);\n    // Ephemeral wraps (kind 21059) are not stored; relays reject backdated\n    // ephemeral events as \"expired\", so they MUST carry a current timestamp.\n    // Regular wraps (kind 1059) are backdated per NIP-59 to blur timing metadata.\n    const createdAt =\n      wrapKind === KIND_GIFT_WRAP_EPHEMERAL ? Math.floor(Date.now() / 1000) : randomizedPastTimestamp();\n    const wrap = finalizeEvent(\n      {\n        kind: wrapKind,\n        created_at: createdAt,\n        tags: [['p', server.pubkey]],\n        content: nip44.encrypt(JSON.stringify(inner), conversationKey),\n      },\n      wrapSecretKey,\n    ) as NostrEventLike;\n    pool.publish(relays, wrap);\n  }\n\n  function sendCorrelated(\n    server: CvmServerRef,\n    relays: string[],\n    message: McpMessage,\n    timeout: number,\n  ): Promise<McpMessage> {\n    const correlationId = nextCorrelationId();\n    const originalId = message.id;\n    const outgoing: McpMessage = { ...message, id: correlationId };\n    return new Promise<McpMessage>((resolve, reject) => {\n      const timer = setTimeout(() => {\n        pending.delete(correlationId);\n        reject(new Error('relay timeout'));\n      }, timeout);\n      pending.set(correlationId, { resolve, reject, timer, originalId });\n      try {\n        publishMcp(server, relays, outgoing);\n      } catch (err) {\n        pending.delete(correlationId);\n        clearTimeout(timer);\n        reject(err instanceof Error ? err : new Error('publish failed'));\n      }\n    });\n  }\n\n  function getSession(server: CvmServerRef): ServerSession {\n    let session = sessions.get(server.pubkey);\n    if (!session) {\n      const relays = resolveRelays(server);\n      session = { relays, initialized: false, initializing: null };\n      sessions.set(server.pubkey, session);\n      holdRelays(relays);\n    }\n    return session;\n  }\n\n  async function ensureInitialized(server: CvmServerRef, session: ServerSession, timeout: number): Promise<void> {\n    if (session.initialized) return;\n    if (session.initializing) return session.initializing;\n    session.initializing = (async () => {\n      try {\n        await sendCorrelated(\n          server,\n          session.relays,\n          {\n            jsonrpc: '2.0',\n            id: 'init',\n            method: 'initialize',\n            params: { protocolVersion: MCP_PROTOCOL_VERSION, capabilities: {}, clientInfo },\n          },\n          timeout,\n        );\n        // notifications/initialized completes the handshake; no response expected.\n        publishMcp(server, session.relays, { jsonrpc: '2.0', method: 'notifications/initialized' });\n        session.initialized = true;\n      } catch {\n        throw new Error('initialization failed');\n      } finally {\n        session.initializing = null;\n      }\n    })();\n    return session.initializing;\n  }\n\n  return {\n    async discover(query?: CvmDiscoverQuery): Promise<CvmServer[]> {\n      const relays = query?.relays && query.relays.length > 0 ? query.relays : defaultRelays;\n      if (relays.length === 0) return [];\n      const announces = new Map<string, NostrEventLike>();\n      const toolLists = new Map<string, NostrEventLike>();\n      await new Promise<void>((resolve) => {\n        const sub = pool.subscribe(\n          relays,\n          { kinds: [KIND_ANNOUNCE_SERVER, KIND_ANNOUNCE_TOOLS], limit: query?.limit ? query.limit * 4 : 100 },\n          {\n            onevent(event) {\n              if (event.kind === KIND_ANNOUNCE_SERVER) announces.set(event.pubkey, event);\n              else if (event.kind === KIND_ANNOUNCE_TOOLS) toolLists.set(event.pubkey, event);\n            },\n            oneose() { resolve(); },\n          },\n        );\n        setTimeout(() => { sub.close(); resolve(); }, DEFAULT_DISCOVER_TIMEOUT_MS);\n      });\n\n      const servers: CvmServer[] = [];\n      for (const [pubkey, event] of announces) {\n        const name = tagValue(event.tags, 'name');\n        const description = tagValue(event.tags, 'about');\n        const server: CvmServer = {\n          pubkey,\n          relays: [...relays],\n          ...(name ? { name } : {}),\n          ...(description ? { description } : {}),\n          paymentRequired: false,\n        };\n        const tools = toolLists.get(pubkey);\n        if (tools) {\n          const names = tools.tags.filter((tag) => tag[0] === 'i' && typeof tag[2] === 'string').map((tag) => tag[2]);\n          if (names.length > 0) server.capabilities = names;\n        }\n        servers.push(server);\n      }\n\n      const search = query?.search?.toLowerCase();\n      const filtered = search\n        ? servers.filter((s) => `${s.name ?? ''} ${s.description ?? ''}`.toLowerCase().includes(search))\n        : servers;\n      return query?.limit ? filtered.slice(0, query.limit) : filtered;\n    },\n\n    async request(server: CvmServerRef, message: McpMessage, requestOptions?: CvmRequestOptions): Promise<McpMessage> {\n      const session = getSession(server);\n      const timeout = requestOptions?.timeoutMs ?? timeoutMs;\n      if (requestOptions?.initialize) await ensureInitialized(server, session, timeout);\n      return sendCorrelated(server, session.relays, message, timeout);\n    },\n\n    async close(server: CvmServerRef): Promise<void> {\n      const session = sessions.get(server.pubkey);\n      if (!session) return;\n      sessions.delete(server.pubkey);\n      releaseRelays(session.relays);\n    },\n\n    onEvent(handler: EventHandler): { close(): void } {\n      eventHandlers.add(handler);\n      return {\n        close() {\n          eventHandlers.delete(handler);\n        },\n      };\n    },\n\n    dispose(): void {\n      inbound?.close();\n      inbound = null;\n      for (const entry of pending.values()) {\n        clearTimeout(entry.timer);\n        entry.reject(new Error('transport disposed'));\n      }\n      pending.clear();\n      sessions.clear();\n      relayRefcount.clear();\n      eventHandlers.clear();\n      subscribedRelays = '';\n    },\n  };\n}\n"],"mappings":"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","names":["encrypt"]}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ServiceHandler, Signer } from '@kehto/runtime';
-import { NostrEvent, NappletMessage, NostrFilter } from '@napplet/core';
+import { NostrEvent, NappletMessage, NostrFilter, EventTemplate } from '@napplet/core';
 import { MediaMetadata, MediaAction } from '@napplet/nub/media/types';
 export { MediaAction } from '@napplet/nub/media/types';
 import { NotifySendMessage } from '@napplet/nub/notify/types';
@@ -1532,4 +1532,268 @@ type ResourceService = ServiceHandler;
  */
 declare function createResourceService(options: ResourceServiceOptions): ResourceService;
 
-export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type GiftWrapDecryptResult, type HostCacheBridge, type HostDecryptBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type IdentityDecryptErrorCode, type IdentityDecryptErrorMessage, type IdentityDecryptMessage, type IdentityDecryptResultMessage, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type Rumor, type ThemeService, type ThemeServiceOptions, type VerifyEvent, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createRelayPoolService, createResourceService, createThemeService };
+/**
+ * outbox-service.ts — NAP-OUTBOX (outbox-aware relay routing) reference service.
+ *
+ * Shell-side handler for the NAP-OUTBOX wire protocol. It is a pure envelope
+ * router: it validates `outbox.*` envelopes, delegates the actual relay
+ * discovery / routing / dedup / publish-fanout work to an injected
+ * {@link OutboxRouter}, and posts the correlated result / lifecycle messages
+ * (echoing the request `id` or `subId`) back to the napplet.
+ *
+ * The router is injected (options-as-bridge) so this service has no Nostr
+ * dependency and is fully unit-testable. A concrete relay-pool-backed router
+ * ships alongside as {@link createRelayPoolOutboxRouter}.
+ *
+ * ──────────────────────────── Responsibilities ────────────────────────────
+ *   Inbound:  outbox.query, outbox.subscribe, outbox.close, outbox.publish,
+ *             outbox.resolveRelays
+ *   Outbound: outbox.query.result, outbox.event, outbox.eose, outbox.closed,
+ *             outbox.publish.result, outbox.resolveRelays.result
+ *
+ * The shell owns relay discovery, routing, fallback, deduplication, signature
+ * validation, signing, and publish fanout policy — all of which live behind
+ * the {@link OutboxRouter}. This service only marshals the wire protocol.
+ *
+ * @example
+ * ```ts
+ * import { createOutboxService, createRelayPoolOutboxRouter } from '@kehto/services';
+ *
+ * const router = createRelayPoolOutboxRouter({ relayPool, loadRelayLists, fallbackRelays });
+ * runtime.registerService('outbox', createOutboxService({ router }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Relay-selection strategy:
+ * - `outbox` — query/publish via author write relays (the outbox model)
+ * - `inbox`  — query/publish via recipient read relays (the inbox model)
+ * - `auto`   — let the shell choose per its policy and relay intelligence
+ */
+type OutboxStrategy = 'outbox' | 'inbox' | 'auto';
+/** Options for a one-shot outbox query. */
+interface OutboxQueryOptions {
+    /** Explicit author hints (augment/override authors derived from filters). */
+    authors?: string[];
+    /** Relay hints; treated as a hint subject to shell validation, not a bypass. */
+    relays?: string[];
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+    /** Maximum events to collect. */
+    limit?: number;
+    /** Wall-clock budget for the query, in milliseconds. */
+    timeoutMs?: number;
+}
+/** Options for a live outbox subscription. */
+interface OutboxSubscribeOptions extends OutboxQueryOptions {
+    /** Keep the subscription open for real-time events after EOSE. */
+    live?: boolean;
+}
+/** Options for an outbox publish. */
+interface OutboxPublishOptions {
+    /** Relay hints; treated as a hint subject to shell validation. */
+    relays?: string[];
+    /** Recipient authors whose inbox relays should be included for directed events. */
+    targetAuthors?: string[];
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+}
+/** A read/write target for relay-plan resolution. */
+interface OutboxTarget {
+    /** Authors to resolve relays for. */
+    authors?: string[];
+    /** Single pubkey to resolve relays for. */
+    pubkey?: string;
+    /** Whether the plan is for reading (their write relays) or writing (their read relays). */
+    direction?: 'read' | 'write';
+    /** Relay-selection strategy. */
+    strategy?: OutboxStrategy;
+}
+/** The relay plan the shell would use for a target. */
+interface OutboxRelayPlan {
+    /** Resolved relay URLs. */
+    relays: string[];
+    /** Where the plan came from. */
+    source: 'nip65' | 'cache' | 'policy' | 'fallback';
+    /** Authors for which no relay list could be resolved. */
+    missingAuthors?: string[];
+}
+/** Outcome of an outbox query, as returned by the {@link OutboxRouter}. */
+interface OutboxResult {
+    /** Deduplicated, signature-validated events. */
+    events: NostrEvent[];
+    /** Map of event id -> relay URLs where the shell observed the event. */
+    relays: Record<string, string[]>;
+    /** True when some relay lists or connections failed and results are partial. */
+    incomplete?: boolean;
+    /** Error reason when the query could not complete. */
+    error?: string;
+}
+/** Outcome of an outbox publish, as returned by the {@link OutboxRouter}. */
+interface OutboxPublishResult {
+    /** Whether the publish succeeded on at least the required relays. */
+    ok: boolean;
+    /** The signed event returned by the shell. */
+    event?: NostrEvent;
+    /** The published event id. */
+    eventId?: string;
+    /** Map of relay URL -> per-relay publish success. */
+    relays?: Record<string, boolean>;
+    /** Error reason when the publish failed. */
+    error?: string;
+}
+/** Sink an {@link OutboxRouter} streams subscription lifecycle through. */
+interface OutboxSubscriptionSink {
+    /** Deliver a matching event; `relay` is the relay it was observed on, when known. */
+    event(event: NostrEvent, relay?: string): void;
+    /** Signal end-of-stored-events. */
+    eose(): void;
+    /** Signal that the subscription was closed upstream; `reason` is optional. */
+    closed(reason?: string): void;
+}
+/** Handle to a router-owned subscription. */
+interface OutboxRouterSubscription {
+    /** Stop the subscription and release its relay connections. */
+    close(): void;
+}
+/**
+ * Abstract outbox router. Implementors own relay discovery (NIP-65 / NIP-66),
+ * routing, fallback, deduplication, signature validation, signing, and publish
+ * fanout. The service translates wire envelopes into these calls and back.
+ */
+interface OutboxRouter {
+    /** Resolve relays, query them, dedup by id, validate signatures, collect events. */
+    query(filters: NostrFilter[], options?: OutboxQueryOptions): Promise<OutboxResult>;
+    /** Open a live outbox-aware subscription, streaming through `sink`. */
+    subscribe(filters: NostrFilter[], options: OutboxSubscribeOptions | undefined, sink: OutboxSubscriptionSink): OutboxRouterSubscription;
+    /** Sign `template` and fan it out to the relevant write/inbox relays. */
+    publish(template: EventTemplate, options?: OutboxPublishOptions): Promise<OutboxPublishResult>;
+    /** Return the relay plan the shell would use for a read/write target. */
+    resolveRelays(target: OutboxTarget): Promise<OutboxRelayPlan>;
+}
+/** Options for {@link createOutboxService}. */
+interface OutboxServiceOptions {
+    /** The outbox router the shell uses to reach relays. Required. */
+    router: OutboxRouter;
+}
+/**
+ * Create the NAP-OUTBOX service handler.
+ *
+ * @param options - Must provide an {@link OutboxRouter}.
+ * @returns A `ServiceHandler` ready for `runtime.registerService('outbox', handler)`.
+ * @throws If `options.router` is missing.
+ */
+declare function createOutboxService(options: OutboxServiceOptions): ServiceHandler;
+
+/**
+ * relay-pool-outbox-router.ts — concrete {@link OutboxRouter} backed by a relay pool.
+ *
+ * Implements the outbox-model routing that NAP-OUTBOX centralizes so napplets
+ * don't each reinvent it: derive authors, resolve their NIP-65 relays, fan a
+ * per-relay subscription out across the plan, deduplicate by event id (while
+ * recording every relay an event was observed on), validate signatures, and —
+ * for publish — sign the template and fan it out to the relevant write/inbox
+ * relays.
+ *
+ * NIP-65 relay-list *fetching* is the host's concern (it may come from a
+ * kind-10002 cache, a NIP-66 indexer via `@kehto/nip/66`, or a live query), so
+ * it is injected via {@link RelayPoolOutboxRouterOptions.loadRelayLists}. The
+ * relay pool, signer, and signature verifier are injected too — keeping this
+ * router browser-agnostic and unit-testable with mocks.
+ *
+ * Relay-selection model (per the outbox model):
+ * - reading an author's events  → their **write** relays (where they publish)
+ * - writing to reach an author   → their **read**  relays (their inbox)
+ *
+ * `strategy` overrides the direction default: `outbox` forces write relays,
+ * `inbox` forces read relays, `auto` (default) follows the read/write direction.
+ *
+ * @example
+ * ```ts
+ * import { createOutboxService, createRelayPoolOutboxRouter } from '@kehto/services';
+ *
+ * const router = createRelayPoolOutboxRouter({
+ *   relayPool: myOutboxPool,
+ *   loadRelayLists: (pubkeys) => relayListCache.getMany(pubkeys),
+ *   fallbackRelays: ['wss://relay.damus.io', 'wss://nos.lol'],
+ *   signEvent: (tmpl) => signer.signEvent(tmpl),
+ *   verifyEvent: (ev) => verifyEvent(ev),
+ * });
+ * runtime.registerService('outbox', createOutboxService({ router }));
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/** A NIP-65 relay list for a single pubkey. */
+interface RelayListEntry {
+    /** Relays the author reads from (their inbox). */
+    read: string[];
+    /** Relays the author writes to (where their events land). */
+    write: string[];
+}
+/**
+ * Relay pool contract the router drives. Implementors adapt their pool library
+ * (nostr-tools SimplePool, applesauce-relay, etc.). Unlike the lower-level
+ * relay NUB pool, both methods take an explicit relay-URL set so the router
+ * controls outbox routing and can attribute events to the relay they arrived on.
+ */
+interface OutboxRelayPool {
+    /**
+     * Subscribe to `filters` on exactly `relayUrls`. The callback receives each
+     * matching event or the literal `'EOSE'` once stored events are exhausted.
+     * Returns a handle to cancel the subscription.
+     */
+    subscribe(filters: NostrFilter[], relayUrls: string[], callback: (item: NostrEvent | 'EOSE') => void): {
+        unsubscribe(): void;
+    };
+    /**
+     * Publish `event` to `relayUrls`. May return a per-relay success map; a
+     * `void`/missing return is treated as optimistic success on every target.
+     */
+    publish(event: NostrEvent, relayUrls: string[]): Promise<Record<string, boolean>> | Record<string, boolean> | void;
+    /** Whether the relay pool is connected and able to handle requests. */
+    isAvailable(): boolean;
+}
+/** Options for {@link createRelayPoolOutboxRouter}. */
+interface RelayPoolOutboxRouterOptions {
+    /** Relay pool the router subscribes/publishes through. Required. */
+    relayPool: OutboxRelayPool;
+    /**
+     * Resolve NIP-65 relay lists for a set of pubkeys. Pubkeys with no known
+     * list are simply omitted from the returned map (they become `missingAuthors`).
+     */
+    loadRelayLists(pubkeys: string[]): Promise<Map<string, RelayListEntry>> | Map<string, RelayListEntry>;
+    /** Relays to fall back to when NIP-65 data is absent, stale, or empty. Required. */
+    fallbackRelays: string[];
+    /**
+     * Sign a template before publish (shell-mediated; napplets never sign). When
+     * omitted, `publish` resolves with `{ ok: false, error: 'publish denied' }`.
+     */
+    signEvent?(template: EventTemplate): Promise<NostrEvent>;
+    /**
+     * Validate an event signature before delivering it to a napplet. May be sync
+     * or async. Defaults to accepting every event (host pools often pre-verify).
+     */
+    verifyEvent?(event: NostrEvent): Promise<boolean> | boolean;
+    /**
+     * Gate relay URLs (e.g. block private-network hosts). Defaults to allowing
+     * only `ws://` / `wss://` URLs — `options.relays` hints pass through this too.
+     */
+    isRelayAllowed?(url: string): boolean;
+    /** Default query timeout when `options.timeoutMs` is unset. Default 4000ms. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Create a relay-pool-backed {@link OutboxRouter}.
+ *
+ * @param options - Relay pool, NIP-65 loader, fallback relays, and optional
+ *   signer / verifier / relay gate / timeout.
+ * @returns An {@link OutboxRouter} for {@link createOutboxService}.
+ * @throws If `relayPool`, `loadRelayLists`, or `fallbackRelays` are missing.
+ */
+declare function createRelayPoolOutboxRouter(options: RelayPoolOutboxRouterOptions): OutboxRouter;
+
+export { type AudioServiceOptions, type AudioSource, type CacheServiceOptions, type ConfigSchemaValidation, type ConfigService, type ConfigServiceOptions, type CoordinatedRelayOptions, type GiftWrapDecryptResult, type HostCacheBridge, type HostDecryptBridge, type HostKeyEvent, type HostKeysBridge, type HostMediaBridge, type IdentityDecryptErrorCode, type IdentityDecryptErrorMessage, type IdentityDecryptMessage, type IdentityDecryptResultMessage, type IdentityServiceOptions, type KeysServiceOptions, type MediaMetadataLike, type MediaPlaybackOwner, type MediaServiceOptions, type MediaSessionCreateOptions, type MediaSessionTarget, type MediaSourceRef, type Notification, type NotificationServiceOptions, type NotifyServiceOptions, type OutboxPublishOptions, type OutboxPublishResult, type OutboxQueryOptions, type OutboxRelayPlan, type OutboxRelayPool, type OutboxResult, type OutboxRouter, type OutboxRouterSubscription, type OutboxServiceOptions, type OutboxStrategy, type OutboxSubscribeOptions, type OutboxSubscriptionSink, type OutboxTarget, type RelayListEntry, type RelayPoolOutboxRouterOptions, type RelayPoolServiceOptions, type ResourceService, type ResourceServiceOptions, type Rumor, type ThemeService, type ThemeServiceOptions, type VerifyEvent, createAudioService, createBrowserMediaBridge, createCacheService, createConfigService, createCoordinatedRelay, createIdentityService, createKeysService, createMediaService, createNotificationService, createNotifyService, createOutboxService, createRelayPoolOutboxRouter, createRelayPoolService, createResourceService, createThemeService };