@verbeth/sdk 0.1.4 → 0.1.6

package/dist/esm/src/ratchet/kdf.js

@@ -0,0 +1,91 @@
+// packages/sdk/src/ratchet/kdf.ts
+/**
+ * Key Derivation Functions for Double Ratchet.
+ *
+ * Uses HKDF-SHA256 for root key derivation and HMAC-SHA256 for chain key derivation,
+ * matching Signal protocol specifications.
+ */
+import { hkdf } from '@noble/hashes/hkdf';
+import { sha256 } from '@noble/hashes/sha2';
+import { hmac } from '@noble/hashes/hmac';
+import { keccak256 } from 'ethers';
+import nacl from 'tweetnacl';
+/**
+ * Derive new root key and chain key from DH output.
+ *
+ * @param rootKey - Current root key (32 bytes)
+ * @param dhOutput - DH shared secret (32 bytes)
+ * @returns New root key and chain key
+ */
+export function kdfRootKey(rootKey, dhOutput) {
+    const output = hkdf(sha256, dhOutput, rootKey, 'VerbethRatchet', 64);
+    return {
+        rootKey: output.slice(0, 32),
+        chainKey: output.slice(32, 64),
+    };
+}
+/**
+ * Derive message key and advance chain key.
+ *
+ * @param chainKey - Current chain key (32 bytes)
+ * @returns New chain key and message key for encryption/decryption
+ */
+export function kdfChainKey(chainKey) {
+    // Message key derived with constant 0x01
+    const messageKey = hmac(sha256, chainKey, new Uint8Array([0x01]));
+    // New chain key derived with constant 0x02
+    const newChainKey = hmac(sha256, chainKey, new Uint8Array([0x02]));
+    return {
+        chainKey: newChainKey,
+        messageKey: messageKey,
+    };
+}
+/**
+ * Perform X25519 Diffie-Hellman key exchange.
+ *
+ * @param mySecretKey - My X25519 secret key (32 bytes)
+ * @param theirPublicKey - Their X25519 public key (32 bytes)
+ * @returns Shared secret (32 bytes)
+ */
+export function dh(mySecretKey, theirPublicKey) {
+    return nacl.scalarMult(mySecretKey, theirPublicKey);
+}
+/**
+ * Generate new X25519 keypair for DH ratchet step.
+ *
+ * @returns New keypair with secretKey and publicKey
+ */
+export function generateDHKeyPair() {
+    const kp = nacl.box.keyPair();
+    return { secretKey: kp.secretKey, publicKey: kp.publicKey };
+}
+/**
+ * Derive topic from DH output using rootKey as PQ-secure salt.
+ *
+ * The rootKey (PQ-secure from hybrid handshake) acts as HKDF salt,
+ * providing quantum-resistant topic unlinkability even if dhOutput
+ * is later computed by a quantum adversary.
+ *
+ * @param rootKey - Current root key (32 bytes, PQ-secure)
+ * @param dhOutput - DH shared secret from ratchet step (32 bytes)
+ * @param direction - 'outbound' or 'inbound' for topic direction
+ * @returns bytes32 topic as hex string
+ */
+export function deriveTopic(rootKey, dhOutput, direction) {
+    const info = `verbeth:topic-${direction}:v3`;
+    const okm = hkdf(sha256, dhOutput, rootKey, info, 32);
+    return keccak256(okm);
+}
+/**
+ * Combines classical (X25519) and post-quantum (ML-KEM-768) key exchange
+ *
+ * @param x25519Secret - X25519 DH shared secret (32 bytes)
+ * @param kemSecret - ML-KEM-768 shared secret (32 bytes)
+ * @returns Hybrid shared secret (32 bytes)
+ */
+export function hybridInitialSecret(x25519Secret, kemSecret) {
+    const combined = new Uint8Array(x25519Secret.length + kemSecret.length);
+    combined.set(x25519Secret, 0);
+    combined.set(kemSecret, x25519Secret.length);
+    return hkdf(sha256, combined, new Uint8Array(32), 'VerbethHybrid', 32);
+}

package/dist/esm/src/ratchet/session.d.ts

@@ -0,0 +1,43 @@
+import { RatchetSession, InitResponderParams, InitInitiatorParams } from './types.js';
+/**
+ * Compute deterministic conversation ID from topics.
+ * Sorting ensures both parties derive the same ID regardless of perspective.
+ *
+ * @param topicA - First topic
+ * @param topicB - Second topic
+ * @returns Unique conversation identifier
+ */
+export declare function computeConversationId(topicA: string, topicB: string): string;
+/**
+ * Initialize session as responder (Bob).
+ *
+ * Called after receiving handshake, before/during sending response.
+ * The responder must persist myResponderEphemeralSecret immediately.
+ * This becomes dhMySecretKey and is required for all future ratchet operations.
+ *
+ * Responder starts at epoch 0 (handshake topics).
+ *
+ * If kemSecret is provided (from ML-KEM encapsulation), uses hybrid KDF
+ * combining X25519 DH and ML-KEM for post-quantum security.
+ *
+ * @param params - Initialization parameters
+ * @returns Initialized ratchet session
+ */
+export declare function initSessionAsResponder(params: InitResponderParams): RatchetSession;
+/**
+ * Initialize session as initiator (Alice).
+ *
+ * Called after receiving and validating handshake response.
+ *
+ * Initiator precomputes epoch 1 topics from its first post-handshake DH step.
+ * Outbound should use epoch 1 as soon as we introduce a new DH pubkey.
+ * Inbound stays on epoch 0 until the responder ratchets.
+ *
+ * If kemSecret is provided (from ML-KEM decapsulation), uses hybrid KDF
+ * combining X25519 DH and ML-KEM for post-quantum security.
+ *
+ * @param params - Initialization parameters
+ * @returns Initialized ratchet session
+ */
+export declare function initSessionAsInitiator(params: InitInitiatorParams): RatchetSession;
+//# sourceMappingURL=session.d.ts.map

package/dist/esm/src/ratchet/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/session.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc,CA6DlF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,cAAc,CA4ElF"}

package/dist/esm/src/ratchet/session.js

@@ -0,0 +1,139 @@
+// packages/sdk/src/ratchet/session.ts
+/**
+ * Ratchet Session Initialization.
+ *
+ * Provides functions to initialize ratchet sessions for both
+ * initiator (Alice) and responder (Bob) roles.
+ *
+ * Initial shared secret is derived from ephemeral-to-ephemeral DH only.
+ */
+import { keccak256, toUtf8Bytes } from 'ethers';
+import { kdfRootKey, dh, generateDHKeyPair, deriveTopic, hybridInitialSecret } from './kdf.js';
+/**
+ * Compute deterministic conversation ID from topics.
+ * Sorting ensures both parties derive the same ID regardless of perspective.
+ *
+ * @param topicA - First topic
+ * @param topicB - Second topic
+ * @returns Unique conversation identifier
+ */
+export function computeConversationId(topicA, topicB) {
+    const sorted = [topicA.toLowerCase(), topicB.toLowerCase()].sort();
+    return keccak256(toUtf8Bytes(sorted.join(':')));
+}
+/**
+ * Initialize session as responder (Bob).
+ *
+ * Called after receiving handshake, before/during sending response.
+ * The responder must persist myResponderEphemeralSecret immediately.
+ * This becomes dhMySecretKey and is required for all future ratchet operations.
+ *
+ * Responder starts at epoch 0 (handshake topics).
+ *
+ * If kemSecret is provided (from ML-KEM encapsulation), uses hybrid KDF
+ * combining X25519 DH and ML-KEM for post-quantum security.
+ *
+ * @param params - Initialization parameters
+ * @returns Initialized ratchet session
+ */
+export function initSessionAsResponder(params) {
+    const { myAddress, contactAddress, myResponderEphemeralSecret, myResponderEphemeralPublic, theirHandshakeEphemeralPubKey, topicOutbound, topicInbound, kemSecret, } = params;
+    const x25519Secret = dh(myResponderEphemeralSecret, theirHandshakeEphemeralPubKey);
+    const sharedSecret = kemSecret
+        ? hybridInitialSecret(x25519Secret, kemSecret)
+        : x25519Secret;
+    // Derive initial root key and sending chain key
+    const { rootKey, chainKey: sendingChainKey } = kdfRootKey(new Uint8Array(32), // Initial salt (zeros)
+    sharedSecret);
+    const now = Date.now();
+    return {
+        conversationId: computeConversationId(topicOutbound, topicInbound),
+        topicOutbound,
+        topicInbound,
+        myAddress,
+        contactAddress,
+        rootKey,
+        // Reuse responder ephemeral as first DH ratchet key
+        dhMySecretKey: myResponderEphemeralSecret,
+        dhMyPublicKey: myResponderEphemeralPublic,
+        dhTheirPublicKey: theirHandshakeEphemeralPubKey,
+        sendingChainKey,
+        sendingMsgNumber: 0,
+        // Receiving chain not yet established (Alice sends first post-handshake)
+        receivingChainKey: null,
+        receivingMsgNumber: 0,
+        previousChainLength: 0,
+        skippedKeys: [],
+        // Topic Ratcheting - Epoch 0: use handshake-derived topics
+        currentTopicOutbound: topicOutbound,
+        currentTopicInbound: topicInbound,
+        previousTopicInbound: undefined,
+        previousTopicExpiry: undefined,
+        topicEpoch: 0,
+        createdAt: now,
+        updatedAt: now,
+        epoch: 0,
+    };
+}
+/**
+ * Initialize session as initiator (Alice).
+ *
+ * Called after receiving and validating handshake response.
+ *
+ * Initiator precomputes epoch 1 topics from its first post-handshake DH step.
+ * Outbound should use epoch 1 as soon as we introduce a new DH pubkey.
+ * Inbound stays on epoch 0 until the responder ratchets.
+ *
+ * If kemSecret is provided (from ML-KEM decapsulation), uses hybrid KDF
+ * combining X25519 DH and ML-KEM for post-quantum security.
+ *
+ * @param params - Initialization parameters
+ * @returns Initialized ratchet session
+ */
+export function initSessionAsInitiator(params) {
+    const { myAddress, contactAddress, myHandshakeEphemeralSecret, theirResponderEphemeralPubKey, topicOutbound, topicInbound, kemSecret, } = params;
+    const x25519Secret = dh(myHandshakeEphemeralSecret, theirResponderEphemeralPubKey);
+    const sharedSecret = kemSecret
+        ? hybridInitialSecret(x25519Secret, kemSecret)
+        : x25519Secret;
+    // Derive same initial root key as responder
+    const { rootKey: initialRootKey, chainKey: bobsSendingChain } = kdfRootKey(new Uint8Array(32), sharedSecret);
+    // Generate first DH keypair for sending (Alice performs first DH ratchet)
+    const myDHKeyPair = generateDHKeyPair();
+    const dhSend = dh(myDHKeyPair.secretKey, theirResponderEphemeralPubKey);
+    const { rootKey: finalRootKey, chainKey: sendingChainKey } = kdfRootKey(initialRootKey, dhSend);
+    const conversationId = computeConversationId(topicOutbound, topicInbound);
+    // Pre-compute epoch 1 topics (for when our first message is sent)
+    // Use finalRootKey as PQ-secure salt for quantum-resistant topic unlinkability
+    const epoch1TopicOut = deriveTopic(finalRootKey, dhSend, 'outbound');
+    const epoch1TopicIn = deriveTopic(finalRootKey, dhSend, 'inbound');
+    const now = Date.now();
+    return {
+        conversationId,
+        topicOutbound,
+        topicInbound,
+        myAddress,
+        contactAddress,
+        rootKey: finalRootKey,
+        dhMySecretKey: myDHKeyPair.secretKey,
+        dhMyPublicKey: myDHKeyPair.publicKey,
+        dhTheirPublicKey: theirResponderEphemeralPubKey,
+        sendingChainKey,
+        sendingMsgNumber: 0,
+        // Alice can receive Bob's messages immediately
+        receivingChainKey: bobsSendingChain,
+        receivingMsgNumber: 0,
+        previousChainLength: 0,
+        skippedKeys: [],
+        // Start with handshake topics
+        currentTopicOutbound: topicOutbound,
+        currentTopicInbound: topicInbound,
+        // Pre-computed next topics (will be promoted when we send)
+        nextTopicOutbound: epoch1TopicOut,
+        nextTopicInbound: epoch1TopicIn,
+        topicEpoch: 0,
+        createdAt: now,
+        updatedAt: now,
+        epoch: 0,
+    };
+}

package/dist/esm/src/ratchet/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Double Ratchet types and constants.
+ */
+/**
+ * Sanity cap per ratchet step, protects against malicious peers or corrupted state.
+ */
+export declare const MAX_SKIP_PER_MESSAGE = 100000;
+/**
+ * When exceeded, oldest keys are pruned.
+ */
+export declare const MAX_STORED_SKIPPED_KEYS = 1000;
+/**
+ * Skipped keys TTL (24 hours is sufficient for reorg tolerance).
+ * (this is not message expiry as sequential messages don't use skipped keys)
+ */
+export declare const MAX_SKIPPED_KEYS_AGE_MS: number;
+/**
+ * Yield to UI every N derivations during large backlog processing.
+ */
+export declare const SYNC_BATCH_SIZE = 10000;
+/**
+ * Binary payload version byte.
+ */
+export declare const RATCHET_VERSION_V1 = 1;
+export declare const TOPIC_TRANSITION_WINDOW_MS: number;
+/**
+ * Ratchet session state.
+ *
+ * This is stateful - must be persisted after every encrypt/decrypt.
+ * Session is identified by conversationId (derived from topics), enabling
+ * correct handling of Safe addresses vs EOAs.
+ */
+export interface RatchetSession {
+    /** Primary key: keccak256(sort([topicOut, topicIn])) */
+    conversationId: string;
+    /** Original handshake-derived outbound topic (immutable reference) */
+    topicOutbound: `0x${string}`;
+    /** Original handshake-derived inbound topic (immutable reference) */
+    topicInbound: `0x${string}`;
+    /** My EOA address (for convenience/lookup) */
+    myAddress: string;
+    /** Their EOA address (for convenience/lookup) */
+    contactAddress: string;
+    /** Current root key (32 bytes) */
+    rootKey: Uint8Array;
+    /** My current DH secret key (32 bytes) */
+    dhMySecretKey: Uint8Array;
+    /** My current DH public key (32 bytes) */
+    dhMyPublicKey: Uint8Array;
+    /** Their last received DH public key (32 bytes) */
+    dhTheirPublicKey: Uint8Array;
+    /** Current sending chain key (null until first DH ratchet as sender) */
+    sendingChainKey: Uint8Array | null;
+    /** Next sending message number (Ns) */
+    sendingMsgNumber: number;
+    /** Current receiving chain key (null until first message received) */
+    receivingChainKey: Uint8Array | null;
+    /** Next expected receiving message number (Nr) */
+    receivingMsgNumber: number;
+    /** Message count in previous sending chain (PN header field) */
+    previousChainLength: number;
+    /** Stored keys for out-of-order messages */
+    skippedKeys: SkippedKey[];
+    /** Current outbound topic (may differ from original after ratcheting) */
+    currentTopicOutbound: `0x${string}`;
+    /** Current inbound topic (may differ from original after ratcheting) */
+    currentTopicInbound: `0x${string}`;
+    /** Pre-computed next outbound topic (for our next DH ratchet) */
+    nextTopicOutbound?: `0x${string}`;
+    /** Pre-computed next inbound topic (for their next DH ratchet) */
+    nextTopicInbound?: `0x${string}`;
+    /** Previous inbound topic (grace period for late messages) */
+    previousTopicInbound?: `0x${string}`;
+    /** Expiry timestamp for previous topic */
+    previousTopicExpiry?: number;
+    /** Topic epoch counter */
+    topicEpoch: number;
+    /** Session creation timestamp */
+    createdAt: number;
+    /** Last state update timestamp */
+    updatedAt: number;
+    /** Increments on session reset (internal bookkeeping only) */
+    epoch: number;
+}
+/**
+ * Stored key for out-of-order message decryption.
+ */
+export interface SkippedKey {
+    /** DH epoch identifier (hex of their DH pubkey) */
+    dhPubKeyHex: string;
+    /** Message number in that epoch */
+    msgNumber: number;
+    /** Derived message key (32 bytes) */
+    messageKey: Uint8Array;
+    /** Creation timestamp for TTL pruning */
+    createdAt: number;
+}
+/**
+ * Message header (40 bytes when encoded).
+ */
+export interface MessageHeader {
+    /** Sender's current DH ratchet public key (32 bytes) */
+    dh: Uint8Array;
+    /** Previous chain length - messages in sender's previous sending chain */
+    pn: number;
+    /** Message number in current sending chain */
+    n: number;
+}
+/**
+ * Result of ratchetEncrypt - includes new session state for two-phase commit.
+ */
+export interface EncryptResult {
+    /** Updated session state (MUST be persisted) */
+    session: RatchetSession;
+    header: MessageHeader;
+    ciphertext: Uint8Array;
+    signature: Uint8Array;
+    topic: `0x${string}`;
+}
+/**
+ * Result of ratchetDecrypt.
+ */
+export interface DecryptResult {
+    /** Updated session state (MUST be persisted) */
+    session: RatchetSession;
+    plaintext: Uint8Array;
+}
+/**
+ * Parsed binary ratchet payload.
+ */
+export interface ParsedRatchetPayload {
+    version: number;
+    signature: Uint8Array;
+    header: MessageHeader;
+    ciphertext: Uint8Array;
+}
+/**
+ * Parameters for initializing session as responder.
+ */
+export interface InitResponderParams {
+    myAddress: string;
+    contactAddress: string;
+    /** Ephemeral secret used in HandshakeResponse (becomes dhMySecretKey) */
+    myResponderEphemeralSecret: Uint8Array;
+    myResponderEphemeralPublic: Uint8Array;
+    /** Initiator's ephemeral from Handshake event */
+    theirHandshakeEphemeralPubKey: Uint8Array;
+    topicOutbound: `0x${string}`;
+    topicInbound: `0x${string}`;
+    /** ML-KEM shared secret for PQ-hybrid handshake */
+    kemSecret?: Uint8Array;
+}
+/**
+ * Parameters for initializing session as initiator.
+ */
+export interface InitInitiatorParams {
+    myAddress: string;
+    contactAddress: string;
+    /** Handshake ephemeral secret (must persist until response arrives) */
+    myHandshakeEphemeralSecret: Uint8Array;
+    /** Responder's ephemeral from HandshakeResponse (inside encrypted payload) */
+    theirResponderEphemeralPubKey: Uint8Array;
+    topicOutbound: `0x${string}`;
+    topicInbound: `0x${string}`;
+    /** ML-KEM shared secret for PQ-hybrid handshake */
+    kemSecret?: Uint8Array;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/src/ratchet/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/ratchet/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/src/ratchet/types.js

@@ -0,0 +1,27 @@
+// packages/sdk/src/ratchet/types.ts
+/**
+ * Double Ratchet types and constants.
+ */
+/**
+ * Sanity cap per ratchet step, protects against malicious peers or corrupted state.
+ */
+export const MAX_SKIP_PER_MESSAGE = 100000;
+/**
+ * When exceeded, oldest keys are pruned.
+ */
+export const MAX_STORED_SKIPPED_KEYS = 1000;
+/**
+ * Skipped keys TTL (24 hours is sufficient for reorg tolerance).
+ * (this is not message expiry as sequential messages don't use skipped keys)
+ */
+export const MAX_SKIPPED_KEYS_AGE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Yield to UI every N derivations during large backlog processing.
+ */
+export const SYNC_BATCH_SIZE = 10000;
+/**
+ * Binary payload version byte.
+ */
+export const RATCHET_VERSION_V1 = 0x01;
+// Previous topic remains valid for this duration after promotion.
+export const TOPIC_TRANSITION_WINDOW_MS = 5 * 60 * 1000;

package/dist/esm/src/safeSessionSigner.d.ts

@@ -0,0 +1,35 @@
+import { AbstractSigner, type Provider, type Signer, type TransactionRequest, type TransactionResponse, type TypedDataDomain, type TypedDataField } from "ethers";
+export interface SafeSessionSignerOptions {
+    provider: Provider;
+    safeAddress: string;
+    /** Safe module enabled on the Safe */
+    moduleAddress: string;
+    /** only allowed target */
+    logChainAddress: string;
+    /** The EOA session signer (pays gas, calls the module). Must be connected to a provider. */
+    sessionSigner: Signer;
+    /** Default: execute(address,uint256,bytes,uint8) */
+    moduleAbi?: readonly string[];
+    /** Default: "execute" */
+    executeMethod?: string;
+}
+/**
+ * Ethers v6 Signer adapter:
+ * - Exposes address = Safe
+ * - Intercepts txs to LogChain and routes them through the Safe module
+ *
+ * sessionSigner is an EOA that directly sends the module tx.
+ */
+export declare class SafeSessionSigner extends AbstractSigner {
+    private module;
+    private executeMethod;
+    private opts;
+    constructor(opts: SafeSessionSignerOptions);
+    getAddress(): Promise<string>;
+    signMessage(message: string | Uint8Array): Promise<string>;
+    signTransaction(_tx: TransactionRequest): Promise<string>;
+    signTypedData(domain: TypedDataDomain, types: Record<string, Array<TypedDataField>>, value: Record<string, any>): Promise<string>;
+    sendTransaction(tx: TransactionRequest): Promise<TransactionResponse>;
+    connect(provider: Provider): SafeSessionSigner;
+}
+//# sourceMappingURL=safeSessionSigner.d.ts.map

package/dist/esm/src/safeSessionSigner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeSessionSigner.d.ts","sourceRoot":"","sources":["../../../src/safeSessionSigner.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EAEd,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,QAAQ,CAAC;AAEhB,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,0BAA0B;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAC;IAEtB,oDAAoD;IACpD,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,yBAAyB;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,aAAa,CAAS;IAE9B,OAAO,CAAC,IAAI,CAA2B;gBAE3B,IAAI,EAAE,wBAAwB;IAkB3B,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1D,eAAe,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzD,aAAa,CAC1B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC,EAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACzB,OAAO,CAAC,MAAM,CAAC;IASH,eAAe,CAAC,EAAE,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAsB3E,OAAO,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB;CAGxD"}

package/dist/esm/src/safeSessionSigner.js

@@ -0,0 +1,59 @@
+// packages/sdk/src/safeSessionSigner.ts
+import { AbstractSigner, Contract, } from "ethers";
+const DEFAULT_ABI = [
+    "function execute(address to, uint256 value, bytes data, uint8 operation)",
+];
+/**
+ * Ethers v6 Signer adapter:
+ * - Exposes address = Safe
+ * - Intercepts txs to LogChain and routes them through the Safe module
+ *
+ * sessionSigner is an EOA that directly sends the module tx.
+ */
+export class SafeSessionSigner extends AbstractSigner {
+    constructor(opts) {
+        super(opts.provider);
+        this.opts = opts;
+        if (!opts.sessionSigner.provider) {
+            throw new Error("SafeSessionSigner: sessionSigner must be connected to a Provider (e.g., new Wallet(pk, provider)).");
+        }
+        this.module = new Contract(opts.moduleAddress, (opts.moduleAbi ?? DEFAULT_ABI), opts.sessionSigner);
+        this.executeMethod = opts.executeMethod ?? "execute";
+    }
+    async getAddress() {
+        return this.opts.safeAddress;
+    }
+    async signMessage(message) {
+        return this.opts.sessionSigner.signMessage(message);
+    }
+    async signTransaction(_tx) {
+        throw new Error("SafeSessionSigner: signTransaction not supported; use sendTransaction().");
+    }
+    async signTypedData(domain, types, value) {
+        // delegate
+        const anySigner = this.opts.sessionSigner;
+        if (typeof anySigner.signTypedData === "function") {
+            return anySigner.signTypedData(domain, types, value);
+        }
+        throw new Error("SafeSessionSigner: underlying sessionSigner does not support signTypedData.");
+    }
+    async sendTransaction(tx) {
+        if (!tx.to)
+            throw new Error("SafeSessionSigner: tx.to is required");
+        const to = String(tx.to).toLowerCase();
+        const logChain = this.opts.logChainAddress.toLowerCase();
+        if (to !== logChain) {
+            throw new Error(`SafeSessionSigner: only LogChain txs are supported. Got to=${tx.to}`);
+        }
+        const data = tx.data ?? "0x";
+        const fn = this.module[this.executeMethod];
+        if (typeof fn !== "function") {
+            throw new Error(`SafeSessionSigner: module execute method "${this.executeMethod}" not found on ${this.opts.moduleAddress}`);
+        }
+        // operation: 0 = CALL, value: 0
+        return fn(this.opts.logChainAddress, 0n, data, 0);
+    }
+    connect(provider) {
+        return new SafeSessionSigner({ ...this.opts, provider });
+    }
+}

package/dist/esm/src/send.d.ts

@@ -2,49 +2,57 @@ import { Signer } from "ethers";
 import nacl from 'tweetnacl';
 import { IdentityKeyPair, IdentityProof } from './types.js';
 import { IExecutor } from './executor.js';
-/**
- * Sends an encrypted message assuming recipient's keys were already obtained via handshake.
- * Executor-agnostic: works with EOA, UserOp, and Direct EntryPoint (for tests)
- */
-export declare function sendEncryptedMessage({ executor, topic, message, recipientPubKey, senderAddress, senderSignKeyPair, timestamp }: {
-    executor: IExecutor;
-    topic: string;
-    message: string;
-    recipientPubKey: Uint8Array;
-    senderAddress: string;
-    senderSignKeyPair: nacl.SignKeyPair;
-    timestamp: number;
-}): Promise<any>;
+/** ML-KEM keypair for PQ-hybrid handshake */
+export interface KemKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
 /**
  * Initiates an on-chain handshake with unified keys and mandatory identity proof.
  * Executor-agnostic: works with EOA, UserOp, and Direct EntryPoint (for tests)
+ *
+ * Includes ML-KEM-768 public key for post-quantum hybrid key exchange.
+ *
+ * @returns Transaction, ephemeral keypair, and KEM keypair (MUST be persisted for session init)
  */
-export declare function initiateHandshake({ executor, recipientAddress, identityKeyPair, ephemeralPubKey, plaintextPayload, identityProof, signer }: {
+export declare function initiateHandshake({ executor, recipientAddress, identityKeyPair, plaintextPayload, identityProof, }: {
     executor: IExecutor;
     recipientAddress: string;
     identityKeyPair: IdentityKeyPair;
-    ephemeralPubKey: Uint8Array;
     plaintextPayload: string;
     identityProof: IdentityProof;
-    signer: Signer;
-}): Promise<any>;
+    signer?: Signer;
+}): Promise<{
+    tx: any;
+    ephemeralKeyPair: nacl.BoxKeyPair;
+    kemKeyPair: KemKeyPair;
+}>;
 /**
  * Responds to a handshake with unified keys and mandatory identity proof.
  * Executor-agnostic: works with EOA, UserOp, and Direct EntryPoint (for tests)
+ *
+ * Supports PQ-hybrid handshake: if initiator includes KEM public key,
+ * encapsulates a shared secret and includes ciphertext in response.
+ *
+ * @returns Transaction, tag, salt, ephemeral keys, and KEM secret
  */
-export declare function respondToHandshake({ executor, initiatorPubKey, // X25519 key from initiator (ephemeral)
-responderIdentityKeyPair, responderEphemeralKeyPair, note, identityProof, signer, initiatorIdentityPubKey, }: {
+export declare function respondToHandshake({ executor, initiatorEphemeralPubKey, responderIdentityKeyPair, note, identityProof, }: {
     executor: IExecutor;
-    initiatorPubKey: Uint8Array;
+    /** Initiator's ephemeral key (32 bytes X25519) OR extended key (1216 bytes: X25519 + ML-KEM) */
+    initiatorEphemeralPubKey: Uint8Array;
     responderIdentityKeyPair: IdentityKeyPair;
-    responderEphemeralKeyPair?: nacl.BoxKeyPair;
     note?: string;
     identityProof: IdentityProof;
-    signer: Signer;
-    initiatorIdentityPubKey?: Uint8Array;
+    signer?: Signer;
 }): Promise<{
     tx: any;
-    salt: Uint8Array<ArrayBufferLike>;
+    salt: Uint8Array;
     tag: `0x${string}`;
+    /** Responder's DH ratchet secret - must persist as dhMySecretKey in ratchet session */
+    responderEphemeralSecret: Uint8Array;
+    /** Responder's DH ratchet public - inside encrypted payload, not on-chain */
+    responderEphemeralPublic: Uint8Array;
+    /** ML-KEM shared secret (32 bytes) - MUST persist for hybrid KDF, undefined if no KEM in handshake */
+    kemSharedSecret?: Uint8Array;
 }>;
 //# sourceMappingURL=send.d.ts.map

package/dist/esm/src/send.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/send.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,MAAM,EAEP,MAAM,QAAQ,CAAC;AAChB,OAAO,IAAI,MAAM,WAAW,CAAC;AAU7B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAK1C;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,QAAQ,EACR,KAAK,EACL,OAAO,EACP,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,SAAS,EACV,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,UAAU,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,IAAI,CAAC,WAAW,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB,gBAmBA;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,MAAM,EACP,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC,eAAe,EAAE,UAAU,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB,gBA4BA;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,QAAQ,EACR,eAAe,EAAE,wCAAwC;AACzD,wBAAwB,EACxB,yBAAyB,EACzB,IAAI,EACJ,aAAa,EACb,MAAM,EACN,uBAAuB,GACxB,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,eAAe,EAAE,UAAU,CAAC;IAC5B,wBAAwB,EAAE,eAAe,CAAC;IAC1C,yBAAyB,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB,CAAC,EAAE,UAAU,CAAC;CACtC;;;;GAuDA"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../src/send.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,MAAM,EAEP,MAAM,QAAQ,CAAC;AAChB,OAAO,IAAI,MAAM,WAAW,CAAC;AAQ7B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI1C,6CAA6C;AAC7C,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,UAAU,CAAC;IACtB,SAAS,EAAE,UAAU,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,GACd,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,eAAe,EAAE,eAAe,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,EAAE,EAAE,GAAG,CAAC;IACR,gBAAgB,EAAE,IAAI,CAAC,UAAU,CAAC;IAClC,UAAU,EAAE,UAAU,CAAC;CACxB,CAAC,CA6CD;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,QAAQ,EACR,wBAAwB,EACxB,wBAAwB,EACxB,IAAI,EACJ,aAAa,GACd,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;IACpB,gGAAgG;IAChG,wBAAwB,EAAE,UAAU,CAAC;IACrC,wBAAwB,EAAE,eAAe,CAAC;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,EAAE,EAAE,GAAG,CAAC;IACR,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,KAAK,MAAM,EAAE,CAAC;IACnB,uFAAuF;IACvF,wBAAwB,EAAE,UAAU,CAAC;IACrC,6EAA6E;IAC7E,wBAAwB,EAAE,UAAU,CAAC;IACrC,sGAAsG;IACtG,eAAe,CAAC,EAAE,UAAU,CAAC;CAC9B,CAAC,CA+FD"}