@chainpayhq/sdk 0.0.0-stage → 0.1.0

package/dist/x402-challenge.js

@@ -0,0 +1,385 @@
+import { publicKey } from "./encoding.js";
+export const CUSTOM_X402_VERSION = "x402/1.0";
+export const SOLANA_DEVNET_CAIP2 = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+export const CUSTOM_NETWORK = "solana-devnet";
+export const CUSTOM_PROTOCOL = "chainpay-custom-x402/1.0";
+export const STANDARD_V2_PROTOCOL = "x402-v2";
+export const CUSTOM_PROTOCOL_LABEL = "ChainPay custom receipt-proof flow (x402/1.0). Proof is a settled signature and receipt PDA, not a standard x402 v2 sponsor countersign.";
+export const STANDARD_V2_PROTOCOL_LABEL = "Standard x402 v2 exact SVM. Proof is a partially signed transaction for sponsor countersign. ChainPay does not operate a facilitator.";
+const MAX_HEADER_CHARS = 16 * 1024;
+const MAX_DECODED_CHARS = 16 * 1024;
+const MAX_ACCEPTS = 16;
+const MAX_RESOURCE_CHARS = 2048;
+const MAX_NONCE_CHARS = 128;
+const MAX_U64 = 18446744073709551615n;
+export class X402ProtocolError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "X402ProtocolError";
+        this.code = code;
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function fail(code, message) {
+    throw new X402ProtocolError(code, message);
+}
+export function canonicalU64String(value, name, allowZero = false) {
+    if (typeof value !== "string") {
+        fail("malformed", `${name} must be a canonical decimal u64 string`);
+    }
+    const pattern = allowZero ? /^(0|[1-9]\d*)$/ : /^[1-9]\d*$/;
+    if (!pattern.test(value)) {
+        fail("malformed", `${name} must be a canonical decimal u64 string`);
+    }
+    const parsed = BigInt(value);
+    if (parsed > MAX_U64 || parsed.toString() !== value) {
+        fail("malformed", `${name} must fit in an unsigned 64-bit integer`);
+    }
+    return value;
+}
+function canonicalAddress(value, name) {
+    if (typeof value !== "string" || value.trim() === "") {
+        fail("malformed", `${name} is required`);
+    }
+    let encoded;
+    try {
+        encoded = publicKey(value).toBase58();
+    }
+    catch {
+        fail("malformed", `${name} must be a canonical Solana address`);
+    }
+    if (encoded !== value)
+        fail("malformed", `${name} must be a canonical Solana address`);
+    return encoded;
+}
+function boundedString(value, name, max) {
+    if (typeof value !== "string" || value.trim() === "")
+        fail("malformed", `${name} is required`);
+    if (value.length > max)
+        fail("malformed", `${name} is too long`);
+    return value;
+}
+export function decodePaymentRequiredWire(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > MAX_HEADER_CHARS) {
+        fail("malformed", "x402 payment-required payload is missing or too large");
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (value.length > MAX_DECODED_CHARS)
+            fail("malformed", "x402 payment-required payload is too large");
+        return parsed;
+    }
+    catch (error) {
+        if (error instanceof X402ProtocolError)
+            throw error;
+    }
+    let decoded;
+    try {
+        decoded = Buffer.from(value, "base64").toString("utf8");
+    }
+    catch {
+        fail("malformed", "x402 payment-required header is neither JSON nor base64 JSON");
+    }
+    if (!decoded || decoded.length > MAX_DECODED_CHARS) {
+        fail("malformed", "x402 payment-required payload is too large");
+    }
+    try {
+        return JSON.parse(decoded);
+    }
+    catch {
+        fail("malformed", "x402 payment-required header is neither JSON nor base64 JSON");
+    }
+}
+export function paymentRequiredDocumentsFromResponse(headers, body) {
+    const documents = [];
+    const seen = new Set();
+    for (const name of ["payment-required", "x-payment-required"]) {
+        const header = headers.get(name);
+        if (!header)
+            continue;
+        const document = decodePaymentRequiredWire(header);
+        const key = JSON.stringify(document);
+        if (!seen.has(key)) {
+            seen.add(key);
+            documents.push(document);
+        }
+    }
+    if (body && "parsed" in body && body.parsed !== undefined) {
+        const key = JSON.stringify(body.parsed);
+        if (!seen.has(key))
+            documents.push(body.parsed);
+    }
+    return documents;
+}
+function resourceBinding(value, expectedResource) {
+    const resource = boundedString(value, "resource", MAX_RESOURCE_CHARS);
+    let url;
+    try {
+        url = new URL(resource);
+    }
+    catch {
+        fail("malformed", "resource must be an absolute URL");
+    }
+    if (url.username || url.password) {
+        fail("malformed", "x402 resource URLs must not contain credentials");
+    }
+    const normalized = url.toString();
+    if (expectedResource && normalized !== expectedResource && resource !== expectedResource) {
+        fail("resource_mismatch", "x402 challenge resource does not match the requested resource URL");
+    }
+    return resource;
+}
+function customAmount(option) {
+    const amount = option.amount;
+    const maxAmountRequired = option.maxAmountRequired;
+    if (amount !== undefined && maxAmountRequired !== undefined && amount !== maxAmountRequired) {
+        fail("malformed", "custom x402 amount and maxAmountRequired must be identical canonical strings");
+    }
+    return canonicalU64String(amount ?? maxAmountRequired, "amount");
+}
+function parseCustomOption(option, expectedResource) {
+    if (option.scheme !== "exact")
+        fail("unsupported_scheme", "Only the x402 exact scheme is enabled");
+    if (option.network !== CUSTOM_NETWORK) {
+        fail("unsupported_network", "Custom ChainPay x402/1.0 requires network solana-devnet");
+    }
+    const mintValue = option.asset ?? option.mint;
+    if (option.asset !== undefined && option.mint !== undefined && option.asset !== option.mint) {
+        fail("malformed", "custom x402 asset and mint must match");
+    }
+    const payTo = option.payTo ?? option.recipient;
+    if (option.payTo !== undefined && option.recipient !== undefined && option.payTo !== option.recipient) {
+        fail("malformed", "custom x402 payTo and recipient must match");
+    }
+    const resource = resourceBinding(typeof option.resource === "string" ? option.resource : "", expectedResource);
+    const parsed = {
+        protocol: CUSTOM_PROTOCOL,
+        protocolLabel: CUSTOM_PROTOCOL_LABEL,
+        proofKind: "settled-receipt-pda",
+        network: CUSTOM_NETWORK,
+        scheme: "exact",
+        mint: canonicalAddress(mintValue, "asset"),
+        recipient: canonicalAddress(payTo, "payTo"),
+        amount: customAmount(option),
+        resource,
+    };
+    if (option.tokenProgram !== undefined) {
+        if (option.tokenProgram !== "spl-token" && option.tokenProgram !== "token-2022") {
+            fail("malformed", "tokenProgram must be spl-token or token-2022");
+        }
+        parsed.tokenProgram = option.tokenProgram;
+    }
+    if (option.nonce !== undefined) {
+        parsed.nonce = boundedString(option.nonce, "nonce", MAX_NONCE_CHARS).trim();
+    }
+    if (option.expiresAtSlot !== undefined) {
+        parsed.expiresAtSlot = canonicalU64String(option.expiresAtSlot, "expiresAtSlot", true);
+    }
+    return parsed;
+}
+function v2Resource(envelope, option, expectedResource) {
+    const envelopeUrl = isRecord(envelope.resource) && typeof envelope.resource.url === "string"
+        ? envelope.resource.url
+        : undefined;
+    const optionUrl = typeof option.resource === "string" ? option.resource : undefined;
+    if (envelopeUrl && optionUrl && envelopeUrl !== optionUrl) {
+        fail("resource_mismatch", "x402 v2 resource.url does not match the selected requirement resource");
+    }
+    const resource = envelopeUrl ?? optionUrl;
+    if (!resource)
+        fail("malformed", "standard x402 v2 resource.url is required");
+    return resourceBinding(resource, expectedResource);
+}
+function parseV2Option(option, resource) {
+    if (option.scheme !== "exact")
+        fail("unsupported_scheme", "Only the x402 exact scheme is enabled");
+    if (option.network !== SOLANA_DEVNET_CAIP2) {
+        fail("unsupported_network", `Standard x402 v2 Solana Devnet must use CAIP-2 ${SOLANA_DEVNET_CAIP2}`);
+    }
+    if (option.maxAmountRequired !== undefined && option.amount !== undefined && option.maxAmountRequired !== option.amount) {
+        fail("malformed", "standard x402 v2 amount fields must be identical canonical strings");
+    }
+    if (option.amount === undefined)
+        fail("malformed", "standard x402 v2 amount is required");
+    const extra = option.extra === undefined ? undefined : option.extra;
+    if (extra !== undefined && !isRecord(extra))
+        fail("malformed", "standard x402 v2 extra must be an object");
+    const parsed = {
+        protocol: STANDARD_V2_PROTOCOL,
+        protocolLabel: STANDARD_V2_PROTOCOL_LABEL,
+        proofKind: "partially-signed-sponsored-transaction",
+        network: SOLANA_DEVNET_CAIP2,
+        scheme: "exact",
+        amount: canonicalU64String(option.amount, "amount"),
+        asset: canonicalAddress(option.asset, "asset"),
+        merchantOwner: canonicalAddress(option.payTo, "payTo"),
+        resource,
+    };
+    if (option.maxTimeoutSeconds !== undefined) {
+        if (typeof option.maxTimeoutSeconds !== "number" || !Number.isInteger(option.maxTimeoutSeconds)
+            || option.maxTimeoutSeconds < 1 || option.maxTimeoutSeconds > 86_400) {
+            fail("malformed", "maxTimeoutSeconds must be an integer between 1 and 86400");
+        }
+        parsed.maxTimeoutSeconds = option.maxTimeoutSeconds;
+    }
+    if (extra && extra.feePayer !== undefined) {
+        parsed.feePayer = canonicalAddress(extra.feePayer, "extra.feePayer");
+    }
+    return parsed;
+}
+function acceptRecords(value) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > MAX_ACCEPTS) {
+        fail("malformed", "x402 accepts must be a bounded non-empty array");
+    }
+    if (!value.every(isRecord))
+        fail("malformed", "x402 accepts entries must be objects");
+    return value;
+}
+function selectCustomAccept(accepts) {
+    const selected = accepts.find((option) => option.network === CUSTOM_NETWORK && option.scheme === "exact");
+    if (selected)
+        return selected;
+    if (accepts.some((option) => option.scheme === "exact" && typeof option.network === "string")) {
+        fail("unsupported_network", "Custom ChainPay x402/1.0 requires network solana-devnet");
+    }
+    fail("malformed", "x402/1.0 response has no Solana Devnet exact payment option");
+}
+function selectV2Accept(accepts) {
+    const selected = accepts.find((option) => option.network === SOLANA_DEVNET_CAIP2 && option.scheme === "exact");
+    if (selected)
+        return selected;
+    if (accepts.some((option) => typeof option.network === "string")) {
+        fail("unsupported_network", `Standard x402 v2 Solana Devnet must use CAIP-2 ${SOLANA_DEVNET_CAIP2}`);
+    }
+    fail("malformed", "standard x402 v2 response has no Solana Devnet exact payment option");
+}
+function parseCustomEnvelope(value, expectedResource) {
+    const option = Array.isArray(value.accepts)
+        ? selectCustomAccept(acceptRecords(value.accepts))
+        : value;
+    return { kind: "custom", option: parseCustomOption(option, expectedResource), envelope: value };
+}
+function parseV2Envelope(value, expectedResource) {
+    const option = Array.isArray(value.accepts)
+        ? selectV2Accept(acceptRecords(value.accepts))
+        : isRecord(value.accepted)
+            ? value.accepted
+            : value;
+    const resource = v2Resource(value, option, expectedResource);
+    return { kind: "standard-v2", option: parseV2Option(option, resource), envelope: value };
+}
+function parseBareOption(value, expectedResource) {
+    if (value.network === SOLANA_DEVNET_CAIP2) {
+        return parseV2Envelope(value, expectedResource);
+    }
+    if (value.network === CUSTOM_NETWORK) {
+        fail("malformed", `Custom ChainPay x402 requires an explicit version ${CUSTOM_X402_VERSION}; refusing to infer it from the network name`);
+    }
+    if (typeof value.network === "string") {
+        fail("unsupported_network", "Unsupported x402 network");
+    }
+    fail("malformed", "x402 challenge is missing an explicit protocol version or network");
+}
+export function parsePaymentRequiredDocument(value, expectedResource) {
+    if (!isRecord(value))
+        fail("malformed", "x402 payment requirements must be an object");
+    if (value.x402Version === 2 && value.version === CUSTOM_X402_VERSION) {
+        fail("malformed", "x402 document must not mix x402Version 2 with custom x402/1.0");
+    }
+    if (value.paymentRequired !== undefined) {
+        return parsePaymentRequiredDocument(value.paymentRequired, expectedResource);
+    }
+    if (value.x402Version === 2)
+        return parseV2Envelope(value, expectedResource);
+    if (value.version === CUSTOM_X402_VERSION)
+        return parseCustomEnvelope(value, expectedResource);
+    if (value.x402Version !== undefined)
+        fail("malformed", "unsupported x402Version");
+    if (value.version !== undefined)
+        fail("malformed", "unsupported x402 version");
+    return parseBareOption(value, expectedResource);
+}
+export function detectAndParsePaymentRequired(documents, expectedResource) {
+    if (documents.length === 0) {
+        fail("malformed", "HTTP 402 response did not include payment requirements");
+    }
+    const parsed = [];
+    const errors = [];
+    for (const document of documents) {
+        try {
+            parsed.push(parsePaymentRequiredDocument(document, expectedResource));
+        }
+        catch (error) {
+            if (error instanceof X402ProtocolError)
+                errors.push(error);
+            else
+                throw error;
+        }
+    }
+    if (parsed.length === 0) {
+        throw errors[0] ?? new X402ProtocolError("malformed", "HTTP 402 response did not include payment requirements");
+    }
+    const kinds = new Set(parsed.map((item) => item.kind));
+    if (kinds.size > 1) {
+        fail("conflicting_protocols", "PAYMENT-REQUIRED sources disagree on custom vs standard v2");
+    }
+    return parsed[0];
+}
+/** Alias for agent/SDK callers: parse HTTP 402 headers and body into a detected challenge. */
+export function detectPaymentChallenge(headers, body, expectedResource) {
+    return detectAndParsePaymentRequired(paymentRequiredDocumentsFromResponse(headers, body), expectedResource);
+}
+export function parsePaymentRequiredFromResponse(headers, body, expectedResource) {
+    return detectPaymentChallenge(headers, body, expectedResource);
+}
+export function customReceiptProofDocument(signature, receiptPDA) {
+    return {
+        version: CUSTOM_X402_VERSION,
+        scheme: "exact",
+        network: CUSTOM_NETWORK,
+        payload: { signature, receiptPDA },
+    };
+}
+export function unsupportedSponsorResult(option, extras) {
+    return {
+        action: "x402_unsupported_sponsor",
+        mode: "unsupported-sponsor",
+        protocol: option.protocol,
+        protocolLabel: option.protocolLabel,
+        proofKind: option.proofKind,
+        network: option.network,
+        scheme: option.scheme,
+        amount: option.amount,
+        asset: option.asset,
+        merchantOwner: option.merchantOwner,
+        resource: option.resource,
+        sponsorAvailable: false,
+        wouldSettle: false,
+        reason: "facilitator_required",
+        message: "Standard x402 v2 exact SVM requires a sponsor or facilitator to countersign a partially signed transaction. ChainPay settles through an on-chain mandate and returns a receipt-PDA proof. This challenge is quoted against your mandate; use pay.sh for facilitator merchants, or settleIfReceiptMerchant on allowlisted receipt merchants.",
+        ...(extras?.derivedRecipientTokenAccount
+            ? { derivedRecipientTokenAccount: extras.derivedRecipientTokenAccount }
+            : {}),
+        ...(extras?.mandateQuote ? { mandateQuote: extras.mandateQuote } : {}),
+    };
+}
+export function parseMppWwwAuthenticate(value) {
+    if (!value || !value.trim().toLowerCase().startsWith("payment"))
+        return null;
+    const trimmed = value.trim();
+    const intent = trimmed.match(/\bintent="([^"]+)"/i)?.[1];
+    const method = trimmed.match(/\bmethod="([^"]+)"/i)?.[1];
+    const challengeId = trimmed.match(/\bid="([^"]+)"/i)?.[1];
+    return {
+        action: "mpp_unsupported",
+        mode: "unsupported-mpp",
+        message: "Machine Payments Protocol (MPP) uses WWW-Authenticate: Payment, not x402 PAYMENT-REQUIRED. ChainPay does not settle MPP sessions or Tempo/Stripe methods. Use pay.sh for MPP-gated APIs.",
+        wwwAuthenticate: trimmed,
+        ...(intent ? { intent } : {}),
+        ...(method ? { method } : {}),
+        ...(challengeId ? { challengeId } : {}),
+    };
+}

package/dist/x402.d.ts

@@ -0,0 +1,18 @@
+import type { Address, TokenProgram } from "./types.js";
+export type X402ExactPayment = {
+    mint: Address;
+    recipient: Address;
+    amount: string;
+    resource: string;
+    tokenProgram: TokenProgram;
+    nonce?: string;
+    expiresAtSlot?: string;
+};
+export type X402PaymentReferences = {
+    nonce: string;
+    invoiceHash: string;
+    paymentId: string;
+    signatureReference: string;
+};
+/** Canonical references shared by the x402 client and independent merchant verifier. */
+export declare function deriveX402PaymentReferences(input: X402ExactPayment): Promise<X402PaymentReferences>;

package/dist/x402.js

@@ -0,0 +1,35 @@
+async function sha256Hex(value) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(value).slice().buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Canonical references shared by the x402 client and independent merchant verifier. */
+export async function deriveX402PaymentReferences(input) {
+    const nonceSeed = JSON.stringify({
+        network: "solana-devnet",
+        scheme: "exact",
+        mint: input.mint,
+        recipient: input.recipient,
+        amount: input.amount,
+        resource: input.resource,
+        expiresAtSlot: input.expiresAtSlot,
+    });
+    const nonce = input.nonce?.trim() || (await sha256Hex(`nonce:${nonceSeed}`)).slice(0, 32);
+    const canonical = JSON.stringify({
+        network: "solana-devnet",
+        scheme: "exact",
+        asset: input.mint,
+        payTo: input.recipient,
+        amount: input.amount,
+        resource: input.resource,
+        nonce,
+        tokenProgram: input.tokenProgram,
+        ...(input.expiresAtSlot ? { expiresAtSlot: input.expiresAtSlot } : {}),
+    });
+    const invoiceHash = await sha256Hex(canonical);
+    return {
+        nonce,
+        invoiceHash,
+        paymentId: await sha256Hex(`payment:${invoiceHash}`),
+        signatureReference: await sha256Hex(`x402:${invoiceHash}`),
+    };
+}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@chainpayhq/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Policy-controlled Solana Devnet payments and receipt verification for ChainPay integrations",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stawuah/chainpay-mcp-sdk.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/stawuah/chainpay-mcp-sdk/tree/master/sdk#readme",
+  "bugs": "https://github.com/stawuah/chainpay-mcp-sdk/issues",
+  "keywords": ["chainpay", "solana", "devnet", "stablecoin", "payments", "receipts"],
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "chainpay": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./known-assets": {
+      "types": "./dist/known-assets.d.ts",
+      "import": "./dist/known-assets.js"
+    },
+    "./cards/private-repayment": {
+      "types": "./dist/cards/private-repayment.d.ts",
+      "import": "./dist/cards/private-repayment.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@solana/addresses": "^8.3.0",
+    "@solana/instructions": "^8.3.0",
+    "@solana/rpc-types": "^8.3.0",
+    "@solana/spl-token": "^0.4.15",
+    "@solana/transaction-messages": "^8.3.0",
+    "@solana/transactions": "^8.3.0",
+    "@solana/web3.js": "^1.98.4"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}