@unicitylabs/sphere-sdk 0.14.1-dev.2 → 0.14.2

package/dist/impl/nodejs/index.d.cts

@@ -13,6 +13,8 @@ interface GroupChatModuleConfig {
     maxReconnectAttempts?: number;
 }
 
+type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -416,6 +418,19 @@ interface PeerInfo {
     chainPubkey: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
+    /**
+     * Network the peer's identity binding DECLARES ('testnet2', …) — absent when
+     * the binding carries none, which is every binding published so far. Parsed
+     * only, never invented: money refuses a PROVEN foreign network (§5.6).
+     *
+     * Absent is also the STRUCTURAL answer on the `@nametag` and `DIRECT://`
+     * routes of the Nostr transport, whichever binding is out there: those two
+     * resolve through nostr-js-sdk's `queryBindingBy*`, whose parser drops every
+     * content field outside its whitelist and never hands back the signed event
+     * (#734 tracks the upstream fix). Only routes that parse the raw event —
+     * `resolveTransportPubkeyInfo`, `discoverAddresses` — can populate it today.
+     */
+    network?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -631,6 +646,26 @@ declare class NostrTransportProvider implements TransportProvider {
     resolveAddressInfo(address: string): Promise<PeerInfo | null>;
     /**
      * Convert a BindingInfo (from nostr-js-sdk) to PeerInfo (sphere-sdk type).
+     *
+     * `network` IS DELIBERATELY ABSENT HERE — a live limitation, not an oversight
+     * (#734). `queryBindingByNametag`/`queryBindingByAddress` are the whole public
+     * resolution API for `@nametag` and `DIRECT://`, and both hardcode
+     * `parseBindingInfo` inside the SDK's PRIVATE `queryWithFirstSeenWins`: the
+     * caller never sees the signed event that resolution selected, and the parse
+     * has already dropped every content field outside its whitelist. Re-querying
+     * raw would mean re-deriving UNIP-01 ownership ourselves (marker preference,
+     * cross-author first-seen-wins, ambiguity→null, multi-relay settle — all
+     * private), and a second resolver that can disagree with the SDK's is worse
+     * than a missing field on a MONEY guard. Nothing can declare a network today
+     * regardless: the publish builders whitelist the same fields.
+     *
+     * CONSEQUENCE, stated plainly: for `@nametag` and `DIRECT://` recipients the
+     * §5.6 cross-network guard can only SIGNAL (`recipient:network-unverified`),
+     * never refuse. Upstream #734 must add `network` to the binding builders AND
+     * to `BindingInfo`; the tripwire in
+     * tests/unit/payments-v2/recipient-network.transport.test.ts fails the day it
+     * lands, so this wiring cannot be forgotten. Do not "fix" this by inventing a
+     * value — a stamped network is what made the guard unfalsifiable (#733).
      */
     private bindingInfoToPeerInfo;
     /**
@@ -1066,12 +1101,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus$1;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus$1) => void): () => void;
 }
 interface IntentWireLike {
     transferId: string;

package/dist/impl/nodejs/index.d.ts

@@ -13,6 +13,8 @@ interface GroupChatModuleConfig {
     maxReconnectAttempts?: number;
 }
 
+type ConnectionStatus$1 = 'connected' | 'degraded' | 'offline';
+
 /**
  * SDK2 Core Types
  * Platform-independent type definitions
@@ -416,6 +418,19 @@ interface PeerInfo {
     chainPubkey: string;
     /** L3 DIRECT address (DIRECT://...) */
     directAddress: string;
+    /**
+     * Network the peer's identity binding DECLARES ('testnet2', …) — absent when
+     * the binding carries none, which is every binding published so far. Parsed
+     * only, never invented: money refuses a PROVEN foreign network (§5.6).
+     *
+     * Absent is also the STRUCTURAL answer on the `@nametag` and `DIRECT://`
+     * routes of the Nostr transport, whichever binding is out there: those two
+     * resolve through nostr-js-sdk's `queryBindingBy*`, whose parser drops every
+     * content field outside its whitelist and never hands back the signed event
+     * (#734 tracks the upstream fix). Only routes that parse the raw event —
+     * `resolveTransportPubkeyInfo`, `discoverAddresses` — can populate it today.
+     */
+    network?: string;
     /** Event timestamp */
     timestamp: number;
 }
@@ -631,6 +646,26 @@ declare class NostrTransportProvider implements TransportProvider {
     resolveAddressInfo(address: string): Promise<PeerInfo | null>;
     /**
      * Convert a BindingInfo (from nostr-js-sdk) to PeerInfo (sphere-sdk type).
+     *
+     * `network` IS DELIBERATELY ABSENT HERE — a live limitation, not an oversight
+     * (#734). `queryBindingByNametag`/`queryBindingByAddress` are the whole public
+     * resolution API for `@nametag` and `DIRECT://`, and both hardcode
+     * `parseBindingInfo` inside the SDK's PRIVATE `queryWithFirstSeenWins`: the
+     * caller never sees the signed event that resolution selected, and the parse
+     * has already dropped every content field outside its whitelist. Re-querying
+     * raw would mean re-deriving UNIP-01 ownership ourselves (marker preference,
+     * cross-author first-seen-wins, ambiguity→null, multi-relay settle — all
+     * private), and a second resolver that can disagree with the SDK's is worse
+     * than a missing field on a MONEY guard. Nothing can declare a network today
+     * regardless: the publish builders whitelist the same fields.
+     *
+     * CONSEQUENCE, stated plainly: for `@nametag` and `DIRECT://` recipients the
+     * §5.6 cross-network guard can only SIGNAL (`recipient:network-unverified`),
+     * never refuse. Upstream #734 must add `network` to the binding builders AND
+     * to `BindingInfo`; the tripwire in
+     * tests/unit/payments-v2/recipient-network.transport.test.ts fails the day it
+     * lands, so this wiring cannot be forgotten. Do not "fix" this by inventing a
+     * value — a stamped network is what made the guard unfalsifiable (#733).
      */
     private bindingInfoToPeerInfo;
     /**
@@ -1066,12 +1101,17 @@ interface FacadeSession {
      * stream nudge resumes. The facade registers handleEpochChange here.
      */
     subscribeEpochChange(handler: (epoch: string) => Promise<void>): () => void;
+    /**
+     * The session's CURRENT status — REQUIRED, and the ONE source `connectionStatus()`
+     * and `connection:status` both come from ('offline' before first contact).
+     */
+    status(): ConnectionStatus$1;
     /**
      * Optional connection-status feed (same wiring pattern as the streams; the
      * emission point is the session's existing `connection:status` transition).
      * The facade's heartbeat resets its backoff on a 'connected' recovery.
      */
-    subscribeStatus?(handler: (status: 'connected' | 'degraded' | 'offline') => void): () => void;
+    subscribeStatus?(handler: (status: ConnectionStatus$1) => void): () => void;
 }
 interface IntentWireLike {
     transferId: string;

package/dist/impl/nodejs/index.js

@@ -24428,6 +24428,15 @@ function defaultUUIDGenerator() {
 var COMPOSING_INDICATOR_KIND = 25050;
 var TIMESTAMP_RANDOMIZATION = 2 * 24 * 60 * 60;
 var EVENT_KINDS = NOSTR_EVENT_KINDS;
+function declaredNetwork(event) {
+  let value;
+  try {
+    value = JSON.parse(event.content)?.network;
+  } catch {
+    return void 0;
+  }
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
 var NostrTransportProvider = class _NostrTransportProvider {
   id = "nostr";
   name = "Nostr Transport";
@@ -24924,6 +24933,26 @@ var NostrTransportProvider = class _NostrTransportProvider {
   }
   /**
    * Convert a BindingInfo (from nostr-js-sdk) to PeerInfo (sphere-sdk type).
+   *
+   * `network` IS DELIBERATELY ABSENT HERE — a live limitation, not an oversight
+   * (#734). `queryBindingByNametag`/`queryBindingByAddress` are the whole public
+   * resolution API for `@nametag` and `DIRECT://`, and both hardcode
+   * `parseBindingInfo` inside the SDK's PRIVATE `queryWithFirstSeenWins`: the
+   * caller never sees the signed event that resolution selected, and the parse
+   * has already dropped every content field outside its whitelist. Re-querying
+   * raw would mean re-deriving UNIP-01 ownership ourselves (marker preference,
+   * cross-author first-seen-wins, ambiguity→null, multi-relay settle — all
+   * private), and a second resolver that can disagree with the SDK's is worse
+   * than a missing field on a MONEY guard. Nothing can declare a network today
+   * regardless: the publish builders whitelist the same fields.
+   *
+   * CONSEQUENCE, stated plainly: for `@nametag` and `DIRECT://` recipients the
+   * §5.6 cross-network guard can only SIGNAL (`recipient:network-unverified`),
+   * never refuse. Upstream #734 must add `network` to the binding builders AND
+   * to `BindingInfo`; the tripwire in
+   * tests/unit/payments-v2/recipient-network.transport.test.ts fails the day it
+   * lands, so this wiring cannot be forgotten. Do not "fix" this by inventing a
+   * value — a stamped network is what made the guard unfalsifiable (#733).
    */
   async bindingInfoToPeerInfo(binding, nametag) {
     return {
@@ -24950,11 +24979,13 @@ var NostrTransportProvider = class _NostrTransportProvider {
     const bindingEvent = events[0];
     try {
       const content = JSON.parse(bindingEvent.content);
+      const network = declaredNetwork(bindingEvent);
       return {
         nametag: content.nametag || void 0,
         transportPubkey: bindingEvent.pubkey,
         chainPubkey: content.public_key || "",
         directAddress: content.direct_address || "",
+        ...network !== void 0 ? { network } : {},
         timestamp: bindingEvent.created_at * 1e3
       };
     } catch {
@@ -24990,11 +25021,13 @@ var NostrTransportProvider = class _NostrTransportProvider {
     for (const [pubkey, event] of byAuthor) {
       try {
         const content = JSON.parse(event.content);
+        const network = declaredNetwork(event);
         results.push({
           nametag: content.nametag || void 0,
           transportPubkey: pubkey,
           chainPubkey: content.public_key || "",
           directAddress: content.direct_address || "",
+          ...network !== void 0 ? { network } : {},
           timestamp: event.created_at * 1e3
         });
       } catch {