@unicitylabs/sphere-sdk 0.12.0-dev.1 → 0.13.0

package/dist/impl/browser/connect/index.cjs

@@ -124,26 +124,6 @@ var logger = {
   }
 };
 
-// core/errors.ts
-var SphereError = class extends Error {
-  code;
-  cause;
-  /**
-   * #441 deferred-paid linkage: the transferId of the possibly-committed send,
-   * stamped by `sendOnce` before the error leaves so a payment-request consumer
-   * can durably journal request→transfer and resolve 'paid' only when that
-   * transfer actually completes (never optimistically). Present ONLY on
-   * possibly-committed outcomes ({@link isPossiblyCommittedSendOutcome}).
-   */
-  transferId;
-  constructor(message, code, cause) {
-    super(message);
-    this.name = "SphereError";
-    this.code = code;
-    this.cause = cause;
-  }
-};
-
 // connect/semver.ts
 function majorOf(v) {
   return parseInt(String(v).split(".")[0], 10);
@@ -342,7 +322,7 @@ var HOST_READY_TIMEOUT = 3e4;
 
 // connect/protocol.ts
 var SPHERE_CONNECT_NAMESPACE = "sphere-connect";
-var SPHERE_CONNECT_VERSION = "2.0";
+var SPHERE_CONNECT_VERSION = "2.1";
 var RPC_METHODS = {
   GET_IDENTITY: "sphere_getIdentity",
   GET_BALANCE: "sphere_getBalance",
@@ -378,6 +358,78 @@ var INTENT_ACTIONS = {
   SET_AUTO_RETURN: "set_auto_return",
   MINT: "mint"
 };
+var ERROR_CODES = {
+  // Standard JSON-RPC
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  // Sphere Connect (4xxx)
+  NOT_CONNECTED: 4001,
+  PERMISSION_DENIED: 4002,
+  USER_REJECTED: 4003,
+  SESSION_EXPIRED: 4004,
+  ORIGIN_BLOCKED: 4005,
+  RATE_LIMITED: 4006,
+  UNSUPPORTED_PROTOCOL_VERSION: 4007,
+  // Connect MAJOR mismatch (incompatible era)
+  INCOMPATIBLE_NETWORK: 4008,
+  // dApp targets a different network than the wallet
+  // Wallet locked; THE SESSION IS STILL ALIVE. A QUERY may be retried after wallet:unlocked.
+  // An INTENT already delegated to the wallet is NEVER answered with this code — it gets
+  // INTENT_OUTCOME_UNKNOWN (4201) instead, because a retry could double-spend.
+  WALLET_LOCKED: 4009,
+  INSUFFICIENT_BALANCE: 4100,
+  INVALID_RECIPIENT: 4101,
+  TRANSFER_FAILED: 4102,
+  INTENT_CANCELLED: 4200,
+  /**
+   * The intent was DELEGATED to the wallet and the host lost track of the answer — a host
+   * deadline fired, or the wallet locked / logged out mid-flight. **The outcome is UNKNOWN:
+   * the money may or may not have moved.**
+   *
+   * A dApp MUST NOT retry on this code. Reconcile out of band (poll the recipient, the
+   * aggregator, or your own backend) and only then decide.
+   *
+   * This code exists because every other answer would be a lie. `INTENT_CANCELLED` (4200)
+   * asserts the user declined and nothing happened; `WALLET_LOCKED` (4009) invites a retry
+   * after the unlock. Sending either for an intent the wallet had already submitted is how a
+   * paid-but-not-credited order — and then a double spend on retry — happens.
+   */
+  INTENT_OUTCOME_UNKNOWN: 4201
+};
+var WALLET_EVENTS = {
+  /** Wallet is LOCKED — the session is STILL ALIVE. Requests are answered
+   *  WALLET_LOCKED (4009) until `wallet:unlocked`. The dApp must NOT disconnect,
+   *  must NOT clear its sessionId, and must NOT re-handshake.
+   *  Payload: {@link WalletLockedPayload}. Pushed by ConnectHost.setLocked() and
+   *  immediately after a handshake response carrying `locked: true`. */
+  LOCKED: "wallet:locked",
+  /** Wallet was unlocked — the SAME session continues: no re-handshake, no re-approval,
+   *  no re-subscribe (the host re-arms the dApp's subscriptions before pushing this).
+   *  Payload: {@link WalletUnlockedPayload} — carries the CURRENT identity, which may
+   *  differ from the one the dApp connected with. Pushed by ConnectHost.updateSphere()
+   *  on the locked -> live edge only. */
+  UNLOCKED: "wallet:unlocked",
+  /** The session is GONE (logout, wallet deleted, dApp sphere_disconnect, expiry seen at
+   *  unlock, a different seed behind the lock screen, host destroy).
+   *  The dApp must clear its session and re-handshake to continue. Unlocking does not cure it.
+   *  Payload: {@link WalletDisconnectedPayload}. Pushed by ConnectHost.revokeSession(). */
+  DISCONNECTED: "wallet:disconnected",
+  /** Active wallet address changed. dApp should update displayed identity.
+   *  Pushed automatically by ConnectHost — no sphere_subscribe needed. */
+  IDENTITY_CHANGED: "identity:changed"
+};
+var AUTO_PUSHED_EVENTS = [
+  WALLET_EVENTS.LOCKED,
+  WALLET_EVENTS.UNLOCKED,
+  WALLET_EVENTS.DISCONNECTED,
+  WALLET_EVENTS.IDENTITY_CHANGED
+];
+function isAutoPushedEvent(event) {
+  return AUTO_PUSHED_EVENTS.includes(event);
+}
 function isSphereConnectMessage(msg) {
   if (!msg || typeof msg !== "object") return false;
   const m = msg;
@@ -394,7 +446,7 @@ function createRequestId() {
 }
 
 // connect/version.ts
-var SDK_VERSION = "0.12.0-dev.1";
+var SDK_VERSION = "0.13.0";
 
 // connect/permissions.ts
 var PERMISSION_SCOPES = {
@@ -453,6 +505,37 @@ var INTENT_PERMISSIONS = {
   [INTENT_ACTIONS.MINT]: PERMISSION_SCOPES.MINT_REQUEST
 };
 
+// connect/host/host-state.ts
+var WALLET_LOCKED_MESSAGE = "Wallet is locked";
+var NOT_CONNECTED_MESSAGE = "Not connected";
+var LOCKED_ALLOWLIST = /* @__PURE__ */ new Set([
+  RPC_METHODS.GET_IDENTITY,
+  RPC_METHODS.SUBSCRIBE,
+  RPC_METHODS.UNSUBSCRIBE,
+  RPC_METHODS.DISCONNECT
+]);
+var REFUSE_NOT_CONNECTED = {
+  kind: "refuse",
+  error: { code: ERROR_CODES.NOT_CONNECTED, message: NOT_CONNECTED_MESSAGE }
+};
+var REFUSE_LOCKED = {
+  kind: "refuse",
+  error: {
+    code: ERROR_CODES.WALLET_LOCKED,
+    message: WALLET_LOCKED_MESSAGE,
+    data: { reason: "locked" }
+  }
+};
+
+// connect/host/WalletSnapshot.ts
+var EMPTY_WALLET_SNAPSHOT = Object.freeze({ capturedAt: 0 });
+
+// connect/host/ConnectHost.ts
+var CHANNEL_ONLY_CODES = /* @__PURE__ */ new Set([
+  ERROR_CODES.WALLET_LOCKED,
+  ERROR_CODES.NOT_CONNECTED
+]);
+
 // connect/client/ConnectClient.ts
 var ConnectError = class extends Error {
   constructor(message, code, data) {
@@ -477,6 +560,8 @@ var ConnectClient = class {
   grantedPermissions = [];
   identity = null;
   walletNet = null;
+  walletProto = null;
+  locked = false;
   connected = false;
   pendingRequests = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
@@ -549,12 +634,37 @@ var ConnectClient = class {
   get walletNetwork() {
     return this.walletNet;
   }
+  /**
+   * The wallet's Connect protocol version, captured from the handshake response `v`.
+   * Null before the first handshake response and after a disconnect.
+   *
+   * Feature-detect with it: compare against '2.1' to decide whether the wallet can be
+   * trusted to send wallet:unlocked / wallet:disconnected. A Connect 2.0 wallet destroys
+   * the session on lock and never emits either, so a dApp waiting for them against one
+   * waits forever.
+   *
+   * CAVEAT: on an ERROR response the host echoes the dApp's own `v` back
+   * (ConnectHost.sendHandshakeResponse), so after a refused connection this may be the
+   * dApp's version rather than the wallet's. Only trust it after a successful handshake.
+   */
+  get walletProtocol() {
+    return this.walletProto;
+  }
+  /**
+   * Whether the wallet was locked at the last handshake or lifecycle event.
+   * A locked client is still CONNECTED: `isConnected` stays true and `session` stays valid.
+   * Requests answer WALLET_LOCKED (4009) until `wallet:unlocked` arrives on the SAME
+   * session — do not disconnect, do not clear the session, do not re-handshake.
+   */
+  get walletLocked() {
+    return this.locked;
+  }
   // ===========================================================================
   // Query (read data)
   // ===========================================================================
   /** Send a query request and return the result */
   async query(method, params) {
-    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    if (!this.connected) throw new ConnectError("Not connected", ERROR_CODES.NOT_CONNECTED);
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
@@ -564,7 +674,8 @@ var ConnectClient = class {
       this.pendingRequests.set(id, {
         resolve,
         reject,
-        timer
+        timer,
+        kind: "query"
       });
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
@@ -581,17 +692,23 @@ var ConnectClient = class {
   // ===========================================================================
   /** Send an intent request. The wallet will open its UI for user confirmation. */
   async intent(action, params) {
-    if (!this.connected) throw new SphereError("Not connected", "NOT_INITIALIZED");
+    if (!this.connected) throw new ConnectError("Not connected", ERROR_CODES.NOT_CONNECTED);
     const id = createRequestId();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pendingRequests.delete(id);
-        reject(new Error(`Intent timeout: ${action}`));
+        reject(
+          new ConnectError(
+            `Intent outcome unknown \u2014 do not retry; reconcile before acting: ${action}`,
+            ERROR_CODES.INTENT_OUTCOME_UNKNOWN
+          )
+        );
       }, this.intentTimeout);
       this.pendingRequests.set(id, {
         resolve,
         reject,
-        timer
+        timer,
+        kind: "intent"
       });
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
@@ -610,7 +727,7 @@ var ConnectClient = class {
   on(event, handler) {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, /* @__PURE__ */ new Set());
-      if (this.connected) {
+      if (this.connected && !isAutoPushedEvent(event)) {
         this.query(RPC_METHODS.SUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event subscription failed", err));
       }
     }
@@ -621,7 +738,7 @@ var ConnectClient = class {
         handlers.delete(handler);
         if (handlers.size === 0) {
           this.eventHandlers.delete(event);
-          if (this.connected) {
+          if (this.connected && !isAutoPushedEvent(event)) {
             this.query(RPC_METHODS.UNSUBSCRIBE, { event }).catch((err) => logger.debug("Connect", "Event unsubscription failed", err));
           }
         }
@@ -645,15 +762,36 @@ var ConnectClient = class {
       return;
     }
     if (msg.type === "event") {
-      const handlers = this.eventHandlers.get(msg.event);
-      if (handlers) {
-        for (const handler of handlers) {
-          try {
-            handler(msg.data);
-          } catch (err) {
-            logger.debug("Connect", "Event handler error", err);
-          }
-        }
+      if (!this.connected || !this.sessionId) {
+        logger.warn("Connect", `Ignoring wallet event before a session exists: ${msg.event}`);
+        return;
+      }
+      if (msg.event === WALLET_EVENTS.LOCKED) {
+        this.locked = true;
+      } else if (msg.event === WALLET_EVENTS.UNLOCKED) {
+        this.locked = false;
+        const identity = msg.data?.identity;
+        if (identity) this.identity = identity;
+      } else if (msg.event === WALLET_EVENTS.DISCONNECTED) {
+        this.connected = false;
+      } else if (msg.event === WALLET_EVENTS.IDENTITY_CHANGED) {
+        const data = msg.data;
+        if (data && typeof data.chainPubkey === "string") this.identity = data;
+      }
+      this.dispatchEvent(msg.event, msg.data);
+      if (msg.event === WALLET_EVENTS.DISCONNECTED) {
+        this.cleanup();
+      }
+    }
+  }
+  dispatchEvent(event, data) {
+    const handlers = this.eventHandlers.get(event);
+    if (!handlers) return;
+    for (const handler of handlers) {
+      try {
+        handler(data);
+      } catch (err) {
+        logger.debug("Connect", "Event handler error", err);
       }
     }
   }
@@ -661,6 +799,7 @@ var ConnectClient = class {
     if (!this.handshakeResolver) return;
     clearTimeout(this.handshakeResolver.timer);
     const m = msg;
+    this.walletProto = msg.v ?? null;
     if (m.error) {
       this.handshakeResolver.reject(new ConnectError(m.error.message, m.error.code, m.error.data));
       this.handshakeResolver = null;
@@ -671,12 +810,16 @@ var ConnectClient = class {
       this.grantedPermissions = msg.permissions;
       this.identity = msg.identity;
       this.walletNet = m.network ?? null;
+      this.locked = m.locked === true;
       this.connected = true;
       if (m.warning) logger.warn("Connect", "Wallet deprecation notice", m.warning.message);
       this.handshakeResolver.resolve({
         sessionId: msg.sessionId,
         permissions: this.grantedPermissions,
-        identity: msg.identity
+        identity: msg.identity,
+        // A resume DURING a lock succeeds: the dApp is connected on the same session and
+        // must not re-handshake. It will get wallet:unlocked when the user unlocks.
+        ...this.locked ? { locked: true } : {}
       });
     } else {
       this.handshakeResolver.reject(new Error("Connection rejected by wallet"));
@@ -702,9 +845,19 @@ var ConnectClient = class {
       this.unsubscribeTransport();
       this.unsubscribeTransport = null;
     }
+    if (this.handshakeResolver) {
+      clearTimeout(this.handshakeResolver.timer);
+      this.handshakeResolver.reject(new ConnectError("Disconnected", ERROR_CODES.NOT_CONNECTED));
+      this.handshakeResolver = null;
+    }
     for (const [, pending] of this.pendingRequests) {
       clearTimeout(pending.timer);
-      pending.reject(new Error("Disconnected"));
+      pending.reject(
+        pending.kind === "intent" ? new ConnectError(
+          "Intent outcome unknown \u2014 do not retry; reconcile before acting",
+          ERROR_CODES.INTENT_OUTCOME_UNKNOWN
+        ) : new ConnectError("Disconnected", ERROR_CODES.NOT_CONNECTED)
+      );
     }
     this.pendingRequests.clear();
     this.eventHandlers.clear();
@@ -713,11 +866,21 @@ var ConnectClient = class {
     this.grantedPermissions = [];
     this.identity = null;
     this.walletNet = null;
+    this.walletProto = null;
+    this.locked = false;
   }
 };
 
 // impl/browser/connect/PostMessageTransport.ts
 var POPUP_CLOSE_CHECK_INTERVAL = 1e3;
+function originOf(targetOrigin) {
+  if (targetOrigin === "*") return null;
+  try {
+    return [new URL(targetOrigin).origin];
+  } catch {
+    return null;
+  }
+}
 var PostMessageTransport = class _PostMessageTransport {
   targetWindow;
   targetOrigin;
@@ -731,6 +894,9 @@ var PostMessageTransport = class _PostMessageTransport {
     this.targetOrigin = targetOrigin;
     this.allowedOrigins = allowedOrigins ? new Set(allowedOrigins) : null;
     this.listener = (event) => {
+      if (event.source && event.source !== this.targetWindow) {
+        return;
+      }
       if (this.allowedOrigins && !this.allowedOrigins.has("*") && !this.allowedOrigins.has(event.origin)) {
         return;
       }
@@ -769,7 +935,8 @@ var PostMessageTransport = class _PostMessageTransport {
   static forClient(options) {
     const target = options?.target ?? window.parent;
     const targetOrigin = options?.targetOrigin ?? "*";
-    const transport = new _PostMessageTransport(target, targetOrigin, null);
+    const allowedOrigins = originOf(targetOrigin);
+    const transport = new _PostMessageTransport(target, targetOrigin, allowedOrigins);
     if (options?.target && options.target !== window.parent) {
       transport.startPopupCloseDetection(options.target);
     }