@oobe-protocol-labs/synapse-sap-sdk 0.4.2 → 0.6.0

package/dist/esm/utils/endpoint-validator.js

@@ -0,0 +1,226 @@
+/**
+ * @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
+ */
+// ═══════════════════════════════════════════════════════════════════
+//  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, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const retries = opts.retries ?? 1;
+    const method = opts.method ?? "HEAD";
+    const warnings = [];
+    let lastError;
+    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, opts = {}) {
+    const headers = {
+        ...(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) {
+    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, opts = {}) {
+    const results = new Map();
+    // 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;
+}
+//# sourceMappingURL=endpoint-validator.js.map

package/dist/esm/utils/endpoint-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint-validator.js","sourceRoot":"","sources":["../../../src/utils/endpoint-validator.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/index.js

@@ -16,4 +16,9 @@
 export { sha256, hashToArray } from "./hash";
 export { assert } from "./validation";
 export { serializeAccount, serializeValue } from "./serialization";
+// ── v0.6.0  Hardening utilities ─────────────────────
+export { normalizeNetworkId, isNetworkEquivalent, getNetworkGenesisHash, getNetworkClusterName, isKnownNetwork, } from "./network-normalizer";
+export { validateEndpoint, validateEndpointDescriptor, validateHealthCheck, validateAgentEndpoints, } from "./endpoint-validator";
+export { getRpcUrl, getFallbackRpcUrl, createDualConnection, findATA, classifyAnchorError, extractAnchorErrorCode, } from "./rpc-strategy";
+export { createEnvSchema, createEndpointDescriptorSchema, createHealthCheckSchema, createToolManifestEntrySchema, createAgentManifestSchema, createPreparePaymentSchema, createRegisterAgentSchema, createCallArgsSchema, validateOrThrow, } from "./schemas";
 //# sourceMappingURL=index.js.map

package/dist/esm/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnE,uDAAuD;AACvD,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,GACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,gBAAgB,EAChB,0BAA0B,EAC1B,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,OAAO,EACP,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,eAAe,EACf,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,WAAW,CAAC"}

package/dist/esm/utils/network-normalizer.js

@@ -0,0 +1,229 @@
+/**
+ * @module utils/network-normalizer
+ * @description Network identifier normalization for x402 payment headers.
+ *
+ * Solves the canonical-string mismatch between SAP clients and servers:
+ * some providers accept `solana:mainnet-beta` while others require
+ * the genesis-hash form `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`.
+ *
+ * This module provides a single source of truth for normalizing
+ * network identifiers so that both clients and agents canonicalize
+ * before comparing. Catches the Kamiyo "sap network mismatch" error
+ * at the SDK level.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+import { SapNetwork } from "../constants/network";
+// ═══════════════════════════════════════════════════════════════════
+//  Canonical Mapping
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Bidirectional alias map: for every known network string, stores the
+ * canonical SapNetworkId it resolves to, plus all known aliases.
+ */
+const NETWORK_ALIASES = new Map([
+    // ── Mainnet ───────────────────────────────
+    // Canonical: genesis-hash form
+    ["solana:mainnet-beta", SapNetwork.SOLANA_MAINNET],
+    ["solana:mainnet", SapNetwork.SOLANA_MAINNET],
+    ["mainnet-beta", SapNetwork.SOLANA_MAINNET],
+    ["mainnet", SapNetwork.SOLANA_MAINNET],
+    ["solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
+    ["5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", SapNetwork.SOLANA_MAINNET_GENESIS],
+    // ── Devnet ────────────────────────────────
+    ["solana:devnet", SapNetwork.SOLANA_DEVNET_NAMED],
+    ["devnet", SapNetwork.SOLANA_DEVNET_NAMED],
+    ["solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
+    ["EtWTRABZaYq6iMfeYKouRu166VU2xqa1", SapNetwork.SOLANA_DEVNET],
+]);
+/**
+ * Mainnet equivalence set: all strings that refer to Solana mainnet-beta,
+ * regardless of format.
+ */
+const MAINNET_EQUIVALENTS = new Set([
+    SapNetwork.SOLANA_MAINNET,
+    SapNetwork.SOLANA_MAINNET_GENESIS,
+    "solana:mainnet",
+    "mainnet-beta",
+    "mainnet",
+    "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
+]);
+/**
+ * Devnet equivalence set.
+ */
+const DEVNET_EQUIVALENTS = new Set([
+    SapNetwork.SOLANA_DEVNET,
+    SapNetwork.SOLANA_DEVNET_NAMED,
+    "devnet",
+    "EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+]);
+// ═══════════════════════════════════════════════════════════════════
+//  Public API
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name normalizeNetworkId
+ * @description Normalize a raw network identifier string to its canonical
+ * {@link SapNetworkId} form.
+ *
+ * Handles:
+ *   - Case-insensitive matching
+ *   - Stripping whitespace
+ *   - Resolving genesis-hash vs. cluster-name aliases
+ *   - Unknown strings are returned as-is (passthrough)
+ *
+ * @param raw - Raw network identifier string from headers, env vars, or config.
+ * @returns The canonical {@link SapNetworkId}, or the trimmed input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { normalizeNetworkId } from "@synapse-sap/sdk";
+ *
+ * normalizeNetworkId("solana:mainnet-beta");
+ * // → "solana:mainnet-beta"
+ *
+ * normalizeNetworkId("5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+ *
+ * normalizeNetworkId("  MAINNET  ");
+ * // → "solana:mainnet-beta"
+ * ```
+ */
+export function normalizeNetworkId(raw) {
+    const trimmed = raw.trim();
+    // Exact match first
+    const exact = NETWORK_ALIASES.get(trimmed);
+    if (exact)
+        return exact;
+    // Case-insensitive lookup
+    const lower = trimmed.toLowerCase();
+    for (const [alias, canonical] of NETWORK_ALIASES) {
+        if (alias.toLowerCase() === lower)
+            return canonical;
+    }
+    // Passthrough for unknown networks (custom chains, etc.)
+    return trimmed;
+}
+/**
+ * @name isNetworkEquivalent
+ * @description Check if two network identifier strings refer to the same network,
+ * even if they use different formats (cluster-name vs. genesis-hash).
+ *
+ * This is the key function that prevents the Kamiyo "sap network mismatch"
+ * error — instead of comparing strings literally, we compare their
+ * canonical equivalence class.
+ *
+ * @param a - First network identifier.
+ * @param b - Second network identifier.
+ * @returns `true` if both identifiers refer to the same Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ *
+ * @example
+ * ```ts
+ * import { isNetworkEquivalent } from "@synapse-sap/sdk";
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:devnet", "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1");
+ * // → true
+ *
+ * isNetworkEquivalent("solana:mainnet-beta", "solana:devnet");
+ * // → false
+ * ```
+ */
+export function isNetworkEquivalent(a, b) {
+    const normA = a.trim();
+    const normB = b.trim();
+    // Fast path: identical strings
+    if (normA === normB)
+        return true;
+    // Check if both are in the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(normA) && MAINNET_EQUIVALENTS.has(normB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(normA) && DEVNET_EQUIVALENTS.has(normB))
+        return true;
+    // Case-insensitive match
+    const lowerA = normA.toLowerCase();
+    const lowerB = normB.toLowerCase();
+    if (lowerA === lowerB)
+        return true;
+    // Resolve both to canonical and compare
+    const canonA = normalizeNetworkId(normA);
+    const canonB = normalizeNetworkId(normB);
+    if (canonA === canonB)
+        return true;
+    // Final check: both resolve to the same equivalence set
+    if (MAINNET_EQUIVALENTS.has(canonA) && MAINNET_EQUIVALENTS.has(canonB))
+        return true;
+    if (DEVNET_EQUIVALENTS.has(canonA) && DEVNET_EQUIVALENTS.has(canonB))
+        return true;
+    return false;
+}
+/**
+ * @name getNetworkGenesisHash
+ * @description Get the genesis-hash form of a network identifier.
+ * Returns the genesis-hash variant for known networks, or the input as-is.
+ *
+ * Useful for agents that require the genesis-hash form (Kamiyo, Helius x402).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The genesis-hash form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function getNetworkGenesisHash(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_MAINNET_GENESIS;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_DEVNET;
+    }
+    return norm;
+}
+/**
+ * @name getNetworkClusterName
+ * @description Get the cluster-name form of a network identifier.
+ * Returns the human-readable cluster name for known networks.
+ *
+ * Useful for providers that accept cluster names (Coinbase, Phantom).
+ *
+ * @param networkId - Any network identifier.
+ * @returns The cluster-name form, or the input if unknown.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function getNetworkClusterName(networkId) {
+    const norm = normalizeNetworkId(networkId);
+    if (MAINNET_EQUIVALENTS.has(networkId) || MAINNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_MAINNET;
+    }
+    if (DEVNET_EQUIVALENTS.has(networkId) || DEVNET_EQUIVALENTS.has(norm)) {
+        return SapNetwork.SOLANA_DEVNET_NAMED;
+    }
+    return norm;
+}
+/**
+ * @name isKnownNetwork
+ * @description Check if a network identifier is recognized by the SDK.
+ *
+ * @param networkId - The network identifier to check.
+ * @returns `true` if the identifier maps to a known Solana network.
+ *
+ * @category Utils
+ * @since v0.6.0
+ */
+export function isKnownNetwork(networkId) {
+    const trimmed = networkId.trim();
+    return MAINNET_EQUIVALENTS.has(trimmed) || DEVNET_EQUIVALENTS.has(trimmed) ||
+        NETWORK_ALIASES.has(trimmed);
+}
+//# sourceMappingURL=network-normalizer.js.map

package/dist/esm/utils/network-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-normalizer.js","sourceRoot":"","sources":["../../../src/utils/network-normalizer.ts"],"names":[],"mappings":"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"}