emblem-vault-ai-signers 0.1.8-experimental.0 → 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/package.json

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