@gvnrdao/dh-sdk 0.0.309 → 0.0.312

package/dist/index.d.ts

@@ -35,6 +35,8 @@ export type { BitcoinOperationsConfig, BitcoinNetwork, EnrichedBitcoinBalance, }
 export type { SupportedStablecoinData } from './graphs/diamond-hands';
 export { validateSDKConfig, validateServiceModeConfig, validateStandaloneModeConfig, isServiceModeConfig, isStandaloneModeConfig, } from './interfaces/chunks/config.i';
 export { assertSafeServiceEndpoint } from './utils/service-endpoint-policy';
+export { buildLoginDomain, buildSignedLoginPayload, LOGIN_TYPES, LOGIN_TYPES_WITH_AUDIENCE, } from './utils/eip712-login';
+export type { DhServerLoginMessage, DhServerLoginPayload, } from './utils/eip712-login';
 export { DEFAULT_LIT_NETWORK, VALID_LIT_NETWORKS, SDK_DEFAULTS, } from './constants/chunks/sdk-config';
 export { ALL_CONTRACTS, ALL_DEPLOYMENTS, getContractsByNetwork, getDeploymentByNetwork, LOCALHOST_CONTRACTS, SEPOLIA_CONTRACTS, } from './constants/chunks/deployment-addresses';
 export type { DeploymentContracts, DeploymentData, DeploymentLatestEnv, } from './constants/chunks/deployment-addresses';

package/dist/index.js

@@ -5574,6 +5574,8 @@ __export(src_exports, {
   ErrorSeverity: () => ErrorSeverity,
   EventHelpers: () => EventHelpers,
   LOCALHOST_CONTRACTS: () => LOCALHOST_CONTRACTS,
+  LOGIN_TYPES: () => LOGIN_TYPES,
+  LOGIN_TYPES_WITH_AUDIENCE: () => LOGIN_TYPES_WITH_AUDIENCE,
   LRUCache: () => LRUCache,
   LoanCreator: () => LoanCreator,
   LoanQuery: () => LoanQuery,
@@ -5596,6 +5598,8 @@ __export(src_exports, {
   buildBtcExecuteEnvelope: () => buildBtcExecuteEnvelope,
   buildInvalidateMessageHash: () => buildInvalidateMessageHash,
   buildInvalidateStaleSpendEnvelope: () => buildInvalidateStaleSpendEnvelope,
+  buildLoginDomain: () => buildLoginDomain,
+  buildSignedLoginPayload: () => buildSignedLoginPayload,
   collectFailures: () => collectFailures,
   collectSuccesses: () => collectSuccesses,
   combine: () => combine,
@@ -6527,12 +6531,12 @@ var LOGIN_TYPES_WITH_AUDIENCE = {
     { name: "audience", type: "string" }
   ]
 };
-async function buildSignedLoginPayload(signer, chainId, audience) {
+async function buildSignedLoginPayload(signer, chainId, audience, reuse) {
   const address = await signer.getAddress();
   const message = {
     address,
-    issuedAt: Math.floor(Date.now() / 1e3),
-    nonce: (0, import_ethers4.hexlify)((0, import_ethers4.randomBytes)(32)),
+    issuedAt: reuse?.issuedAt ?? Math.floor(Date.now() / 1e3),
+    nonce: reuse?.nonce ?? (0, import_ethers4.hexlify)((0, import_ethers4.randomBytes)(32)),
     ...audience ? { audience } : {}
   };
   const signature = await signer.signTypedData(
@@ -6550,6 +6554,13 @@ var STORE_PREFIX = "dh-server-session:";
 function sessionStoreKey(address, chainId, endpoint) {
   return STORE_PREFIX + `${address.trim().toLowerCase()}:${chainId}:${endpoint.replace(/\/+$/, "")}`;
 }
+var PENDING_ENVELOPE_TTL_SECONDS = 8 * 60;
+function pendingEnvelopeKey(sessionKey) {
+  return sessionKey + ":pending";
+}
+function isPendingEnvelopeShape(value) {
+  return !!value && typeof value === "object" && typeof value.issuedAt === "number" && typeof value.nonce === "string";
+}
 function isPayloadShape(value) {
   return !!value && typeof value === "object" && typeof value.chainId === "number" && typeof value.signature === "string" && !!value.message && typeof value.message.address === "string" && typeof value.message.issuedAt === "number" && typeof value.message.nonce === "string";
 }
@@ -6591,9 +6602,48 @@ var LocalStorageSessionStore = class {
     } catch {
     }
   }
+  loadPending(key) {
+    let raw;
+    try {
+      raw = window.localStorage.getItem(pendingEnvelopeKey(key));
+    } catch {
+      return null;
+    }
+    if (!raw)
+      return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      this.clearPending(key);
+      return null;
+    }
+    const nowSec = Math.floor(Date.now() / 1e3);
+    if (!isPendingEnvelopeShape(parsed) || nowSec >= parsed.issuedAt + PENDING_ENVELOPE_TTL_SECONDS) {
+      this.clearPending(key);
+      return null;
+    }
+    return parsed;
+  }
+  savePending(key, envelope) {
+    try {
+      window.localStorage.setItem(
+        pendingEnvelopeKey(key),
+        JSON.stringify(envelope)
+      );
+    } catch {
+    }
+  }
+  clearPending(key) {
+    try {
+      window.localStorage.removeItem(pendingEnvelopeKey(key));
+    } catch {
+    }
+  }
 };
 var MemorySessionStore = class {
   entries = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
   load(key) {
     return this.entries.get(key) ?? null;
   }
@@ -6603,6 +6653,23 @@ var MemorySessionStore = class {
   clear(key) {
     this.entries.delete(key);
   }
+  loadPending(key) {
+    const envelope = this.pending.get(key);
+    if (!envelope)
+      return null;
+    const nowSec = Math.floor(Date.now() / 1e3);
+    if (nowSec >= envelope.issuedAt + PENDING_ENVELOPE_TTL_SECONDS) {
+      this.pending.delete(key);
+      return null;
+    }
+    return envelope;
+  }
+  savePending(key, envelope) {
+    this.pending.set(key, envelope);
+  }
+  clearPending(key) {
+    this.pending.delete(key);
+  }
 };
 function localStorageUsable() {
   try {
@@ -6637,9 +6704,11 @@ function isLoginRejection(error) {
 var ServerSession = class {
   signer;
   serviceEndpoint;
+  loginAudience;
   chainId;
   store;
   onSignaturePrompt;
+  onSignatureResolved;
   now;
   fetchImpl;
   cached = null;
@@ -6666,9 +6735,14 @@ var ServerSession = class {
     assertSafeServiceEndpoint(opts.serviceEndpoint);
     this.signer = opts.signer;
     this.serviceEndpoint = opts.serviceEndpoint.replace(/\/+$/, "");
+    this.loginAudience = (opts.loginAudience ?? this.serviceEndpoint).replace(
+      /\/+$/,
+      ""
+    );
     this.chainId = opts.chainId;
     this.store = opts.persistSession === false ? null : opts.sessionStore ?? createDefaultSessionStore();
     this.onSignaturePrompt = opts.onSignaturePrompt;
+    this.onSignatureResolved = opts.onSignatureResolved;
     this.now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
     this.fetchImpl = opts.fetchImpl ?? ((...a) => fetch(...a));
   }
@@ -6764,6 +6838,53 @@ var ServerSession = class {
       );
     }
   }
+  /**
+   * Adopt a login envelope signed ELSEWHERE and exchange it for a session now.
+   *
+   * The browser frontend collects one wallet signature and spends it at both the
+   * api and this service, so the envelope is minted outside the SDK. Without this
+   * seam the SDK would mint its own — a second wallet prompt, which for a
+   * multi-sig Safe is another full propose-and-confirm ceremony across owners.
+   *
+   * Must be called PROMPTLY after signing. Each server pins the nonce on FIRST
+   * use and requires that first use to be fresh (±120s EOA, ±600s contract
+   * wallet); the stores are independent, so a late hand-off is rejected as
+   * `stale_first_use` even though the other service already accepted it. After a
+   * successful first use, silent re-mint covers the next 24h.
+   *
+   * No-ops the prompt path entirely: on success the session is cached and
+   * persisted exactly as a self-minted login would be.
+   */
+  adoptLoginPayload(payload) {
+    const gen = this.generation;
+    const notCleared = () => gen === this.generation;
+    const attempt = (async () => {
+      if (payload?.chainId !== this.chainId) {
+        throw new Error(
+          `ServerSession: cannot adopt a login for chain ${payload?.chainId} \u2014 this session is on ${this.chainId}`
+        );
+      }
+      const payloadAddress = payload.message?.address?.toLowerCase();
+      const signerAddress = (await this.signer.getAddress()).toLowerCase();
+      if (!payloadAddress || payloadAddress !== signerAddress) {
+        throw new Error(
+          "ServerSession: cannot adopt a login signed by a different address"
+        );
+      }
+      const session = await this.login(payload);
+      if (notCleared()) {
+        this.persist(payload, session);
+        this.cached = session;
+        this.promptBackoff = null;
+      }
+      return session;
+    })();
+    this.inFlight = attempt;
+    return attempt.then(() => void 0).finally(() => {
+      if (notCleared())
+        this.inFlight = null;
+    });
+  }
   /**
    * Resolve a session WITHOUT ever prompting for a wallet signature: a live
    * cached token, else the persisted JWT (adopted if still fresh, otherwise
@@ -6830,17 +6951,31 @@ var ServerSession = class {
         this.onSignaturePrompt?.();
         let session;
         try {
+          const store = this.store;
+          const storeKey = store ? this.lastStoreKey : null;
+          const reuse = storeKey ? store.loadPending?.(storeKey) ?? void 0 : void 0;
           const payload = await buildSignedLoginPayload(
             this.signer,
             this.chainId,
-            this.serviceEndpoint
+            this.loginAudience,
+            reuse
           );
+          if (storeKey && !reuse) {
+            store.savePending?.(storeKey, {
+              issuedAt: payload.message.issuedAt,
+              nonce: payload.message.nonce
+            });
+          }
           session = await this.login(payload);
           if (notCleared()) {
             this.persist(payload, session);
             this.cached = session;
           }
+          if (storeKey)
+            store.clearPending?.(storeKey);
+          this.onSignatureResolved?.(true);
         } catch (error) {
+          this.onSignatureResolved?.(false);
           const failures = (this.promptBackoff?.failures ?? 0) + 1;
           this.promptBackoff = {
             failures,
@@ -16466,6 +16601,32 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       await this.serverSession.clearPersisted();
     }
   }
+  /**
+   * Establish the lit-ops-server session from a login envelope the CALLER already
+   * had signed, instead of prompting the wallet for one.
+   *
+   * For a host that authenticates several services from one wallet signature (the
+   * browser frontend signs once and spends the same envelope at the api and here),
+   * this is what turns two wallet prompts into one — and for a multi-sig Safe each
+   * prompt saved is a whole propose-and-confirm ceremony across owners.
+   *
+   * Call it PROMPTLY after signing: each server pins the nonce on first use and
+   * requires that first use to be fresh (±120s EOA, ±600s contract wallet), and
+   * the two servers' replay stores are independent, so a late hand-off is rejected
+   * as stale even though the other service already accepted the same envelope.
+   * Once accepted, silent re-mint covers the next 24h with no further prompts.
+   *
+   * Requires `loginAudience` to be configured to a value BOTH servers accept —
+   * otherwise this service rejects the envelope as `audience_mismatch`.
+   *
+   * Throws if the exchange fails, so a caller can fall back to the prompt path.
+   * No-op in standalone mode (no server session to prime).
+   */
+  async primeServerSession(payload) {
+    if (!this.serverSession)
+      return;
+    await this.serverSession.adoptLoginPayload(payload);
+  }
   /**
    * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
    * the post-write state. We clear the entire loan-query cache (not just
@@ -16577,10 +16738,12 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       this.serverSession = new ServerSession({
         signer: config.authSigner ?? config.contractSigner,
         serviceEndpoint: config.serviceEndpoint,
+        loginAudience: config.loginAudience,
         chainId: config.chainId,
         persistSession: config.sessionPersistence?.enabled,
         sessionStore: config.sessionPersistence?.store,
-        onSignaturePrompt: config.onSessionSignaturePrompt
+        onSignaturePrompt: config.onSessionSignaturePrompt,
+        onSignatureResolved: config.onSessionSignatureResolved
       });
     }
     const contractManagerResult = createContractManager({
@@ -23786,6 +23949,8 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   ErrorSeverity,
   EventHelpers,
   LOCALHOST_CONTRACTS,
+  LOGIN_TYPES,
+  LOGIN_TYPES_WITH_AUDIENCE,
   LRUCache,
   LoanCreator,
   LoanQuery,
@@ -23808,6 +23973,8 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   buildBtcExecuteEnvelope,
   buildInvalidateMessageHash,
   buildInvalidateStaleSpendEnvelope,
+  buildLoginDomain,
+  buildSignedLoginPayload,
   collectFailures,
   collectSuccesses,
   combine,

package/dist/index.mjs

@@ -6446,12 +6446,12 @@ var LOGIN_TYPES_WITH_AUDIENCE = {
     { name: "audience", type: "string" }
   ]
 };
-async function buildSignedLoginPayload(signer, chainId, audience) {
+async function buildSignedLoginPayload(signer, chainId, audience, reuse) {
   const address = await signer.getAddress();
   const message = {
     address,
-    issuedAt: Math.floor(Date.now() / 1e3),
-    nonce: hexlify(randomBytes(32)),
+    issuedAt: reuse?.issuedAt ?? Math.floor(Date.now() / 1e3),
+    nonce: reuse?.nonce ?? hexlify(randomBytes(32)),
     ...audience ? { audience } : {}
   };
   const signature = await signer.signTypedData(
@@ -6469,6 +6469,13 @@ var STORE_PREFIX = "dh-server-session:";
 function sessionStoreKey(address, chainId, endpoint) {
   return STORE_PREFIX + `${address.trim().toLowerCase()}:${chainId}:${endpoint.replace(/\/+$/, "")}`;
 }
+var PENDING_ENVELOPE_TTL_SECONDS = 8 * 60;
+function pendingEnvelopeKey(sessionKey) {
+  return sessionKey + ":pending";
+}
+function isPendingEnvelopeShape(value) {
+  return !!value && typeof value === "object" && typeof value.issuedAt === "number" && typeof value.nonce === "string";
+}
 function isPayloadShape(value) {
   return !!value && typeof value === "object" && typeof value.chainId === "number" && typeof value.signature === "string" && !!value.message && typeof value.message.address === "string" && typeof value.message.issuedAt === "number" && typeof value.message.nonce === "string";
 }
@@ -6510,9 +6517,48 @@ var LocalStorageSessionStore = class {
     } catch {
     }
   }
+  loadPending(key) {
+    let raw;
+    try {
+      raw = window.localStorage.getItem(pendingEnvelopeKey(key));
+    } catch {
+      return null;
+    }
+    if (!raw)
+      return null;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      this.clearPending(key);
+      return null;
+    }
+    const nowSec = Math.floor(Date.now() / 1e3);
+    if (!isPendingEnvelopeShape(parsed) || nowSec >= parsed.issuedAt + PENDING_ENVELOPE_TTL_SECONDS) {
+      this.clearPending(key);
+      return null;
+    }
+    return parsed;
+  }
+  savePending(key, envelope) {
+    try {
+      window.localStorage.setItem(
+        pendingEnvelopeKey(key),
+        JSON.stringify(envelope)
+      );
+    } catch {
+    }
+  }
+  clearPending(key) {
+    try {
+      window.localStorage.removeItem(pendingEnvelopeKey(key));
+    } catch {
+    }
+  }
 };
 var MemorySessionStore = class {
   entries = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Map();
   load(key) {
     return this.entries.get(key) ?? null;
   }
@@ -6522,6 +6568,23 @@ var MemorySessionStore = class {
   clear(key) {
     this.entries.delete(key);
   }
+  loadPending(key) {
+    const envelope = this.pending.get(key);
+    if (!envelope)
+      return null;
+    const nowSec = Math.floor(Date.now() / 1e3);
+    if (nowSec >= envelope.issuedAt + PENDING_ENVELOPE_TTL_SECONDS) {
+      this.pending.delete(key);
+      return null;
+    }
+    return envelope;
+  }
+  savePending(key, envelope) {
+    this.pending.set(key, envelope);
+  }
+  clearPending(key) {
+    this.pending.delete(key);
+  }
 };
 function localStorageUsable() {
   try {
@@ -6556,9 +6619,11 @@ function isLoginRejection(error) {
 var ServerSession = class {
   signer;
   serviceEndpoint;
+  loginAudience;
   chainId;
   store;
   onSignaturePrompt;
+  onSignatureResolved;
   now;
   fetchImpl;
   cached = null;
@@ -6585,9 +6650,14 @@ var ServerSession = class {
     assertSafeServiceEndpoint(opts.serviceEndpoint);
     this.signer = opts.signer;
     this.serviceEndpoint = opts.serviceEndpoint.replace(/\/+$/, "");
+    this.loginAudience = (opts.loginAudience ?? this.serviceEndpoint).replace(
+      /\/+$/,
+      ""
+    );
     this.chainId = opts.chainId;
     this.store = opts.persistSession === false ? null : opts.sessionStore ?? createDefaultSessionStore();
     this.onSignaturePrompt = opts.onSignaturePrompt;
+    this.onSignatureResolved = opts.onSignatureResolved;
     this.now = opts.now ?? (() => Math.floor(Date.now() / 1e3));
     this.fetchImpl = opts.fetchImpl ?? ((...a) => fetch(...a));
   }
@@ -6683,6 +6753,53 @@ var ServerSession = class {
       );
     }
   }
+  /**
+   * Adopt a login envelope signed ELSEWHERE and exchange it for a session now.
+   *
+   * The browser frontend collects one wallet signature and spends it at both the
+   * api and this service, so the envelope is minted outside the SDK. Without this
+   * seam the SDK would mint its own — a second wallet prompt, which for a
+   * multi-sig Safe is another full propose-and-confirm ceremony across owners.
+   *
+   * Must be called PROMPTLY after signing. Each server pins the nonce on FIRST
+   * use and requires that first use to be fresh (±120s EOA, ±600s contract
+   * wallet); the stores are independent, so a late hand-off is rejected as
+   * `stale_first_use` even though the other service already accepted it. After a
+   * successful first use, silent re-mint covers the next 24h.
+   *
+   * No-ops the prompt path entirely: on success the session is cached and
+   * persisted exactly as a self-minted login would be.
+   */
+  adoptLoginPayload(payload) {
+    const gen = this.generation;
+    const notCleared = () => gen === this.generation;
+    const attempt = (async () => {
+      if (payload?.chainId !== this.chainId) {
+        throw new Error(
+          `ServerSession: cannot adopt a login for chain ${payload?.chainId} \u2014 this session is on ${this.chainId}`
+        );
+      }
+      const payloadAddress = payload.message?.address?.toLowerCase();
+      const signerAddress = (await this.signer.getAddress()).toLowerCase();
+      if (!payloadAddress || payloadAddress !== signerAddress) {
+        throw new Error(
+          "ServerSession: cannot adopt a login signed by a different address"
+        );
+      }
+      const session = await this.login(payload);
+      if (notCleared()) {
+        this.persist(payload, session);
+        this.cached = session;
+        this.promptBackoff = null;
+      }
+      return session;
+    })();
+    this.inFlight = attempt;
+    return attempt.then(() => void 0).finally(() => {
+      if (notCleared())
+        this.inFlight = null;
+    });
+  }
   /**
    * Resolve a session WITHOUT ever prompting for a wallet signature: a live
    * cached token, else the persisted JWT (adopted if still fresh, otherwise
@@ -6749,17 +6866,31 @@ var ServerSession = class {
         this.onSignaturePrompt?.();
         let session;
         try {
+          const store = this.store;
+          const storeKey = store ? this.lastStoreKey : null;
+          const reuse = storeKey ? store.loadPending?.(storeKey) ?? void 0 : void 0;
           const payload = await buildSignedLoginPayload(
             this.signer,
             this.chainId,
-            this.serviceEndpoint
+            this.loginAudience,
+            reuse
           );
+          if (storeKey && !reuse) {
+            store.savePending?.(storeKey, {
+              issuedAt: payload.message.issuedAt,
+              nonce: payload.message.nonce
+            });
+          }
           session = await this.login(payload);
           if (notCleared()) {
             this.persist(payload, session);
             this.cached = session;
           }
+          if (storeKey)
+            store.clearPending?.(storeKey);
+          this.onSignatureResolved?.(true);
         } catch (error) {
+          this.onSignatureResolved?.(false);
           const failures = (this.promptBackoff?.failures ?? 0) + 1;
           this.promptBackoff = {
             failures,
@@ -16395,6 +16526,32 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       await this.serverSession.clearPersisted();
     }
   }
+  /**
+   * Establish the lit-ops-server session from a login envelope the CALLER already
+   * had signed, instead of prompting the wallet for one.
+   *
+   * For a host that authenticates several services from one wallet signature (the
+   * browser frontend signs once and spends the same envelope at the api and here),
+   * this is what turns two wallet prompts into one — and for a multi-sig Safe each
+   * prompt saved is a whole propose-and-confirm ceremony across owners.
+   *
+   * Call it PROMPTLY after signing: each server pins the nonce on first use and
+   * requires that first use to be fresh (±120s EOA, ±600s contract wallet), and
+   * the two servers' replay stores are independent, so a late hand-off is rejected
+   * as stale even though the other service already accepted the same envelope.
+   * Once accepted, silent re-mint covers the next 24h with no further prompts.
+   *
+   * Requires `loginAudience` to be configured to a value BOTH servers accept —
+   * otherwise this service rejects the envelope as `audience_mismatch`.
+   *
+   * Throws if the exchange fails, so a caller can fall back to the prompt path.
+   * No-op in standalone mode (no server session to prime).
+   */
+  async primeServerSession(payload) {
+    if (!this.serverSession)
+      return;
+    await this.serverSession.adoptLoginPayload(payload);
+  }
   /**
    * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
    * the post-write state. We clear the entire loan-query cache (not just
@@ -16506,10 +16663,12 @@ var DiamondHandsSDK = class _DiamondHandsSDK {
       this.serverSession = new ServerSession({
         signer: config.authSigner ?? config.contractSigner,
         serviceEndpoint: config.serviceEndpoint,
+        loginAudience: config.loginAudience,
         chainId: config.chainId,
         persistSession: config.sessionPersistence?.enabled,
         sessionStore: config.sessionPersistence?.store,
-        onSignaturePrompt: config.onSessionSignaturePrompt
+        onSignaturePrompt: config.onSessionSignaturePrompt,
+        onSignatureResolved: config.onSessionSignatureResolved
       });
     }
     const contractManagerResult = createContractManager({
@@ -23714,6 +23873,8 @@ export {
   ErrorSeverity,
   EventHelpers,
   LOCALHOST_CONTRACTS,
+  LOGIN_TYPES,
+  LOGIN_TYPES_WITH_AUDIENCE,
   LRUCache,
   LoanCreator,
   LoanQuery,
@@ -23736,6 +23897,8 @@ export {
   buildBtcExecuteEnvelope,
   buildInvalidateMessageHash,
   buildInvalidateStaleSpendEnvelope,
+  buildLoginDomain,
+  buildSignedLoginPayload,
   collectFailures,
   collectSuccesses,
   combine,

package/dist/interfaces/chunks/config.i.d.ts

@@ -71,12 +71,33 @@ interface BaseSDKConfig {
         /** Custom store (e.g. a file-backed store for CLI daemons). */
         store?: ServerSessionStore;
     };
+    /**
+     * Audit M-8 audience the server-session login binds to. Defaults to
+     * `serviceEndpoint`.
+     *
+     * Set this only when ONE signature must authenticate several services — the
+     * browser frontend signs a single envelope and spends it at both
+     * lit-ops-server and the api, and a per-endpoint audience cannot name two
+     * endpoints. Every server the envelope is presented to must list this value as
+     * an accepted audience, so changing it requires a server-side config change
+     * FIRST. Node callers (CLI, MCP, cr-monitor) omit it and keep binding to the
+     * endpoint they call.
+     */
+    loginAudience?: string;
     /**
      * Fires immediately before the server-session login requests a wallet
      * signature — never on the silent re-mint paths. Lets UIs show a
      * "check your wallet" prompt.
      */
     onSessionSignaturePrompt?: () => void;
+    /**
+     * Fires once that signature request has concluded — `true` when a session was
+     * established, `false` when it failed or was rejected. Pairs with
+     * `onSessionSignaturePrompt`, which otherwise has no ending: a UI that shows
+     * "check your wallet" on the prompt has no way to stop showing it, and a
+     * contract wallet can leave that request open for minutes.
+     */
+    onSessionSignatureResolved?: (ok: boolean) => void;
     ethRpcUrl?: string;
     chainId?: number;
     networkOverride?: {

package/dist/modules/diamond-hands-sdk.d.ts

@@ -18,6 +18,7 @@ import { SDKError } from "../utils/error-handler";
 import type { CreateLoanRequest, CreateLoanResult, LoanDataDetail, UCDMintRequest, UCDMintResult, PartialPaymentRequest, PartialPaymentResult, BTCWithdrawalResult, RenewPositionRequest, RenewPositionResult, LiquidationRequest, LiquidationResult, ConfirmBalanceRequest, ConfirmBalanceResult, TermsWithFeesResult } from "../interfaces/chunks/loan-operations.i";
 import type { DiamondHandsSDKConfig } from "../interfaces/chunks/config.i";
 import type { PKPData } from "../interfaces/chunks/pkp-integration.i";
+import type { DhServerLoginPayload } from "../utils/eip712-login";
 import { type ReconciledWithdrawal } from "../utils/withdrawal-reconciliation.utils";
 import { ContractManager } from "./contract/contract-manager.module";
 import { WithdrawalAddressModule } from "./withdrawal-address/withdrawal-address.module";
@@ -125,6 +126,28 @@ export declare class DiamondHandsSDK {
      * and never prompts the wallet.
      */
     clearServerSession(): Promise<void>;
+    /**
+     * Establish the lit-ops-server session from a login envelope the CALLER already
+     * had signed, instead of prompting the wallet for one.
+     *
+     * For a host that authenticates several services from one wallet signature (the
+     * browser frontend signs once and spends the same envelope at the api and here),
+     * this is what turns two wallet prompts into one — and for a multi-sig Safe each
+     * prompt saved is a whole propose-and-confirm ceremony across owners.
+     *
+     * Call it PROMPTLY after signing: each server pins the nonce on first use and
+     * requires that first use to be fresh (±120s EOA, ±600s contract wallet), and
+     * the two servers' replay stores are independent, so a late hand-off is rejected
+     * as stale even though the other service already accepted the same envelope.
+     * Once accepted, silent re-mint covers the next 24h with no further prompts.
+     *
+     * Requires `loginAudience` to be configured to a value BOTH servers accept —
+     * otherwise this service rejects the envelope as `audience_mismatch`.
+     *
+     * Throws if the exchange fails, so a caller can fall back to the prompt path.
+     * No-op in standalone mode (no server session to prime).
+     */
+    primeServerSession(payload: DhServerLoginPayload): Promise<void>;
     /**
      * Audit H-9: invalidate the LoanQuery cache so subsequent reads return
      * the post-write state. We clear the entire loan-query cache (not just

package/dist/utils/eip712-login.d.ts

@@ -31,4 +31,16 @@ export declare const LOGIN_TYPES_WITH_AUDIENCE: Record<string, TypedDataField[]>
  * Audit M-8: pass `audience` (the service endpoint URL being logged into) to bind the login to
  * one service. Omit it for legacy compatibility during the migration window.
  */
-export declare function buildSignedLoginPayload(signer: Signer, chainId: number, audience?: string): Promise<DhServerLoginPayload>;
+export declare function buildSignedLoginPayload(signer: Signer, chainId: number, audience?: string, 
+/**
+ * Reuse the envelope of a login already collecting signatures instead of
+ * minting a fresh one. Every field is hashed into the EIP-712 message, so a
+ * new nonce produces a new hash — which a multi-owner Safe shows as a new
+ * message needing its FIRST signature, discarding the ones already collected.
+ * Passing the pending envelope back reproduces the same hash, so the next
+ * owner adds to it. See `server-session-store.ts`.
+ */
+reuse?: {
+    issuedAt: number;
+    nonce: string;
+}): Promise<DhServerLoginPayload>;