@buildersgarden/siwa 0.0.11 → 0.0.13

package/dist/registry.d.ts

@@ -8,7 +8,7 @@
  *   npm install viem
  */
 import { type PublicClient } from 'viem';
-import { type KeystoreConfig } from './keystore.js';
+import type { TransactionSigner } from './signer.js';
 /** Service endpoint types defined in ERC-8004 */
 export type ServiceType = 'web' | 'A2A' | 'MCP' | 'OASF' | 'ENS' | 'DID' | 'email';
 /** Trust models defined in ERC-8004 */
@@ -74,10 +74,14 @@ export declare function getAgent(agentId: number, options: GetAgentOptions): Pro
  */
 export declare function getReputation(agentId: number, options: GetReputationOptions): Promise<ReputationSummary>;
 export interface RegisterAgentOptions {
+    /** The agent metadata URI (IPFS, HTTP, or data URL) */
     agentURI: string;
+    /** The chain ID to register on */
     chainId: number;
+    /** Optional RPC URL (defaults to chain's default endpoint) */
     rpcUrl?: string;
-    keystoreConfig: KeystoreConfig;
+    /** A TransactionSigner for signing the registration transaction */
+    signer: TransactionSigner;
 }
 export interface RegisterAgentResult {
     agentId: string;
@@ -88,7 +92,22 @@ export interface RegisterAgentResult {
 /**
  * Register an agent on the ERC-8004 Identity Registry in a single call.
  *
- * Builds, signs (via keyring proxy), and broadcasts the `register(agentURI)`
+ * Builds, signs (via the provided signer), and broadcasts the `register(agentURI)`
  * transaction, then waits for confirmation and parses the `Registered` event.
+ *
+ * @example
+ * ```typescript
+ * import { registerAgent, createLocalAccountSigner } from '@buildersgarden/siwa';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const signer = createLocalAccountSigner(account);
+ *
+ * const result = await registerAgent({
+ *   agentURI: 'ipfs://...',
+ *   chainId: 84532,
+ *   signer,
+ * });
+ * ```
  */
 export declare function registerAgent(options: RegisterAgentOptions): Promise<RegisterAgentResult>;

package/dist/registry.js

@@ -9,7 +9,6 @@
  */
 import { zeroAddress, createPublicClient, http, encodeFunctionData, parseEventLogs, } from 'viem';
 import { getRegistryAddress, getAgentRegistryString, RPC_ENDPOINTS } from './addresses.js';
-import { getAddress, signTransaction } from './keystore.js';
 // ─── ABI Fragments ──────────────────────────────────────────────────
 const IDENTITY_REGISTRY_ABI = [
     {
@@ -160,27 +159,39 @@ export async function getReputation(agentId, options) {
 /**
  * Register an agent on the ERC-8004 Identity Registry in a single call.
  *
- * Builds, signs (via keyring proxy), and broadcasts the `register(agentURI)`
+ * Builds, signs (via the provided signer), and broadcasts the `register(agentURI)`
  * transaction, then waits for confirmation and parses the `Registered` event.
+ *
+ * @example
+ * ```typescript
+ * import { registerAgent, createLocalAccountSigner } from '@buildersgarden/siwa';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const signer = createLocalAccountSigner(account);
+ *
+ * const result = await registerAgent({
+ *   agentURI: 'ipfs://...',
+ *   chainId: 84532,
+ *   signer,
+ * });
+ * ```
  */
 export async function registerAgent(options) {
-    const { agentURI, chainId, keystoreConfig } = options;
+    const { agentURI, chainId, signer } = options;
     const registryAddress = getRegistryAddress(chainId);
     const rpcUrl = options.rpcUrl || RPC_ENDPOINTS[chainId];
     if (!rpcUrl) {
         throw new Error(`No RPC URL provided and no default endpoint for chain ${chainId}.`);
     }
     const publicClient = createPublicClient({ transport: http(rpcUrl) });
-    const address = await getAddress(keystoreConfig);
-    if (!address) {
-        throw new Error('Could not resolve wallet address from keyring proxy.');
-    }
+    const address = await signer.getAddress();
     const data = encodeFunctionData({
         abi: IDENTITY_REGISTRY_ABI,
         functionName: 'register',
         args: [agentURI],
     });
-    const nonce = await publicClient.getTransactionCount({ address: address });
+    const nonce = await publicClient.getTransactionCount({ address });
     const feeData = await publicClient.estimateFeesPerGas();
     const gasEstimate = await publicClient.estimateGas({
         to: registryAddress,
@@ -198,7 +209,7 @@ export async function registerAgent(options) {
         maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
         gas,
     };
-    const { signedTx } = await signTransaction(txReq, keystoreConfig);
+    const signedTx = await signer.signTransaction(txReq);
     const txHash = await publicClient.sendRawTransaction({
         serializedTransaction: signedTx,
     });

package/dist/signer.d.ts

@@ -0,0 +1,145 @@
+/**
+ * signer.ts
+ *
+ * Wallet-agnostic signing abstraction for SIWA.
+ *
+ * This module provides a `Signer` interface that abstracts signing operations,
+ * allowing developers to use any wallet provider without changing the SDK.
+ *
+ * Available signer implementations:
+ *   - createKeyringProxySigner(config)    — Keyring proxy server (HMAC-authenticated)
+ *   - createLocalAccountSigner(account)   — viem LocalAccount (privateKeyToAccount)
+ *   - createWalletClientSigner(client)    — viem WalletClient (Privy, MetaMask, etc.)
+ *
+ * Usage:
+ *   import { signSIWAMessage, createLocalAccountSigner } from '@buildersgarden/siwa';
+ *   import { privateKeyToAccount } from 'viem/accounts';
+ *
+ *   const account = privateKeyToAccount('0x...');
+ *   const signer = createLocalAccountSigner(account);
+ *   const { message, signature } = await signSIWAMessage(fields, signer);
+ */
+import type { Address, Hex, WalletClient } from 'viem';
+import type { LocalAccount } from 'viem/accounts';
+/**
+ * Signer type detected during SIWA sign-in.
+ *
+ * - `'eoa'` — Externally Owned Account (ECDSA key pair)
+ * - `'sca'` — Smart Contract Account (ERC-1271, e.g. Safe, TBA, Kernel)
+ */
+export type SignerType = 'eoa' | 'sca';
+/**
+ * Core signer interface for message signing.
+ *
+ * Implement this interface to add support for new wallet providers.
+ */
+export interface Signer {
+    /** Get the signer's address */
+    getAddress(): Promise<Address>;
+    /** Sign a message (EIP-191 personal_sign) */
+    signMessage(message: string): Promise<Hex>;
+    /**
+     * Sign raw bytes (optional).
+     * Used by ERC-8128 for HTTP message signatures.
+     * If not implemented, signMessage will be used as fallback.
+     */
+    signRawMessage?(rawHex: Hex): Promise<Hex>;
+}
+/**
+ * Extended signer with transaction signing capabilities.
+ *
+ * Required for onchain operations like agent registration.
+ */
+export interface TransactionSigner extends Signer {
+    /** Sign a transaction and return the serialized signed transaction */
+    signTransaction(tx: TransactionRequest): Promise<Hex>;
+}
+/** Transaction request compatible with viem */
+export interface TransactionRequest {
+    to?: Address;
+    data?: Hex;
+    value?: bigint;
+    nonce?: number;
+    chainId?: number;
+    gas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    gasPrice?: bigint;
+    type?: number | string;
+    accessList?: any[];
+}
+/** Configuration for the keyring proxy signer */
+export interface KeyringProxyConfig {
+    /** URL of the keyring proxy server (or KEYRING_PROXY_URL env var) */
+    proxyUrl?: string;
+    /** HMAC shared secret (or KEYRING_PROXY_SECRET env var) */
+    proxySecret?: string;
+}
+/**
+ * Create a signer backed by the keyring proxy server.
+ *
+ * The private key is stored securely in the proxy server and never
+ * enters the calling process. All signing operations are performed
+ * via HMAC-authenticated HTTP requests.
+ *
+ * @param config - Proxy URL and secret (or use env vars)
+ * @returns A TransactionSigner that delegates to the keyring proxy
+ *
+ * @example
+ * ```typescript
+ * const signer = createKeyringProxySigner({
+ *   proxyUrl: 'http://localhost:3100',
+ *   proxySecret: 'my-secret',
+ * });
+ * const { message, signature } = await signSIWAMessage(fields, signer);
+ * ```
+ */
+export declare function createKeyringProxySigner(config?: KeyringProxyConfig): TransactionSigner;
+/**
+ * Create a signer from a viem LocalAccount.
+ *
+ * Use this when you have direct access to a private key via
+ * viem's `privateKeyToAccount()` or similar.
+ *
+ * @param account - A viem LocalAccount (from privateKeyToAccount, mnemonicToAccount, etc.)
+ * @returns A TransactionSigner that signs using the local account
+ *
+ * @example
+ * ```typescript
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const signer = createLocalAccountSigner(account);
+ * const { message, signature } = await signSIWAMessage(fields, signer);
+ * ```
+ */
+export declare function createLocalAccountSigner(account: LocalAccount): TransactionSigner;
+/**
+ * Create a signer from a viem WalletClient.
+ *
+ * Use this for browser wallets (MetaMask, etc.), embedded wallets (Privy),
+ * WalletConnect, or any wallet that provides an EIP-1193 provider.
+ *
+ * @param client - A viem WalletClient
+ * @param account - Optional specific account address to use
+ * @returns A Signer that delegates to the WalletClient
+ *
+ * @example
+ * ```typescript
+ * // With Privy embedded wallet
+ * const provider = await privyWallet.getEthereumProvider();
+ * const walletClient = createWalletClient({
+ *   chain: baseSepolia,
+ *   transport: custom(provider),
+ * });
+ * const signer = createWalletClientSigner(walletClient);
+ *
+ * // With browser wallet (MetaMask)
+ * const walletClient = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * });
+ * const signer = createWalletClientSigner(walletClient);
+ * ```
+ */
+export declare function createWalletClientSigner(client: WalletClient, account?: Address): Signer;

package/dist/signer.js

@@ -0,0 +1,179 @@
+/**
+ * signer.ts
+ *
+ * Wallet-agnostic signing abstraction for SIWA.
+ *
+ * This module provides a `Signer` interface that abstracts signing operations,
+ * allowing developers to use any wallet provider without changing the SDK.
+ *
+ * Available signer implementations:
+ *   - createKeyringProxySigner(config)    — Keyring proxy server (HMAC-authenticated)
+ *   - createLocalAccountSigner(account)   — viem LocalAccount (privateKeyToAccount)
+ *   - createWalletClientSigner(client)    — viem WalletClient (Privy, MetaMask, etc.)
+ *
+ * Usage:
+ *   import { signSIWAMessage, createLocalAccountSigner } from '@buildersgarden/siwa';
+ *   import { privateKeyToAccount } from 'viem/accounts';
+ *
+ *   const account = privateKeyToAccount('0x...');
+ *   const signer = createLocalAccountSigner(account);
+ *   const { message, signature } = await signSIWAMessage(fields, signer);
+ */
+import { computeHmac } from './proxy-auth.js';
+// ─── Internal: Keyring Proxy Request ─────────────────────────────────
+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('Keyring proxy requires KEYRING_PROXY_URL or config.proxyUrl');
+    }
+    if (!secret) {
+        throw new Error('Keyring proxy 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',
+        headers: {
+            'Content-Type': 'application/json',
+            ...hmacHeaders,
+        },
+        body: bodyStr,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Proxy ${endpoint} failed (${res.status}): ${text}`);
+    }
+    return res.json();
+}
+// ─── Keyring Proxy Signer ────────────────────────────────────────────
+/**
+ * Create a signer backed by the keyring proxy server.
+ *
+ * The private key is stored securely in the proxy server and never
+ * enters the calling process. All signing operations are performed
+ * via HMAC-authenticated HTTP requests.
+ *
+ * @param config - Proxy URL and secret (or use env vars)
+ * @returns A TransactionSigner that delegates to the keyring proxy
+ *
+ * @example
+ * ```typescript
+ * const signer = createKeyringProxySigner({
+ *   proxyUrl: 'http://localhost:3100',
+ *   proxySecret: 'my-secret',
+ * });
+ * const { message, signature } = await signSIWAMessage(fields, signer);
+ * ```
+ */
+export function createKeyringProxySigner(config = {}) {
+    return {
+        async getAddress() {
+            const data = await proxyRequest(config, '/get-address');
+            return data.address;
+        },
+        async signMessage(message) {
+            const data = await proxyRequest(config, '/sign-message', { message });
+            return data.signature;
+        },
+        async signRawMessage(rawHex) {
+            const data = await proxyRequest(config, '/sign-message', {
+                message: rawHex,
+                raw: true,
+            });
+            return data.signature;
+        },
+        async signTransaction(tx) {
+            const data = await proxyRequest(config, '/sign-transaction', { tx });
+            return data.signedTx;
+        },
+    };
+}
+// ─── Local Account Signer ────────────────────────────────────────────
+/**
+ * Create a signer from a viem LocalAccount.
+ *
+ * Use this when you have direct access to a private key via
+ * viem's `privateKeyToAccount()` or similar.
+ *
+ * @param account - A viem LocalAccount (from privateKeyToAccount, mnemonicToAccount, etc.)
+ * @returns A TransactionSigner that signs using the local account
+ *
+ * @example
+ * ```typescript
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const signer = createLocalAccountSigner(account);
+ * const { message, signature } = await signSIWAMessage(fields, signer);
+ * ```
+ */
+export function createLocalAccountSigner(account) {
+    return {
+        async getAddress() {
+            return account.address;
+        },
+        async signMessage(message) {
+            return account.signMessage({ message });
+        },
+        async signRawMessage(rawHex) {
+            return account.signMessage({ message: { raw: rawHex } });
+        },
+        async signTransaction(tx) {
+            return account.signTransaction(tx);
+        },
+    };
+}
+// ─── WalletClient Signer ─────────────────────────────────────────────
+/**
+ * Create a signer from a viem WalletClient.
+ *
+ * Use this for browser wallets (MetaMask, etc.), embedded wallets (Privy),
+ * WalletConnect, or any wallet that provides an EIP-1193 provider.
+ *
+ * @param client - A viem WalletClient
+ * @param account - Optional specific account address to use
+ * @returns A Signer that delegates to the WalletClient
+ *
+ * @example
+ * ```typescript
+ * // With Privy embedded wallet
+ * const provider = await privyWallet.getEthereumProvider();
+ * const walletClient = createWalletClient({
+ *   chain: baseSepolia,
+ *   transport: custom(provider),
+ * });
+ * const signer = createWalletClientSigner(walletClient);
+ *
+ * // With browser wallet (MetaMask)
+ * const walletClient = createWalletClient({
+ *   chain: mainnet,
+ *   transport: custom(window.ethereum),
+ * });
+ * const signer = createWalletClientSigner(walletClient);
+ * ```
+ */
+export function createWalletClientSigner(client, account) {
+    const resolveAccount = async () => {
+        if (account)
+            return account;
+        const addresses = await client.getAddresses();
+        if (!addresses || addresses.length === 0) {
+            throw new Error('No address found in wallet');
+        }
+        return addresses[0];
+    };
+    return {
+        async getAddress() {
+            return resolveAccount();
+        },
+        async signMessage(message) {
+            const addr = await resolveAccount();
+            return client.signMessage({ account: addr, message });
+        },
+        async signRawMessage(rawHex) {
+            const addr = await resolveAccount();
+            return client.signMessage({ account: addr, message: { raw: rawHex } });
+        },
+    };
+}

package/dist/siwa.d.ts

@@ -9,6 +9,7 @@
  */
 import { type PublicClient } from 'viem';
 import { AgentProfile, ServiceType, TrustModel } from './registry.js';
+import type { Signer, SignerType } from './signer.js';
 export declare enum SIWAErrorCode {
     INVALID_SIGNATURE = "INVALID_SIGNATURE",
     DOMAIN_MISMATCH = "DOMAIN_MISMATCH",
@@ -47,6 +48,7 @@ export interface SIWAVerificationResult {
     agentRegistry: string;
     chainId: number;
     verified: 'offline' | 'onchain';
+    signerType?: SignerType;
     code?: SIWAErrorCode;
     error?: string;
     agent?: AgentProfile;
@@ -58,6 +60,7 @@ export interface SIWAVerifyCriteria {
     requiredServices?: (ServiceType | (string & {}))[];
     mustBeActive?: boolean;
     requiredTrust?: (TrustModel | (string & {}))[];
+    allowedSignerTypes?: SignerType[];
     custom?: (agent: AgentProfile) => boolean | Promise<boolean>;
 }
 export interface SIWAResponse {
@@ -67,6 +70,7 @@ export interface SIWAResponse {
     agentRegistry?: string;
     chainId?: number;
     verified?: 'offline' | 'onchain';
+    signerType?: SignerType;
     code?: SIWAErrorCode;
     error?: string;
     action?: SIWAAction;
@@ -141,26 +145,47 @@ export declare function createSIWANonce(params: SIWANonceParams, client: PublicC
 /**
  * Fields accepted by signSIWAMessage.
  * `address` is optional — when omitted, the address is fetched directly
- * from the keystore (the trusted source of truth for the agent wallet).
+ * from the signer (the trusted source of truth for the agent wallet).
  */
 export type SIWASignFields = Omit<SIWAMessageFields, 'address'> & {
     address?: string;
 };
 /**
- * Sign a SIWA message using the secure keystore.
+ * Sign a SIWA message using the provided signer.
  *
- * The private key is loaded from the keystore, used to sign, and discarded.
- * It is NEVER returned or exposed to the caller.
+ * The signer abstracts the wallet implementation, allowing you to use:
+ *   - createKeyringProxySigner(config)   — Keyring proxy server
+ *   - createLocalAccountSigner(account)  — viem LocalAccount (private key)
+ *   - createWalletClientSigner(client)   — viem WalletClient (Privy, MetaMask, etc.)
  *
- * The agent address is always resolved from the keystore — the single source
+ * The agent address is always resolved from the signer — the single source
  * of truth — so the caller doesn't need to supply (or risk hallucinating) it.
- * If `fields.address` is provided it must match the keystore address.
+ * If `fields.address` is provided it must match the signer's address.
  *
  * @param fields — SIWA message fields (domain, agentId, etc.). `address` is optional.
- * @param keystoreConfig — Optional keystore configuration override
+ * @param signer — A Signer implementation (see createKeyringProxySigner, createLocalAccountSigner, createWalletClientSigner)
  * @returns { message, signature, address } — the plaintext message, EIP-191 signature, and resolved address
+ *
+ * @example
+ * ```typescript
+ * import { signSIWAMessage, createLocalAccountSigner } from '@buildersgarden/siwa';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const account = privateKeyToAccount('0x...');
+ * const signer = createLocalAccountSigner(account);
+ *
+ * const { message, signature, address } = await signSIWAMessage({
+ *   domain: 'example.com',
+ *   uri: 'https://example.com/login',
+ *   agentId: 123,
+ *   agentRegistry: 'eip155:84532:0x...',
+ *   chainId: 84532,
+ *   nonce: 'abc123',
+ *   issuedAt: new Date().toISOString(),
+ * }, signer);
+ * ```
  */
-export declare function signSIWAMessage(fields: SIWASignFields, keystoreConfig?: import('./keystore').KeystoreConfig): Promise<{
+export declare function signSIWAMessage(fields: SIWASignFields, signer: Signer): Promise<{
     message: string;
     signature: string;
     address: string;