emblem-vault-ai-signers 0.1.7 → 0.1.8-experimental.1

package/README.md

@@ -20,6 +20,9 @@ See the Changelog for release details: CHANGELOG.md
 npm install emblem-vault-ai-signers
 # and bring your own peers
 npm install ethers viem
+
+# Optional: for SDK integration
+npm install emblem-auth-sdk
 ```
 
 ## Usage
@@ -31,7 +34,11 @@ import { mainnet } from "viem/chains";
 import { JsonRpcProvider } from "ethers";
 
 const client = createEmblemClient({
-  apiKey: "your-x-api-key",
+  apiKey: "your-x-api-key", // traditional API key auth
+  // OR use JWT authentication (see Authentication section below)
+  // jwt: "your-jwt-token",
+  // OR use SDK integration
+  // sdk: yourAuthSDK,
   // baseUrl: "https://api.emblemvault.ai" // optional (tests use https://dev-api.emblemvault.ai)
 });
 
@@ -66,6 +73,142 @@ const solKit = await client.toSolanaKitSigner();
 console.log(solKit.publicKey);
 ```
 
+## Authentication
+
+The library supports multiple authentication methods. You only need to provide **one** of the following:
+
+### API Key Authentication (Traditional)
+
+```ts
+const client = createEmblemClient({
+  apiKey: "pk_your_api_key_here"
+});
+```
+
+### JWT Authentication
+
+#### Static JWT Token
+```ts
+const client = createEmblemClient({
+  jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+});
+```
+
+#### Dynamic JWT Provider
+For tokens that need refreshing or are fetched asynchronously:
+```ts
+const client = createEmblemClient({
+  getJwt: async () => {
+    // Fetch from your auth service, refresh if needed
+    return await authService.getAccessToken();
+  }
+});
+
+// Or synchronous
+const client = createEmblemClient({
+  getJwt: () => localStorage.getItem('authToken')
+});
+```
+
+### SDK Integration
+
+If you're using an authentication SDK that manages sessions:
+```ts
+const client = createEmblemClient({
+  sdk: myAuthSDK  // Must have getSession() method that returns { authToken }
+});
+
+// Example with EmblemAuthSDK:
+import { EmblemAuthSDK } from 'emblem-auth-sdk';
+
+const authSDK = new EmblemAuthSDK({
+  appId: 'your-app-id',
+  apiUrl: 'https://api.emblemvault.ai'
+});
+
+const client = createEmblemClient({
+  sdk: authSDK  // EmblemAuthSDK has getSession() that returns { authToken, user, ... }
+});
+
+// Example with custom auth SDK:
+const client = createEmblemClient({
+  sdk: {
+    getSession: () => ({
+      authToken: auth0.getIdToken(),
+      user: { id: '123' }
+    })
+  }
+});
+```
+
+### Custom Auth Headers
+
+For advanced authentication schemes:
+```ts
+const client = createEmblemClient({
+  getAuthHeaders: async () => ({
+    'Authorization': 'Custom my-custom-token',
+    'X-API-Version': '2.0',
+    'X-Client-ID': 'my-app'
+  })
+});
+```
+
+### Authentication Priority
+
+When multiple auth methods are provided, they're used in this order:
+1. `getAuthHeaders()` (highest priority)
+2. `apiKey`
+3. `jwt` / `getJwt()` / `sdk` (lowest priority)
+
+### Browser vs Server Usage
+
+- **Browser**: JWT/SDK authentication is recommended for client-side apps where users authenticate themselves
+- **Server**: API key authentication is recommended for server-side applications with stored credentials
+
+### Complete SDK Integration Example
+
+Here's a complete example using the EmblemAuthSDK with the signers library:
+
+```ts
+import { EmblemAuthSDK } from 'emblem-auth-sdk';
+import { createEmblemClient } from 'emblem-vault-ai-signers';
+import { JsonRpcProvider, parseEther } from 'ethers';
+
+// 1. Initialize the auth SDK
+const authSDK = new EmblemAuthSDK({
+  appId: 'your-app-id',
+  apiUrl: 'https://api.emblemvault.ai',
+  onSuccess: (session) => {
+    console.log('User authenticated:', session.user);
+  }
+});
+
+// 2. Create the signer client using the SDK
+const client = createEmblemClient({
+  sdk: authSDK  // Pass the SDK instance directly
+});
+
+// 3. Authenticate the user (opens auth modal)
+await authSDK.openAuthModal();
+
+// 4. Once authenticated, create wallets/accounts
+const provider = new JsonRpcProvider(process.env.RPC_URL);
+const wallet = await client.toEthersWallet(provider);
+
+// 5. Sign and send transactions
+const txHash = await wallet.signAndBroadcast({
+  to: "0x...",
+  value: parseEther("0.01")
+});
+```
+
+The SDK integration automatically handles:
+- JWT token management and refresh
+- Session persistence across page reloads
+- Authentication state management
+- Seamless integration with the signers library
+
 ## Replace Private Keys (Examples)
 
 Below are quick swaps showing how to remove local private keys and route signing through Emblem.
@@ -175,7 +318,13 @@ console.log(solWeb3.publicKey);
 
 ```ts
 type EmblemRemoteConfig = {
-  apiKey: string;
+  // Authentication (pick one method):
+  apiKey?: string;                    // traditional x-api-key header
+  jwt?: string;                       // static JWT for Authorization: Bearer
+  getJwt?: () => Promise<string> | string; // dynamic JWT provider
+  getAuthHeaders?: () => Promise<Record<string, string>> | Record<string, string>; // custom auth headers
+  sdk?: { getSession: () => { authToken?: string } | null }; // SDK integration (e.g., EmblemAuthSDK)
+
   baseUrl?: string; // default https://api.emblemvault.ai
 };
 
@@ -200,7 +349,7 @@ Adapters POST to the Emblem API endpoints:
 - `POST /sign-typed-message` – `{ vaultId, domain, types, message }`
 - `POST /sign-eth-tx` – `{ vaultId, transaction }` (expects ethers-serializable fields)
 
-On first use, both adapters query `GET /vault/info` with header `x-api-key` to obtain:
+On first use, both adapters query `POST /vault/info` with authentication headers to obtain:
 
 - Vault ID
 - Solana Address
@@ -222,15 +371,20 @@ This library is designed for environments where **users provide their own API ke
 
 #### What This Means
 ```javascript
-// Users provide their OWN API keys to YOUR dApp
+// Users provide their OWN credentials to YOUR dApp
 const client = createEmblemClient({
+  // Traditional API key
   apiKey: userApiKey, // User's key, not yours
+  // OR JWT token from user's authentication
+  jwt: userJwtToken, // User's JWT, not yours
+  // OR SDK integration
+  sdk: userAuthSDK, // User's auth SDK
   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
+If a user runs your dApp code, they are trusting it with their authentication credentials and signing authority. There is no way to prevent malicious dApp code from:
+- Logging API keys or JWT tokens
 - Intercepting `fetch()` calls
 - Changing the `baseUrl`
 - Making unauthorized signing requests
@@ -241,9 +395,10 @@ If a user runs your dApp code, they are trusting it with their API key and signi
 
 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
+3. **Use separate credentials** for different dApps (API keys, JWT tokens)
 4. **Monitor signing activity** in your Emblem dashboard
-5. **Test with staging keys first** before using production
+5. **Test with staging credentials first** before using production
+6. **Understand token expiration** - JWT tokens expire and may need refresh
 
 ### Best Practices for Implementers
 
@@ -251,16 +406,20 @@ If a user runs your dApp code, they are trusting it with their API key and signi
 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
+5. **Never log or store user credentials** - Only use API keys/JWTs in-memory for signing
+6. **Implement proper error handling** - Don't expose credentials in error messages
+7. **Handle JWT expiration gracefully** - Implement token refresh when using dynamic JWTs
+8. **Prefer JWT auth for client-side apps** - More secure than exposing long-lived API keys
 
 ### Server-Side Usage
 
 When used server-side (Node.js):
 - Store API keys in environment variables
-- Never expose keys to client-side code
+- Never expose credentials to client-side code
 - Use proper access controls and authentication
 - Implement rate limiting if exposing signing endpoints
+- Consider API key auth for server-to-server communication
+- Use JWT auth when proxying user authentication
 
 ### Development vs Production
 
@@ -273,14 +432,20 @@ const devClient = createEmblemClient({
   baseUrl: "https://dev-api.emblemvault.ai"
 });
 
-// Production
+// Production with API key
 const prodClient = createEmblemClient({
   apiKey: process.env.PROD_API_KEY,
   baseUrl: "https://api.emblemvault.ai"
 });
+
+// Production with JWT (client-side)
+const jwtClient = createEmblemClient({
+  getJwt: async () => await auth.getAccessToken(),
+  baseUrl: "https://api.emblemvault.ai"
+});
 ```
 
-API keys from one environment do not work in another, providing natural isolation.
+Credentials from one environment do not work in another, providing natural isolation.
 
 ---
 

package/dist/http.d.ts

@@ -1,3 +1,3 @@
 import type { EmblemRemoteConfig } from "./types.js";
-export declare function emblemPost<T = any>(path: string, body: any, { apiKey, baseUrl }: EmblemRemoteConfig): Promise<T>;
-export declare function emblemGet<T = any>(path: string, { apiKey, baseUrl }: EmblemRemoteConfig): Promise<T>;
+export declare function emblemPost<T = any>(path: string, body: any, config: EmblemRemoteConfig): Promise<T>;
+export declare function emblemGet<T = any>(path: string, config: EmblemRemoteConfig): Promise<T>;

package/dist/http.js

@@ -19,12 +19,30 @@ function sanitizeErrorMessage(status, text) {
     }
     return errorMessage;
 }
-export async function emblemPost(path, body, { apiKey, baseUrl = "https://api.emblemvault.ai" }) {
+async function resolveAuthHeaders(config) {
+    // Priority: custom headers -> apiKey -> jwt/getJwt/sdk
+    if (typeof config.getAuthHeaders === 'function') {
+        const h = await config.getAuthHeaders();
+        if (h && typeof h === 'object')
+            return h;
+    }
+    if (config.apiKey) {
+        return { 'x-api-key': config.apiKey };
+    }
+    const tok = config.jwt ?? (typeof config.getJwt === 'function' ? await config.getJwt() : undefined) ?? (config.sdk?.getSession()?.authToken ?? undefined);
+    if (tok) {
+        return { 'Authorization': `Bearer ${tok}` };
+    }
+    throw new Error('No authentication available: provide apiKey, jwt, getJwt(), getAuthHeaders(), or sdk');
+}
+export async function emblemPost(path, body, config) {
+    const baseUrl = config.baseUrl ?? "https://api.emblemvault.ai";
+    const authHeaders = await resolveAuthHeaders(config);
     const res = await fetch(`${baseUrl}${path}`, {
         method: "POST",
         headers: {
             "content-type": "application/json",
-            "x-api-key": apiKey,
+            ...authHeaders,
         },
         body: JSON.stringify(body, (key, value) => typeof value === "bigint" ? value.toString() : value),
     });
@@ -34,12 +52,12 @@ export async function emblemPost(path, body, { apiKey, baseUrl = "https://api.em
     }
     return res.json();
 }
-export async function emblemGet(path, { apiKey, baseUrl = "https://api.emblemvault.ai" }) {
+export async function emblemGet(path, config) {
+    const baseUrl = config.baseUrl ?? "https://api.emblemvault.ai";
+    const authHeaders = await resolveAuthHeaders(config);
     const res = await fetch(`${baseUrl}${path}`, {
         method: "GET",
-        headers: {
-            "x-api-key": apiKey,
-        },
+        headers: authHeaders,
     });
     if (!res.ok) {
         const text = await res.text().catch(() => "");

package/dist/types.d.ts

@@ -1,8 +1,23 @@
 export type Hex = `0x${string}`;
+/** Optional auth providers */
+export type EmblemAuthProvider = {
+    /** Static JWT to send as Authorization: Bearer */
+    jwt?: string;
+    /** Lazy JWT provider */
+    getJwt?: () => Promise<string | null | undefined> | string | null | undefined;
+    /** Custom headers provider (e.g., Authorization) */
+    getAuthHeaders?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** SDK-like object exposing getSession() that returns { authToken? } */
+    sdk?: {
+        getSession: () => {
+            authToken?: string | null | undefined;
+        } | null | undefined;
+    };
+};
 /** Config for Emblem remote signer */
-export type EmblemRemoteConfig = {
-    /** x-api-key for your authenticate middleware */
-    apiKey: string;
+export type EmblemRemoteConfig = EmblemAuthProvider & {
+    /** x-api-key for your authenticate middleware (optional when JWT provided) */
+    apiKey?: string;
     /** Base URL for the Emblem signer API */
     baseUrl?: string;
 };

package/dist/validation.d.ts

@@ -13,7 +13,7 @@ export declare function isNodeEnvironment(): boolean;
 /**
  * Validate API key format and warn about potential security issues
  */
-export declare function validateApiKey(apiKey: string, options?: {
+export declare function validateApiKey(apiKey?: string, options?: {
     warnOnBrowser?: boolean;
 }): void;
 /**

package/dist/validation.js

@@ -19,24 +19,20 @@ export function isNodeEnvironment() {
  * 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 == null)
+        return; // optional
+    if (typeof apiKey !== 'string') {
+        throw new Error('apiKey must be a string when provided');
     }
     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().');
+        console.warn('[Emblem Security Warning] API key is being used in a browser environment. '
+            + 'Prefer JWT or a secure server-side usage. '
+            + '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) {
+    if (!apiKey.startsWith('pk_') && !apiKey.startsWith('sk_') && apiKey.length < 16) {
         console.warn('[Emblem Security Warning] API key seems unusually short. Is this correct?');
     }
 }
@@ -93,7 +89,16 @@ export function toSafeNumber(value, fieldName) {
  * Comprehensive configuration validation
  */
 export function validateConfig(config) {
-    // Validate API key
+    // Validate auth: require at least one method (apiKey, jwt, getJwt, getAuthHeaders, sdk)
+    const hasApiKey = !!config.apiKey;
+    const hasJwt = !!config.jwt;
+    const hasGetJwt = typeof config.getJwt === 'function';
+    const hasHeaders = typeof config.getAuthHeaders === 'function';
+    const hasSdk = !!config.sdk && typeof config.sdk.getSession === 'function';
+    if (!hasApiKey && !hasJwt && !hasGetJwt && !hasHeaders && !hasSdk) {
+        throw new Error('Authentication required: provide apiKey, jwt, getJwt(), getAuthHeaders(), or sdk');
+    }
+    // Validate API key if present
     validateApiKey(config.apiKey, { warnOnBrowser: config.warnOnBrowser });
     // Validate baseUrl if provided
     if (config.baseUrl) {
@@ -104,7 +109,7 @@ export function validateConfig(config) {
         console.log('[Emblem Security Debug]', {
             environment: isBrowserEnvironment() ? 'browser' : 'node',
             hasBaseUrl: !!config.baseUrl,
-            apiKeyLength: config.apiKey.length,
+            apiKeyLength: config.apiKey ? config.apiKey.length : 0,
             timestamp: new Date().toISOString(),
         });
     }

package/dist/vault.js

@@ -3,17 +3,17 @@ export async function fetchVaultInfo(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) {
+    // Validate required response data (vaultId + evmAddress are required for EVM)
+    if (!data || !data.vaultId || !data.evmAddress) {
         throw new Error('Invalid vault info response: missing required fields');
     }
-    if (!data.evmAddress.startsWith('0x')) {
+    if (!String(data.evmAddress).startsWith('0x')) {
         throw new Error('Invalid evmAddress format in response');
     }
     return {
         vaultId: data.vaultId,
         tokenId: data.vaultId,
-        address: data.address,
+        address: data.address || '', // Solana address may be absent; keep optional
         evmAddress: data.evmAddress,
         created_by: data.created_by,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emblem-vault-ai-signers",
-  "version": "0.1.7",
+  "version": "0.1.8-experimental.1",
   "description": "Emblem Vault remote signer adapters for viem and ethers",
   "type": "module",
   "main": "dist/index.js",
@@ -25,7 +25,8 @@
     "test:ci": "vitest run --reporter=default",
     "test:integration": "vitest -c vitest.int.config.ts run --reporter=verbose",
     "test:all": "npm test && npm run test:integration",
-    "release:patch": "npm version patch && npm run build && npm run test:all && npm publish"
+    "release:patch": "npm version patch && npm run build && npm run test:all && npm publish",
+    "release:experimental": "npm version prerelease --preid=experimental && npm run build && npm run test:all && npm publish --tag experimental"
   },
   "keywords": [
     "emblem",