@volr/sdk-core 0.1.64 → 0.1.66

package/dist/index.d.cts

@@ -30,6 +30,25 @@ type AesGcmParams = {
     /** Additional Authenticated Data (optional) */
     aad?: Uint8Array;
 };
+/**
+ * Generate a unique 12-byte nonce for AES-GCM
+ *
+ * Format: [4 bytes timestamp] + [8 bytes random]
+ *
+ * This hybrid approach provides:
+ * 1. Timestamp component: Reduces collision probability across different times
+ * 2. Random component: Reduces collision probability at the same time
+ *
+ * Collision analysis:
+ * - With purely random 96-bit nonces: 2^32 encryptions before 50% collision probability
+ * - With timestamp + 64-bit random: Collisions require same second + same random (2^64 per second)
+ *
+ * Note: This is belt-and-suspenders - in practice, master seeds are encrypted
+ * only once per enrollment, so collisions are extremely unlikely either way.
+ *
+ * @returns 12-byte Uint8Array nonce
+ */
+declare function generateNonce(): Uint8Array;
 /**
  * AES-256-GCM encryption
  *
@@ -1262,6 +1281,14 @@ type PasskeyProviderOptions = {
     };
     /** Additional Authenticated Data for unwrapping */
     aad?: Uint8Array;
+    /**
+     * Session TTL in milliseconds.
+     * - 0 (default): No caching - requires WebAuthn authentication for every signature (most secure)
+     * - >0: Cache private key in memory for this duration (less secure, better UX)
+     *
+     * @default 0
+     */
+    sessionTtlMs?: number;
 };
 /**
  * Create passkey provider
@@ -1341,4 +1368,4 @@ type SelectSignerContext = {
  */
 declare function selectSigner(ctx: SelectSignerContext): Promise<SignerPort>;
 
-export { type AesGcmParams, type AuthorizationTuple, type Call, ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, type DeriveArgs, EIP1193ErrorCode, type EIP1193Provider, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, type EvmKeypair, type ExtendedRPCClient, ExternalWalletSigner, type KeyStorageType, type Sig$1 as LegacySig, type MasterKeyProvider, type MasterSeed, type MasterSeedHandle, type MpcTransport, PasskeyP256Signer, type PasskeyProviderOptions, type PasskeyProviderPort, type PrecheckInput, type PrecheckQuote, type PrfInput, type RelayInput, type RelayMode, type RelayResult, RequestPendingError, type RpcLike, Secp256k1SoftwareSigner, type SelectSignerContext, type SessionAuth, type Sig, type SignerContext, type SignerKind, type SignerPort, TYPES, type TypedDataInput, UnauthorizedError, UnsupportedMethodError, type UploadBlobOptions, type UploadViaPresignOptions, UserRejectedError, VolrError, WalletError, type WalletProviderPort, type WrapKey, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner$1 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };
+export { type AesGcmParams, type AuthorizationTuple, type Call, ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, type DeriveArgs, EIP1193ErrorCode, type EIP1193Provider, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, type EvmKeypair, type ExtendedRPCClient, ExternalWalletSigner, type KeyStorageType, type Sig$1 as LegacySig, type MasterKeyProvider, type MasterSeed, type MasterSeedHandle, type MpcTransport, PasskeyP256Signer, type PasskeyProviderOptions, type PasskeyProviderPort, type PrecheckInput, type PrecheckQuote, type PrfInput, type RelayInput, type RelayMode, type RelayResult, RequestPendingError, type RpcLike, Secp256k1SoftwareSigner, type SelectSignerContext, type SessionAuth, type Sig, type SignerContext, type SignerKind, type SignerPort, TYPES, type TypedDataInput, UnauthorizedError, UnsupportedMethodError, type UploadBlobOptions, type UploadViaPresignOptions, UserRejectedError, VolrError, WalletError, type WalletProviderPort, type WrapKey, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, generateNonce, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner$1 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };

package/dist/index.d.ts

@@ -30,6 +30,25 @@ type AesGcmParams = {
     /** Additional Authenticated Data (optional) */
     aad?: Uint8Array;
 };
+/**
+ * Generate a unique 12-byte nonce for AES-GCM
+ *
+ * Format: [4 bytes timestamp] + [8 bytes random]
+ *
+ * This hybrid approach provides:
+ * 1. Timestamp component: Reduces collision probability across different times
+ * 2. Random component: Reduces collision probability at the same time
+ *
+ * Collision analysis:
+ * - With purely random 96-bit nonces: 2^32 encryptions before 50% collision probability
+ * - With timestamp + 64-bit random: Collisions require same second + same random (2^64 per second)
+ *
+ * Note: This is belt-and-suspenders - in practice, master seeds are encrypted
+ * only once per enrollment, so collisions are extremely unlikely either way.
+ *
+ * @returns 12-byte Uint8Array nonce
+ */
+declare function generateNonce(): Uint8Array;
 /**
  * AES-256-GCM encryption
  *
@@ -1262,6 +1281,14 @@ type PasskeyProviderOptions = {
     };
     /** Additional Authenticated Data for unwrapping */
     aad?: Uint8Array;
+    /**
+     * Session TTL in milliseconds.
+     * - 0 (default): No caching - requires WebAuthn authentication for every signature (most secure)
+     * - >0: Cache private key in memory for this duration (less secure, better UX)
+     *
+     * @default 0
+     */
+    sessionTtlMs?: number;
 };
 /**
  * Create passkey provider
@@ -1341,4 +1368,4 @@ type SelectSignerContext = {
  */
 declare function selectSigner(ctx: SelectSignerContext): Promise<SignerPort>;
 
-export { type AesGcmParams, type AuthorizationTuple, type Call, ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, type DeriveArgs, EIP1193ErrorCode, type EIP1193Provider, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, type EvmKeypair, type ExtendedRPCClient, ExternalWalletSigner, type KeyStorageType, type Sig$1 as LegacySig, type MasterKeyProvider, type MasterSeed, type MasterSeedHandle, type MpcTransport, PasskeyP256Signer, type PasskeyProviderOptions, type PasskeyProviderPort, type PrecheckInput, type PrecheckQuote, type PrfInput, type RelayInput, type RelayMode, type RelayResult, RequestPendingError, type RpcLike, Secp256k1SoftwareSigner, type SelectSignerContext, type SessionAuth, type Sig, type SignerContext, type SignerKind, type SignerPort, TYPES, type TypedDataInput, UnauthorizedError, UnsupportedMethodError, type UploadBlobOptions, type UploadViaPresignOptions, UserRejectedError, VolrError, WalletError, type WalletProviderPort, type WrapKey, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner$1 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };
+export { type AesGcmParams, type AuthorizationTuple, type Call, ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, type DeriveArgs, EIP1193ErrorCode, type EIP1193Provider, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, type EvmKeypair, type ExtendedRPCClient, ExternalWalletSigner, type KeyStorageType, type Sig$1 as LegacySig, type MasterKeyProvider, type MasterSeed, type MasterSeedHandle, type MpcTransport, PasskeyP256Signer, type PasskeyProviderOptions, type PasskeyProviderPort, type PrecheckInput, type PrecheckQuote, type PrfInput, type RelayInput, type RelayMode, type RelayResult, RequestPendingError, type RpcLike, Secp256k1SoftwareSigner, type SelectSignerContext, type SessionAuth, type Sig, type SignerContext, type SignerKind, type SignerPort, TYPES, type TypedDataInput, UnauthorizedError, UnsupportedMethodError, type UploadBlobOptions, type UploadViaPresignOptions, UserRejectedError, VolrError, WalletError, type WalletProviderPort, type WrapKey, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, generateNonce, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner$1 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };

package/dist/index.js

@@ -73,6 +73,15 @@ function getRandomBytes(len) {
 }
 
 // src/core/crypto/aes-gcm.ts
+function generateNonce() {
+  const nonce = new Uint8Array(12);
+  const timestamp = Math.floor(Date.now() / 1e3);
+  const view = new DataView(nonce.buffer);
+  view.setUint32(0, timestamp, false);
+  const random = getRandomBytes(8);
+  nonce.set(random, 4);
+  return nonce;
+}
 function getSubtleCrypto() {
   if (typeof crypto !== "undefined" && crypto.subtle) {
     return crypto.subtle;
@@ -93,7 +102,7 @@ async function aesGcmEncrypt(plain, params) {
   if (key.length !== 32) {
     throw new Error(`${ERR_INVALID_PARAM}: key must be 32 bytes, got ${key.length}`);
   }
-  const nonce = providedNonce || getRandomBytes(12);
+  const nonce = providedNonce || generateNonce();
   if (nonce.length !== 12) {
     throw new Error(`${ERR_NONCE_SIZE}: nonce must be 12 bytes, got ${nonce.length}`);
   }
@@ -1050,62 +1059,79 @@ async function getAuthNonce(client, from, mode) {
 }
 function createPasskeyProvider(passkey, options) {
   let unwrappedKeypair = null;
-  const ensureSession = async (opts) => {
-    if (opts?.force && unwrappedKeypair) {
-      console.log("[PasskeyProvider] force=true: zeroizing existing session");
+  const sessionTtlMs = options.sessionTtlMs ?? 0;
+  let sessionExpiresAt = null;
+  let lockTimer = null;
+  const isSessionExpired = () => {
+    if (sessionTtlMs === 0) return true;
+    if (!sessionExpiresAt) return true;
+    return Date.now() >= sessionExpiresAt;
+  };
+  const resetSessionTimer = () => {
+    if (sessionTtlMs <= 0) return;
+    if (lockTimer) {
+      clearTimeout(lockTimer);
+      lockTimer = null;
+    }
+    sessionExpiresAt = Date.now() + sessionTtlMs;
+    lockTimer = setTimeout(async () => {
+      console.log("[PasskeyProvider] Session expired, auto-locking");
+      await lock();
+    }, sessionTtlMs);
+  };
+  const lock = async () => {
+    if (lockTimer) {
+      clearTimeout(lockTimer);
+      lockTimer = null;
+    }
+    sessionExpiresAt = null;
+    if (unwrappedKeypair) {
+      console.log("[PasskeyProvider] lock(): zeroizing sensitive data from memory");
       zeroize(unwrappedKeypair.privateKey);
       zeroize(unwrappedKeypair.publicKey);
       unwrappedKeypair = null;
     }
-    if (unwrappedKeypair) {
+  };
+  const ensureSession = async (opts) => {
+    if (opts?.force && unwrappedKeypair) {
+      console.log("[PasskeyProvider] force=true: zeroizing existing session");
+      await lock();
+    }
+    if (unwrappedKeypair && !isSessionExpired()) {
+      resetSessionTimer();
       return;
     }
-    if (opts?.interactive || opts?.force) {
-      console.log("[PasskeyProvider] interactive mode: triggering WebAuthn prompt");
-      const prfSalt = deriveWrapKey(options.prfInput);
-      const { prfOutput } = await passkey.authenticate({
-        salt: prfSalt,
-        credentialId: options.prfInput.credentialId
-      });
-      const wrapKey = prfOutput;
-      const aad = options.aad || new TextEncoder().encode("volr/master-seed/v1");
-      const masterSeed = await unsealMasterSeed(
-        options.encryptedBlob.cipher,
-        wrapKey,
-        aad,
-        options.encryptedBlob.nonce
-      );
-      const keypair = deriveEvmKey({ masterSeed });
-      unwrappedKeypair = {
-        privateKey: keypair.privateKey,
-        publicKey: keypair.publicKey,
-        address: keypair.address
-      };
-      zeroize(masterSeed);
-      zeroize(wrapKey);
-      zeroize(prfSalt);
-    } else {
-      console.warn("[PasskeyProvider] Non-interactive mode: using deterministic wrap key (insecure for TTL=0)");
-      const wrapKey = deriveWrapKey(options.prfInput);
-      const aad = options.aad || new TextEncoder().encode("volr/master-seed/v1");
-      const masterSeed = await unsealMasterSeed(
-        options.encryptedBlob.cipher,
-        wrapKey,
-        aad,
-        options.encryptedBlob.nonce
-      );
-      const keypair = deriveEvmKey({ masterSeed });
-      unwrappedKeypair = {
-        privateKey: keypair.privateKey,
-        publicKey: keypair.publicKey,
-        address: keypair.address
-      };
-      zeroize(masterSeed);
-      zeroize(wrapKey);
+    if (unwrappedKeypair && isSessionExpired()) {
+      console.log("[PasskeyProvider] Session expired, re-authenticating");
+      await lock();
     }
+    console.log("[PasskeyProvider] Triggering WebAuthn prompt for hardware-backed authentication");
+    const prfSalt = deriveWrapKey(options.prfInput);
+    const { prfOutput } = await passkey.authenticate({
+      salt: prfSalt,
+      credentialId: options.prfInput.credentialId
+    });
+    const wrapKey = prfOutput;
+    const aad = options.aad || new TextEncoder().encode("volr/master-seed/v1");
+    const masterSeed = await unsealMasterSeed(
+      options.encryptedBlob.cipher,
+      wrapKey,
+      aad,
+      options.encryptedBlob.nonce
+    );
+    const keypair = deriveEvmKey({ masterSeed });
+    unwrappedKeypair = {
+      privateKey: keypair.privateKey,
+      publicKey: keypair.publicKey,
+      address: keypair.address
+    };
+    zeroize(masterSeed);
+    zeroize(wrapKey);
+    zeroize(prfSalt);
+    resetSessionTimer();
   };
   const getAddress = async () => {
-    await ensureSession();
+    await ensureSession({ });
     if (!unwrappedKeypair) {
       throw new Error(`${ERR_INVALID_PARAM}: Session not established`);
     }
@@ -1115,11 +1141,15 @@ function createPasskeyProvider(passkey, options) {
     if (hash32.length !== 32) {
       throw new Error(`${ERR_INVALID_PARAM}: Message hash must be 32 bytes, got ${hash32.length}`);
     }
-    await ensureSession();
+    const shouldForceFresh = sessionTtlMs === 0;
+    await ensureSession({ force: shouldForceFresh });
     if (!unwrappedKeypair) {
       throw new Error(`${ERR_INVALID_PARAM}: Session not established`);
     }
     const sig = evmSign(unwrappedKeypair.privateKey, hash32);
+    if (shouldForceFresh) {
+      await lock();
+    }
     return {
       r: sig.r,
       s: sig.s,
@@ -1127,7 +1157,8 @@ function createPasskeyProvider(passkey, options) {
     };
   };
   const signTypedData = async (input) => {
-    await ensureSession();
+    const shouldForceFresh = sessionTtlMs === 0;
+    await ensureSession({ force: shouldForceFresh });
     if (!unwrappedKeypair) {
       throw new Error(`${ERR_INVALID_PARAM}: Session not established`);
     }
@@ -1143,7 +1174,10 @@ function createPasskeyProvider(passkey, options) {
     for (let i = 0; i < 32; i++) {
       msgHashBytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
     }
-    const sig = await signMessage(msgHashBytes);
+    const sig = evmSign(unwrappedKeypair.privateKey, msgHashBytes);
+    if (shouldForceFresh) {
+      await lock();
+    }
     const v = sig.yParity + 27;
     const rHex = Array.from(sig.r).map((b) => b.toString(16).padStart(2, "0")).join("");
     const sHex = Array.from(sig.s).map((b) => b.toString(16).padStart(2, "0")).join("");
@@ -1151,20 +1185,12 @@ function createPasskeyProvider(passkey, options) {
     return `0x${rHex}${sHex}${vHex}`;
   };
   const getPublicKey = async () => {
-    await ensureSession();
+    await ensureSession({ });
     if (!unwrappedKeypair) {
       throw new Error(`${ERR_INVALID_PARAM}: Session not established`);
     }
     return new Uint8Array(unwrappedKeypair.publicKey);
   };
-  const lock = async () => {
-    if (unwrappedKeypair) {
-      console.log("[PasskeyProvider] lock(): zeroizing sensitive data from memory");
-      zeroize(unwrappedKeypair.privateKey);
-      zeroize(unwrappedKeypair.publicKey);
-      unwrappedKeypair = null;
-    }
-  };
   return {
     keyStorageType: "passkey",
     ensureSession,
@@ -1283,6 +1309,6 @@ async function selectSigner2(ctx) {
   );
 }
 
-export { ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, EIP1193ErrorCode, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, ExternalWalletSigner, PasskeyP256Signer, RequestPendingError, Secp256k1SoftwareSigner, TYPES, UnauthorizedError, UnsupportedMethodError, UserRejectedError, VolrError, WalletError, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner2 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };
+export { ChainNotAddedError, DEFAULT_EVM_PATH, DOMAIN, EIP1193ErrorCode, EIP712_DOMAIN, ERR_AAD_MISMATCH, ERR_CHAIN_MISMATCH, ERR_CRYPTO_FAIL, ERR_INVALID_PARAM, ERR_LOW_ENTROPY, ERR_NONCE_SIZE, ExternalWalletSigner, PasskeyP256Signer, RequestPendingError, Secp256k1SoftwareSigner, TYPES, UnauthorizedError, UnsupportedMethodError, UserRejectedError, VolrError, WalletError, WrongNetworkError, ZERO_ADDRESS, ZERO_HASH, aesGcmDecrypt, aesGcmEncrypt, buildSignedBatchMessage, computeCallsHash, createMasterKeyProvider, createMpcProvider, createPasskeyProvider, deriveEvmKey, deriveWrapKey, evmSign, evmVerify, generateNonce, getAuthNonce, getRandomBytes, hkdfSha256, normalizeWalletError, sealMasterSeed, selectSigner, selectSigner2 as selectSignerLegacy, signAuthorization, signSession, toChecksumAddress, unsealMasterSeed, uploadBlob, uploadBlobViaPresign, zeroize };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map