emblem-vault-ai-signers 0.1.4 → 0.1.5

package/README.md

@@ -208,6 +208,82 @@ On first use, both adapters query `GET /vault/info` with header `x-api-key` to o
 
 Transactions are normalized to hex/number-like fields before submission.
 
+## Security Considerations
+
+### Client-Side Usage
+
+This library is designed for environments where **users provide their own API keys**. When used client-side (browser/dApp):
+
+#### Trust Model
+- **Users must trust the dApp code** - Any JavaScript running in the browser has full access to API keys
+- **No technical enforcement possible** - Browser dev tools, breakpoints, and code injection can modify any behavior
+- **baseUrl is configurable** - Required for development/staging/production environments
+- **Transparent by design** - This is a feature, not a bug
+
+#### What This Means
+```javascript
+// Users provide their OWN API keys to YOUR dApp
+const client = createEmblemClient({
+  apiKey: userApiKey, // User's key, not yours
+  baseUrl: "https://api.emblemvault.ai"
+});
+```
+
+If a user runs your dApp code, they are trusting it with their API key and signing authority. There is no way to prevent malicious dApp code from:
+- Logging API keys
+- Intercepting `fetch()` calls
+- Changing the `baseUrl`
+- Making unauthorized signing requests
+
+**This is the same trust model as MetaMask and other browser wallets.**
+
+### Best Practices for Users
+
+1. **Only use trusted dApps** - Verify the source and reputation
+2. **Review open source code** when possible
+3. **Use separate API keys** for different dApps
+4. **Monitor signing activity** in your Emblem dashboard
+5. **Test with staging keys first** before using production
+
+### Best Practices for Implementers
+
+1. **Open source your dApp** - Allow security audits
+2. **Document your security model** - Be transparent about API key handling
+3. **Minimize dependencies** - Reduce supply chain attack surface
+4. **Use Content Security Policy** - Add CSP headers to protect against XSS
+5. **Never log or store user API keys** - Only use them in-memory for signing
+6. **Implement proper error handling** - Don't expose API keys in error messages
+
+### Server-Side Usage
+
+When used server-side (Node.js):
+- Store API keys in environment variables
+- Never expose keys to client-side code
+- Use proper access controls and authentication
+- Implement rate limiting if exposing signing endpoints
+
+### Development vs Production
+
+This library supports multiple environments via `baseUrl`:
+
+```javascript
+// Development
+const devClient = createEmblemClient({
+  apiKey: process.env.DEV_API_KEY,
+  baseUrl: "https://dev-api.emblemvault.ai"
+});
+
+// Production
+const prodClient = createEmblemClient({
+  apiKey: process.env.PROD_API_KEY,
+  baseUrl: "https://api.emblemvault.ai"
+});
+```
+
+API keys from one environment do not work in another, providing natural isolation.
+
+---
+
 ## Testing
 
 - Copy `.env.example` to `.env` and set:

package/dist/ethers.d.ts

@@ -6,6 +6,7 @@ export declare class EmblemEthersWallet extends AbstractSigner {
     private _address;
     private _vaultId;
     private _chainId;
+    private _initPromise?;
     constructor(config: EmblemRemoteConfig, provider?: Provider | null, seed?: {
         address?: `0x${string}`;
         vaultId?: string;

package/dist/ethers.js

@@ -17,9 +17,18 @@ export class EmblemEthersWallet extends AbstractSigner {
             this._chainId = seed.chainId;
     }
     async initialize() {
-        const info = await fetchVaultInfo(this._config);
-        this._address = info.evmAddress;
-        this._vaultId = info.vaultId;
+        // Prevent race condition: cache the promise
+        if (this._initPromise)
+            return this._initPromise;
+        this._initPromise = fetchVaultInfo(this._config).then(info => {
+            this._address = info.evmAddress;
+            this._vaultId = info.vaultId;
+        }).catch(err => {
+            // Clear promise on error to allow retry
+            this._initPromise = undefined;
+            throw err;
+        });
+        return this._initPromise;
     }
     async getAddress() {
         if (!this._address)
@@ -67,6 +76,7 @@ export class EmblemEthersWallet extends AbstractSigner {
             await this.initialize();
         const from = tx.from;
         const addr = await this.getAddress();
+        // Validate from address if present, ensure it matches signer
         if (from && from.toLowerCase() !== addr.toLowerCase()) {
             throw new Error("transaction from does not match signer address");
         }

package/dist/http.js

@@ -1,3 +1,24 @@
+function sanitizeErrorMessage(status, text) {
+    // Sanitize error messages to avoid leaking sensitive server information
+    let errorMessage = `Emblem signer error ${status}`;
+    if (status >= 500) {
+        errorMessage += ": Internal server error";
+    }
+    else if (status === 401 || status === 403) {
+        errorMessage += ": Authentication failed";
+    }
+    else if (status === 404) {
+        errorMessage += ": Resource not found";
+    }
+    else if (status === 405) {
+        errorMessage += ": Method not allowed";
+    }
+    else if (text) {
+        // For 4xx client errors, include limited error details
+        errorMessage += `: ${text.substring(0, 200)}`; // Limit to 200 chars
+    }
+    return errorMessage;
+}
 export async function emblemPost(path, body, { apiKey, baseUrl = "https://api.emblemvault.ai" }) {
     const res = await fetch(`${baseUrl}${path}`, {
         method: "POST",
@@ -9,7 +30,7 @@ export async function emblemPost(path, body, { apiKey, baseUrl = "https://api.em
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(`Emblem signer error ${res.status}: ${text || res.statusText}`);
+        throw new Error(sanitizeErrorMessage(res.status, text));
     }
     return res.json();
 }
@@ -22,7 +43,7 @@ export async function emblemGet(path, { apiKey, baseUrl = "https://api.emblemvau
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");
-        throw new Error(`Emblem signer error ${res.status}: ${text || res.statusText}`);
+        throw new Error(sanitizeErrorMessage(res.status, text));
     }
     return res.json();
 }

package/dist/index.d.ts

@@ -1,13 +1,16 @@
 import type { Provider } from "ethers";
 import type { EmblemRemoteConfig } from "./types.js";
 export type { EmblemRemoteConfig, Hex, VaultInfo } from "./types.js";
+export type { EmblemSecurityConfig } from "./validation.js";
+export { isBrowserEnvironment, isNodeEnvironment } from "./validation.js";
 import { EmblemEthersWallet } from "./ethers.js";
 import { EmblemSolanaSigner } from "./solana.js";
 import { EmblemWeb3Adapter } from "./web3.js";
+import { type EmblemSecurityConfig } from "./validation.js";
 export declare class EmblemVaultClient {
     private readonly config;
     private _infoPromise?;
-    constructor(config: EmblemRemoteConfig);
+    constructor(config: EmblemRemoteConfig | EmblemSecurityConfig);
     /** Lazily fetch and cache vault info */
     private getInfo;
     toViemAccount(): Promise<{

package/dist/index.js

@@ -1,16 +1,25 @@
+export { isBrowserEnvironment, isNodeEnvironment } from "./validation.js";
 import { toViemAccount } from "./viem.js";
 import { toEthersWallet } from "./ethers.js";
 import { toSolanaKitSigner, toSolanaWeb3Signer } from "./solana.js";
 import { toWeb3Adapter } from "./web3.js";
 import { fetchVaultInfo } from "./vault.js";
+import { validateConfig } from "./validation.js";
 export class EmblemVaultClient {
     constructor(config) {
+        // Comprehensive security validation
+        validateConfig(config);
         this.config = config;
     }
     /** Lazily fetch and cache vault info */
     getInfo() {
-        if (!this._infoPromise)
-            this._infoPromise = fetchVaultInfo(this.config);
+        if (!this._infoPromise) {
+            this._infoPromise = fetchVaultInfo(this.config).catch(err => {
+                // Clear cache on error to allow retry
+                this._infoPromise = undefined;
+                throw err;
+            });
+        }
         return this._infoPromise;
     }
     async toViemAccount() {

package/dist/utils.js

@@ -1,3 +1,4 @@
+import { toSafeNumber } from "./validation.js";
 export function toHexIfBigInt(v) {
     return typeof v === "bigint" ? ("0x" + v.toString(16)) : v;
 }
@@ -22,9 +23,9 @@ export function normalizeTxForEmblem(tx) {
     if (out.maxPriorityFeePerGas !== undefined)
         out.maxPriorityFeePerGas = toHexIfBigInt(out.maxPriorityFeePerGas);
     if (out.nonce !== undefined)
-        out.nonce = Number(out.nonce);
+        out.nonce = toSafeNumber(out.nonce, 'nonce');
     if (out.chainId !== undefined)
-        out.chainId = Number(out.chainId);
+        out.chainId = toSafeNumber(out.chainId, 'chainId');
     // Some backends only accept legacy fields; fold EIP-1559 into gasPrice and drop unsupported keys
     if (out.maxFeePerGas !== undefined || out.maxPriorityFeePerGas !== undefined) {
         if (out.gasPrice === undefined && out.maxFeePerGas !== undefined) {

package/dist/validation.d.ts

@@ -0,0 +1,53 @@
+import type { EmblemRemoteConfig } from "./types.js";
+/**
+ * Environment detection utilities for warning about unsafe usage patterns
+ */
+/**
+ * Detect if code is running in a browser environment
+ */
+export declare function isBrowserEnvironment(): boolean;
+/**
+ * Check if we're in a Node.js server environment
+ */
+export declare function isNodeEnvironment(): boolean;
+/**
+ * Validate API key format and warn about potential security issues
+ */
+export declare function validateApiKey(apiKey: string, options?: {
+    warnOnBrowser?: boolean;
+}): void;
+/**
+ * Validate baseUrl format
+ */
+export declare function validateBaseUrl(baseUrl?: string): void;
+/**
+ * Validate Ethereum address format
+ */
+export declare function validateEthereumAddress(address: string): void;
+/**
+ * Validate vault ID
+ */
+export declare function validateVaultId(vaultId: string): void;
+/**
+ * Safe number conversion with bounds checking
+ */
+export declare function toSafeNumber(value: any, fieldName: string): number;
+/**
+ * Extended config with security options
+ */
+export interface EmblemSecurityConfig extends EmblemRemoteConfig {
+    /**
+     * Suppress browser environment warning
+     * @default false
+     */
+    warnOnBrowser?: boolean;
+    /**
+     * Enable debug logging for security-related checks
+     * @default false
+     */
+    debugSecurity?: boolean;
+}
+/**
+ * Comprehensive configuration validation
+ */
+export declare function validateConfig(config: EmblemSecurityConfig): void;

package/dist/validation.js

@@ -0,0 +1,111 @@
+/**
+ * Environment detection utilities for warning about unsafe usage patterns
+ */
+/**
+ * Detect if code is running in a browser environment
+ */
+export function isBrowserEnvironment() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+/**
+ * Check if we're in a Node.js server environment
+ */
+export function isNodeEnvironment() {
+    return typeof process !== 'undefined' &&
+        process.versions != null &&
+        process.versions.node != null;
+}
+/**
+ * Validate API key format and warn about potential security issues
+ */
+export function validateApiKey(apiKey, options = {}) {
+    if (!apiKey || typeof apiKey !== 'string') {
+        throw new Error('apiKey is required and must be a string');
+    }
+    if (apiKey.trim() === '') {
+        throw new Error('apiKey cannot be empty or whitespace');
+    }
+    // Warn if API key looks like it might be exposed in client-side code
+    if (options.warnOnBrowser !== false && isBrowserEnvironment()) {
+        console.warn('[Emblem Security Warning] API key is being used in a browser environment. ' +
+            'API keys should only be used server-side (Node.js). ' +
+            'Client-side usage exposes your API key to anyone who can view the page source. ' +
+            'To suppress this warning, pass { warnOnBrowser: false } to createEmblemClient().');
+    }
+    // Check for common mistakes
+    if (apiKey.startsWith('pk_') || apiKey.startsWith('sk_')) {
+        // Looks like a typical API key format - good
+    }
+    else if (apiKey.length < 16) {
+        console.warn('[Emblem Security Warning] API key seems unusually short. Is this correct?');
+    }
+}
+/**
+ * Validate baseUrl format
+ */
+export function validateBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return; // undefined is ok, will use default
+    if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+        throw new Error('baseUrl must be a valid HTTP(S) URL');
+    }
+    // Warn about http (not https)
+    if (baseUrl.startsWith('http://') && !baseUrl.includes('localhost') && !baseUrl.includes('127.0.0.1')) {
+        console.warn('[Emblem Security Warning] baseUrl uses HTTP instead of HTTPS. This is insecure for production use.');
+    }
+}
+/**
+ * Validate Ethereum address format
+ */
+export function validateEthereumAddress(address) {
+    if (!address || typeof address !== 'string') {
+        throw new Error('Address is required');
+    }
+    if (!address.startsWith('0x')) {
+        throw new Error('Address must start with 0x');
+    }
+    if (!/^0x[0-9a-fA-F]{40}$/.test(address)) {
+        throw new Error('Invalid Ethereum address format');
+    }
+}
+/**
+ * Validate vault ID
+ */
+export function validateVaultId(vaultId) {
+    if (!vaultId || typeof vaultId !== 'string') {
+        throw new Error('vaultId is required');
+    }
+    if (vaultId.trim() === '') {
+        throw new Error('vaultId cannot be empty');
+    }
+}
+/**
+ * Safe number conversion with bounds checking
+ */
+export function toSafeNumber(value, fieldName) {
+    const num = Number(value);
+    if (!Number.isSafeInteger(num)) {
+        throw new Error(`${fieldName} value ${value} exceeds safe integer range (max: ${Number.MAX_SAFE_INTEGER})`);
+    }
+    return num;
+}
+/**
+ * Comprehensive configuration validation
+ */
+export function validateConfig(config) {
+    // Validate API key
+    validateApiKey(config.apiKey, { warnOnBrowser: config.warnOnBrowser });
+    // Validate baseUrl if provided
+    if (config.baseUrl) {
+        validateBaseUrl(config.baseUrl);
+    }
+    // Security audit logging
+    if (config.debugSecurity) {
+        console.log('[Emblem Security Debug]', {
+            environment: isBrowserEnvironment() ? 'browser' : 'node',
+            hasBaseUrl: !!config.baseUrl,
+            apiKeyLength: config.apiKey.length,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}

package/dist/vault.js

@@ -1,12 +1,14 @@
-import { emblemGet, emblemPost } from "./http.js";
+import { emblemPost } from "./http.js";
 export async function fetchVaultInfo(config) {
-    let data;
-    try {
-        data = await emblemGet("/vault/info", config);
+    // Note: The server only supports POST for /vault/info
+    // No need to try GET first, just use POST directly
+    const data = await emblemPost("/vault/info", {}, config);
+    // Validate response data
+    if (!data.vaultId || !data.address || !data.evmAddress) {
+        throw new Error('Invalid vault info response: missing required fields');
     }
-    catch (err) {
-        // Some environments may require POST for this endpoint; try POST fallback
-        data = await emblemPost("/vault/info", {}, config);
+    if (!data.evmAddress.startsWith('0x')) {
+        throw new Error('Invalid evmAddress format in response');
     }
     return {
         vaultId: data.vaultId,

package/dist/viem.js

@@ -23,7 +23,8 @@ export async function toViemAccount(config, infoOverride) {
                 payload = message;
             }
             else {
-                payload = String(message);
+                // Don't silently convert objects to "[object Object]"
+                throw new Error(`Unsupported message type: ${typeof message}. Expected string, Uint8Array, or hex string.`);
             }
             const data = await emblemPost("/sign-eth-message", { vaultId, message: payload }, config);
             return data.signature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emblem-vault-ai-signers",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Emblem Vault remote signer adapters for viem and ethers",
   "type": "module",
   "main": "dist/index.js",