@bounded-sh/server 0.0.41 → 0.0.44

package/README.md

@@ -1,6 +1,6 @@
 # @bounded-sh/server
 
-Server SDK for Tarobase API - Node.js/Backend implementation. This package provides functionality for server-side applications to interact with the Tarobase API using Solana keypairs for authentication.
+Server SDK for the Bounded API. It provides explicit, isolated Solana-keypair or EVM-private-key clients for backend applications; no signer is loaded from ambient process state.
 
 ## Installation
 
@@ -16,7 +16,7 @@ yarn add @bounded-sh/server
 
 ## Features
 
-- Server-side authentication using Solana keypairs
+- Server-side authentication using Solana keypairs or EVM private keys (SIWS/SIWE)
 - In-memory session management (no cookies or local storage required)
 - Support for all Tarobase data operations (get, getMany, set, query)
 - Real-time subscriptions
@@ -86,6 +86,27 @@ const signature = await wallet.signMessage("Hello, world!");
 // const signature = await wallet.signAndSubmitTransaction(transaction);
 ```
 
+### EVM Keypair Client
+
+EVM clients require a trusted RPC and deployed `BoundedRuntime` address. A write response can select only an explicitly configured chain/runtime pair, and the SDK verifies the returned `setDocuments` calldata against the requested app, paths, actions, and values before signing.
+
+```typescript
+import { init, createWalletClient } from '@bounded-sh/server';
+
+await init({ appId: 'your-app-id', chain: 'base' });
+
+const wallet = await createWalletClient({
+  evmPrivateKey: process.env.EVM_PRIVATE_KEY!,
+  chainId: 8453,
+  rpcUrl: process.env.BASE_RPC_URL!,
+  runtimeAddress: process.env.BOUNDED_RUNTIME_BASE!,
+});
+
+await wallet.set('todos/123', { text: 'Buy milk', completed: false });
+```
+
+For deliberate multi-chain use, provide `chains: { [chainId]: { rpcUrl, runtimeAddress } }`. There is no implicit RPC, runtime address, or chain switch.
+
 ### Subscriptions
 
 ```typescript
@@ -117,7 +138,16 @@ function getWebhookKeysUrl(): string | undefined;
 ### Authentication
 
 ```typescript
-function createWalletClient(options: { keypair: string }): Promise<WalletClient>;
+function createWalletClient(options:
+  | { keypair: string }
+  | {
+      evmPrivateKey: string;
+      chainId: number;
+      rpcUrl?: string;
+      runtimeAddress?: string;
+      chains?: Record<string, { rpcUrl: string; runtimeAddress: string; name?: string }>;
+    }
+): Promise<WalletClient>;
 function getAuthProvider(): Promise<AuthProvider>; // always rejects; no process-global provider
 function getIdToken(): Promise<string | null>; // always rejects; no process-global session
 ```
@@ -212,7 +242,7 @@ Please see the main repository for contribution guidelines.
 
 This server-side SDK differs from the web SDK in several important ways:
 
-1. **Authentication Method**: Uses Solana keypairs instead of browser wallets
+1. **Authentication Method**: Uses explicit Solana or EVM keys instead of browser wallets
 2. **Storage Strategy**: Uses in-memory storage instead of localStorage/sessionStorage 
 3. **Environment**: Optimized for Node.js/backend environments rather than browsers
 4. **Session Management**: Does not rely on browser-specific APIs

package/dist/auth/providers/evm-keypair-provider.d.ts

@@ -0,0 +1,33 @@
+import type { AuthProvider, EVMTransaction, SolTransaction, TransactionResult, User, SetOptions } from '@bounded-sh/core';
+import type { PublicKey, Transaction, VersionedTransaction } from '@solana/web3.js';
+export interface EvmKeypairChainConfig {
+    chainId: number;
+    rpcUrl: string;
+    runtimeAddress: string;
+    name?: string;
+}
+export declare class EvmKeypairProvider implements AuthProvider {
+    readonly address: string;
+    readonly defaultChainId: number;
+    private readonly account;
+    private readonly chains;
+    constructor(privateKey: string, defaultChainId: number, chainConfigs: EvmKeypairChainConfig[]);
+    private user;
+    createBoundedSession(): Promise<{
+        address: string;
+        accessToken: string;
+        idToken: string;
+        refreshToken: string;
+    }>;
+    login(): Promise<User>;
+    restoreSession(): Promise<User>;
+    logout(): Promise<void>;
+    signMessage(message: string): Promise<string>;
+    signTransaction(_transaction: Transaction | VersionedTransaction): Promise<Transaction | VersionedTransaction>;
+    signAndSubmitTransaction(_transaction: Transaction | VersionedTransaction, _feePayer?: PublicKey): Promise<string>;
+    runTransaction(evm?: EVMTransaction, sol?: SolTransaction, options?: SetOptions): Promise<TransactionResult>;
+    getNativeMethods(): Promise<any>;
+    transactionPolicy(): {
+        runtimeAddresses: Record<string, string>;
+    };
+}

package/dist/index.d.ts

@@ -8,5 +8,7 @@ export type { AuthProvider, ClientConfig, User, GetOptions, SearchOptions, SetOp
 export { getIdToken } from './utils';
 export { createWalletClient, WalletClient } from './wallet-client';
 export type { CreateWalletClientOptions } from './wallet-client';
+export { EvmKeypairProvider } from './auth/providers/evm-keypair-provider';
+export type { EvmKeypairChainConfig } from './auth/providers/evm-keypair-provider';
 export { verifyWebhook, clearWebhookKeyCache, clearWebhookReplayCache, WebhookVerificationError, DEFAULT_WEBHOOK_KEYS_URL, InMemoryReplayStore, } from './webhooks';
 export type { WebhookPayload, WebhookPublicKey, WebhookOperation, VerifyWebhookOptions, WebhookHeaders, WebhookReplayStore, } from './webhooks';

package/dist/index.js

@@ -6,6 +6,8 @@ var bs58 = require('bs58');
 var buffer = require('buffer');
 var anchor = require('@coral-xyz/anchor');
 var nacl = require('tweetnacl');
+var viem = require('viem');
+var accounts = require('viem/accounts');
 
 function _interopNamespaceDefault(e) {
     var n = Object.create(null);
@@ -677,6 +679,144 @@ class OffchainAuthProvider {
     }
 }
 
+const NO_SOLANA = 'An EVM keypair client cannot sign Solana transactions.';
+function normalizeChainConfig(input) {
+    var _a;
+    if (!Number.isSafeInteger(input.chainId) || input.chainId <= 0)
+        throw new Error('EVM chainId must be a positive safe integer');
+    let rpc;
+    try {
+        rpc = new URL(input.rpcUrl);
+    }
+    catch (_b) {
+        throw new Error(`EVM RPC URL is invalid for chain ${input.chainId}`);
+    }
+    if (rpc.protocol !== 'https:' && !(rpc.protocol === 'http:' && (rpc.hostname === 'localhost' || rpc.hostname === '127.0.0.1' || rpc.hostname === '[::1]'))) {
+        throw new Error(`EVM RPC URL must use HTTPS for chain ${input.chainId}`);
+    }
+    const runtimeAddress = core.normalizeEvmAddress(input.runtimeAddress);
+    if (!runtimeAddress)
+        throw new Error(`BoundedRuntime address is invalid for chain ${input.chainId}`);
+    return { chainId: input.chainId, rpcUrl: rpc.toString(), runtimeAddress, name: ((_a = input.name) === null || _a === void 0 ? void 0 : _a.trim()) || `EVM ${input.chainId}` };
+}
+function asViemChain(config) {
+    return viem.defineChain({
+        id: config.chainId,
+        name: config.name,
+        nativeCurrency: { name: 'Native token', symbol: 'NATIVE', decimals: 18 },
+        rpcUrls: { default: { http: [config.rpcUrl] } },
+    });
+}
+class EvmKeypairProvider {
+    constructor(privateKey, defaultChainId, chainConfigs) {
+        this.chains = new Map();
+        if (!/^0x[0-9a-fA-F]{64}$/.test(privateKey))
+            throw new Error('Invalid EVM private key: expected 0x followed by 64 hex characters.');
+        this.account = accounts.privateKeyToAccount(privateKey);
+        const address = core.normalizeEvmAddress(this.account.address);
+        if (!address)
+            throw new Error('Could not derive a valid EVM address from the private key');
+        this.address = address;
+        for (const raw of chainConfigs) {
+            const chain = normalizeChainConfig(raw);
+            if (this.chains.has(chain.chainId))
+                throw new Error(`Duplicate EVM chain configuration: ${chain.chainId}`);
+            this.chains.set(chain.chainId, chain);
+        }
+        if (!this.chains.has(defaultChainId))
+            throw new Error(`Default EVM chain ${defaultChainId} is not configured`);
+        this.defaultChainId = defaultChainId;
+    }
+    user() {
+        return { id: this.address, address: null, evmAddress: this.address, provider: this };
+    }
+    async createBoundedSession() {
+        var _a, _b, _c;
+        const nonce = await core.genAuthNonce();
+        const { appId } = await core.getConfig();
+        const message = core.genSiweMessage(this.address, nonce, appId, 'server', 'https://server/login', { chainId: this.defaultChainId });
+        const signature = await this.account.signMessage({ message });
+        const session = await core.createSessionWithSignature(this.address, message, signature, 'siwe');
+        return {
+            address: this.address,
+            accessToken: String((_a = session.accessToken) !== null && _a !== void 0 ? _a : ''),
+            idToken: String((_b = session.idToken) !== null && _b !== void 0 ? _b : ''),
+            refreshToken: String((_c = session.refreshToken) !== null && _c !== void 0 ? _c : ''),
+        };
+    }
+    async login() { return this.user(); }
+    async restoreSession() { return this.user(); }
+    async logout() { }
+    async signMessage(message) {
+        return this.account.signMessage({ message });
+    }
+    async signTransaction(_transaction) {
+        throw new Error(NO_SOLANA);
+    }
+    async signAndSubmitTransaction(_transaction, _feePayer) {
+        throw new Error(NO_SOLANA);
+    }
+    async runTransaction(evm, sol, options) {
+        var _a;
+        if (evm && sol)
+            throw new Error('A transaction cannot target EVM and Solana at the same time.');
+        if (!evm || !evm.chainId || !evm.to || !evm.data)
+            throw new Error('A complete EVM transaction is required');
+        if ((options === null || options === void 0 ? void 0 : options.shouldSubmitTx) === false)
+            throw new Error('EVM keypair writes submit atomically; shouldSubmitTx:false is unsupported.');
+        const config = this.chains.get(evm.chainId);
+        if (!config)
+            throw new Error(`EVM chain ${evm.chainId} is not configured for this wallet client`);
+        if (core.normalizeEvmAddress(evm.to) !== config.runtimeAddress)
+            throw new Error('EVM transaction target is not the configured BoundedRuntime');
+        if (evm.nonce !== undefined)
+            throw new Error('Server-supplied EVM nonces are not accepted');
+        try {
+            if (BigInt((_a = evm.value) !== null && _a !== void 0 ? _a : '0') !== BigInt(0))
+                throw new Error('BoundedRuntime.setDocuments cannot transfer native value');
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('cannot transfer'))
+                throw error;
+            throw new Error('Invalid EVM transaction value');
+        }
+        // The shared decoder accepts only canonical ordinary/attested document
+        // writes and rejects selector-prefix smuggling, aliases and trailing bytes.
+        core.assertCanonicalBoundedRuntimeWriteCalldata(evm.data);
+        // A server key can safely switch between explicitly configured chains: each
+        // tx selects its own immutable viem client/RPC/runtime tuple. No untrusted
+        // server response may introduce a new chain or RPC endpoint.
+        const chain = asViemChain(config);
+        const transport = viem.http(config.rpcUrl);
+        const wallet = viem.createWalletClient({ account: this.account, chain, transport });
+        const publicClient = viem.createPublicClient({ chain, transport });
+        const hash = await wallet.sendTransaction({
+            account: this.account,
+            chain,
+            to: config.runtimeAddress,
+            data: evm.data,
+            value: BigInt(0),
+        });
+        const receipt = await publicClient.waitForTransactionReceipt({ hash });
+        if (receipt.status !== 'success')
+            throw new Error(`EVM transaction ${hash} reverted on-chain`);
+        if (receipt.blockNumber > BigInt(Number.MAX_SAFE_INTEGER))
+            throw new Error('EVM receipt block number exceeds the SDK safe-integer range');
+        return {
+            transactionSignature: hash,
+            blockNumber: Number(receipt.blockNumber),
+            gasUsed: receipt.gasUsed.toString(),
+            data: receipt,
+        };
+    }
+    async getNativeMethods() { return this.account; }
+    transactionPolicy() {
+        return {
+            runtimeAddresses: Object.fromEntries([...this.chains].map(([id, config]) => [String(id), config.runtimeAddress])),
+        };
+    }
+}
+
 var __rest = (undefined && undefined.__rest) || function (s, e) {
     var t = {};
     for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
@@ -728,10 +868,11 @@ function jwtExpiringSoon(token) {
 /*  WalletClient                                                       */
 /* ------------------------------------------------------------------ */
 class WalletClient {
-    constructor(provider, sessionManager, address) {
+    constructor(provider, sessionManager, address, evmTransactionPolicy) {
         this.provider = provider;
         this.sessionManager = sessionManager;
         this.address = address;
+        this.evmTransactionPolicy = evmTransactionPolicy;
         this.live = {
             intent: (roomPath, intent, opts = {}) => core.live.intent(roomPath, intent, this.mergeLiveIntentOptions(opts)),
             status: (roomPath, opts = {}) => core.live.status(roomPath, Object.assign(Object.assign({}, opts), { headers: this.sanitizeHeaders(opts.headers) })),
@@ -759,9 +900,7 @@ class WalletClient {
     }
     /* ---- Auth override helpers ---- */
     buildOverrides() {
-        return {
-            authProvider: this.provider,
-            _getAuthHeaders: async () => {
+        return Object.assign({ authProvider: this.provider, _getAuthHeaders: async () => {
                 let s = await this.sessionManager.getSession();
                 // Keypair-backed session: if the cached token is expired/near-expiry,
                 // re-sign for a fresh one (we always hold the key). Keeps long-lived WS
@@ -772,12 +911,9 @@ class WalletClient {
                     s = await this.sessionManager.getSession();
                 }
                 return { Authorization: `Bearer ${s.idToken}` };
-            },
-            _clearAuth: async () => {
+            }, _clearAuth: async () => {
                 this.sessionManager.clearSession();
-            },
-            _walletAddress: this.address,
-        };
+            }, _walletAddress: this.address }, (this.evmTransactionPolicy ? { _evmTransactionPolicy: this.evmTransactionPolicy } : {}));
     }
     /** Strip Authorization from caller headers to prevent overriding wallet token */
     sanitizeHeaders(headers) {
@@ -789,7 +925,7 @@ class WalletClient {
     mergeSetOverrides(opts) {
         var _a;
         const ovr = this.buildOverrides();
-        return Object.assign(Object.assign({}, opts), { _overrides: Object.assign(Object.assign({}, opts === null || opts === void 0 ? void 0 : opts._overrides), { headers: this.sanitizeHeaders((_a = opts === null || opts === void 0 ? void 0 : opts._overrides) === null || _a === void 0 ? void 0 : _a.headers), authProvider: ovr.authProvider, _getAuthHeaders: ovr._getAuthHeaders, _clearAuth: ovr._clearAuth }) });
+        return Object.assign(Object.assign({}, opts), { _overrides: Object.assign(Object.assign({}, opts === null || opts === void 0 ? void 0 : opts._overrides), { headers: this.sanitizeHeaders((_a = opts === null || opts === void 0 ? void 0 : opts._overrides) === null || _a === void 0 ? void 0 : _a.headers), authProvider: ovr.authProvider, _getAuthHeaders: ovr._getAuthHeaders, _clearAuth: ovr._clearAuth, _evmTransactionPolicy: ovr._evmTransactionPolicy }) });
     }
     mergeReadOverrides(existing) {
         const ovr = this.buildOverrides();
@@ -883,19 +1019,53 @@ class WalletClient {
     }
 }
 /**
- * Create a self-contained wallet client bound to a specific keypair.
+ * Create a self-contained wallet client bound to one Solana or EVM keypair.
  * Each client has its own auth session — no global state is mutated.
  *
  * @example
  * ```ts
  * const vault = await createWalletClient({ keypair: process.env.VAULT_KEY });
  * await vault.set('markets/123', data);
+ *
+ * const evmVault = await createWalletClient({
+ *   evmPrivateKey: process.env.EVM_PRIVATE_KEY,
+ *   chainId: 8453,
+ *   rpcUrl: process.env.BASE_RPC_URL,
+ *   runtimeAddress: process.env.BOUNDED_RUNTIME,
+ * });
  * ```
  */
 async function createWalletClient(opts) {
     var _a;
-    const kp = parseKeypair(opts.keypair);
     const config = await core.getConfig();
+    if ('evmPrivateKey' in opts && typeof opts.evmPrivateKey === 'string') {
+        const chainConfigs = [];
+        if (opts.chains) {
+            for (const [rawId, chain] of Object.entries(opts.chains)) {
+                const chainId = Number(rawId);
+                if (!Number.isSafeInteger(chainId) || chainId <= 0)
+                    throw new Error(`Invalid EVM chain id in chains map: ${rawId}`);
+                chainConfigs.push({ chainId, rpcUrl: chain.rpcUrl, runtimeAddress: chain.runtimeAddress, name: chain.name });
+            }
+        }
+        if (opts.rpcUrl !== undefined || opts.runtimeAddress !== undefined) {
+            if (!opts.rpcUrl || !opts.runtimeAddress)
+                throw new Error('Single-chain EVM clients require both rpcUrl and runtimeAddress');
+            if (chainConfigs.some((chain) => chain.chainId === opts.chainId))
+                throw new Error(`EVM chain ${opts.chainId} is configured twice`);
+            chainConfigs.push({ chainId: opts.chainId, rpcUrl: opts.rpcUrl, runtimeAddress: opts.runtimeAddress });
+        }
+        if (chainConfigs.length === 0)
+            throw new Error('EVM wallet clients require an explicit RPC URL and BoundedRuntime address');
+        const provider = new EvmKeypairProvider(opts.evmPrivateKey, opts.chainId, chainConfigs);
+        const sessionManager = core.ServerSessionManager.forSessionFactory(() => provider.createBoundedSession());
+        await sessionManager.getSession();
+        return new WalletClient(provider, sessionManager, provider.address, provider.transactionPolicy());
+    }
+    if (!('keypair' in opts) || typeof opts.keypair !== 'string') {
+        throw new Error('createWalletClient requires exactly one of keypair or evmPrivateKey');
+    }
+    const kp = parseKeypair(opts.keypair);
     let provider = new SolanaKeypairProvider((_a = config.rpcUrl) !== null && _a !== void 0 ? _a : null, kp);
     if (config.chain === 'offchain') {
         provider = new OffchainAuthProvider(provider);
@@ -1193,6 +1363,7 @@ Object.defineProperty(exports, "getWebhookKeysUrl", {
     get: function () { return core.getWebhookKeysUrl; }
 });
 exports.DEFAULT_WEBHOOK_KEYS_URL = DEFAULT_WEBHOOK_KEYS_URL;
+exports.EvmKeypairProvider = EvmKeypairProvider;
 exports.InMemoryReplayStore = InMemoryReplayStore;
 exports.WalletClient = WalletClient;
 exports.WebhookVerificationError = WebhookVerificationError;