@teneo-protocol/sdk 1.0.0

package/dist/utils/secure-private-key.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Secure private key storage with in-memory encryption
+ * Addresses SEC-3: Private Key Exposure Risk
+ *
+ * This class encrypts private keys in memory using AES-256-GCM to prevent
+ * exposure through memory dumps, heap snapshots, or accidental logging.
+ *
+ * @example
+ * ```typescript
+ * const secureKey = new SecurePrivateKey(privateKey);
+ *
+ * // Use the key temporarily for signing
+ * const signature = secureKey.use((key) => {
+ *   return signMessage(key);
+ * });
+ *
+ * // Clean up when done
+ * secureKey.destroy();
+ * ```
+ */
+/**
+ * Securely stores and manages an encrypted private key in memory.
+ *
+ * The key is encrypted immediately upon construction and only decrypted
+ * temporarily when needed for operations like signing. Decrypted keys
+ * are zeroed out immediately after use.
+ */
+export declare class SecurePrivateKey {
+    private encrypted;
+    private encryptionKey;
+    private destroyed;
+    /**
+     * Creates a new secure private key storage.
+     * The provided private key is encrypted immediately and the original
+     * string becomes eligible for garbage collection.
+     *
+     * @param privateKey - The private key to encrypt and store securely
+     * @throws {Error} If private key is empty or invalid
+     */
+    constructor(privateKey: string);
+    /**
+     * Temporarily decrypts the private key and passes it to the provided function.
+     * The decrypted key is automatically zeroed out after the function completes,
+     * whether it succeeds or throws an error.
+     *
+     * This is the only way to access the decrypted private key, ensuring minimal
+     * exposure time in plaintext.
+     *
+     * @template T - The return type of the function
+     * @param fn - Function that uses the decrypted private key
+     * @returns The result of the function
+     * @throws {Error} If the key has been destroyed
+     * @throws Any error thrown by the provided function
+     *
+     * @example
+     * ```typescript
+     * const account = secureKey.use((key) => privateKeyToAccount(key));
+     * const signature = secureKey.use((key) => account.signMessage(key));
+     * ```
+     */
+    use<T>(fn: (key: string) => T): T;
+    /**
+     * Destroys this secure key by zeroing out all sensitive buffers.
+     * After calling destroy(), this instance can no longer be used.
+     *
+     * This should be called when the SDK is disconnected or the key
+     * is no longer needed to prevent memory exposure.
+     *
+     * @example
+     * ```typescript
+     * secureKey.destroy();
+     * // secureKey.use(...) will now throw an error
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Checks if this secure key has been destroyed.
+     *
+     * @returns True if destroyed, false otherwise
+     */
+    isDestroyed(): boolean;
+    /**
+     * Encrypts the private key using AES-256-GCM.
+     *
+     * The encrypted buffer format is: [IV (16 bytes) | Auth Tag (16 bytes) | Ciphertext]
+     *
+     * @param data - The private key to encrypt
+     * @returns Buffer containing IV + auth tag + encrypted data
+     */
+    private encrypt;
+    /**
+     * Decrypts the stored private key.
+     *
+     * @returns The decrypted private key as a string
+     * @throws {Error} If decryption fails (tampered data or wrong key)
+     */
+    private decrypt;
+    /**
+     * Best-effort attempt to zero out a string in memory.
+     * JavaScript strings are immutable, but we can try to overwrite
+     * the backing buffer if it exists.
+     *
+     * @param str - The string to zero out
+     */
+    private zeroOutString;
+    /**
+     * Checks if this instance has been destroyed and throws if so.
+     *
+     * @throws {Error} If the key has been destroyed
+     */
+    private checkNotDestroyed;
+}
+//# sourceMappingURL=secure-private-key.d.ts.map

package/dist/utils/secure-private-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-private-key.d.ts","sourceRoot":"","sources":["../../src/utils/secure-private-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,SAAS,CAAS;IAE1B;;;;;;;OAOG;gBACS,UAAU,EAAE,MAAM;IAc9B;;;;;;;;;;;;;;;;;;;OAmBG;IACI,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC;IAcxC;;;;;;;;;;;;OAYG;IACI,OAAO,IAAI,IAAI;IAYtB;;;;OAIG;IACI,WAAW,IAAI,OAAO;IAI7B;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAoBf;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAmBf;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IASrB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAK1B"}

package/dist/utils/secure-private-key.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Secure private key storage with in-memory encryption
+ * Addresses SEC-3: Private Key Exposure Risk
+ *
+ * This class encrypts private keys in memory using AES-256-GCM to prevent
+ * exposure through memory dumps, heap snapshots, or accidental logging.
+ *
+ * @example
+ * ```typescript
+ * const secureKey = new SecurePrivateKey(privateKey);
+ *
+ * // Use the key temporarily for signing
+ * const signature = secureKey.use((key) => {
+ *   return signMessage(key);
+ * });
+ *
+ * // Clean up when done
+ * secureKey.destroy();
+ * ```
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurePrivateKey = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Securely stores and manages an encrypted private key in memory.
+ *
+ * The key is encrypted immediately upon construction and only decrypted
+ * temporarily when needed for operations like signing. Decrypted keys
+ * are zeroed out immediately after use.
+ */
+class SecurePrivateKey {
+    /**
+     * Creates a new secure private key storage.
+     * The provided private key is encrypted immediately and the original
+     * string becomes eligible for garbage collection.
+     *
+     * @param privateKey - The private key to encrypt and store securely
+     * @throws {Error} If private key is empty or invalid
+     */
+    constructor(privateKey) {
+        this.destroyed = false;
+        if (!privateKey || typeof privateKey !== 'string') {
+            throw new Error('Private key must be a non-empty string');
+        }
+        // Generate a random encryption key for AES-256
+        this.encryptionKey = crypto_1.default.randomBytes(32);
+        // Encrypt the private key immediately
+        this.encrypted = this.encrypt(privateKey);
+        // Original privateKey string will be garbage collected
+    }
+    /**
+     * Temporarily decrypts the private key and passes it to the provided function.
+     * The decrypted key is automatically zeroed out after the function completes,
+     * whether it succeeds or throws an error.
+     *
+     * This is the only way to access the decrypted private key, ensuring minimal
+     * exposure time in plaintext.
+     *
+     * @template T - The return type of the function
+     * @param fn - Function that uses the decrypted private key
+     * @returns The result of the function
+     * @throws {Error} If the key has been destroyed
+     * @throws Any error thrown by the provided function
+     *
+     * @example
+     * ```typescript
+     * const account = secureKey.use((key) => privateKeyToAccount(key));
+     * const signature = secureKey.use((key) => account.signMessage(key));
+     * ```
+     */
+    use(fn) {
+        this.checkNotDestroyed();
+        const decrypted = this.decrypt();
+        try {
+            return fn(decrypted);
+        }
+        finally {
+            // Zero out the decrypted string in memory
+            // Note: This is best-effort as JavaScript strings are immutable
+            // but we overwrite the backing buffer
+            this.zeroOutString(decrypted);
+        }
+    }
+    /**
+     * Destroys this secure key by zeroing out all sensitive buffers.
+     * After calling destroy(), this instance can no longer be used.
+     *
+     * This should be called when the SDK is disconnected or the key
+     * is no longer needed to prevent memory exposure.
+     *
+     * @example
+     * ```typescript
+     * secureKey.destroy();
+     * // secureKey.use(...) will now throw an error
+     * ```
+     */
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        // Zero out all sensitive buffers
+        this.encryptionKey.fill(0);
+        this.encrypted.fill(0);
+        this.destroyed = true;
+    }
+    /**
+     * Checks if this secure key has been destroyed.
+     *
+     * @returns True if destroyed, false otherwise
+     */
+    isDestroyed() {
+        return this.destroyed;
+    }
+    /**
+     * Encrypts the private key using AES-256-GCM.
+     *
+     * The encrypted buffer format is: [IV (16 bytes) | Auth Tag (16 bytes) | Ciphertext]
+     *
+     * @param data - The private key to encrypt
+     * @returns Buffer containing IV + auth tag + encrypted data
+     */
+    encrypt(data) {
+        // Generate random initialization vector
+        const iv = crypto_1.default.randomBytes(16);
+        // Create cipher
+        const cipher = crypto_1.default.createCipheriv('aes-256-gcm', this.encryptionKey, iv);
+        // Encrypt the data
+        const encrypted = Buffer.concat([
+            cipher.update(data, 'utf8'),
+            cipher.final()
+        ]);
+        // Get authentication tag for integrity verification
+        const authTag = cipher.getAuthTag();
+        // Combine IV + authTag + encrypted data
+        return Buffer.concat([iv, authTag, encrypted]);
+    }
+    /**
+     * Decrypts the stored private key.
+     *
+     * @returns The decrypted private key as a string
+     * @throws {Error} If decryption fails (tampered data or wrong key)
+     */
+    decrypt() {
+        // Extract components from encrypted buffer
+        const iv = this.encrypted.subarray(0, 16);
+        const authTag = this.encrypted.subarray(16, 32);
+        const ciphertext = this.encrypted.subarray(32);
+        // Create decipher
+        const decipher = crypto_1.default.createDecipheriv('aes-256-gcm', this.encryptionKey, iv);
+        decipher.setAuthTag(authTag);
+        // Decrypt the data
+        const decrypted = Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final()
+        ]);
+        return decrypted.toString('utf8');
+    }
+    /**
+     * Best-effort attempt to zero out a string in memory.
+     * JavaScript strings are immutable, but we can try to overwrite
+     * the backing buffer if it exists.
+     *
+     * @param str - The string to zero out
+     */
+    zeroOutString(str) {
+        // Convert to buffer and zero it out
+        const buffer = Buffer.from(str, 'utf8');
+        buffer.fill(0);
+        // Note: The original string object may still exist in memory
+        // until garbage collected, but this reduces the attack surface
+    }
+    /**
+     * Checks if this instance has been destroyed and throws if so.
+     *
+     * @throws {Error} If the key has been destroyed
+     */
+    checkNotDestroyed() {
+        if (this.destroyed) {
+            throw new Error('SecurePrivateKey has been destroyed and can no longer be used');
+        }
+    }
+}
+exports.SecurePrivateKey = SecurePrivateKey;
+//# sourceMappingURL=secure-private-key.js.map

package/dist/utils/secure-private-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-private-key.js","sourceRoot":"","sources":["../../src/utils/secure-private-key.ts"],"names":[],"mappings":"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"}

package/dist/utils/signature-verifier.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Signature Verifier for Message Authentication
+ * Provides cryptographic verification of message signatures using Ethereum ECDSA
+ */
+import { type Address } from 'viem';
+import { BaseMessage, MessageType } from '../types';
+/**
+ * Options for signature verification
+ */
+export interface SignatureVerificationOptions {
+    /** Whitelist of trusted agent addresses (empty = allow all) */
+    trustedAddresses?: Address[];
+    /** Message types that require signatures */
+    requireSignaturesFor?: MessageType[];
+    /** Reject messages with missing signatures (vs just warn) */
+    strictMode?: boolean;
+}
+/**
+ * Result of signature verification
+ */
+export interface VerificationResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Recovered address from signature (if signature present) */
+    recoveredAddress?: Address;
+    /** Reason for failure (if not valid) */
+    reason?: string;
+    /** Whether signature was missing */
+    signatureMissing: boolean;
+    /** Whether address is in trusted whitelist (if whitelist configured) */
+    isTrusted?: boolean;
+}
+/**
+ * Signature verifier for authenticating message origins
+ * Prevents spoofing attacks by verifying Ethereum signatures on messages
+ *
+ * @example
+ * ```typescript
+ * const verifier = new SignatureVerifier({
+ *   trustedAddresses: ['0x123...', '0x456...'],
+ *   requireSignaturesFor: ['task_response', 'agent_selected'],
+ *   strictMode: true
+ * });
+ *
+ * const result = await verifier.verify(message);
+ * if (!result.valid) {
+ *   console.log(`Verification failed: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare class SignatureVerifier {
+    private readonly options;
+    /**
+     * Creates a new signature verifier
+     *
+     * @param options - Verification options
+     *
+     * @example
+     * ```typescript
+     * const verifier = new SignatureVerifier({
+     *   trustedAddresses: ['0x123...'],
+     *   requireSignaturesFor: ['task_response'],
+     *   strictMode: false
+     * });
+     * ```
+     */
+    constructor(options?: SignatureVerificationOptions);
+    /**
+     * Verify a message's signature
+     *
+     * @param message - The message to verify
+     * @returns Verification result with validity and recovered address
+     *
+     * @example
+     * ```typescript
+     * const result = await verifier.verify(message);
+     * if (result.valid) {
+     *   console.log(`Valid signature from ${result.recoveredAddress}`);
+     * } else {
+     *   console.log(`Invalid: ${result.reason}`);
+     * }
+     * ```
+     */
+    verify(message: BaseMessage): Promise<VerificationResult>;
+    /**
+     * Create a canonical hash of message content for signing
+     *
+     * @param content - The signable content object
+     * @returns Message hash string
+     */
+    createMessageHash(content: object): string;
+    /**
+     * Extract signable content from message
+     * Excludes signature and publicKey fields to prevent circular dependency
+     *
+     * @param message - The message to extract content from
+     * @returns Object containing signable fields
+     */
+    getSignableContent(message: BaseMessage): object;
+    /**
+     * Check if signature is required for a message type
+     *
+     * @param messageType - The type of message
+     * @returns True if signature is required
+     */
+    isSignatureRequired(messageType: MessageType): boolean;
+    /**
+     * Check if an address is in the trusted whitelist
+     *
+     * @param address - The address to check
+     * @returns True if address is trusted (or no whitelist configured)
+     */
+    isTrustedAddress(address: Address): boolean;
+    /**
+     * Get the address to verify against
+     * Tries publicKey first, falls back to 'from' field
+     *
+     * @param message - The message to get address from
+     * @returns Address to verify, or undefined if none available
+     */
+    private getVerificationAddress;
+    /**
+     * Update verification options
+     *
+     * @param options - New options (merged with existing)
+     *
+     * @example
+     * ```typescript
+     * verifier.updateOptions({
+     *   trustedAddresses: ['0x789...'],
+     *   strictMode: true
+     * });
+     * ```
+     */
+    updateOptions(options: Partial<SignatureVerificationOptions>): void;
+    /**
+     * Get current verification options
+     *
+     * @returns Copy of current options
+     */
+    getOptions(): SignatureVerificationOptions;
+}
+//# sourceMappingURL=signature-verifier.d.ts.map

package/dist/utils/signature-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature-verifier.d.ts","sourceRoot":"","sources":["../../src/utils/signature-verifier.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA8B,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,OAAO,EAAE,CAAC;IAE7B,4CAA4C;IAC5C,oBAAoB,CAAC,EAAE,WAAW,EAAE,CAAC;IAErC,6DAA6D;IAC7D,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IAEf,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oCAAoC;IACpC,gBAAgB,EAAE,OAAO,CAAC;IAE1B,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IAEjE;;;;;;;;;;;;;OAaG;gBACS,OAAO,GAAE,4BAAiC;IAQtD;;;;;;;;;;;;;;;OAeG;IACU,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA8EtE;;;;;OAKG;IACI,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAQjD;;;;;;OAMG;IACI,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM;IAcvD;;;;;OAKG;IACI,mBAAmB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO;IAI7D;;;;;OAKG;IACI,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAUlD;;;;;;OAMG;YACW,sBAAsB;IAiBpC;;;;;;;;;;;;OAYG;IACI,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,4BAA4B,CAAC,GAAG,IAAI;IAY1E;;;;OAIG;IACI,UAAU,IAAI,4BAA4B;CAGlD"}

package/dist/utils/signature-verifier.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * Signature Verifier for Message Authentication
+ * Provides cryptographic verification of message signatures using Ethereum ECDSA
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignatureVerifier = void 0;
+const viem_1 = require("viem");
+/**
+ * Signature verifier for authenticating message origins
+ * Prevents spoofing attacks by verifying Ethereum signatures on messages
+ *
+ * @example
+ * ```typescript
+ * const verifier = new SignatureVerifier({
+ *   trustedAddresses: ['0x123...', '0x456...'],
+ *   requireSignaturesFor: ['task_response', 'agent_selected'],
+ *   strictMode: true
+ * });
+ *
+ * const result = await verifier.verify(message);
+ * if (!result.valid) {
+ *   console.log(`Verification failed: ${result.reason}`);
+ * }
+ * ```
+ */
+class SignatureVerifier {
+    /**
+     * Creates a new signature verifier
+     *
+     * @param options - Verification options
+     *
+     * @example
+     * ```typescript
+     * const verifier = new SignatureVerifier({
+     *   trustedAddresses: ['0x123...'],
+     *   requireSignaturesFor: ['task_response'],
+     *   strictMode: false
+     * });
+     * ```
+     */
+    constructor(options = {}) {
+        this.options = {
+            trustedAddresses: options.trustedAddresses || [],
+            requireSignaturesFor: options.requireSignaturesFor || [],
+            strictMode: options.strictMode !== undefined ? options.strictMode : false
+        };
+    }
+    /**
+     * Verify a message's signature
+     *
+     * @param message - The message to verify
+     * @returns Verification result with validity and recovered address
+     *
+     * @example
+     * ```typescript
+     * const result = await verifier.verify(message);
+     * if (result.valid) {
+     *   console.log(`Valid signature from ${result.recoveredAddress}`);
+     * } else {
+     *   console.log(`Invalid: ${result.reason}`);
+     * }
+     * ```
+     */
+    async verify(message) {
+        // Check if signature is present
+        if (!message.signature) {
+            const isRequired = this.isSignatureRequired(message.type);
+            return {
+                valid: !isRequired && !this.options.strictMode,
+                signatureMissing: true,
+                reason: isRequired
+                    ? `Signature required for message type '${message.type}'`
+                    : 'Signature missing but not required'
+            };
+        }
+        // Extract signable content (excludes signature and publicKey fields)
+        const signableContent = this.getSignableContent(message);
+        // Create canonical message hash
+        const messageHash = this.createMessageHash(signableContent);
+        try {
+            // Determine which address to verify against
+            const addressToVerify = await this.getVerificationAddress(message);
+            if (!addressToVerify) {
+                return {
+                    valid: false,
+                    signatureMissing: false,
+                    reason: 'No address available for verification (missing publicKey and from fields)'
+                };
+            }
+            // Verify signature using viem
+            const isValid = await (0, viem_1.verifyMessage)({
+                address: addressToVerify,
+                message: messageHash,
+                signature: message.signature
+            });
+            if (!isValid) {
+                return {
+                    valid: false,
+                    recoveredAddress: addressToVerify,
+                    signatureMissing: false,
+                    reason: 'Signature verification failed - signature does not match message content'
+                };
+            }
+            // Check if address is trusted (if whitelist configured)
+            const isTrusted = this.isTrustedAddress(addressToVerify);
+            // If whitelist is configured and address is not trusted, reject
+            if (this.options.trustedAddresses.length > 0 && !isTrusted) {
+                return {
+                    valid: false,
+                    recoveredAddress: addressToVerify,
+                    signatureMissing: false,
+                    isTrusted: false,
+                    reason: `Address ${addressToVerify} is not in trusted whitelist`
+                };
+            }
+            return {
+                valid: true,
+                recoveredAddress: addressToVerify,
+                signatureMissing: false,
+                isTrusted
+            };
+        }
+        catch (error) {
+            return {
+                valid: false,
+                signatureMissing: false,
+                reason: `Signature verification error: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    /**
+     * Create a canonical hash of message content for signing
+     *
+     * @param content - The signable content object
+     * @returns Message hash string
+     */
+    createMessageHash(content) {
+        // Create canonical JSON string (sorted keys for consistency)
+        const canonical = JSON.stringify(content, Object.keys(content).sort());
+        // Use viem's hashMessage for Ethereum-compatible hashing
+        return (0, viem_1.hashMessage)(canonical);
+    }
+    /**
+     * Extract signable content from message
+     * Excludes signature and publicKey fields to prevent circular dependency
+     *
+     * @param message - The message to extract content from
+     * @returns Object containing signable fields
+     */
+    getSignableContent(message) {
+        const { signature, publicKey, id, ...signableContent } = message;
+        // Include only defined fields for consistent hashing
+        const filtered = {};
+        for (const [key, value] of Object.entries(signableContent)) {
+            if (value !== undefined) {
+                filtered[key] = value;
+            }
+        }
+        return filtered;
+    }
+    /**
+     * Check if signature is required for a message type
+     *
+     * @param messageType - The type of message
+     * @returns True if signature is required
+     */
+    isSignatureRequired(messageType) {
+        return this.options.requireSignaturesFor.includes(messageType);
+    }
+    /**
+     * Check if an address is in the trusted whitelist
+     *
+     * @param address - The address to check
+     * @returns True if address is trusted (or no whitelist configured)
+     */
+    isTrustedAddress(address) {
+        if (this.options.trustedAddresses.length === 0) {
+            return true; // No whitelist = trust all
+        }
+        return this.options.trustedAddresses.some(trusted => trusted.toLowerCase() === address.toLowerCase());
+    }
+    /**
+     * Get the address to verify against
+     * Tries publicKey first, falls back to 'from' field
+     *
+     * @param message - The message to get address from
+     * @returns Address to verify, or undefined if none available
+     */
+    async getVerificationAddress(message) {
+        // If message includes publicKey, derive address from it
+        if (message.publicKey) {
+            // publicKey should be an Ethereum address already
+            // If it's actually a public key, we'd need to derive the address
+            // For now, assume publicKey field contains the address
+            return message.publicKey;
+        }
+        // Fall back to 'from' field if it looks like an address
+        if (message.from && message.from.startsWith('0x') && message.from.length === 42) {
+            return message.from;
+        }
+        return undefined;
+    }
+    /**
+     * Update verification options
+     *
+     * @param options - New options (merged with existing)
+     *
+     * @example
+     * ```typescript
+     * verifier.updateOptions({
+     *   trustedAddresses: ['0x789...'],
+     *   strictMode: true
+     * });
+     * ```
+     */
+    updateOptions(options) {
+        if (options.trustedAddresses !== undefined) {
+            this.options.trustedAddresses = options.trustedAddresses;
+        }
+        if (options.requireSignaturesFor !== undefined) {
+            this.options.requireSignaturesFor = options.requireSignaturesFor;
+        }
+        if (options.strictMode !== undefined) {
+            this.options.strictMode = options.strictMode;
+        }
+    }
+    /**
+     * Get current verification options
+     *
+     * @returns Copy of current options
+     */
+    getOptions() {
+        return { ...this.options };
+    }
+}
+exports.SignatureVerifier = SignatureVerifier;
+//# sourceMappingURL=signature-verifier.js.map