@agirails/sdk 2.0.3 → 2.2.0

package/src/storage/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Storage Module - Hybrid Storage Architecture (AIP-7 §4)
+ *
+ * Two-tier storage model:
+ * - Tier 1: IPFS (Filebase) for hot storage
+ * - Tier 2: Arweave (Irys) for permanent archive
+ *
+ * @module storage
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   FilebaseClient,
+ *   ArweaveClient,
+ *   ArchiveBundleBuilder
+ * } from '@agirails/sdk/storage';
+ *
+ * // IPFS hot storage
+ * const ipfs = new FilebaseClient({
+ *   accessKey: process.env.FILEBASE_ACCESS_KEY!,
+ *   secretKey: process.env.FILEBASE_SECRET_KEY!
+ * });
+ *
+ * // Arweave permanent storage
+ * const arweave = await ArweaveClient.create({
+ *   privateKey: process.env.ARCHIVE_KEY!,
+ *   rpcUrl: process.env.BASE_RPC!
+ * });
+ *
+ * // Build archive bundle
+ * const bundle = new ArchiveBundleBuilder()
+ *   .setTransactionId(txId)
+ *   .setChainId(8453)
+ *   // ... other fields
+ *   .build();
+ *
+ * // Upload to Arweave
+ * const result = await arweave.uploadBundle(bundle);
+ * console.log('Archived at:', result.txId);
+ * ```
+ */
+
+// ============================================================================
+// Clients
+// ============================================================================
+
+export { FilebaseClient } from './FilebaseClient';
+export { ArweaveClient } from './ArweaveClient';
+
+// ============================================================================
+// Builders
+// ============================================================================
+
+export {
+  ArchiveBundleBuilder,
+  computeContentHash,
+  validateArchiveBundle
+} from './ArchiveBundleBuilder';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type {
+  // Filebase
+  FilebaseConfig,
+
+  // Arweave
+  ArweaveConfig,
+  IrysCurrency,
+  IrysNetwork,
+
+  // Archive Bundle
+  ArchiveBundle,
+  ArchiveChainId,
+  ArchiveFinalState,
+  ArchiveParticipants,
+  ArchiveReferences,
+  ArchiveHashes,
+  ArchiveSignatures,
+  ArchiveAttestation,
+  ArchiveSettlement,
+  EscrowRelease,
+  ArchiveTags,
+
+  // Results
+  IPFSUploadResult,
+  ArweaveUploadResult,
+  DownloadResult
+} from './types';
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+export { ARCHIVE_BUNDLE_TYPE } from './types';

package/src/storage/types.ts

@@ -0,0 +1,348 @@
+/**
+ * Storage Types (AIP-7 §4)
+ *
+ * Type definitions for the AGIRAILS hybrid storage architecture:
+ * - Tier 1: IPFS (Filebase) for hot storage
+ * - Tier 2: Arweave (Irys) for permanent archive
+ */
+
+// ============================================================================
+// Filebase Configuration
+// ============================================================================
+
+/**
+ * Configuration for Filebase S3-compatible IPFS client
+ */
+export interface FilebaseConfig {
+  /**
+   * Filebase access key ID
+   * Get from: https://console.filebase.com/keys
+   */
+  accessKey: string;
+
+  /**
+   * Filebase secret access key
+   * SECURITY: Store in environment variable, never in code
+   */
+  secretKey: string;
+
+  /**
+   * Filebase bucket name
+   * @default 'agirails-storage'
+   */
+  bucket?: string;
+
+  /**
+   * Filebase S3 endpoint
+   * @default 'https://s3.filebase.com'
+   */
+  endpoint?: string;
+
+  /**
+   * IPFS gateway URL for retrieval
+   * @default 'https://ipfs.filebase.io/ipfs/'
+   */
+  gatewayUrl?: string;
+
+  /**
+   * Request timeout in milliseconds
+   * @default 30000 (30 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Maximum file size in bytes for uploads
+   * @default 104857600 (100MB)
+   */
+  maxFileSize?: number;
+
+  /**
+   * Maximum download size in bytes (P1-1: DoS protection)
+   * Downloads exceeding this limit will be rejected
+   * @default 52428800 (50MB)
+   */
+  maxDownloadSize?: number;
+
+  /**
+   * Circuit breaker configuration for gateway health tracking
+   * When enabled, tracks gateway failures and temporarily blocks
+   * requests to unhealthy gateways (retry amplification protection)
+   */
+  circuitBreaker?: {
+    /** Enable circuit breaker (default: true) */
+    enabled?: boolean;
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Cooldown period in ms before attempting reset (default: 60000) */
+    resetTimeoutMs?: number;
+    /** Time window in ms for counting failures (default: 300000) */
+    failureWindowMs?: number;
+    /** Number of successes in half-open to close circuit (default: 2) */
+    successThreshold?: number;
+  };
+}
+
+// ============================================================================
+// Arweave Configuration
+// ============================================================================
+
+/**
+ * Supported Irys payment tokens
+ * @see https://docs.irys.xyz/build/d/features/supported-tokens
+ */
+export type IrysCurrency =
+  | 'base-eth'      // RECOMMENDED: Base ETH (native to AGIRAILS)
+  | 'ethereum'      // Ethereum mainnet ETH
+  | 'matic'         // Polygon MATIC
+  | 'arbitrum'      // Arbitrum ETH
+  | 'usdc-eth'      // USDC on Ethereum
+  | 'usdc-polygon'; // USDC on Polygon
+
+/**
+ * Irys network
+ */
+export type IrysNetwork = 'mainnet' | 'devnet';
+
+/**
+ * Configuration for Arweave client via Irys
+ */
+export interface ArweaveConfig {
+  /**
+   * Private key for signing transactions
+   * SECURITY: Store in environment variable, never in code
+   */
+  privateKey: string;
+
+  /**
+   * RPC URL for the payment chain
+   * Required for blockchain operations
+   */
+  rpcUrl: string;
+
+  /**
+   * Payment currency/token
+   * @default 'base-eth'
+   */
+  currency?: IrysCurrency;
+
+  /**
+   * Irys network (mainnet or devnet)
+   * @default 'mainnet'
+   */
+  network?: IrysNetwork;
+
+  /**
+   * Request timeout in milliseconds
+   * @default 60000 (60 seconds)
+   */
+  timeout?: number;
+
+  /**
+   * Circuit breaker configuration for gateway health tracking
+   * When enabled, tracks gateway failures and temporarily blocks
+   * requests to unhealthy gateways (retry amplification protection)
+   */
+  circuitBreaker?: {
+    /** Enable circuit breaker (default: true) */
+    enabled?: boolean;
+    /** Number of failures before opening circuit (default: 5) */
+    failureThreshold?: number;
+    /** Cooldown period in ms before attempting reset (default: 60000) */
+    resetTimeoutMs?: number;
+    /** Time window in ms for counting failures (default: 300000) */
+    failureWindowMs?: number;
+    /** Number of successes in half-open to close circuit (default: 2) */
+    successThreshold?: number;
+  };
+}
+
+// ============================================================================
+// Archive Bundle Types (AIP-7 §4.4)
+// ============================================================================
+
+/**
+ * Archive bundle type identifier
+ */
+export const ARCHIVE_BUNDLE_TYPE = 'actp.archive.v1.minimal' as const;
+
+/**
+ * Supported chain IDs for archive bundles
+ */
+export type ArchiveChainId = 8453 | 84532; // Base Mainnet | Base Sepolia
+
+/**
+ * Final transaction states that can be archived
+ */
+export type ArchiveFinalState = 'SETTLED' | 'CANCELLED';
+
+/**
+ * Transaction participants (addresses only, not full profiles)
+ */
+export interface ArchiveParticipants {
+  /** Requester Ethereum address */
+  requester: string;
+  /** Provider Ethereum address */
+  provider: string;
+}
+
+/**
+ * IPFS CID references to full content
+ */
+export interface ArchiveReferences {
+  /** IPFS CID of AIP-1 request metadata */
+  requestCID: string;
+  /** IPFS CID of AIP-4 delivery proof */
+  deliveryCID: string;
+  /** IPFS CID of actual result/output (optional) */
+  resultCID?: string;
+}
+
+/**
+ * Cryptographic hashes for verification
+ */
+export interface ArchiveHashes {
+  /** keccak256 of canonical request metadata JSON */
+  requestHash: string;
+  /** keccak256 of canonical delivery proof JSON */
+  deliveryHash: string;
+  /** serviceHash from ACTPKernel transaction */
+  serviceHash: string;
+}
+
+/**
+ * Cryptographic signatures for self-verification
+ */
+export interface ArchiveSignatures {
+  /** EIP-712 signature by provider over deliveryHash */
+  providerDeliverySignature: string;
+  /** Optional: requester signature authorizing settlement */
+  requesterSettlementSignature?: string;
+}
+
+/**
+ * EAS attestation reference
+ */
+export interface ArchiveAttestation {
+  /** Ethereum Attestation Service UID */
+  easUID: string;
+  /** EAS schema UID used for attestation (optional) */
+  schemaUID?: string;
+}
+
+/**
+ * Escrow release details
+ */
+export interface EscrowRelease {
+  /** Recipient address (provider or requester) */
+  to: string;
+  /** Released amount (USDC base units, string for BigInt safety) */
+  amount: string;
+}
+
+/**
+ * Settlement information
+ */
+export interface ArchiveSettlement {
+  /** Settlement timestamp (Unix seconds) */
+  settledAt: number;
+  /** Final transaction state */
+  finalState: ArchiveFinalState;
+  /** Escrow release details */
+  escrowReleased: EscrowRelease;
+  /** Platform fee collected (USDC base units) */
+  platformFee: string;
+  /** Whether transaction went through dispute */
+  wasDisputed: boolean;
+}
+
+/**
+ * Archive Bundle (AIP-7 §4.4 - Minimal Hash-First)
+ *
+ * Contains minimal metadata with cryptographic hashes and references.
+ * Full content (request metadata, delivery proof) remains on IPFS.
+ */
+export interface ArchiveBundle {
+  /** AGIRAILS protocol version (e.g., "1.0.0") */
+  protocolVersion: string;
+  /** Archive bundle schema version (e.g., "1.0.0") */
+  archiveSchemaVersion: string;
+  /** Archive bundle type identifier */
+  type: typeof ARCHIVE_BUNDLE_TYPE;
+  /** ACTP transaction ID (bytes32) */
+  txId: string;
+  /** Blockchain network chain ID */
+  chainId: ArchiveChainId;
+  /** Archive timestamp (Unix seconds) */
+  archivedAt: number;
+  /** Transaction participants (addresses only) */
+  participants: ArchiveParticipants;
+  /** IPFS CID references to full content */
+  references: ArchiveReferences;
+  /** Cryptographic hashes for verification */
+  hashes: ArchiveHashes;
+  /** Cryptographic signatures */
+  signatures: ArchiveSignatures;
+  /** EAS attestation reference (optional for cancelled transactions) */
+  attestation?: ArchiveAttestation;
+  /** Settlement information */
+  settlement: ArchiveSettlement;
+}
+
+// ============================================================================
+// Upload/Download Results
+// ============================================================================
+
+/**
+ * Result of uploading to IPFS
+ */
+export interface IPFSUploadResult {
+  /** IPFS CID (CIDv1, base32) */
+  cid: string;
+  /** Size of uploaded content in bytes */
+  size: number;
+  /** Upload timestamp */
+  uploadedAt: Date;
+}
+
+/**
+ * Result of uploading to Arweave
+ */
+export interface ArweaveUploadResult {
+  /** Arweave transaction ID */
+  txId: string;
+  /** Size of uploaded content in bytes */
+  size: number;
+  /** Upload timestamp */
+  uploadedAt: Date;
+  /** Cost in the payment currency (wei for ETH) */
+  cost: string;
+}
+
+/**
+ * Result of downloading content
+ */
+export interface DownloadResult<T = unknown> {
+  /** Downloaded and parsed content */
+  data: T;
+  /** Size of downloaded content in bytes */
+  size: number;
+  /** Download timestamp */
+  downloadedAt: Date;
+}
+
+// ============================================================================
+// Irys Tags
+// ============================================================================
+
+/**
+ * Arweave/Irys tags for archive bundles
+ */
+export interface ArchiveTags {
+  'Content-Type': 'application/json';
+  Protocol: 'AGIRAILS';
+  Version: string;
+  Schema: string;
+  Type: typeof ARCHIVE_BUNDLE_TYPE;
+  ChainId: string;
+  TxId: string;
+}

package/src/types/state.ts

@@ -18,22 +18,23 @@ export class StateMachine {
   /**
    * Valid state transitions per Yellow Paper §3.2.2
    *
-   * SECURITY FIX (CRITICAL-1): State machine must match ACTPKernel contract exactly
-   * Per CLAUDE.md §Architecture Overview - ACTP Protocol State Machine:
-   * - COMMITTED can transition to IN_PROGRESS, DELIVERED, or CANCELLED
+   * SECURITY FIX (AUDIT-2026-02): State machine must match ACTPKernel contract exactly
+   *
+   * Per on-chain ACTPKernel contract:
+   * - COMMITTED must go through IN_PROGRESS before DELIVERED (cannot skip)
+   * - DISPUTED can transition to SETTLED or CANCELLED (admin/pauser can cancel disputes)
    * - IN_PROGRESS can transition to DELIVERED or CANCELLED (not DISPUTED)
-   * - DISPUTED can only transition to SETTLED (not CANCELLED)
    */
   private static readonly TRANSITIONS: Record<State, State[]> = {
     [State.INITIATED]: [State.QUOTED, State.COMMITTED, State.CANCELLED], // Allow direct INITIATED → COMMITTED (AIP-3)
     [State.QUOTED]: [State.COMMITTED, State.CANCELLED],
-    // SECURITY FIX (CRITICAL-1): Add DELIVERED (can skip IN_PROGRESS)
-    [State.COMMITTED]: [State.IN_PROGRESS, State.DELIVERED, State.CANCELLED],
-    // SECURITY FIX (CRITICAL-1): Remove DISPUTED, add CANCELLED
+    // AUDIT FIX: COMMITTED cannot skip to DELIVERED - must go through IN_PROGRESS first
+    [State.COMMITTED]: [State.IN_PROGRESS, State.CANCELLED],
+    // IN_PROGRESS can transition to DELIVERED or CANCELLED
     [State.IN_PROGRESS]: [State.DELIVERED, State.CANCELLED],
     [State.DELIVERED]: [State.SETTLED, State.DISPUTED],
-    // SECURITY FIX (CRITICAL-1): Remove CANCELLED (disputes resolve to SETTLED only)
-    [State.DISPUTED]: [State.SETTLED],
+    // AUDIT FIX: DISPUTED can also transition to CANCELLED (admin/pauser emergency cancellation)
+    [State.DISPUTED]: [State.SETTLED, State.CANCELLED],
     [State.SETTLED]: [], // Terminal state
     [State.CANCELLED]: [] // Terminal state
   };

package/src/utils/ErrorRecoveryGuide.ts

@@ -637,14 +637,12 @@ export async function withRecoveryGuidance<T>(
 ): Promise<T> {
   const { logGuidance = false, autoRetry = false, onError } = options;
 
-  let lastError: unknown;
   let attempts = 0;
 
   do {
     try {
       return await operation();
     } catch (error) {
-      lastError = error;
       const recovery = ErrorRecoveryGuide.analyze(error);
 
       if (onError) {
@@ -671,5 +669,6 @@ export async function withRecoveryGuidance<T>(
 
       throw error;
     }
+    // eslint-disable-next-line no-constant-condition
   } while (true);
 }

package/src/utils/IPFSClient.ts

@@ -4,6 +4,7 @@
  */
 
 import { create, IPFSHTTPClient, Options } from 'kubo-rpc-client';
+import { sdkLogger } from './Logger';
 
 /**
  * IPFS Client Interface (from DeliveryProofBuilder)
@@ -202,10 +203,10 @@ export class IPFSHTTPClientImpl implements IPFSClient {
 
     // For remote hosts, require HTTPS
     if (!isLocalhost && parsed.protocol !== 'https:') {
-      console.warn(
-        `[SECURITY WARNING] Using non-HTTPS protocol "${parsed.protocol}" for remote IPFS endpoint "${hostname}". ` +
-        `This may expose data in transit. Consider using HTTPS.`
-      );
+      sdkLogger.warn('Using non-HTTPS protocol for remote IPFS endpoint - data may be exposed in transit', {
+        protocol: parsed.protocol,
+        hostname,
+      });
     }
   }
 

package/src/utils/NonceManager.ts

@@ -10,6 +10,7 @@
  */
 
 import { assertSafeFileForRead, ensureSafeDir, ensureSafeFile } from './fsSafe';
+import { sdkLogger } from './Logger';
 
 /**
  * Maximum allowed nonce value.
@@ -525,7 +526,7 @@ export class FileBasedNonceManager implements NonceManager {
     this.inMemory.recordNonce(messageType, nonce);
     // Fire-and-forget to maintain sync interface
     this.saveToFile().catch((err) => {
-      console.error('Failed to save nonce manager state:', err);
+      sdkLogger.error('Failed to save nonce manager state', { error: err instanceof Error ? err.message : String(err) });
     });
   }
 
@@ -537,7 +538,7 @@ export class FileBasedNonceManager implements NonceManager {
     this.inMemory.resetNonce(messageType);
     // Fire-and-forget to maintain sync interface
     this.saveToFile().catch((err) => {
-      console.error('Failed to save nonce manager state:', err);
+      sdkLogger.error('Failed to save nonce manager state', { error: err instanceof Error ? err.message : String(err) });
     });
   }
 

package/src/utils/UsedAttestationTracker.ts

@@ -12,6 +12,7 @@
  */
 
 import { assertSafeFileForRead, ensureSafeDir, ensureSafeFile } from './fsSafe';
+import { sdkLogger } from './Logger';
 
 /**
  * Interface for tracking used attestations
@@ -202,13 +203,10 @@ export class InMemoryUsedAttestationTracker implements IUsedAttestationTracker {
    *
    * @param maxAgeHours - Remove entries older than this many hours
    */
-  cleanupOldEntries(maxAgeHours: number): number {
+  cleanupOldEntries(_maxAgeHours: number): number {
     // In-memory tracker doesn't track timestamps
     // This is a placeholder for future enhancement
-    console.warn(
-      'cleanupOldEntries not implemented for InMemoryUsedAttestationTracker. ' +
-      'Consider using FileBasedUsedAttestationTracker for time-based cleanup.'
-    );
+    sdkLogger.warn('cleanupOldEntries not implemented for InMemoryUsedAttestationTracker - use FileBasedUsedAttestationTracker');
     return 0;
   }
 }
@@ -350,7 +348,7 @@ export class FileBasedUsedAttestationTracker implements IUsedAttestationTracker
     const result = this.inMemory.recordUsageSync(attestationUID, txId);
     if (result) {
       this.saveToFile().catch((err) => {
-        console.error('Failed to save attestation tracker state:', err);
+        sdkLogger.error('Failed to save attestation tracker state', { error: err instanceof Error ? err.message : String(err) });
       });
     }
     return result;