@nullclear/x402-arbiter 0.0.0-stage → 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+import { PrivateKeyAccount } from 'viem/accounts';
+import { WalletClient } from 'viem';
+import { X402PaymentOption, ValidationConfig, FallbackTarget, SpendPolicy, KYAMandate, InvariantRule } from '@nullclear/shared';
+import { z } from 'zod';
+
+type SignerInput = `0x${string}` | PrivateKeyAccount | {
+    account: {
+        address: `0x${string}`;
+    };
+    signTypedData: (params: any) => Promise<`0x${string}`>;
+} | WalletClient;
+/**
+ * Signs an EIP-3009 TransferWithAuthorization and returns a Base64 encoded X402PaymentSignaturePayload
+ */
+declare function signX402Payment(signer: SignerInput, option: X402PaymentOption, resourceUrl?: string): Promise<string>;
+
+interface NullClearClientConfig {
+    arbiterUrl?: string;
+    defaultChainId?: number;
+    fetch?: typeof fetch;
+}
+interface ClearRequest {
+    targetUrl: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    headers?: Record<string, string>;
+    body?: unknown;
+    paymentSignatureHeader: string;
+    sellerAgentId?: string;
+    minTrustScore?: number;
+    twoPhaseRelease?: boolean;
+    validation?: ValidationConfig;
+    fallbacks?: FallbackTarget[];
+    spendPolicy?: SpendPolicy;
+}
+interface ClearResult<T = unknown> {
+    cleared: boolean;
+    settled: boolean;
+    clearingId?: string;
+    buyerCharged: string;
+    clearingFee?: string;
+    settlementRouting?: string;
+    transaction?: `0x${string}`;
+    attestation?: unknown;
+    data?: T;
+    stage?: string;
+    error?: string;
+    validationErrors?: string[];
+    failoverAttempts?: number;
+    winningSellerAgentId?: string;
+    failedCandidates?: Array<{
+        targetUrl: string;
+        sellerAgentId?: string;
+        stage: string;
+        reason: string;
+    }>;
+}
+declare class NullClearClient {
+    private arbiterUrl;
+    private defaultChainId;
+    private customFetch;
+    constructor(config?: NullClearClientConfig);
+    getScore(agentId: string, chainId?: number): Promise<any>;
+    clear<T = unknown>(request: ClearRequest): Promise<ClearResult<T>>;
+    getKya(agentId: string, chainId?: number): Promise<any>;
+    attestKya(mandate: KYAMandate, chainId?: number, signature?: string, signerAddress?: `0x${string}`): Promise<any>;
+}
+
+declare class NullClearEscrowAbortedError extends Error {
+    stage: string;
+    buyerCharged: string;
+    validationErrors: string[];
+    score?: number;
+    upstreamStatus?: number;
+    reason?: string;
+    failoverAttempts?: number;
+    failedCandidates?: Array<{
+        targetUrl: string;
+        sellerAgentId?: string;
+        stage: string;
+        reason: string;
+    }>;
+    constructor(message: string, details: {
+        stage: string;
+        buyerCharged?: string;
+        validationErrors?: string[];
+        score?: number;
+        upstreamStatus?: number;
+        reason?: string;
+        failoverAttempts?: number;
+        failedCandidates?: Array<{
+            targetUrl: string;
+            sellerAgentId?: string;
+            stage: string;
+            reason: string;
+        }>;
+    });
+}
+/**
+ * Lightweight deterministic Zod-to-JSON-Schema converter
+ */
+declare function zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown>;
+interface NullClearOptions {
+    sellerAgentId?: string;
+    minTrustScore?: number;
+    schema?: z.ZodTypeAny | Record<string, unknown>;
+    requiredFields?: string[];
+    sha256Match?: string;
+    invariants?: InvariantRule[];
+    rejectRefusals?: boolean;
+    fallbacks?: FallbackTarget[];
+    spendPolicy?: SpendPolicy;
+}
+interface NullClearFetchConfig {
+    accountOrPrivateKey: SignerInput;
+    chainId?: number;
+    arbiterUrl?: string;
+    defaultMinTrustScore?: number;
+    customFetch?: typeof fetch;
+}
+type NullClearRequestInit = RequestInit & {
+    nullclear?: NullClearOptions;
+};
+/**
+ * Creates an enhanced fetch client that autonomously intercepts HTTP 402 Payment Required
+ * and safely wraps the call in NullClear Deferred Non-Custodial Schema Escrow
+ */
+declare function createNullClearFetch(config: NullClearFetchConfig): (input: RequestInfo | URL, init?: NullClearRequestInit) => Promise<Response>;
+
+export { type ClearRequest, type ClearResult, NullClearClient, type NullClearClientConfig, NullClearEscrowAbortedError, type NullClearFetchConfig, type NullClearOptions, type NullClearRequestInit, type SignerInput, createNullClearFetch, signX402Payment, zodToJsonSchema };

package/dist/index.js

@@ -0,0 +1,303 @@
+// src/signer.ts
+import { privateKeyToAccount } from "viem/accounts";
+import {
+  EIP3009_TYPES,
+  getChainConfig,
+  encodeBase64Json
+} from "@nullclear/shared";
+async function signX402Payment(signer, option, resourceUrl) {
+  let accountAddress;
+  let signTypedDataFn;
+  if (typeof signer === "string" && signer.startsWith("0x")) {
+    const account = privateKeyToAccount(signer);
+    accountAddress = account.address;
+    signTypedDataFn = (params) => account.signTypedData(params);
+  } else if (typeof signer === "object" && signer !== null && "signTypedData" in signer && "account" in signer && signer.account) {
+    const rawAccount = signer.account;
+    accountAddress = typeof rawAccount === "string" ? rawAccount : rawAccount.address;
+    signTypedDataFn = (params) => signer.signTypedData(params);
+  } else {
+    throw new Error("Invalid signer provided to signX402Payment: must be private key or viem account/wallet client");
+  }
+  const randomBytes = new Uint8Array(32);
+  crypto.getRandomValues(randomBytes);
+  const nonce = `0x` + Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  const validAfter = "0";
+  const timeoutSeconds = option.maxTimeoutSeconds && option.maxTimeoutSeconds > 0 ? option.maxTimeoutSeconds : 300;
+  const validBefore = String(Math.floor(Date.now() / 1e3) + timeoutSeconds);
+  const chainConfig = getChainConfig(option.network);
+  const domain = {
+    name: chainConfig.usdcDomain.name,
+    version: chainConfig.usdcDomain.version,
+    chainId: chainConfig.chainId,
+    verifyingContract: chainConfig.usdc
+  };
+  const authorization = {
+    from: accountAddress,
+    to: option.payTo,
+    value: option.amount,
+    validAfter,
+    validBefore,
+    nonce
+  };
+  const signature = await signTypedDataFn({
+    domain,
+    types: EIP3009_TYPES,
+    primaryType: "TransferWithAuthorization",
+    message: {
+      from: authorization.from,
+      to: authorization.to,
+      value: BigInt(authorization.value),
+      validAfter: BigInt(authorization.validAfter),
+      validBefore: BigInt(authorization.validBefore),
+      nonce: authorization.nonce
+    }
+  });
+  const payload = {
+    x402Version: 2,
+    resource: resourceUrl ? { url: resourceUrl } : void 0,
+    accepted: option,
+    payload: {
+      signature,
+      authorization
+    }
+  };
+  return encodeBase64Json(payload);
+}
+
+// src/client.ts
+var NullClearClient = class {
+  arbiterUrl;
+  defaultChainId;
+  customFetch;
+  constructor(config = {}) {
+    this.arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+    this.defaultChainId = config.defaultChainId || 8453;
+    this.customFetch = config.fetch || fetch;
+  }
+  async getScore(agentId, chainId) {
+    const targetChainId = chainId || this.defaultChainId;
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/score/${targetChainId}/${agentId}`);
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to fetch score for agent ${agentId}: ${res.status} ${err}`);
+    }
+    const data = await res.json();
+    return data.data;
+  }
+  async clear(request) {
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/clear`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(request)
+    });
+    const data = await res.json();
+    return data;
+  }
+  async getKya(agentId, chainId) {
+    const targetChainId = chainId || this.defaultChainId;
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/kya/${targetChainId}/${agentId}`);
+    if (!res.ok) {
+      if (res.status === 404) return null;
+      const err = await res.text();
+      throw new Error(`Failed to fetch KYA mandate for agent ${agentId}: ${res.status} ${err}`);
+    }
+    const data = await res.json();
+    return data.data;
+  }
+  async attestKya(mandate, chainId, signature, signerAddress) {
+    const targetChainId = chainId || this.defaultChainId;
+    const res = await this.customFetch(`${this.arbiterUrl}/v1/kya/attest`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        mandate,
+        chainId: targetChainId,
+        signature,
+        signerAddress
+      })
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Failed to attest KYA mandate: ${res.status} ${err}`);
+    }
+    const data = await res.json();
+    return data.data;
+  }
+};
+
+// src/fetch-wrapper.ts
+import { z } from "zod";
+import {
+  decodeBase64Json
+} from "@nullclear/shared";
+var NullClearEscrowAbortedError = class extends Error {
+  stage;
+  buyerCharged;
+  validationErrors;
+  score;
+  upstreamStatus;
+  reason;
+  failoverAttempts;
+  failedCandidates;
+  constructor(message, details) {
+    super(message);
+    this.name = "NullClearEscrowAbortedError";
+    this.stage = details.stage;
+    this.buyerCharged = details.buyerCharged || "0";
+    this.validationErrors = details.validationErrors || [];
+    this.score = details.score;
+    this.upstreamStatus = details.upstreamStatus;
+    this.reason = details.reason;
+  }
+};
+function zodToJsonSchema(schema) {
+  const def = schema._def;
+  if (!def) return {};
+  const typeName = def.typeName;
+  switch (typeName) {
+    case "ZodString":
+      return { type: "string" };
+    case "ZodNumber":
+      return { type: "number" };
+    case "ZodBoolean":
+      return { type: "boolean" };
+    case "ZodArray":
+      return {
+        type: "array",
+        items: def.type ? zodToJsonSchema(def.type) : {}
+      };
+    case "ZodObject": {
+      const shape = def.shape();
+      const properties = {};
+      const required = [];
+      for (const [key, value] of Object.entries(shape)) {
+        properties[key] = zodToJsonSchema(value);
+        const subDef = value._def;
+        if (subDef.typeName !== "ZodOptional" && subDef.typeName !== "ZodNullable") {
+          required.push(key);
+        }
+      }
+      return {
+        type: "object",
+        properties,
+        required: required.length > 0 ? required : void 0
+      };
+    }
+    case "ZodEnum":
+      return {
+        type: "string",
+        enum: def.values
+      };
+    case "ZodOptional":
+    case "ZodNullable":
+      return def.innerType ? zodToJsonSchema(def.innerType) : {};
+    default:
+      return {};
+  }
+}
+function createNullClearFetch(config) {
+  const chainId = config.chainId || 8453;
+  const arbiterUrl = (config.arbiterUrl || "https://arbiter.nullclear.dev").replace(/\/$/, "");
+  const defaultMinTrustScore = config.defaultMinTrustScore || 50;
+  const customFetch = config.customFetch || fetch;
+  return async function nullclearFetch(input, init) {
+    const targetUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const fetchInit = { ...init };
+    delete fetchInit.nullclear;
+    const initialRes = await customFetch(input, fetchInit);
+    if (initialRes.status !== 402) {
+      return initialRes;
+    }
+    const paymentRequiredHeader = initialRes.headers.get("PAYMENT-REQUIRED") || initialRes.headers.get("payment-required");
+    if (!paymentRequiredHeader) {
+      return initialRes;
+    }
+    let paymentRequired;
+    try {
+      paymentRequired = decodeBase64Json(paymentRequiredHeader);
+    } catch {
+      return initialRes;
+    }
+    const targetNetwork = `eip155:${chainId}`;
+    const selectedOption = paymentRequired.accepts.find(
+      (opt) => opt.network === targetNetwork && opt.scheme === "exact"
+    );
+    if (!selectedOption) {
+      throw new Error(
+        `Seller does not accept payments on network ${targetNetwork}. Accepted: ${paymentRequired.accepts.map((a) => a.network).join(", ")}`
+      );
+    }
+    const paymentSignatureHeader = await signX402Payment(
+      config.accountOrPrivateKey,
+      selectedOption,
+      targetUrl
+    );
+    let jsonSchema;
+    if (init?.nullclear?.schema) {
+      if (init.nullclear.schema instanceof z.ZodType) {
+        jsonSchema = zodToJsonSchema(init.nullclear.schema);
+      } else if (typeof init.nullclear.schema === "object") {
+        jsonSchema = init.nullclear.schema;
+      }
+    }
+    const clearPayload = {
+      targetUrl,
+      method: init?.method || "GET",
+      headers: init?.headers || {},
+      body: init?.body,
+      paymentSignatureHeader,
+      sellerAgentId: init?.nullclear?.sellerAgentId,
+      minTrustScore: init?.nullclear?.minTrustScore ?? defaultMinTrustScore,
+      validation: {
+        expectedStatus: [200],
+        jsonSchema,
+        requiredFields: init?.nullclear?.requiredFields,
+        sha256Match: init?.nullclear?.sha256Match,
+        rejectRefusals: init?.nullclear?.rejectRefusals ?? true,
+        invariants: init?.nullclear?.invariants
+      },
+      fallbacks: init?.nullclear?.fallbacks,
+      spendPolicy: init?.nullclear?.spendPolicy
+    };
+    const arbiterRes = await customFetch(`${arbiterUrl}/v1/clear`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(clearPayload)
+    });
+    const arbiterData = await arbiterRes.json();
+    if (arbiterRes.status === 200 && arbiterData.cleared) {
+      const resBody = typeof arbiterData.data === "string" ? arbiterData.data : JSON.stringify(arbiterData.data);
+      const resHeaders = new Headers();
+      resHeaders.set("Content-Type", "application/json");
+      const paymentResponseHdr = arbiterRes.headers.get("PAYMENT-RESPONSE");
+      if (paymentResponseHdr) resHeaders.set("PAYMENT-RESPONSE", paymentResponseHdr);
+      const attestationHdr = arbiterRes.headers.get("X-NullClear-Attestation");
+      if (attestationHdr) resHeaders.set("X-NullClear-Attestation", attestationHdr);
+      return new Response(resBody, {
+        status: 200,
+        headers: resHeaders
+      });
+    }
+    throw new NullClearEscrowAbortedError(
+      `NullClear Escrow Aborted: ${arbiterData.stage || "FAILED"} - ${arbiterData.reason || arbiterData.error || (arbiterData.validationErrors || []).join("; ")}`,
+      {
+        stage: arbiterData.stage || "UNKNOWN_FAILURE",
+        buyerCharged: arbiterData.buyerCharged || "0",
+        validationErrors: arbiterData.validationErrors || [],
+        score: arbiterData.score,
+        upstreamStatus: arbiterData.upstreamStatus,
+        reason: arbiterData.reason || arbiterData.error,
+        failoverAttempts: arbiterData.failoverAttempts,
+        failedCandidates: arbiterData.failedCandidates
+      }
+    );
+  };
+}
+export {
+  NullClearClient,
+  NullClearEscrowAbortedError,
+  createNullClearFetch,
+  signX402Payment,
+  zodToJsonSchema
+};