mrmainspring 0.1.0

package/dist/x402/resource.js

@@ -0,0 +1,325 @@
+import { createServer } from "node:http";
+import { canonicalizeJson, toJsonObject } from "../memory/canonical.js";
+import { sha256Hex } from "../memory/hash.js";
+import { verifyX402SettlementResponse } from "./readiness.js";
+const DEFAULT_PAYMENT_HEADER_NAME = "PAYMENT-SIGNATURE";
+const MAX_SIGNATURE_HEADER_BYTES = 64 * 1024;
+export class InMemoryX402PaidResourceReplayStore {
+    records = new Map();
+    reserve(input) {
+        const existing = this.records.get(input.replayKey);
+        if (!existing) {
+            this.records.set(input.replayKey, replayRecord(input, "settling"));
+            return { ok: true };
+        }
+        return {
+            ok: false,
+            reason: existing.state === "settling"
+                ? "payment_settlement_in_progress"
+                : existing.payloadHash === input.payloadHash
+                    ? "payment_payload_replayed"
+                    : "nonce_replayed"
+        };
+    }
+    complete(input) {
+        this.records.set(input.replayKey, replayRecord(input, "settled"));
+    }
+    release(input) {
+        const existing = this.records.get(input.replayKey);
+        if (existing?.payloadHash === input.payloadHash && existing.state === "settling") {
+            this.records.delete(input.replayKey);
+        }
+    }
+}
+export function createX402PaidResourceHttpServer(config) {
+    const paymentHeaderName = config.paymentHeaderName ?? DEFAULT_PAYMENT_HEADER_NAME;
+    const postJson = config.postJson ?? postJsonWithFetch;
+    const replayStore = config.replayStore ?? new InMemoryX402PaidResourceReplayStore();
+    return createServer(async (request, response) => {
+        try {
+            await handleX402PaidResourceRequest(request, response, {
+                ...config,
+                paymentHeaderName,
+                postJson,
+                replayStore
+            });
+        }
+        catch (error) {
+            config.logger?.error?.(`x402 paid resource failed: ${errorMessage(error)}`);
+            sendJson(response, 500, { error: "resource_failed" });
+        }
+    });
+}
+async function handleX402PaidResourceRequest(request, response, config) {
+    const pathname = new URL(request.url ?? "/", "http://127.0.0.1").pathname;
+    if (request.method !== "GET" || pathname !== config.resourcePath) {
+        sendJson(response, 404, { error: "not_found" });
+        return;
+    }
+    const paymentHeader = headerValue(request, config.paymentHeaderName);
+    if (!paymentHeader) {
+        sendPaymentRequired(response, config.paymentRequirements);
+        return;
+    }
+    if (Buffer.byteLength(paymentHeader, "utf8") > MAX_SIGNATURE_HEADER_BYTES) {
+        sendPaymentRequired(response, config.paymentRequirements, {
+            error: "payment_signature_too_large"
+        });
+        return;
+    }
+    const paymentPayload = parsePaymentHeader(paymentHeader);
+    if (!paymentPayload) {
+        sendPaymentRequired(response, config.paymentRequirements, {
+            error: "invalid_payment_signature"
+        });
+        return;
+    }
+    const payloadHash = sha256Hex(canonicalizeJson(paymentPayload));
+    const replayKey = replayKeyForPayload(paymentPayload, payloadHash);
+    const selectedRequirement = selectedRequirementForPayload(config.paymentRequirements, paymentPayload);
+    if (!selectedRequirement) {
+        config.logger?.error?.("x402 paid resource could not match selected requirement");
+        sendJson(response, 500, { error: "payment_requirement_mismatch" });
+        return;
+    }
+    const replayReservation = config.replayStore?.reserve({ replayKey, payloadHash });
+    if (replayReservation && !replayReservation.ok) {
+        config.logger?.warn?.(`x402 paid resource replay rejected reason=${replayReservation.reason} payload_hash=${payloadHash}`);
+        sendJson(response, 409, {
+            error: "payment_replayed",
+            reason: replayReservation.reason,
+            payload_hash: payloadHash
+        });
+        return;
+    }
+    const facilitatorRequest = {
+        paymentPayload,
+        paymentRequirements: config.paymentRequirements
+    };
+    const verify = await postFacilitator(config, "verify", facilitatorRequest);
+    if (!verify.ok || !facilitatorVerifyAccepted(verify.body)) {
+        config.replayStore?.release({ replayKey, payloadHash });
+        config.logger?.warn?.(`x402 paid resource rejected verify status=${verify.status} reason=${facilitatorReason(verify.body)}`);
+        sendPaymentRequired(response, config.paymentRequirements, {
+            error: "payment_verify_failed",
+            reason: facilitatorReason(verify.body),
+            facilitator_status: verify.status
+        });
+        return;
+    }
+    const settle = await postFacilitator(config, "settle", facilitatorRequest);
+    if (!settle.ok) {
+        config.replayStore?.release({ replayKey, payloadHash });
+        sendJson(response, 502, {
+            error: "payment_settle_failed",
+            reason: facilitatorReason(settle.body),
+            facilitator_status: settle.status
+        });
+        return;
+    }
+    let settlementBody;
+    try {
+        settlementBody = toJsonObject(settle.body, "settlement_response");
+    }
+    catch {
+        config.replayStore?.release({ replayKey, payloadHash });
+        sendJson(response, 502, {
+            error: "payment_settlement_not_verified",
+            reason: "settlement_response_not_object",
+            facilitator_status: settle.status
+        });
+        return;
+    }
+    const settlement = verifyX402SettlementResponse(settlementBody, {
+        selectedRequirement,
+        signedPayload: paymentPayload
+    });
+    if (!settlement.settled) {
+        config.replayStore?.release({ replayKey, payloadHash });
+        config.logger?.warn?.(`x402 paid resource settlement not verified reason=${settlement.reason}`);
+        sendJson(response, 502, {
+            error: "payment_settlement_not_verified",
+            reason: settlement.reason,
+            facilitator_status: settle.status
+        });
+        return;
+    }
+    response.setHeader("PAYMENT-RESPONSE", encodeBase64Json(settlementBody));
+    response.setHeader("X-PAYMENT-RESPONSE", encodeBase64Json(settlementBody));
+    config.replayStore?.complete({ replayKey, payloadHash });
+    sendJson(response, 200, await resourceBody(config, paymentPayload, settlementBody));
+}
+async function postFacilitator(config, path, body) {
+    try {
+        const result = await config.postJson(facilitatorEndpoint(config.facilitatorUrl, path), body);
+        return {
+            ...result,
+            ok: result.status >= 200 && result.status < 300
+        };
+    }
+    catch {
+        return {
+            status: 502,
+            ok: false,
+            body: { error: `facilitator_${path}_request_failed` }
+        };
+    }
+}
+function facilitatorVerifyAccepted(value) {
+    const body = asRecord(value);
+    return Boolean(body && (body.valid === true || body.success === true));
+}
+async function resourceBody(config, paymentPayload, settlementResponse) {
+    if (typeof config.resourceBody === "function") {
+        return config.resourceBody({ paymentPayload, settlementResponse });
+    }
+    return (config.resourceBody ?? {
+        weather: "sunny",
+        unit: "celsius",
+        temperature: 22,
+        source: "casper-x402-resource",
+        settlement: "settled"
+    });
+}
+function selectedRequirementForPayload(paymentRequirements, paymentPayload) {
+    const selectedRequirementHash = firstString(paymentPayload, [
+        "selectedRequirementHash",
+        "selected_requirement_hash"
+    ]);
+    if (!selectedRequirementHash) {
+        return null;
+    }
+    const accepts = paymentRequirements.accepts;
+    if (Array.isArray(accepts)) {
+        for (const candidate of accepts) {
+            if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+                continue;
+            }
+            const requirement = toJsonObject(candidate, "paymentRequirements.accepts[]");
+            if (sha256Hex(canonicalizeJson(requirement)) === selectedRequirementHash.toLowerCase()) {
+                return requirement;
+            }
+        }
+        return null;
+    }
+    if (sha256Hex(canonicalizeJson(paymentRequirements)) === selectedRequirementHash.toLowerCase()) {
+        return paymentRequirements;
+    }
+    return null;
+}
+function replayKeyForPayload(paymentPayload, fallbackHash) {
+    const authorization = asRecord(paymentPayload.authorization) ?? {};
+    const network = firstString(paymentPayload, ["network", "networkId", "network_id"]) ??
+        firstString(authorization, ["network", "networkId", "network_id"]) ??
+        "unknown-network";
+    const payer = firstString(paymentPayload, ["payer", "payerAccount", "payer_account"]) ??
+        firstString(authorization, ["payer", "from"]) ??
+        "unknown-payer";
+    const nonce = firstString(paymentPayload, ["nonce"]) ??
+        firstString(authorization, ["nonce"]) ??
+        fallbackHash;
+    return sha256Hex([network.toLowerCase(), payer.toLowerCase(), nonce.toLowerCase()].join(":"));
+}
+function sendPaymentRequired(response, paymentRequirements, body = null) {
+    const encodedRequirements = encodeBase64Json(paymentRequirements);
+    response.setHeader("PAYMENT-REQUIRED", encodedRequirements);
+    response.setHeader("X-PAYMENT-REQUIRED", encodedRequirements);
+    sendJson(response, 402, body ?? paymentRequirements);
+}
+function sendJson(response, statusCode, value) {
+    if (response.writableEnded) {
+        return;
+    }
+    response.statusCode = statusCode;
+    response.setHeader("content-type", "application/json");
+    response.end(`${JSON.stringify(value)}\n`);
+}
+function headerValue(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    if (Array.isArray(value)) {
+        return value[0] ?? null;
+    }
+    return value ?? null;
+}
+function parsePaymentHeader(value) {
+    for (const candidate of [decodeBase64(value), value]) {
+        if (!candidate) {
+            continue;
+        }
+        try {
+            return toJsonObject(JSON.parse(candidate), "payment_signature");
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function postJsonWithFetch(url, body) {
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json"
+        },
+        body: JSON.stringify(body)
+    });
+    const text = await response.text();
+    return {
+        status: response.status,
+        body: text ? parseJsonOrRaw(text) : {}
+    };
+}
+function parseJsonOrRaw(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function facilitatorEndpoint(facilitatorUrl, path) {
+    return new URL(path, facilitatorUrl.endsWith("/") ? facilitatorUrl : `${facilitatorUrl}/`).toString();
+}
+function encodeBase64Json(value) {
+    return Buffer.from(JSON.stringify(value), "utf8").toString("base64");
+}
+function decodeBase64(value) {
+    try {
+        return Buffer.from(value.trim(), "base64").toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function firstString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function facilitatorReason(value) {
+    const body = asRecord(value);
+    if (!body) {
+        return null;
+    }
+    return firstString(body, ["reason", "error", "message"]);
+}
+function replayRecord(input, state) {
+    return {
+        replayKey: input.replayKey,
+        payloadHash: input.payloadHash,
+        state,
+        updatedAt: new Date().toISOString()
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/x402/settlement.d.ts

@@ -0,0 +1,176 @@
+import { type CasperCommandInvocation, type CasperCommandResult, type CasperCommandRunner } from "../casper/anchorClient.js";
+import type { JsonObject } from "../memory/types.js";
+export type X402SettlementBlocker = "x402_settlement_disabled" | "x402_settlement_provider_unavailable" | "x402_signing_provider_not_configured" | "x402_signer_request_failed" | "x402_signer_response_invalid" | "x402_facilitator_verify_failed" | "x402_facilitator_settle_failed" | "x402_facilitator_settlement_not_verified" | "x402_paid_resource_fetch_failed" | "x402_paid_resource_still_requires_payment" | "x402_paid_resource_settlement_not_verified" | "x402_casper_settlement_not_configured" | "x402_casper_transaction_submission_disabled" | "x402_casper_payment_payload_invalid" | "x402_casper_transaction_submission_failed" | "x402_casper_transaction_hash_missing" | "x402_casper_transaction_lookup_failed" | "x402_casper_transaction_execution_unavailable" | "x402_casper_transaction_execution_failed";
+export type X402SettlementInput = {
+    payment_id: string;
+    facilitator_url: string | null;
+    method: string;
+    url: string;
+    selected_requirement: JsonObject;
+    selected_requirement_hash: string;
+    policy_hash: string;
+};
+export type X402SigningInput = X402SettlementInput;
+export type X402SigningResult = {
+    signed: true;
+    signed_payload: JsonObject;
+    signed_payload_hash: string;
+} | {
+    signed: false;
+    blocker: X402SettlementBlocker;
+};
+export type X402SignedPaymentProvider = {
+    sign(input: X402SigningInput): Promise<X402SigningResult>;
+};
+export type X402SettlementOutcome = {
+    status: "unavailable";
+    blocker: X402SettlementBlocker;
+    signed_payload_hash: string | null;
+    response_status: number | null;
+    casper_transaction_hash: null;
+    receipt_json: string;
+} | {
+    status: "failed";
+    blocker: X402SettlementBlocker;
+    signed_payload_hash: string | null;
+    response_status: number | null;
+    casper_transaction_hash: string | null;
+    receipt_json: string;
+} | {
+    status: "settled";
+    signed_payload_hash: string;
+    response_status: number;
+    casper_transaction_hash: string;
+    receipt_json: string;
+};
+export type X402SettlementProvider = {
+    settle(input: X402SettlementInput): Promise<X402SettlementOutcome>;
+};
+export type X402JsonPostResult = {
+    status: number;
+    body: unknown;
+};
+export type X402JsonPoster = (url: string, body: JsonObject) => Promise<X402JsonPostResult>;
+export type X402HttpSigningProviderConfig = {
+    signerUrl: string | null;
+    authToken?: string | null;
+    timeoutMs?: number;
+    now?: () => Date;
+    maxValiditySeconds?: number | null;
+};
+export type X402ResourceRetrySettlementConfig = {
+    paymentHeaderName?: string;
+    now?: () => Date;
+    maxValiditySeconds?: number | null;
+};
+export type X402ResourceFetchResult = {
+    status: number;
+    headers: Headers;
+    bodyText: string;
+};
+export type X402ResourceFetcher = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+}) => Promise<X402ResourceFetchResult>;
+export type X402CasperCliSettlementConfig = {
+    networkName: string;
+    caip2ChainId: string;
+    rpcUrl: string | null;
+    accountKeyPath: string | null;
+    submissionEnabled: boolean;
+    clientBin: string;
+    clientWslDistro: string | null;
+    gasPriceTolerance: string;
+    pricingMode: string;
+    paymentAmountMotes: string;
+    confirmationPollIntervalMs?: number;
+    confirmationTimeoutMs?: number;
+    now?: () => Date;
+    maxValiditySeconds?: number | null;
+};
+export type ValidatedX402CasperCliSettlementConfig = X402CasperCliSettlementConfig & {
+    rpcUrl: string;
+    accountKeyPath: string;
+};
+export type CasperX402SettlementPayment = {
+    settlementKind: "native-transfer";
+    scheme: "exact";
+    network: string;
+    assetId: "casper-native-cspr";
+    target: string;
+    amount: string;
+    nonce: string;
+} | {
+    settlementKind: "cep18-transfer-with-authorization";
+    scheme: "exact";
+    network: string;
+    assetPackageHash: string;
+    from: string;
+    to: string;
+    amount: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+    publicKey: string;
+    signature: string;
+};
+export declare class DisabledX402SettlementProvider implements X402SettlementProvider {
+    private readonly blocker;
+    constructor(blocker?: X402SettlementBlocker);
+    settle(input: X402SettlementInput): Promise<X402SettlementOutcome>;
+}
+export declare class DisabledX402SigningProvider implements X402SignedPaymentProvider {
+    sign(): Promise<X402SigningResult>;
+}
+export declare class HttpX402SigningProvider implements X402SignedPaymentProvider {
+    private readonly config;
+    constructor(config: X402HttpSigningProviderConfig);
+    sign(input: X402SigningInput): Promise<X402SigningResult>;
+}
+export declare class CasperCliX402SettlementProvider implements X402SettlementProvider {
+    private readonly signer;
+    private readonly config;
+    private readonly commandRunner;
+    constructor(signer: X402SignedPaymentProvider, config: X402CasperCliSettlementConfig, commandRunner?: CasperCommandRunner);
+    settle(input: X402SettlementInput): Promise<X402SettlementOutcome>;
+    private waitForExecution;
+}
+export declare class FacilitatorX402SettlementProvider implements X402SettlementProvider {
+    private readonly signer;
+    private readonly postJson;
+    private readonly config;
+    constructor(signer: X402SignedPaymentProvider, postJson?: X402JsonPoster, config?: {
+        now?: () => Date;
+        maxValiditySeconds?: number | null;
+    });
+    settle(input: X402SettlementInput): Promise<X402SettlementOutcome>;
+}
+export declare class ResourceRetryX402SettlementProvider implements X402SettlementProvider {
+    private readonly signer;
+    private readonly resourceFetch;
+    private readonly paymentHeaderName;
+    private readonly now;
+    private readonly maxValiditySeconds;
+    constructor(signer: X402SignedPaymentProvider, resourceFetch?: X402ResourceFetcher, config?: X402ResourceRetrySettlementConfig);
+    settle(input: X402SettlementInput): Promise<X402SettlementOutcome>;
+}
+export declare function createSignedPayloadHash(payload: unknown): string;
+export declare function validateX402CasperCliSettlementConfig(config: X402CasperCliSettlementConfig): ValidatedX402CasperCliSettlementConfig | null;
+export declare function buildCasperX402SettlementCommand(config: ValidatedX402CasperCliSettlementConfig, payment: CasperX402SettlementPayment): CasperCommandInvocation;
+export declare function buildCasperGetTransactionCommand(config: ValidatedX402CasperCliSettlementConfig, transactionHash: string): CasperCommandInvocation;
+export declare function verifyCasperTransactionExecution(result: CasperCommandResult): CasperX402ExecutionStatus;
+type CasperX402ExecutionStatus = {
+    status: "success";
+    receipt: unknown;
+} | {
+    status: "failed";
+    errorMessage: string;
+    receipt: unknown;
+} | {
+    status: "not_executed";
+    receipt: unknown;
+} | {
+    status: "lookup_failed";
+    result: CasperCommandResult;
+};
+export {};