@unicitylabs/sphere-sdk 0.12.0 → 0.13.0

package/dist/impl/browser/connect/index.d.cts

@@ -14,7 +14,7 @@ interface NetworkInfo {
  * JSON-RPC-like message types for wallet ↔ dApp communication.
  */
 declare const SPHERE_CONNECT_NAMESPACE = "sphere-connect";
-declare const SPHERE_CONNECT_VERSION = "2.0";
+declare const SPHERE_CONNECT_VERSION = "2.1";
 
 interface SphereMessageBase {
     readonly ns: typeof SPHERE_CONNECT_NAMESPACE;
@@ -72,6 +72,11 @@ interface SphereHandshake extends SphereMessageBase {
     readonly error?: SphereRpcError;
     /** Response: non-fatal deprecation notice (does not block the connection). */
     readonly warning?: SphereRpcError;
+    /** Response only: the wallet is LOCKED and the session is ALIVE. The dApp is connected
+     *  and must not re-handshake; it will receive `wallet:unlocked` on the same session.
+     *  Additive and safe for old clients: handleHandshakeResponse reads only sessionId,
+     *  permissions, identity, network, warning and error and ignores unknown fields. */
+    readonly locked?: boolean;
 }
 interface SphereRpcError {
     readonly code: number;
@@ -152,6 +157,9 @@ interface ConnectResult {
     readonly sessionId: string;
     readonly permissions: PermissionScope[];
     readonly identity: PublicIdentity;
+    /** True when the wallet is locked but the session is alive — a resume during a lock,
+     *  the most common entry into this feature. Requests answer 4009 until wallet:unlocked. */
+    readonly locked?: boolean;
 }
 type ConnectEventHandler = (data: unknown) => void;
 
@@ -178,6 +186,8 @@ declare class ConnectClient {
     private grantedPermissions;
     private identity;
     private walletNet;
+    private walletProto;
+    private locked;
     private connected;
     private pendingRequests;
     private eventHandlers;
@@ -198,6 +208,27 @@ declare class ConnectClient {
     get walletIdentity(): PublicIdentity | null;
     /** Wallet's active network, received during handshake. */
     get walletNetwork(): NetworkInfo | null;
+    /**
+     * 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(): string | null;
+    /**
+     * 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(): boolean;
     /** Send a query request and return the result */
     query<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     /** Send an intent request. The wallet will open its UI for user confirmation. */
@@ -205,6 +236,7 @@ declare class ConnectClient {
     /** Subscribe to a wallet event. Returns unsubscribe function. */
     on(event: string, handler: ConnectEventHandler): () => void;
     private handleMessage;
+    private dispatchEvent;
     private handleHandshakeResponse;
     private handlePendingResponse;
     private cleanup;

package/dist/impl/browser/connect/index.d.ts

@@ -14,7 +14,7 @@ interface NetworkInfo {
  * JSON-RPC-like message types for wallet ↔ dApp communication.
  */
 declare const SPHERE_CONNECT_NAMESPACE = "sphere-connect";
-declare const SPHERE_CONNECT_VERSION = "2.0";
+declare const SPHERE_CONNECT_VERSION = "2.1";
 
 interface SphereMessageBase {
     readonly ns: typeof SPHERE_CONNECT_NAMESPACE;
@@ -72,6 +72,11 @@ interface SphereHandshake extends SphereMessageBase {
     readonly error?: SphereRpcError;
     /** Response: non-fatal deprecation notice (does not block the connection). */
     readonly warning?: SphereRpcError;
+    /** Response only: the wallet is LOCKED and the session is ALIVE. The dApp is connected
+     *  and must not re-handshake; it will receive `wallet:unlocked` on the same session.
+     *  Additive and safe for old clients: handleHandshakeResponse reads only sessionId,
+     *  permissions, identity, network, warning and error and ignores unknown fields. */
+    readonly locked?: boolean;
 }
 interface SphereRpcError {
     readonly code: number;
@@ -152,6 +157,9 @@ interface ConnectResult {
     readonly sessionId: string;
     readonly permissions: PermissionScope[];
     readonly identity: PublicIdentity;
+    /** True when the wallet is locked but the session is alive — a resume during a lock,
+     *  the most common entry into this feature. Requests answer 4009 until wallet:unlocked. */
+    readonly locked?: boolean;
 }
 type ConnectEventHandler = (data: unknown) => void;
 
@@ -178,6 +186,8 @@ declare class ConnectClient {
     private grantedPermissions;
     private identity;
     private walletNet;
+    private walletProto;
+    private locked;
     private connected;
     private pendingRequests;
     private eventHandlers;
@@ -198,6 +208,27 @@ declare class ConnectClient {
     get walletIdentity(): PublicIdentity | null;
     /** Wallet's active network, received during handshake. */
     get walletNetwork(): NetworkInfo | null;
+    /**
+     * 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(): string | null;
+    /**
+     * 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(): boolean;
     /** Send a query request and return the result */
     query<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
     /** Send an intent request. The wallet will open its UI for user confirmation. */
@@ -205,6 +236,7 @@ declare class ConnectClient {
     /** Subscribe to a wallet event. Returns unsubscribe function. */
     on(event: string, handler: ConnectEventHandler): () => void;
     private handleMessage;
+    private dispatchEvent;
     private handleHandshakeResponse;
     private handlePendingResponse;
     private cleanup;

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

@@ -90,26 +90,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);
@@ -308,7 +288,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",
@@ -344,6 +324,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;
@@ -360,7 +412,7 @@ function createRequestId() {
 }
 
 // connect/version.ts
-var SDK_VERSION = "0.12.0";
+var SDK_VERSION = "0.13.0";
 
 // connect/permissions.ts
 var PERMISSION_SCOPES = {
@@ -419,6 +471,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) {
@@ -443,6 +526,8 @@ var ConnectClient = class {
   grantedPermissions = [];
   identity = null;
   walletNet = null;
+  walletProto = null;
+  locked = false;
   connected = false;
   pendingRequests = /* @__PURE__ */ new Map();
   eventHandlers = /* @__PURE__ */ new Map();
@@ -515,12 +600,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(() => {
@@ -530,7 +640,8 @@ var ConnectClient = class {
       this.pendingRequests.set(id, {
         resolve,
         reject,
-        timer
+        timer,
+        kind: "query"
       });
       this.transport.send({
         ns: SPHERE_CONNECT_NAMESPACE,
@@ -547,17 +658,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,
@@ -576,7 +693,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));
       }
     }
@@ -587,7 +704,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));
           }
         }
@@ -611,15 +728,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);
       }
     }
   }
@@ -627,6 +765,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;
@@ -637,12 +776,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"));
@@ -668,9 +811,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();
@@ -679,11 +832,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;
@@ -697,6 +860,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;
       }
@@ -735,7 +901,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);
     }