@gvnrdao/dh-sdk 0.0.311 → 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,
@@ -6700,6 +6704,7 @@ function isLoginRejection(error) {
 var ServerSession = class {
   signer;
   serviceEndpoint;
+  loginAudience;
   chainId;
   store;
   onSignaturePrompt;
@@ -6730,6 +6735,10 @@ 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;
@@ -6829,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
@@ -6901,7 +6957,7 @@ var ServerSession = class {
           const payload = await buildSignedLoginPayload(
             this.signer,
             this.chainId,
-            this.serviceEndpoint,
+            this.loginAudience,
             reuse
           );
           if (storeKey && !reuse) {
@@ -16545,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
@@ -16656,6 +16738,7 @@ 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,
@@ -23866,6 +23949,8 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   ErrorSeverity,
   EventHelpers,
   LOCALHOST_CONTRACTS,
+  LOGIN_TYPES,
+  LOGIN_TYPES_WITH_AUDIENCE,
   LRUCache,
   LoanCreator,
   LoanQuery,
@@ -23888,6 +23973,8 @@ async function getPositionDelegate(positionId, provider, registryAddress) {
   buildBtcExecuteEnvelope,
   buildInvalidateMessageHash,
   buildInvalidateStaleSpendEnvelope,
+  buildLoginDomain,
+  buildSignedLoginPayload,
   collectFailures,
   collectSuccesses,
   combine,

package/dist/index.mjs

@@ -6619,6 +6619,7 @@ function isLoginRejection(error) {
 var ServerSession = class {
   signer;
   serviceEndpoint;
+  loginAudience;
   chainId;
   store;
   onSignaturePrompt;
@@ -6649,6 +6650,10 @@ 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;
@@ -6748,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
@@ -6820,7 +6872,7 @@ var ServerSession = class {
           const payload = await buildSignedLoginPayload(
             this.signer,
             this.chainId,
-            this.serviceEndpoint,
+            this.loginAudience,
             reuse
           );
           if (storeKey && !reuse) {
@@ -16474,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
@@ -16585,6 +16663,7 @@ 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,
@@ -23794,6 +23873,8 @@ export {
   ErrorSeverity,
   EventHelpers,
   LOCALHOST_CONTRACTS,
+  LOGIN_TYPES,
+  LOGIN_TYPES_WITH_AUDIENCE,
   LRUCache,
   LoanCreator,
   LoanQuery,
@@ -23816,6 +23897,8 @@ export {
   buildBtcExecuteEnvelope,
   buildInvalidateMessageHash,
   buildInvalidateStaleSpendEnvelope,
+  buildLoginDomain,
+  buildSignedLoginPayload,
   collectFailures,
   collectSuccesses,
   combine,

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

@@ -71,6 +71,19 @@ 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

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/server-session.d.ts

@@ -22,6 +22,7 @@
  * `~/.diamond-hands/session.json` for cross-invocation reuse.
  */
 import type { Signer } from "ethers";
+import { type DhServerLoginPayload } from "./eip712-login";
 import { type ServerSessionStore } from "./server-session-store";
 export interface ServerSessionOptions {
     signer: Signer;
@@ -34,6 +35,16 @@ export interface ServerSessionOptions {
     sessionStore?: ServerSessionStore;
     /** Set false to disable persistence entirely (fresh signature per instance + expiry). */
     persistSession?: boolean;
+    /**
+     * Audit M-8 audience to bind the login to. Defaults to `serviceEndpoint`.
+     *
+     * A caller that shares ONE signature across several services (the browser
+     * frontend, which authenticates both lit-ops-server and the api from a single
+     * wallet prompt) cannot bind to a single endpoint, so it passes the app audience
+     * instead — and every server it talks to must accept that value. Node callers
+     * (CLI, MCP, cr-monitor) omit it and keep the endpoint binding unchanged.
+     */
+    loginAudience?: string;
     /**
      * Fires immediately before a wallet signature is requested — i.e. only when
      * neither the cached JWT nor the persisted envelope could renew the session,
@@ -59,6 +70,7 @@ export declare class ServerLoginError extends Error {
 export declare class ServerSession {
     private readonly signer;
     private readonly serviceEndpoint;
+    private readonly loginAudience;
     private readonly chainId;
     private readonly store;
     private readonly onSignaturePrompt?;
@@ -118,6 +130,24 @@ export declare class ServerSession {
      * of server response so the client stops presenting the token.
      */
     logout(): Promise<void>;
+    /**
+     * 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: DhServerLoginPayload): Promise<void>;
     /**
      * Resolve a session WITHOUT ever prompting for a wallet signature: a live
      * cached token, else the persisted JWT (adopted if still fresh, otherwise

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gvnrdao/dh-sdk",
-  "version": "0.0.311",
+  "version": "0.0.312",
   "description": "TypeScript SDK for Diamond Hands Protocol - Bitcoin-backed lending with LIT Protocol PKPs",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",