@gvnrdao/dh-sdk 0.0.309 → 0.0.312

package/dist/utils/server-session-store.d.ts

@@ -39,18 +39,62 @@ export interface ServerSessionStore {
     load(key: string): PersistedServerSession | null;
     save(key: string, session: PersistedServerSession): void;
     clear(key: string): void;
+    /**
+     * Optional pending-envelope persistence (see `PendingLoginEnvelope`). Optional
+     * so a custom store written before this existed still satisfies the interface;
+     * without it the session simply mints a fresh envelope each attempt, which is
+     * the pre-existing behavior and only costs a multi-owner Safe a restart.
+     */
+    loadPending?(key: string): PendingLoginEnvelope | null;
+    savePending?(key: string, envelope: PendingLoginEnvelope): void;
+    clearPending?(key: string): void;
 }
 export declare function sessionStoreKey(address: string, chainId: number, endpoint: string): string;
+/**
+ * The UNSIGNED envelope of a login already collecting signatures.
+ *
+ * A multi-owner Safe signs across sessions — owner 1 now, owner 2 later — and
+ * identifies the pending message solely by its EIP-712 hash. Every field is
+ * hashed, so minting a fresh `nonce`/`issuedAt` for the next attempt yields a
+ * DIFFERENT hash, which Safe presents as a new message needing its FIRST
+ * signature. Whatever owner 1 signed is orphaned, and a 2-of-N Safe can never
+ * reach threshold: every retry resets the count to zero.
+ *
+ * Reusing the envelope makes the re-request hash identically, so Safe shows the
+ * same pending message and the next owner ADDS to it. Invisible for an EOA,
+ * which signs immediately and spends the envelope.
+ */
+export interface PendingLoginEnvelope {
+    issuedAt: number;
+    nonce: string;
+}
+/**
+ * How long an unsigned envelope stays reusable. Must stay UNDER the server's
+ * contract-wallet first-use skew (`CONTRACT_ISSUED_AT_SKEW_SECONDS`, 10 min):
+ * beyond it the first use is rejected as stale, so reuse would guarantee failure
+ * instead of preventing a re-sign.
+ */
+export declare const PENDING_ENVELOPE_TTL_SECONDS: number;
+/** Storage key for the pending envelope matching a session key. */
+export declare function pendingEnvelopeKey(sessionKey: string): string;
+export declare function isPendingEnvelopeShape(value: any): value is PendingLoginEnvelope;
 export declare class LocalStorageSessionStore implements ServerSessionStore {
     load(key: string): PersistedServerSession | null;
     save(key: string, session: PersistedServerSession): void;
     clear(key: string): void;
+    loadPending(key: string): PendingLoginEnvelope | null;
+    savePending(key: string, envelope: PendingLoginEnvelope): void;
+    clearPending(key: string): void;
 }
 export declare class MemorySessionStore implements ServerSessionStore {
     private readonly entries;
+    private readonly pending;
     load(key: string): PersistedServerSession | null;
     save(key: string, session: PersistedServerSession): void;
     clear(key: string): void;
+    loadPending(key: string): PendingLoginEnvelope | null;
+    savePending(key: string, envelope: PendingLoginEnvelope): void;
+    clearPending(key: string): void;
 }
 /** `localStorage` when usable (browser, not blocked), else per-instance memory. */
 export declare function createDefaultSessionStore(): ServerSessionStore;

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,12 +35,28 @@ 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,
      * never on the silent paths. Lets UIs show a "check your wallet" prompt.
      */
     onSignaturePrompt?: () => void;
+    /**
+     * Fires once the prompted signature has concluded, with whether a session was
+     * established. Without it `onSignaturePrompt` has no ending, so a UI showing
+     * "check your wallet" can never take it down.
+     */
+    onSignatureResolved?: (ok: boolean) => void;
     /** Override for tests. */
     now?: () => number;
     /** Override for tests. */
@@ -53,9 +70,11 @@ 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?;
+    private readonly onSignatureResolved?;
     private readonly now;
     private readonly fetchImpl;
     private cached;
@@ -111,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.309",
+  "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",