@buildersgarden/siwa 0.0.4 → 0.0.5

package/dist/keystore.d.ts

@@ -34,8 +34,8 @@
  *   KEYSTORE_PATH         — Path to encrypted keystore file (default: ./agent-keystore.json)
  *   AGENT_PRIVATE_KEY     — Fallback for env backend only
  */
-import { type WalletClient, type Account, type Chain, type Transport } from 'viem';
-export type KeystoreBackend = 'encrypted-file' | 'env' | 'proxy';
+import { type WalletClient, type Account, type Chain, type Transport } from "viem";
+export type KeystoreBackend = "encrypted-file" | "env" | "proxy";
 export interface KeystoreConfig {
     backend?: KeystoreBackend;
     keystorePath?: string;

package/dist/keystore.js

@@ -34,20 +34,20 @@
  *   KEYSTORE_PATH         — Path to encrypted keystore file (default: ./agent-keystore.json)
  *   AGENT_PRIVATE_KEY     — Fallback for env backend only
  */
-import { createWalletClient, http, keccak256, toBytes, toHex, concat, } from 'viem';
-import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
-import { hashAuthorization } from 'viem/experimental';
-import { scrypt } from '@noble/hashes/scrypt';
-import { randomBytes } from '@noble/hashes/utils';
-import { ctr } from '@noble/ciphers/aes';
-import * as fs from 'fs';
-import * as crypto from 'crypto';
-import * as os from 'os';
-import { computeHmac } from './proxy-auth.js';
+import { createWalletClient, http, keccak256, toBytes, toHex, concat, } from "viem";
+import { privateKeyToAccount, generatePrivateKey } from "viem/accounts";
+import { hashAuthorization } from "viem/experimental";
+import { scrypt } from "@noble/hashes/scrypt";
+import { randomBytes } from "@noble/hashes/utils";
+import { ctr } from "@noble/ciphers/aes";
+import * as fs from "fs";
+import * as crypto from "crypto";
+import * as os from "os";
+import { computeHmac } from "./proxy-auth.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const DEFAULT_KEYSTORE_PATH = './agent-keystore.json';
+const DEFAULT_KEYSTORE_PATH = "./agent-keystore.json";
 function generateUUID() {
     const bytes = randomBytes(16);
     bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
@@ -65,13 +65,21 @@ async function encryptKeystore(privateKey, password) {
     const p = 1;
     const dklen = 32;
     // Derive key using scrypt
-    const derivedKey = scrypt(new TextEncoder().encode(password), salt, { N: n, r, p, dkLen: dklen });
+    const derivedKey = scrypt(new TextEncoder().encode(password), salt, {
+        N: n,
+        r,
+        p,
+        dkLen: dklen,
+    });
     // Encrypt private key with AES-128-CTR
     const encryptionKey = derivedKey.slice(0, 16);
     const cipher = ctr(encryptionKey, iv);
     const ciphertext = cipher.encrypt(privateKeyBytes);
     // Calculate MAC: keccak256(derivedKey[16:32] + ciphertext)
-    const macData = concat([toHex(derivedKey.slice(16, 32)), toHex(ciphertext)]);
+    const macData = concat([
+        toHex(derivedKey.slice(16, 32)),
+        toHex(ciphertext),
+    ]);
     const mac = keccak256(macData);
     // Get address from private key
     const account = privateKeyToAccount(privateKey);
@@ -82,8 +90,8 @@ async function encryptKeystore(privateKey, password) {
         crypto: {
             ciphertext: toHex(ciphertext).slice(2),
             cipherparams: { iv: toHex(iv).slice(2) },
-            cipher: 'aes-128-ctr',
-            kdf: 'scrypt',
+            cipher: "aes-128-ctr",
+            kdf: "scrypt",
             kdfparams: {
                 dklen,
                 salt: toHex(salt).slice(2),
@@ -102,10 +110,10 @@ async function decryptKeystore(json, password) {
         throw new Error(`Unsupported keystore version: ${keystore.version}`);
     }
     const { crypto: cryptoData } = keystore;
-    if (cryptoData.kdf !== 'scrypt') {
+    if (cryptoData.kdf !== "scrypt") {
         throw new Error(`Unsupported KDF: ${cryptoData.kdf}`);
     }
-    if (cryptoData.cipher !== 'aes-128-ctr') {
+    if (cryptoData.cipher !== "aes-128-ctr") {
         throw new Error(`Unsupported cipher: ${cryptoData.cipher}`);
     }
     const { kdfparams } = cryptoData;
@@ -113,12 +121,20 @@ async function decryptKeystore(json, password) {
     const iv = toBytes(`0x${cryptoData.cipherparams.iv}`);
     const ciphertext = toBytes(`0x${cryptoData.ciphertext}`);
     // Derive key using scrypt
-    const derivedKey = scrypt(new TextEncoder().encode(password), salt, { N: kdfparams.n, r: kdfparams.r, p: kdfparams.p, dkLen: kdfparams.dklen });
+    const derivedKey = scrypt(new TextEncoder().encode(password), salt, {
+        N: kdfparams.n,
+        r: kdfparams.r,
+        p: kdfparams.p,
+        dkLen: kdfparams.dklen,
+    });
     // Verify MAC
-    const macData = concat([toHex(derivedKey.slice(16, 32)), toHex(ciphertext)]);
+    const macData = concat([
+        toHex(derivedKey.slice(16, 32)),
+        toHex(ciphertext),
+    ]);
     const calculatedMac = keccak256(macData).slice(2);
     if (calculatedMac.toLowerCase() !== cryptoData.mac.toLowerCase()) {
-        throw new Error('Invalid password or corrupted keystore');
+        throw new Error("Invalid password or corrupted keystore");
     }
     // Decrypt private key with AES-128-CTR
     const encryptionKey = derivedKey.slice(0, 16);
@@ -133,15 +149,15 @@ async function proxyRequest(config, endpoint, body = {}) {
     const url = config.proxyUrl || process.env.KEYRING_PROXY_URL;
     const secret = config.proxySecret || process.env.KEYRING_PROXY_SECRET;
     if (!url)
-        throw new Error('Proxy backend requires KEYRING_PROXY_URL or config.proxyUrl');
+        throw new Error("Proxy backend requires KEYRING_PROXY_URL or config.proxyUrl");
     if (!secret)
-        throw new Error('Proxy backend requires KEYRING_PROXY_SECRET or config.proxySecret');
-    const bodyStr = JSON.stringify(body, (_key, value) => typeof value === 'bigint' ? '0x' + value.toString(16) : value);
-    const hmacHeaders = computeHmac(secret, 'POST', endpoint, bodyStr);
+        throw new Error("Proxy backend requires KEYRING_PROXY_SECRET or config.proxySecret");
+    const bodyStr = JSON.stringify(body, (_key, value) => typeof value === "bigint" ? "0x" + value.toString(16) : value);
+    const hmacHeaders = computeHmac(secret, "POST", endpoint, bodyStr);
     const res = await fetch(`${url}${endpoint}`, {
-        method: 'POST',
+        method: "POST",
         headers: {
-            'Content-Type': 'application/json',
+            "Content-Type": "application/json",
             ...hmacHeaders,
         },
         body: bodyStr,
@@ -158,16 +174,16 @@ async function proxyRequest(config, endpoint, body = {}) {
 export async function detectBackend() {
     // 0. Proxy backend (if URL is set)
     if (process.env.KEYRING_PROXY_URL)
-        return 'proxy';
+        return "proxy";
     // 1. Check for existing encrypted keystore file
     if (fs.existsSync(process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH)) {
-        return 'encrypted-file';
+        return "encrypted-file";
     }
     // 2. Check for env var
     if (process.env.AGENT_PRIVATE_KEY)
-        return 'env';
+        return "env";
     // 3. Default to encrypted-file (will be created on first use)
-    return 'encrypted-file';
+    return "encrypted-file";
 }
 // ---------------------------------------------------------------------------
 // Encrypted V3 JSON Keystore backend
@@ -179,7 +195,7 @@ async function encryptedFileStore(privateKey, password, filePath) {
 async function encryptedFileLoad(password, filePath) {
     if (!fs.existsSync(filePath))
         return null;
-    const json = fs.readFileSync(filePath, 'utf-8');
+    const json = fs.readFileSync(filePath, "utf-8");
     return decryptKeystore(json, password);
 }
 function encryptedFileExists(filePath) {
@@ -195,15 +211,12 @@ function encryptedFileExists(filePath) {
 // ---------------------------------------------------------------------------
 function deriveMachinePassword() {
     const factors = [
-        process.env.USER || process.env.USERNAME || 'agent',
-        process.env.HOME || process.env.USERPROFILE || '/tmp',
+        process.env.USER || process.env.USERNAME || "agent",
+        process.env.HOME || process.env.USERPROFILE || "/tmp",
         os.hostname(),
         os.platform(),
     ];
-    return crypto
-        .createHash('sha256')
-        .update(factors.join(':'))
-        .digest('hex');
+    return crypto.createHash("sha256").update(factors.join(":")).digest("hex");
 }
 // ---------------------------------------------------------------------------
 // Public API — the ONLY way external code touches private keys
@@ -213,34 +226,36 @@ function deriveMachinePassword() {
  * Returns only the public address — NEVER the private key.
  */
 export async function createWallet(config = {}) {
-    const backend = config.backend || await detectBackend();
+    const backend = config.backend || (await detectBackend());
     const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/create-wallet');
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/create-wallet");
         return { address: data.address, backend, keystorePath: undefined };
     }
     const privateKey = generatePrivateKey();
     const account = privateKeyToAccount(privateKey);
     const address = account.address;
     switch (backend) {
-        case 'encrypted-file': {
-            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+        case "encrypted-file": {
+            const password = config.password ||
+                process.env.KEYSTORE_PASSWORD ||
+                deriveMachinePassword();
             await encryptedFileStore(privateKey, password, keystorePath);
             break;
         }
-        case 'env':
+        case "env":
             // For env backend, we print the key ONCE for the operator to capture.
             // This is the ONLY time the raw key is ever exposed.
-            console.log('=== ENV BACKEND (testing only) ===');
+            console.log("=== ENV BACKEND (testing only) ===");
             console.log(`Set this in your environment:`);
             console.log(`  export AGENT_PRIVATE_KEY="${privateKey}"`);
-            console.log('=================================');
+            console.log("=================================");
             break;
     }
     return {
         address,
         backend,
-        keystorePath: backend === 'encrypted-file' ? keystorePath : undefined,
+        keystorePath: backend === "encrypted-file" ? keystorePath : undefined,
     };
 }
 /**
@@ -249,44 +264,46 @@ export async function createWallet(config = {}) {
  * Returns only the public address.
  */
 export async function importWallet(privateKey, config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        throw new Error('importWallet() is not supported via proxy. Import the wallet on the proxy server directly.');
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        throw new Error("importWallet() is not supported via proxy. Import the wallet on the proxy server directly.");
     }
     const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
-    const hexKey = (privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`);
+    const hexKey = (privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`);
     const account = privateKeyToAccount(hexKey);
     const address = account.address;
     switch (backend) {
-        case 'encrypted-file': {
-            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+        case "encrypted-file": {
+            const password = config.password ||
+                process.env.KEYSTORE_PASSWORD ||
+                deriveMachinePassword();
             await encryptedFileStore(hexKey, password, keystorePath);
             break;
         }
-        case 'env':
+        case "env":
             // Nothing to persist for env backend
             break;
     }
     return {
         address,
         backend,
-        keystorePath: backend === 'encrypted-file' ? keystorePath : undefined,
+        keystorePath: backend === "encrypted-file" ? keystorePath : undefined,
     };
 }
 /**
  * Check if a wallet is available in any backend.
  */
 export async function hasWallet(config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/has-wallet');
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/has-wallet");
         return data.hasWallet;
     }
     const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
     switch (backend) {
-        case 'encrypted-file':
+        case "encrypted-file":
             return encryptedFileExists(keystorePath);
-        case 'env':
+        case "env":
             return !!process.env.AGENT_PRIVATE_KEY;
     }
 }
@@ -294,9 +311,9 @@ export async function hasWallet(config = {}) {
  * Get the wallet's public address (no private key exposed).
  */
 export async function getAddress(config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/get-address');
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/get-address");
         return data.address;
     }
     const privateKey = await _loadPrivateKeyInternal(config);
@@ -311,14 +328,14 @@ export async function getAddress(config = {}) {
  * Only the signature is returned.
  */
 export async function signMessage(message, config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/sign-message', { message });
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/sign-message", { message });
         return { signature: data.signature, address: data.address };
     }
     const privateKey = await _loadPrivateKeyInternal(config);
     if (!privateKey)
-        throw new Error('No wallet found. Run createWallet() first.');
+        throw new Error("No wallet found. Run createWallet() first.");
     const account = privateKeyToAccount(privateKey);
     const signature = await account.signMessage({ message });
     return { signature, address: account.address };
@@ -332,13 +349,13 @@ function parseBigIntFromJson(value) {
     if (value === null || value === undefined)
         return undefined;
     let result;
-    if (typeof value === 'bigint') {
+    if (typeof value === "bigint") {
         result = value;
     }
-    else if (typeof value === 'number') {
+    else if (typeof value === "number") {
         result = BigInt(value);
     }
-    else if (typeof value === 'string') {
+    else if (typeof value === "string") {
         // Handle hex strings (0x...) and decimal strings
         result = BigInt(value);
     }
@@ -355,11 +372,11 @@ function parseBigIntFromJson(value) {
 function parseBigIntKeepZero(value) {
     if (value === null || value === undefined)
         return undefined;
-    if (typeof value === 'bigint')
+    if (typeof value === "bigint")
         return value;
-    if (typeof value === 'number')
+    if (typeof value === "number")
         return BigInt(value);
-    if (typeof value === 'string')
+    if (typeof value === "string")
         return BigInt(value);
     return undefined;
 }
@@ -369,14 +386,16 @@ function parseBigIntKeepZero(value) {
  * Only the signed transaction is returned.
  */
 export async function signTransaction(tx, config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/sign-transaction', { tx: tx });
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/sign-transaction", {
+            tx: tx,
+        });
         return { signedTx: data.signedTx, address: data.address };
     }
     const privateKey = await _loadPrivateKeyInternal(config);
     if (!privateKey)
-        throw new Error('No wallet found. Run createWallet() first.');
+        throw new Error("No wallet found. Run createWallet() first.");
     const account = privateKeyToAccount(privateKey);
     // Parse numeric fields from JSON representation (strings) to bigints.
     // For 'value', zero is converted to undefined so viem encodes it as 0x80 (empty)
@@ -397,12 +416,12 @@ export async function signTransaction(tx, config = {}) {
     };
     // Handle EIP-1559 vs legacy transactions
     if (tx.type === 2 || tx.maxFeePerGas !== undefined) {
-        viemTx.type = 'eip1559';
+        viemTx.type = "eip1559";
         viemTx.maxFeePerGas = maxFeePerGas;
         viemTx.maxPriorityFeePerGas = maxPriorityFeePerGas;
     }
     else if (tx.gasPrice !== undefined) {
-        viemTx.type = 'legacy';
+        viemTx.type = "legacy";
         viemTx.gasPrice = gasPrice;
     }
     if (tx.accessList) {
@@ -422,14 +441,14 @@ export async function signTransaction(tx, config = {}) {
  * @returns Signed authorization tuple (address, nonce, chainId, yParity, r, s)
  */
 export async function signAuthorization(auth, config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        const data = await proxyRequest(config, '/sign-authorization', { auth });
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        const data = await proxyRequest(config, "/sign-authorization", { auth });
         return data;
     }
     const privateKey = await _loadPrivateKeyInternal(config);
     if (!privateKey)
-        throw new Error('No wallet found. Run createWallet() first.');
+        throw new Error("No wallet found. Run createWallet() first.");
     const account = privateKeyToAccount(privateKey);
     // EIP-7702 authorization signing using viem experimental
     const chainId = auth.chainId ?? 1;
@@ -463,13 +482,13 @@ export async function signAuthorization(auth, config = {}) {
  * Prefer signMessage() / signTransaction() when possible.
  */
 export async function getWalletClient(rpcUrl, config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        throw new Error('getWalletClient() is not supported via proxy. The private key cannot be serialized over HTTP. Use signMessage() or signTransaction() instead.');
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        throw new Error("getWalletClient() is not supported via proxy. The private key cannot be serialized over HTTP. Use signMessage() or signTransaction() instead.");
     }
     const privateKey = await _loadPrivateKeyInternal(config);
     if (!privateKey)
-        throw new Error('No wallet found. Run createWallet() first.');
+        throw new Error("No wallet found. Run createWallet() first.");
     const account = privateKeyToAccount(privateKey);
     return createWalletClient({
         account,
@@ -481,20 +500,20 @@ export async function getWalletClient(rpcUrl, config = {}) {
  * DESTRUCTIVE — the identity is lost if no backup exists.
  */
 export async function deleteWallet(config = {}) {
-    const backend = config.backend || await detectBackend();
-    if (backend === 'proxy') {
-        throw new Error('deleteWallet() is not supported via proxy. Delete the wallet on the proxy server directly.');
+    const backend = config.backend || (await detectBackend());
+    if (backend === "proxy") {
+        throw new Error("deleteWallet() is not supported via proxy. Delete the wallet on the proxy server directly.");
     }
     const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
     switch (backend) {
-        case 'encrypted-file':
+        case "encrypted-file":
             if (fs.existsSync(keystorePath)) {
                 fs.unlinkSync(keystorePath);
                 return true;
             }
             return false;
-        case 'env':
-            console.warn('Cannot delete env-based wallet. Unset AGENT_PRIVATE_KEY manually.');
+        case "env":
+            console.warn("Cannot delete env-based wallet. Unset AGENT_PRIVATE_KEY manually.");
             return false;
     }
 }
@@ -502,19 +521,21 @@ export async function deleteWallet(config = {}) {
 // Internal — loads the private key. NEVER exposed publicly.
 // ---------------------------------------------------------------------------
 async function _loadPrivateKeyInternal(config = {}) {
-    const backend = config.backend || await detectBackend();
+    const backend = config.backend || (await detectBackend());
     const keystorePath = config.keystorePath || process.env.KEYSTORE_PATH || DEFAULT_KEYSTORE_PATH;
     let privateKey = null;
     switch (backend) {
-        case 'encrypted-file': {
-            const password = config.password || process.env.KEYSTORE_PASSWORD || deriveMachinePassword();
+        case "encrypted-file": {
+            const password = config.password ||
+                process.env.KEYSTORE_PASSWORD ||
+                deriveMachinePassword();
             privateKey = await encryptedFileLoad(password, keystorePath);
             break;
         }
-        case 'env': {
+        case "env": {
             const envKey = process.env.AGENT_PRIVATE_KEY || null;
             if (envKey) {
-                privateKey = (envKey.startsWith('0x') ? envKey : `0x${envKey}`);
+                privateKey = (envKey.startsWith("0x") ? envKey : `0x${envKey}`);
             }
             break;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "exports": {
     ".": {