@nullclear/x402-arbiter 0.0.0-stage → 1.1.1

package/dist/index.mjs

@@ -0,0 +1,295 @@
+// 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;
+  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
+      }
+    };
+    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
+      }
+    );
+  };
+}
+export {
+  NullClearClient,
+  NullClearEscrowAbortedError,
+  createNullClearFetch,
+  signX402Payment,
+  zodToJsonSchema
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@nullclear/x402-arbiter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.1.1",
+  "description": "NullClear Developer and Agent SDK for safe x402 calls with deferred schema escrow",
+  "license": "MIT",
+  "homepage": "https://nullclear.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nullclear-Protocol/nullclear.git"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@nullclear/shared": "1.1.1",
+    "viem": "^2.23.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@nullclear/worker-arbiter": "1.1.1",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "echo \"@nullclear/x402-arbiter clean\""
+  }
 }