@oobe-protocol-labs/synapse-sap-sdk 0.13.0 → 0.14.0

package/src/utils/endpoint-validator.ts

@@ -1,300 +0,0 @@
-/**
- * @module utils/endpoint-validator
- * @description Endpoint validation utilities for SAP agent discovery.
- *
- * Fetches advertised endpoints and verifies they respond with JSON,
- * proper CORS headers, and SAP-compatible behavior. Designed to
- * fail fast when an endpoint 404s, requires CSRF tokens, or
- * serves HTML instead of JSON.
- *
- * Used by:
- *   - CLI `discovery validate` command
- *   - SDK programmatic validation before x402 calls
- *   - Integration test harnesses
- *
- * @category Utils
- * @since v0.6.0
- */
-
-import type {
-  EndpointDescriptor,
-  HealthCheckDescriptor,
-  EndpointValidationResult,
-} from "../types/endpoint";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Validation Options
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface ValidateEndpointOptions
- * @description Options for endpoint validation.
- * @category Utils
- * @since v0.6.0
- */
-export interface ValidateEndpointOptions {
-  /** Timeout in milliseconds (default: 10000). */
-  readonly timeoutMs?: number;
-  /** Number of retries on failure (default: 1). */
-  readonly retries?: number;
-  /** HTTP method override (default: uses descriptor or HEAD). */
-  readonly method?: string;
-  /** Custom headers to include in the validation request. */
-  readonly headers?: Record<string, string>;
-  /** If true, also sends a preflight OPTIONS request. */
-  readonly checkCors?: boolean;
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Core Validator
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name validateEndpoint
- * @description Validate a single endpoint URL for SAP compatibility.
- *
- * Performs the following checks:
- *   1. URL is reachable (no 4xx/5xx)
- *   2. Response Content-Type is JSON
- *   3. CORS headers are present (if checkCors enabled)
- *   4. No redirect to HTML login pages
- *   5. Measures response latency
- *
- * @param url - The endpoint URL to validate.
- * @param opts - Validation options.
- * @returns An {@link EndpointValidationResult} with detailed check results.
- *
- * @category Utils
- * @since v0.6.0
- *
- * @example
- * ```ts
- * const result = await validateEndpoint("https://api.example.com/x402");
- * if (!result.reachable) console.error(result.error);
- * ```
- */
-export async function validateEndpoint(
-  url: string,
-  opts: ValidateEndpointOptions = {},
-): Promise<EndpointValidationResult> {
-  const timeoutMs = opts.timeoutMs ?? 10_000;
-  const retries = opts.retries ?? 1;
-  const method = opts.method ?? "HEAD";
-  const warnings: string[] = [];
-
-  let lastError: string | undefined;
-
-  for (let attempt = 0; attempt <= retries; attempt++) {
-    try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), timeoutMs);
-      const start = Date.now();
-
-      const response = await fetch(url, {
-        method,
-        signal: controller.signal,
-        headers: {
-          Accept: "application/json",
-          ...(opts.headers ?? {}),
-        },
-        redirect: "follow",
-      });
-
-      clearTimeout(timer);
-      const latencyMs = Date.now() - start;
-
-      const contentType = response.headers.get("content-type") ?? "";
-      const isJson = contentType.includes("application/json") || contentType.includes("text/json");
-      const hasCors = !!response.headers.get("access-control-allow-origin");
-
-      // Check for HTML responses (login pages, CSRF gates)
-      if (contentType.includes("text/html")) {
-        warnings.push("Endpoint returns HTML — may require CSRF or browser session");
-      }
-
-      // Check for redirect chains
-      if (response.redirected) {
-        warnings.push(`Endpoint redirected to ${response.url}`);
-      }
-
-      // Check for common error statuses
-      if (response.status === 403) {
-        warnings.push("403 Forbidden — may require authentication or CSRF tokens");
-      }
-      if (response.status === 404) {
-        warnings.push("404 Not Found — endpoint URL may be incorrect");
-      }
-      if (response.status === 405) {
-        warnings.push(`405 Method Not Allowed — endpoint may not accept ${method}`);
-      }
-
-      // Determine SAP capability
-      const isSapCapable =
-        isJson &&
-        response.status < 400 &&
-        !contentType.includes("text/html");
-
-      // CORS check if requested
-      if (opts.checkCors && !hasCors) {
-        warnings.push("No CORS headers — cross-origin requests will fail");
-      }
-
-      return {
-        url,
-        reachable: response.status < 500,
-        statusCode: response.status,
-        latencyMs,
-        isJson,
-        hasCors,
-        isSapCapable,
-        error:
-          response.status >= 400
-            ? `HTTP ${response.status}: ${response.statusText}`
-            : undefined,
-        warnings,
-      };
-    } catch (err) {
-      lastError =
-        err instanceof Error ? err.message : String(err);
-      if (attempt < retries) continue;
-    }
-  }
-
-  return {
-    url,
-    reachable: false,
-    statusCode: 0,
-    latencyMs: 0,
-    isJson: false,
-    hasCors: false,
-    isSapCapable: false,
-    error: lastError ?? "Unknown error",
-    warnings,
-  };
-}
-
-/**
- * @name validateEndpointDescriptor
- * @description Validate an {@link EndpointDescriptor} with context-aware checks.
- *
- * Uses the descriptor's method, auth requirements, and other metadata to
- * perform a more targeted validation than raw URL checking.
- *
- * @param descriptor - The endpoint descriptor to validate.
- * @param opts - Additional options.
- * @returns An {@link EndpointValidationResult}.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateEndpointDescriptor(
-  descriptor: EndpointDescriptor,
-  opts: ValidateEndpointOptions = {},
-): Promise<EndpointValidationResult> {
-  const headers: Record<string, string> = {
-    ...(opts.headers ?? {}),
-    ...(descriptor.requiredHeaders ?? {}),
-  };
-
-  // Use the descriptor's method, falling back to HEAD for safety
-  const method = opts.method ?? (descriptor.method === "GET" ? "GET" : "HEAD");
-
-  const result = await validateEndpoint(descriptor.url, {
-    ...opts,
-    method,
-    headers,
-  });
-
-  // Add descriptor-specific warnings
-  const warnings = [...result.warnings];
-
-  if (descriptor.requiresCSRF) {
-    warnings.push("Endpoint declares requiresCSRF — automated calls may need token management");
-  }
-  if (descriptor.requiresCookies) {
-    warnings.push("Endpoint declares requiresCookies — stateless calls may fail");
-  }
-  if (descriptor.requiresAuth && !descriptor.authType) {
-    warnings.push("Endpoint requires auth but no authType specified");
-  }
-
-  return { ...result, warnings };
-}
-
-/**
- * @name validateHealthCheck
- * @description Validate an agent's health-check endpoint.
- *
- * @param health - The health-check descriptor.
- * @returns An {@link EndpointValidationResult}.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateHealthCheck(
-  health: HealthCheckDescriptor,
-): Promise<EndpointValidationResult> {
-  const result = await validateEndpoint(health.url, {
-    timeoutMs: health.timeoutMs,
-    method: health.method ?? "GET",
-  });
-
-  const warnings = [...result.warnings];
-
-  if (result.reachable && result.statusCode !== health.expectedStatus) {
-    warnings.push(
-      `Expected status ${health.expectedStatus}, got ${result.statusCode}`,
-    );
-  }
-
-  return {
-    ...result,
-    isSapCapable: result.reachable && result.statusCode === health.expectedStatus,
-    warnings,
-  };
-}
-
-/**
- * @name validateAgentEndpoints
- * @description Validate all endpoints for an agent (primary + health + tool overrides).
- *
- * @param params - Object containing the endpoints to validate.
- * @param params.endpoint - Primary endpoint descriptor.
- * @param params.healthCheck - Optional health-check descriptor.
- * @param params.toolEndpoints - Optional array of tool-specific endpoint overrides.
- * @param opts - Validation options.
- * @returns A map of `label → EndpointValidationResult`.
- *
- * @category Utils
- * @since v0.6.0
- */
-export async function validateAgentEndpoints(
-  params: {
-    endpoint: EndpointDescriptor;
-    healthCheck?: HealthCheckDescriptor;
-    toolEndpoints?: Array<{ name: string; endpoint: EndpointDescriptor }>;
-  },
-  opts: ValidateEndpointOptions = {},
-): Promise<Map<string, EndpointValidationResult>> {
-  const results = new Map<string, EndpointValidationResult>();
-
-  // Validate primary endpoint
-  const primary = await validateEndpointDescriptor(params.endpoint, opts);
-  results.set("primary", primary);
-
-  // Validate health check
-  if (params.healthCheck) {
-    const health = await validateHealthCheck(params.healthCheck);
-    results.set("health", health);
-  }
-
-  // Validate tool-specific endpoints
-  if (params.toolEndpoints) {
-    for (const { name, endpoint } of params.toolEndpoints) {
-      const toolResult = await validateEndpointDescriptor(endpoint, opts);
-      results.set(`tool:${name}`, toolResult);
-    }
-  }
-
-  return results;
-}

package/src/utils/escrow-validation.ts

@@ -1,301 +0,0 @@
-/**
- * @module utils/escrow-validation
- * @description Server-side escrow validation pipeline.
- *
- * Provides typed helpers to validate escrow state before settlement
- * and to build the correct SPL `AccountMeta[]` for token escrows.
- *
- * @category Utils
- * @since v0.6.4
- */
-
-import {
-  PublicKey,
-  type Connection,
-  type AccountMeta,
-} from "@solana/web3.js";
-import { BN } from "@coral-xyz/anchor";
-import { findATA } from "./rpc-strategy";
-import { deriveAgent, deriveEscrow } from "../pda";
-import { SapError } from "../errors";
-import type { EscrowAccountData } from "../types";
-
-// ═══════════════════════════════════════════════════════════════════
-//  Types
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @interface SplAccountMeta
- * @description Typed SPL account metadata for escrow operations.
- * @category Utils
- * @since v0.6.4
- */
-export interface SplAccountMeta {
-  /** Account role in the escrow pipeline. */
-  readonly kind: "escrowAta" | "depositorAta" | "tokenMint" | "tokenProgram";
-  /** Account public key. */
-  readonly pubkey: PublicKey;
-  /** Whether this account is writable. */
-  readonly writable: boolean;
-}
-
-/**
- * @interface EscrowValidationResult
- * @description Result of server-side escrow state validation.
- * @category Utils
- * @since v0.6.4
- */
-export interface EscrowValidationResult {
-  /** Whether the escrow is valid for settlement. */
-  readonly valid: boolean;
-  /** Escrow account data (if found). */
-  readonly escrow: EscrowAccountData | null;
-  /** Escrow PDA address. */
-  readonly escrowPda: PublicKey;
-  /** Agent PDA address. */
-  readonly agentPda: PublicKey;
-  /** Whether this is an SPL token escrow (vs SOL). */
-  readonly isSplEscrow: boolean;
-  /** Generated SPL account metas (empty for SOL escrows). */
-  readonly splAccounts: SplAccountMeta[];
-  /** Validation errors (empty when valid). */
-  readonly errors: string[];
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Error
-// ═══════════════════════════════════════════════════════════════════
-
-/**
- * @name MissingEscrowAtaError
- * @description Thrown when an SPL escrow operation is missing required
- * Associated Token Accounts.
- * @category Errors
- * @since v0.6.4
- */
-export class MissingEscrowAtaError extends SapError {
-  /** The ATA address that is missing. */
-  readonly ataAddress: string;
-  /** Which side is missing: depositor or escrow. */
-  readonly side: "depositor" | "escrow";
-
-  constructor(ataAddress: string, side: "depositor" | "escrow") {
-    super(
-      `Missing ${side} ATA: ${ataAddress}. ` +
-        `Settlement mode is Escrow/SPL but the Associated Token Account does not exist. ` +
-        `The ${side} must create the ATA before escrow operations.`,
-      "SAP_MISSING_ESCROW_ATA",
-    );
-    this.name = "MissingEscrowAtaError";
-    this.ataAddress = ataAddress;
-    this.side = side;
-  }
-}
-
-// ═══════════════════════════════════════════════════════════════════
-//  Validation
-// ═══════════════════════════════════════════════════════════════════
-
-/** Standard SPL Token program ID. */
-const TOKEN_PROGRAM_ID_STR = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
-
-/**
- * @name validateEscrowState
- * @description Validates that an escrow is in a correct state for settlement.
- *
- * Checks:
- * - Escrow PDA exists on-chain
- * - If SPL: depositor ATA exists, escrow ATA exists, token mint matches
- * - Balance >= requested settlement amount
- * - Escrow is not expired
- * - Max calls not exceeded
- *
- * @param connection  - Solana RPC connection.
- * @param agentWallet - The agent's wallet public key.
- * @param depositorWallet - The depositor's wallet public key.
- * @param fetchEscrow - Callback to fetch escrow data (avoids coupling to SapProgram).
- * @param opts
- * @param opts.callsToSettle - Number of calls to validate affordability for.
- *
- * @returns A detailed {@link EscrowValidationResult}.
- *
- * @category Utils
- * @since v0.6.4
- *
- * @example
- * ```ts
- * const result = await validateEscrowState(
- *   connection,
- *   agentWallet,
- *   depositorWallet,
- *   (pda) => client.escrow.fetchByPda(pda),
- *   { callsToSettle: 5 },
- * );
- *
- * if (!result.valid) {
- *   console.error("Escrow validation failed:", result.errors);
- * }
- * ```
- */
-export async function validateEscrowState(
-  connection: Connection,
-  agentWallet: PublicKey,
-  depositorWallet: PublicKey,
-  fetchEscrow: (escrowPda: PublicKey) => Promise<EscrowAccountData | null>,
-  opts?: { callsToSettle?: number },
-): Promise<EscrowValidationResult> {
-  const [agentPda] = deriveAgent(agentWallet);
-  const [escrowPda] = deriveEscrow(agentPda, depositorWallet);
-  const errors: string[] = [];
-
-  // 1. Fetch escrow
-  const escrow = await fetchEscrow(escrowPda);
-  if (!escrow) {
-    return {
-      valid: false,
-      escrow: null,
-      escrowPda,
-      agentPda,
-      isSplEscrow: false,
-      splAccounts: [],
-      errors: [`Escrow not found at ${escrowPda.toBase58()}`],
-    };
-  }
-
-  // 2. Check expiry
-  if (escrow.expiresAt.gt(new BN(0))) {
-    const now = Math.floor(Date.now() / 1000);
-    if (escrow.expiresAt.lt(new BN(now))) {
-      errors.push(`Escrow expired at ${escrow.expiresAt.toString()}`);
-    }
-  }
-
-  // 3. Check balance / calls
-  const callsToSettle = opts?.callsToSettle ?? 1;
-  const costForCalls = escrow.pricePerCall.mul(new BN(callsToSettle));
-  if (escrow.balance.lt(costForCalls)) {
-    errors.push(
-      `Insufficient balance: ${escrow.balance.toString()} < ${costForCalls.toString()} (${callsToSettle} calls × ${escrow.pricePerCall.toString()})`,
-    );
-  }
-
-  // 4. Check max calls
-  if (escrow.maxCalls.gt(new BN(0))) {
-    const remaining = escrow.maxCalls.sub(escrow.totalCallsSettled);
-    if (remaining.lt(new BN(callsToSettle))) {
-      errors.push(
-        `Max calls exceeded: ${remaining.toString()} remaining but needs ${callsToSettle}`,
-      );
-    }
-  }
-
-  // 5. Determine if SPL
-  const isSplEscrow =
-    escrow.tokenMint !== null &&
-    escrow.tokenMint.toBase58() !== "11111111111111111111111111111111";
-
-  // 6. Build SPL accounts (if SPL escrow)
-  const splAccounts: SplAccountMeta[] = [];
-  if (isSplEscrow) {
-    const mint = escrow.tokenMint!;
-    const depositorAta = findATA(depositorWallet, mint);
-    const escrowAta = findATA(escrowPda, mint);
-
-    // Verify depositor ATA exists
-    const depositorAtaInfo = await connection.getAccountInfo(depositorAta);
-    if (!depositorAtaInfo) {
-      errors.push(`Depositor ATA does not exist: ${depositorAta.toBase58()}`);
-    }
-
-    // Verify escrow ATA exists
-    const escrowAtaInfo = await connection.getAccountInfo(escrowAta);
-    if (!escrowAtaInfo) {
-      errors.push(`Escrow ATA does not exist: ${escrowAta.toBase58()}`);
-    }
-
-    // Verify mint matches
-    if (depositorAtaInfo) {
-      // SPL token account data: bytes 0-32 = mint
-      const ataMint = depositorAtaInfo.data.subarray(0, 32);
-      if (Buffer.from(ataMint).toString("hex") !== mint.toBuffer().toString("hex")) {
-        errors.push(`Depositor ATA mint mismatch: expected ${mint.toBase58()}`);
-      }
-    }
-
-    splAccounts.push(
-      { kind: "depositorAta", pubkey: depositorAta, writable: true },
-      { kind: "escrowAta", pubkey: escrowAta, writable: true },
-      { kind: "tokenMint", pubkey: mint, writable: false },
-      { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
-    );
-  }
-
-  return {
-    valid: errors.length === 0,
-    escrow,
-    escrowPda,
-    agentPda,
-    isSplEscrow,
-    splAccounts,
-    errors,
-  };
-}
-
-/**
- * @name attachSplAccounts
- * @description Build the typed `SplAccountMeta[]` for an SPL token escrow operation.
- * Does NOT validate existence — use {@link validateEscrowState} for full validation.
- *
- * @param escrowPda      - The escrow PDA address.
- * @param depositorWallet - The depositor's wallet public key.
- * @param tokenMint      - The SPL token mint.
- * @returns An array of typed {@link SplAccountMeta} for SPL escrow operations.
- *
- * @category Utils
- * @since v0.6.4
- *
- * @example
- * ```ts
- * const splMetas = attachSplAccounts(escrowPda, depositorWallet, usdcMint);
- *
- * // Convert to Anchor-compatible AccountMeta[]
- * const accountMetas = splMetas.map(m => ({
- *   pubkey: m.pubkey,
- *   isWritable: m.writable,
- *   isSigner: false,
- * }));
- *
- * await client.escrow.settle(depositor, calls, hash, accountMetas);
- * ```
- */
-export function attachSplAccounts(
-  escrowPda: PublicKey,
-  depositorWallet: PublicKey,
-  tokenMint: PublicKey,
-): SplAccountMeta[] {
-  return [
-    { kind: "depositorAta", pubkey: findATA(depositorWallet, tokenMint), writable: true },
-    { kind: "escrowAta", pubkey: findATA(escrowPda, tokenMint), writable: true },
-    { kind: "tokenMint", pubkey: tokenMint, writable: false },
-    { kind: "tokenProgram", pubkey: new PublicKey(TOKEN_PROGRAM_ID_STR), writable: false },
-  ];
-}
-
-/**
- * @name toAccountMetas
- * @description Convert typed {@link SplAccountMeta} to Anchor-compatible
- * `AccountMeta[]` for use with `.remainingAccounts()`.
- *
- * @param splMetas - Array of typed SPL account metas.
- * @returns `AccountMeta[]` compatible with Anchor's `remainingAccounts`.
- *
- * @category Utils
- * @since v0.6.4
- */
-export function toAccountMetas(splMetas: SplAccountMeta[]): AccountMeta[] {
-  return splMetas.map((m) => ({
-    pubkey: m.pubkey,
-    isWritable: m.writable,
-    isSigner: false,
-  }));
-}

package/src/utils/hash.ts

@@ -1,113 +0,0 @@
-/**
- * @module utils/hash
- * @description Cryptographic hashing utilities.
- *
- * @category Utils
- * @since v0.1.0
- */
-
-import { createHash } from "crypto";
-
-/**
- * Compute the SHA-256 hash of a UTF-8 string or byte buffer.
- *
- * Returns a 32-byte `Uint8Array` suitable for PDA seeds
- * and Anchor instruction arguments.
- *
- * @name sha256
- * @description Hashes the input using Node’s `crypto.createHash("sha256")`.
- * @param input - A UTF-8 string, `Buffer`, or `Uint8Array` to hash.
- * @returns {Uint8Array} 32-byte SHA-256 digest.
- * @category Utils
- * @since v0.1.0
- * @example
- * ```ts
- * import { sha256 } from "@synapse-sap/sdk/utils";
- *
- * const hash = sha256("jupiter:swap"); // Uint8Array (32 bytes)
- * ```
- */
-export const sha256 = (input: string | Buffer | Uint8Array): Uint8Array => {
-  const hash = createHash("sha256");
-  hash.update(
-    typeof input === "string" ? Buffer.from(input, "utf-8") : input,
-  );
-  return new Uint8Array(hash.digest());
-};
-
-/**
- * Convert a `Uint8Array` hash to a plain `number[]`.
- *
- * Anchor instruction argument types expect `number[]` for hash fields
- * rather than typed arrays.
- *
- * @name hashToArray
- * @description Converts a byte array (typically 32 bytes) to a plain JavaScript `number[]`.
- * @param hash - The byte array to convert.
- * @returns {number[]} Shallow copy as a plain array of numbers.
- * @category Utils
- * @since v0.1.0
- * @example
- * ```ts
- * import { sha256, hashToArray } from "@synapse-sap/sdk/utils";
- *
- * const arr = hashToArray(sha256("jupiter:swap")); // number[]
- * ```
- */
-export const hashToArray = (hash: Uint8Array): number[] => Array.from(hash);
-
-/**
- * Compute the deterministic batch root used by `settle_batch` (v0.10.0).
- *
- * The on-chain program enforces:
- *   `batch_root == sha256(s_0 || s_1 || ... || s_{N-1})`
- * where each `s_i` is a 32-byte service hash, in the same order as the
- * `settlements: Settlement[]` array passed to the instruction.
- *
- * Use this helper to derive the seed for the {@link deriveSettlementReceipt}
- * PDA when batching settlements.
- *
- * @name computeBatchRoot
- * @param serviceHashes - Array of 32-byte service hashes (Buffer/Uint8Array/number[]).
- * @returns {Uint8Array} 32-byte batch root.
- * @throws If any `serviceHashes[i]` is not exactly 32 bytes long.
- * @category Utils
- * @since v0.10.0
- *
- * @example
- * ```ts
- * import { computeBatchRoot, hashToArray } from "@synapse-sap/sdk/utils";
- *
- * const root = computeBatchRoot([h1, h2, h3]);
- * await client.escrow.settleBatch(depositor, settlements, root);
- * ```
- */
-export const computeBatchRoot = (
-  serviceHashes: ReadonlyArray<Uint8Array | Buffer | number[]>,
-): Uint8Array => {
-  if (serviceHashes.length === 0) {
-    throw new Error("computeBatchRoot: serviceHashes must not be empty");
-  }
-  const hash = createHash("sha256");
-  for (let i = 0; i < serviceHashes.length; i++) {
-    const h = serviceHashes[i];
-    let buf: Buffer;
-    if (h instanceof Uint8Array) {
-      buf = Buffer.from(h);
-    } else if (Array.isArray(h)) {
-      buf = Buffer.from(h);
-    } else {
-      throw new Error(
-        `computeBatchRoot: serviceHashes[${i}] is undefined or unsupported type`,
-      );
-    }
-    if (buf.length !== 32) {
-      throw new Error(
-        `computeBatchRoot: serviceHashes[${i}] must be 32 bytes, got ${buf.length}`,
-      );
-    }
-    hash.update(buf);
-  }
-  return new Uint8Array(hash.digest());
-};
-