@agirails/sdk 2.2.2 → 2.3.0

package/src/config/syncOperations.ts

@@ -0,0 +1,279 @@
+/**
+ * Sync Operations - Pull + Diff for AGIRAILS.md
+ *
+ * Terraform-style sync: compare local AGIRAILS.md with on-chain state.
+ * Never auto-overwrites — shows diff and requires explicit confirmation.
+ *
+ * @module config/syncOperations
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { Provider } from 'ethers';
+import { computeConfigHash, parseAgirailsMd, serializeAgirailsMd } from './agirailsmd';
+import { validateCID } from '../utils/validation';
+import { AgentRegistryClient } from '../registry/AgentRegistryClient';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Public IPFS gateways for read-only access (no credentials needed) */
+const IPFS_GATEWAYS = [
+  'https://ipfs.io/ipfs/',
+  'https://dweb.link/ipfs/',
+  'https://cloudflare-ipfs.com/ipfs/',
+];
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DiffResult {
+  /** Whether local and on-chain are in sync */
+  inSync: boolean;
+  /** Local config hash (or null if no local file) */
+  localHash: string | null;
+  /** On-chain config hash (or zero hash if not published) */
+  onChainHash: string;
+  /** On-chain IPFS CID (or empty if not published) */
+  onChainCID: string;
+  /** Whether on-chain has a published config */
+  hasOnChainConfig: boolean;
+  /** Whether local file exists */
+  hasLocalFile: boolean;
+  /** Human-readable status message */
+  status: 'in-sync' | 'local-ahead' | 'remote-ahead' | 'diverged' | 'no-local' | 'no-remote';
+}
+
+export interface PullResult {
+  /** Whether a file was written */
+  written: boolean;
+  /** The pulled content (if any) */
+  content?: string;
+  /** IPFS CID that was fetched */
+  cid?: string;
+  /** Status message */
+  status: string;
+}
+
+export interface DiffOptions {
+  /** Path to local AGIRAILS.md */
+  path: string;
+  /** Agent address to check on-chain */
+  agentAddress: string;
+  /** AgentRegistry contract address */
+  registryAddress: string;
+  /** Provider for reading on-chain state */
+  provider: Provider;
+}
+
+export interface PullOptions extends DiffOptions {
+  /** Force overwrite without confirmation */
+  force?: boolean;
+}
+
+// ============================================================================
+// Diff
+// ============================================================================
+
+const ZERO_HASH = '0x' + '0'.repeat(64);
+
+/**
+ * Compare local AGIRAILS.md with on-chain config state.
+ *
+ * @param options - Diff configuration
+ * @returns Diff result showing sync status
+ */
+export async function diff(options: DiffOptions): Promise<DiffResult> {
+  const { path, agentAddress, registryAddress, provider } = options;
+
+  // Read on-chain state
+  const registryClient = AgentRegistryClient.readOnly(registryAddress, provider);
+  const onChainState = await registryClient.getConfig(agentAddress);
+
+  const hasOnChainConfig = onChainState.configHash !== ZERO_HASH && onChainState.configCID !== '';
+  const onChainHash = onChainState.configHash;
+  const onChainCID = onChainState.configCID;
+
+  // Read local state
+  const hasLocalFile = existsSync(path);
+  let localHash: string | null = null;
+
+  if (hasLocalFile) {
+    const content = readFileSync(path, 'utf-8');
+    const { configHash } = computeConfigHash(content);
+    localHash = configHash;
+  }
+
+  // Determine status
+  let status: DiffResult['status'];
+  let inSync: boolean;
+
+  if (!hasLocalFile && !hasOnChainConfig) {
+    status = 'no-local';
+    inSync = true; // both empty = in sync
+  } else if (!hasLocalFile && hasOnChainConfig) {
+    status = 'remote-ahead';
+    inSync = false;
+  } else if (hasLocalFile && !hasOnChainConfig) {
+    status = 'no-remote';
+    inSync = false;
+  } else if (localHash === onChainHash) {
+    status = 'in-sync';
+    inSync = true;
+  } else {
+    // Both exist but hashes differ. Use the stored config_hash in frontmatter
+    // to determine directionality:
+    // - config_hash matches on-chain → user edited locally after last publish → local-ahead
+    // - config_hash doesn't match on-chain → remote was updated too → diverged
+    // - no config_hash → never published from this file → local-ahead
+    status = 'diverged';
+    inSync = false;
+
+    if (hasLocalFile) {
+      try {
+        const content = readFileSync(path, 'utf-8');
+        const { frontmatter } = parseAgirailsMd(content);
+        if (!frontmatter.config_hash) {
+          // Never published — local is the only source
+          status = 'local-ahead';
+        } else if (frontmatter.config_hash === onChainHash) {
+          // Last publish matches on-chain, so local edits are newer
+          status = 'local-ahead';
+        }
+        // else: frontmatter.config_hash !== onChainHash → remote updated → diverged
+      } catch {
+        // Parse error — keep as diverged
+      }
+    }
+  }
+
+  return {
+    inSync,
+    localHash,
+    onChainHash,
+    onChainCID,
+    hasOnChainConfig,
+    hasLocalFile,
+    status,
+  };
+}
+
+// ============================================================================
+// IPFS Fetch (public gateway, no credentials needed)
+// ============================================================================
+
+/**
+ * Fetch content from IPFS using public gateways (no Filebase credentials needed).
+ * Tries multiple gateways with fallback.
+ *
+ * @param cid - IPFS CID to fetch (validated before use)
+ * @returns Raw content as string
+ * @throws InvalidCIDError if CID format is invalid
+ * @throws Error if all gateways fail
+ */
+async function fetchFromIPFS(cid: string): Promise<string> {
+  // Validate CID format before hitting any gateway
+  validateCID(cid, 'onChainCID');
+
+  const errors: string[] = [];
+
+  for (const gateway of IPFS_GATEWAYS) {
+    try {
+      const response = await fetch(`${gateway}${cid}`, {
+        signal: AbortSignal.timeout(15_000),
+      });
+      if (!response.ok) {
+        errors.push(`${gateway}: HTTP ${response.status}`);
+        continue;
+      }
+      return await response.text();
+    } catch (err) {
+      errors.push(`${gateway}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  throw new Error(
+    `Failed to fetch CID ${cid} from all IPFS gateways:\n${errors.map(e => `  - ${e}`).join('\n')}`
+  );
+}
+
+// ============================================================================
+// Pull
+// ============================================================================
+
+/**
+ * Pull on-chain config to local AGIRAILS.md.
+ *
+ * Downloads from IPFS via public gateways (no Filebase credentials needed),
+ * verifies integrity against on-chain configHash, then writes locally.
+ *
+ * @param options - Pull configuration
+ * @returns Pull result
+ */
+export async function pull(options: PullOptions): Promise<PullResult> {
+  const { path, agentAddress, registryAddress, provider, force = false } = options;
+
+  // First, run diff
+  const diffResult = await diff({ path, agentAddress, registryAddress, provider });
+
+  if (!diffResult.hasOnChainConfig) {
+    return {
+      written: false,
+      status: 'No config published on-chain for this agent.',
+    };
+  }
+
+  if (diffResult.inSync) {
+    return {
+      written: false,
+      status: 'Already in sync. No changes needed.',
+    };
+  }
+
+  // Fetch raw AGIRAILS.md from IPFS (public gateway, no credentials)
+  const content = await fetchFromIPFS(diffResult.onChainCID);
+
+  // Integrity verification: hash downloaded content and compare with on-chain hash
+  const { configHash: downloadedHash } = computeConfigHash(content);
+  if (downloadedHash !== diffResult.onChainHash) {
+    return {
+      written: false,
+      cid: diffResult.onChainCID,
+      status: `Integrity check failed! Downloaded content hash (${downloadedHash}) does not match on-chain hash (${diffResult.onChainHash}). The IPFS content may have been tampered with.`,
+    };
+  }
+
+  // Check if local file exists and we're not forcing
+  if (diffResult.hasLocalFile && !force) {
+    return {
+      written: false,
+      content,
+      cid: diffResult.onChainCID,
+      status: `Remote config differs from local. Use --force to overwrite. CID: ${diffResult.onChainCID}`,
+    };
+  }
+
+  // Stamp on-chain metadata into frontmatter so diff heuristic can detect
+  // future remote changes (without this, pulled files have no config_hash
+  // and diff would always report "local-ahead" instead of "diverged")
+  const { frontmatter, body } = parseAgirailsMd(content);
+  const stamped = serializeAgirailsMd(
+    {
+      ...frontmatter,
+      config_hash: diffResult.onChainHash,
+      config_cid: diffResult.onChainCID,
+    },
+    body
+  );
+
+  // Write the stamped file
+  writeFileSync(path, stamped, 'utf-8');
+
+  return {
+    written: true,
+    content: stamped,
+    cid: diffResult.onChainCID,
+    status: `Pulled and verified config from IPFS (${diffResult.onChainCID}) → ${path}`,
+  };
+}

package/src/index.ts

@@ -176,6 +176,9 @@ export {
   createUsedAttestationTracker,
 } from './utils/UsedAttestationTracker';
 
+// Wallet
+export { resolvePrivateKey, getCachedAddress } from './wallet/keystore';
+
 // Helper utilities
 export {
   USDC,

package/src/level0/request.ts

@@ -14,6 +14,7 @@ import { NoProviderFoundError, TimeoutError, ValidationError } from '../errors';
 import { safeJSONParse, validateServiceName, isValidAddress } from '../utils/security';
 import { Logger } from '../utils/Logger';
 import { ethers } from 'ethers';
+import { resolvePrivateKey } from '../wallet/keystore';
 
 /**
  * Request a service
@@ -61,7 +62,6 @@ export async function request(
   service: string,
   options: RequestOptions
 ): Promise<RequestResult> {
-  // SECURITY FIX (H-2): Validate service name to prevent injection
   const validatedService = validateServiceName(service);
 
   const logger = new Logger({ source: 'request' });
@@ -75,12 +75,8 @@ export async function request(
     });
   }
 
-  // SECURITY FIX (RPCURL): Use rpcUrl from options or fallback to network default
-  // This allows Level0 request() to work with testnet/mainnet without requiring
-  // explicit rpcUrl if user is okay with public RPC endpoints.
   let rpcUrl = options.rpcUrl;
   if (!rpcUrl && (options.network === 'testnet' || options.network === 'mainnet')) {
-    // Import getNetwork to get default rpcUrl from network config
     const { getNetwork } = await import('../config/networks');
     const networkName = options.network === 'testnet' ? 'base-sepolia' : 'base-mainnet';
     const networkConfig = getNetwork(networkName);
@@ -88,27 +84,27 @@ export async function request(
     logger.info(`Using default RPC URL for ${networkName}: ${rpcUrl}`);
   }
 
-  // Create ACTP client
+  const resolvedKey = await resolveKeyIfNeeded(options.wallet, options.network, options.stateDirectory);
+  const resolvedAddress = resolvedKey
+    ? new ethers.Wallet(resolvedKey).address.toLowerCase()
+    : undefined;
+
   const client = await ACTPClient.create({
     mode: options.network === 'testnet' ? 'testnet' : options.network === 'mainnet' ? 'mainnet' : 'mock',
-    requesterAddress: getRequesterAddress(options.wallet),
+    requesterAddress: resolvedAddress || getRequesterAddress(options.wallet),
     stateDirectory: options.stateDirectory,
-    privateKey: getPrivateKey(options.wallet),
+    privateKey: resolvedKey || getPrivateKey(options.wallet),
     rpcUrl,
   });
 
-  // Calculate deadline
   const deadline = calculateDeadline(options.deadline, options.timeout);
-
-  // Create transaction with service metadata
   const startTime = Date.now();
 
   try {
-    const requesterAddress = getRequesterAddress(options.wallet);
+    const requesterAddress = resolvedAddress || getRequesterAddress(options.wallet);
     const amountWei = (options.budget * 1_000_000).toString(); // Convert to USDC wei (6 decimals)
 
     // In mock mode, ensure requester has enough funds
-    // This is a convenience feature for testing - won't exist in production
     if (client.runtime && 'mintTokens' in client.runtime) {
       const mockRuntime = client.runtime as any;
       const balance = await mockRuntime.getBalance(requesterAddress);
@@ -122,30 +118,19 @@ export async function request(
       }
     }
 
-    // ARCHITECTURE FIX: Service metadata handling
-    // - MockRuntime: Store plaintext for provider matching and input extraction
-    // - BlockchainRuntime: Hashes plaintext internally before sending on-chain
-    //
-    // Provider needs plaintext to:
-    // 1. Match service name to handler (findServiceHandler)
-    // 2. Extract input data for job execution (extractJobInput)
-    //
-    // On-chain storage uses bytes32 hash (BlockchainRuntime.validateServiceHash handles this)
     const serviceMetadata = JSON.stringify({
       service: validatedService,
       input: options.input,
       timestamp: Date.now(),
     });
 
-    // Create transaction with structured metadata
-    // MockRuntime stores as-is, BlockchainRuntime hashes for on-chain
     const txId = await client.runtime.createTransaction({
       provider,
       requester: requesterAddress,
       amount: amountWei,
       deadline,
-      disputeWindow: options.disputeWindow ?? 172800, // Default 2 days
-      serviceDescription: serviceMetadata, // Structured JSON for provider parsing
+      disputeWindow: options.disputeWindow ?? 172800,
+      serviceDescription: serviceMetadata,
     });
 
     // Call onProgress if provided
@@ -187,12 +172,8 @@ export async function request(
       attempts++;
     }
 
-    // Check if we got a result
     if (!tx || (tx.state !== 'DELIVERED' && tx.state !== 'SETTLED')) {
-      const _timedOut = true; // Flag for potential future use
-
-      // SECURITY FIX (H-3): Auto-cancel transaction on timeout if still in early state
-      // This prevents funds from being locked indefinitely if provider never responds
+      // Auto-cancel on timeout if still in early state
       if (tx && (tx.state === 'INITIATED' || tx.state === 'COMMITTED')) {
         try {
           logger.warn('Transaction timed out, cancelling to release funds', {
@@ -200,8 +181,6 @@ export async function request(
             state: tx.state,
           });
 
-          // ACTUALLY CANCEL THE TRANSACTION
-          // Check if runtime has cancelTransaction method
           if ('cancelTransaction' in client.runtime) {
             await (client.runtime as any).cancelTransaction(txId);
             logger.info('Transaction cancelled successfully', { txId });
@@ -211,7 +190,6 @@ export async function request(
             (error as any).wasCancelled = true;
             throw error;
           } else {
-            // Fallback: Transition to CANCELLED state
             await client.runtime.transitionState(txId, 'CANCELLED');
             logger.info('Transaction cancelled successfully (via transitionState)', { txId });
 
@@ -222,7 +200,6 @@ export async function request(
           }
         } catch (cancelError) {
           logger.error('Failed to cancel timed-out transaction', { txId }, cancelError as Error);
-          // Continue with original timeout error
         }
       }
 
@@ -232,13 +209,8 @@ export async function request(
       throw error;
     }
 
-    // SECURITY FIX (C-3): Safe JSON parsing with schema validation
-    // Extract result from delivery proof
     let deliveredResult: any = {};
     if (tx.deliveryProof) {
-      // Define expected schema for delivery proof
-      // NOTE: 'type' field with value 'delivery.proof' is the unique wrapper marker
-      // (set by ProofGenerator.generateDeliveryProof) that handlers won't naturally return
       const DELIVERY_PROOF_SCHEMA: Record<string, string> = {
         result: 'any',
         data: 'any',
@@ -247,28 +219,18 @@ export async function request(
         timestamp: 'number',
         contentHash: 'string',
         txId: 'string',
-        type: 'string',  // Unique marker: 'delivery.proof'
+        type: 'string',
       };
 
-      // Use safeJSONParse with schema validation which:
-      // 1. Validates JSON structure
-      // 2. Removes __proto__, constructor, prototype properties
-      // 3. Prevents prototype pollution attacks
-      // 4. Validates against expected schema
-      // 5. Checks size limits to prevent DoS
-      // 6. Returns null if parsing fails
       const parsed = safeJSONParse(tx.deliveryProof, DELIVERY_PROOF_SCHEMA);
 
       if (parsed !== null) {
         deliveredResult = parsed;
       } else {
-        // If parsing failed, treat as plain text (but don't execute or eval)
         deliveredResult = { data: tx.deliveryProof };
         logger.warn('Failed to parse delivery proof as JSON', { txId });
       }
     } else if (options.network === 'testnet' || options.network === 'mainnet') {
-      // KNOWN LIMITATION: BlockchainRuntime doesn't fetch deliveryProof from IPFS yet
-      // Result will be empty until this is implemented
       logger.warn(
         'Delivery proof retrieval not yet implemented for testnet/mainnet. ' +
         'Result may be empty. Use ACTPClient with manual proof handling for production.',
@@ -276,17 +238,11 @@ export async function request(
       );
     }
 
-    // SECURITY FIX (CRITICAL-2): Release escrow only after proper validation
-    // For mock mode, auto-release is safe. For testnet/mainnet, require attestation.
     if (tx.state === 'DELIVERED' && tx.escrowId) {
-      // Wait for dispute window to expire
       const disputeWindowEnd = (tx.completedAt ?? 0) + tx.disputeWindow;
       const currentTime = client.runtime.time.now();
 
       if (currentTime >= disputeWindowEnd) {
-        // SECURITY FIX (CRITICAL-2): Only auto-release in mock mode
-        // For real networks, the requester should manually verify and release
-        // or use attestation-based verification
         const isMockMode = options.network !== 'testnet' && options.network !== 'mainnet';
 
         if (isMockMode) {
@@ -353,6 +309,20 @@ export async function request(
   }
 }
 
+/**
+ * Resolve private key from keystore if wallet is auto/undefined and network is testnet/mainnet.
+ * Returns undefined if wallet is explicitly set (caller should use getPrivateKey instead).
+ */
+async function resolveKeyIfNeeded(
+  wallet?: 'auto' | 'connect' | string | { privateKey: string },
+  network?: string,
+  stateDirectory?: string
+): Promise<string | undefined> {
+  if (wallet && wallet !== 'auto') return undefined; // explicit wallet, skip auto-detect
+  if (network !== 'testnet' && network !== 'mainnet') return undefined;
+  return resolvePrivateKey(stateDirectory);
+}
+
 /**
  * Find provider for service
  *
@@ -381,23 +351,10 @@ function findProvider(
   return providers[0];
 }
 
-/**
- * Get requester address from wallet option
- *
- * SECURITY FIX (HIGH): Properly derive addresses from private keys using ethers
- * Never fabricate addresses or use partial key slices as addresses.
- *
- * @param wallet - Wallet configuration
- * @returns Ethereum address
- * @throws {ValidationError} If address format is invalid
- */
 function getRequesterAddress(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string {
-  // For mock mode only: generate deterministic address
-  // This is only safe because mock mode doesn't involve real funds
   if (!wallet || wallet === 'auto') {
-    // Create a valid Ethereum address (40 hex chars) - ONLY for mock mode
     const hex = Buffer.from('requester').toString('hex');
     return '0x' + hex.padEnd(40, '0');
   }
@@ -407,15 +364,12 @@ function getRequesterAddress(
   }
 
   if (typeof wallet === 'string') {
-    // SECURITY FIX (HIGH): Validate address format
     if (!isValidAddress(wallet)) {
       throw new ValidationError('wallet', `Invalid Ethereum address format: ${wallet}`);
     }
     return wallet.toLowerCase();
   }
 
-  // SECURITY FIX (HIGH): Derive address from private key using ethers
-  // This is the correct way to get address from a private key
   try {
     const walletInstance = new ethers.Wallet(wallet.privateKey);
     return walletInstance.address.toLowerCase();
@@ -424,15 +378,6 @@ function getRequesterAddress(
   }
 }
 
-/**
- * Get private key from wallet option
- *
- * SECURITY FIX (HIGH): Validate private key format before use
- *
- * @param wallet - Wallet configuration
- * @returns Private key or undefined
- * @throws {ValidationError} If private key format is invalid
- */
 function getPrivateKey(
   wallet?: 'auto' | 'connect' | string | { privateKey: string }
 ): string | undefined {
@@ -440,12 +385,8 @@ function getPrivateKey(
     return undefined;
   }
 
-  // If wallet is a string that looks like a private key (0x + 64 hex chars), use it
-  // Otherwise treat it as an address and return undefined
   if (typeof wallet === 'string') {
-    // Check if it looks like a private key (0x + 64 hex chars)
     if (/^0x[0-9a-fA-F]{64}$/.test(wallet)) {
-      // Validate by trying to create a wallet
       try {
         new ethers.Wallet(wallet);
         return wallet;
@@ -453,11 +394,9 @@ function getPrivateKey(
         throw new ValidationError('wallet', 'Invalid private key format');
       }
     }
-    // It's an address, not a private key
     return undefined;
   }
 
-  // Validate private key format
   if (wallet.privateKey) {
     try {
       new ethers.Wallet(wallet.privateKey);