mrmainspring 0.1.0

package/dist/payments/service.js

@@ -0,0 +1,613 @@
+import { createHash, randomUUID } from "node:crypto";
+import { approveX402Requirements } from "../x402/readiness.js";
+import { redactX402Value } from "../x402/redaction.js";
+export class PaymentService {
+    grimoireService;
+    store;
+    audit;
+    challengeClient;
+    settlementProvider;
+    constructor(grimoireService, store, audit, challengeClient, settlementProvider) {
+        this.grimoireService = grimoireService;
+        this.store = store;
+        this.audit = audit;
+        this.challengeClient = challengeClient;
+        this.settlementProvider = settlementProvider;
+    }
+    async preflightFetch(input) {
+        return this.fetch({ ...input, request_challenge: false });
+    }
+    async fetch(input) {
+        const method = input.method.toUpperCase();
+        const idempotencyKey = input.idempotency_key ?? null;
+        if (idempotencyKey) {
+            const existing = await this.store.findIntentByIdempotencyKey(input.agent_id, idempotencyKey);
+            if (existing) {
+                return this.resultFromIntent(existing);
+            }
+        }
+        const now = new Date().toISOString();
+        const paymentId = createPaymentId();
+        const policy = await this.grimoireService.getPolicy(input.agent_id, input.policy_id);
+        let intent = {
+            id: paymentId,
+            agent_id: input.agent_id,
+            policy_id: input.policy_id,
+            method,
+            url: input.url,
+            amount: input.expected_amount ?? null,
+            status: "created",
+            idempotency_key: idempotencyKey,
+            policy_hash: null,
+            denial_reason: null,
+            requirements_json: null,
+            signed_payload_hash: null,
+            settlement_blocker: null,
+            created_at: now,
+            updated_at: now
+        };
+        const denialReason = policy
+            ? validatePolicy(input, method, policy)
+            : "policy_not_found";
+        if (denialReason) {
+            intent = {
+                ...intent,
+                status: "policy_denied",
+                denial_reason: denialReason,
+                policy_hash: policy?.policy_hash ?? null,
+                updated_at: new Date().toISOString()
+            };
+            await this.store.saveIntent(intent);
+            await this.audit?.record({
+                agent_id: intent.agent_id,
+                event_type: "payment.policy_denied",
+                subject_type: "payment",
+                subject_id: intent.id,
+                severity: "warn",
+                metadata: {
+                    policy_id: intent.policy_id,
+                    method: intent.method,
+                    url: intent.url,
+                    amount: intent.amount,
+                    reason: denialReason,
+                    idempotency_key: idempotencyKey
+                }
+            });
+            return this.resultFromIntent(intent);
+        }
+        intent = {
+            ...intent,
+            status: "policy_checked",
+            policy_hash: policy.policy_hash,
+            updated_at: new Date().toISOString()
+        };
+        await this.store.saveIntent(intent);
+        await this.audit?.record({
+            agent_id: intent.agent_id,
+            event_type: "payment.policy_approved",
+            subject_type: "payment",
+            subject_id: intent.id,
+            metadata: {
+                policy_id: intent.policy_id,
+                method: intent.method,
+                url: intent.url,
+                amount: intent.amount,
+                policy_hash: intent.policy_hash,
+                idempotency_key: idempotencyKey,
+                next_state: "challenge_received",
+                request_challenge: input.request_challenge ?? false
+            }
+        });
+        if (input.request_challenge) {
+            return this.fetchChallenge(intent, policy, input.expected_amount ?? null);
+        }
+        return this.resultFromIntent(intent);
+    }
+    async receipt(paymentId) {
+        const intent = await this.store.getIntent(paymentId);
+        if (!intent) {
+            return { found: false, payment_id: paymentId };
+        }
+        return {
+            found: true,
+            payment_id: paymentId,
+            intent,
+            receipt: await this.store.getReceipt(paymentId)
+        };
+    }
+    async fetchChallenge(intent, policy, expectedAmount) {
+        if (!this.challengeClient) {
+            const unavailable = await this.markSettlementUnavailable(intent, "x402_challenge_client_unavailable");
+            return this.resultFromIntent(unavailable, undefined, "x402_challenge_client_unavailable");
+        }
+        try {
+            const challenge = await this.challengeClient.requestChallenge({
+                method: intent.method,
+                url: intent.url
+            });
+            if (challenge.status === "payment_required") {
+                const safeRequirements = redactX402Value(challenge.requirements);
+                const safeRequirementsJson = JSON.stringify(safeRequirements);
+                const safeChallenge = {
+                    ...challenge,
+                    requirements: safeRequirements,
+                    requirements_json: safeRequirementsJson
+                };
+                const updated = {
+                    ...intent,
+                    status: "challenge_received",
+                    requirements_json: safeRequirementsJson,
+                    updated_at: new Date().toISOString()
+                };
+                await this.store.saveIntent(updated);
+                const approval = approveX402Requirements({
+                    requirements: challenge.requirements,
+                    policy,
+                    method: updated.method,
+                    url: updated.url,
+                    expectedAmount
+                });
+                await this.audit?.record({
+                    agent_id: updated.agent_id,
+                    event_type: "payment.challenge_received",
+                    subject_type: "payment",
+                    subject_id: updated.id,
+                    metadata: {
+                        policy_id: updated.policy_id,
+                        method: updated.method,
+                        url: updated.url,
+                        status_code: challenge.status_code,
+                        requirements_source: challenge.requirements_source,
+                        facilitator_url: challenge.facilitator_url,
+                        resource_url: challenge.resource_url,
+                        settlement: "not_started",
+                        requirements_approved: approval.approved,
+                        selected_requirement_hash: approval.approved
+                            ? approval.selected_requirement_hash
+                            : null
+                    }
+                });
+                if (!approval.approved) {
+                    const unavailable = await this.markSettlementUnavailable(updated, "x402_requirements_not_allowed");
+                    await this.audit?.record({
+                        agent_id: unavailable.agent_id,
+                        event_type: "payment.requirements_rejected",
+                        subject_type: "payment",
+                        subject_id: unavailable.id,
+                        severity: "warn",
+                        metadata: {
+                            policy_id: unavailable.policy_id,
+                            method: unavailable.method,
+                            url: unavailable.url,
+                            reason: approval.reason,
+                            rejected_candidates: approval.rejected_candidates
+                        }
+                    });
+                    return this.resultFromIntent(unavailable, safeChallenge, "x402_requirements_not_allowed");
+                }
+                return this.settleApprovedRequirement(updated, safeChallenge, approval.selected_requirement, approval.selected_requirement_hash);
+            }
+            if (challenge.status === "free_response") {
+                await this.audit?.record({
+                    agent_id: intent.agent_id,
+                    event_type: "payment.challenge_not_required",
+                    subject_type: "payment",
+                    subject_id: intent.id,
+                    metadata: {
+                        policy_id: intent.policy_id,
+                        method: intent.method,
+                        url: intent.url,
+                        status_code: challenge.status_code,
+                        response_hash: challenge.response_hash,
+                        settlement: "not_required"
+                    }
+                });
+                return this.resultFromIntent(intent, challenge);
+            }
+            const unavailable = await this.markSettlementUnavailable(intent, "x402_unexpected_resource_response");
+            await this.audit?.record({
+                agent_id: unavailable.agent_id,
+                event_type: "payment.settlement_unavailable",
+                subject_type: "payment",
+                subject_id: unavailable.id,
+                severity: "warn",
+                metadata: {
+                    policy_id: unavailable.policy_id,
+                    method: unavailable.method,
+                    url: unavailable.url,
+                    status_code: challenge.status_code,
+                    response_hash: challenge.response_hash,
+                    reason: "x402_unexpected_resource_response"
+                }
+            });
+            return this.resultFromIntent(unavailable, challenge, "x402_unexpected_resource_response");
+        }
+        catch (error) {
+            const unavailable = await this.markSettlementUnavailable(intent, "x402_challenge_request_failed");
+            await this.audit?.record({
+                agent_id: unavailable.agent_id,
+                event_type: "payment.settlement_unavailable",
+                subject_type: "payment",
+                subject_id: unavailable.id,
+                severity: "error",
+                metadata: {
+                    policy_id: unavailable.policy_id,
+                    method: unavailable.method,
+                    url: unavailable.url,
+                    reason: "x402_challenge_request_failed",
+                    error: errorMessage(error)
+                }
+            });
+            return this.resultFromIntent(unavailable, undefined, "x402_challenge_request_failed");
+        }
+    }
+    async markSettlementUnavailable(intent, reason) {
+        const updated = {
+            ...intent,
+            status: "settlement_unavailable",
+            settlement_blocker: reason,
+            updated_at: new Date().toISOString()
+        };
+        await this.store.saveIntent(updated);
+        if (reason === "x402_challenge_client_unavailable") {
+            await this.audit?.record({
+                agent_id: updated.agent_id,
+                event_type: "payment.settlement_unavailable",
+                subject_type: "payment",
+                subject_id: updated.id,
+                severity: "warn",
+                metadata: {
+                    policy_id: updated.policy_id,
+                    method: updated.method,
+                    url: updated.url,
+                    reason
+                }
+            });
+        }
+        return updated;
+    }
+    async settleApprovedRequirement(intent, challenge, selectedRequirement, selectedRequirementHash) {
+        if (!this.settlementProvider) {
+            const unavailable = await this.markSettlementUnavailable(intent, "x402_settlement_provider_unavailable");
+            await this.persistSettlementReceipt(unavailable, {
+                status: "unavailable",
+                blocker: "x402_settlement_provider_unavailable",
+                signed_payload_hash: null,
+                response_status: null,
+                casper_transaction_hash: null,
+                receipt_json: JSON.stringify({
+                    status: "settlement_unavailable",
+                    blocker: "x402_settlement_provider_unavailable",
+                    payment_id: unavailable.id,
+                    selected_requirement_hash: selectedRequirementHash
+                })
+            }, challenge.facilitator_url);
+            return this.resultFromIntent(unavailable, challenge, "x402_settlement_provider_unavailable");
+        }
+        const selectedAmount = amountFromRequirement(selectedRequirement) ?? intent.amount;
+        if (selectedAmount) {
+            const periodCheck = await this.checkCurrentPeriodSpend(intent, selectedAmount);
+            if (!periodCheck.allowed) {
+                const unavailable = await this.markSettlementUnavailable(intent, periodCheck.reason);
+                await this.audit?.record({
+                    agent_id: unavailable.agent_id,
+                    event_type: "payment.settlement_unavailable",
+                    subject_type: "payment",
+                    subject_id: unavailable.id,
+                    severity: "warn",
+                    metadata: {
+                        policy_id: unavailable.policy_id,
+                        method: unavailable.method,
+                        url: unavailable.url,
+                        selected_requirement_hash: selectedRequirementHash,
+                        reason: periodCheck.reason
+                    }
+                });
+                return this.resultFromIntent(unavailable, challenge, periodCheck.reason);
+            }
+        }
+        const settlement = await this.settlementProvider.settle({
+            payment_id: intent.id,
+            facilitator_url: challenge.facilitator_url,
+            method: intent.method,
+            url: intent.url,
+            selected_requirement: selectedRequirement,
+            selected_requirement_hash: selectedRequirementHash,
+            policy_hash: intent.policy_hash ?? ""
+        });
+        if (settlement.status === "settled") {
+            const settledIntent = {
+                ...intent,
+                status: "settled",
+                signed_payload_hash: settlement.signed_payload_hash,
+                settlement_blocker: null,
+                updated_at: new Date().toISOString()
+            };
+            await this.store.saveIntent(settledIntent);
+            await this.persistSettlementReceipt(settledIntent, settlement, challenge.facilitator_url);
+            if (selectedAmount) {
+                await this.grimoireService.recordPolicySpend(settledIntent.agent_id, settledIntent.policy_id, selectedAmount);
+            }
+            await this.audit?.record({
+                agent_id: settledIntent.agent_id,
+                event_type: "payment.settled",
+                subject_type: "payment",
+                subject_id: settledIntent.id,
+                metadata: {
+                    policy_id: settledIntent.policy_id,
+                    method: settledIntent.method,
+                    url: settledIntent.url,
+                    selected_requirement_hash: selectedRequirementHash,
+                    signed_payload_hash: settlement.signed_payload_hash,
+                    casper_transaction_hash: settlement.casper_transaction_hash
+                }
+            });
+            return this.resultFromIntent(settledIntent, challenge);
+        }
+        const unavailable = {
+            ...intent,
+            status: "settlement_unavailable",
+            signed_payload_hash: settlement.signed_payload_hash,
+            settlement_blocker: settlement.blocker,
+            updated_at: new Date().toISOString()
+        };
+        await this.store.saveIntent(unavailable);
+        await this.persistSettlementReceipt(unavailable, settlement, challenge.facilitator_url);
+        await this.audit?.record({
+            agent_id: unavailable.agent_id,
+            event_type: "payment.settlement_unavailable",
+            subject_type: "payment",
+            subject_id: unavailable.id,
+            severity: settlement.status === "failed" ? "error" : "warn",
+            metadata: {
+                policy_id: unavailable.policy_id,
+                method: unavailable.method,
+                url: unavailable.url,
+                selected_requirement_hash: selectedRequirementHash,
+                signed_payload_hash: settlement.signed_payload_hash,
+                reason: settlement.blocker
+            }
+        });
+        return this.resultFromIntent(unavailable, challenge, settlement.blocker);
+    }
+    async checkCurrentPeriodSpend(intent, amount) {
+        const policy = await this.grimoireService.getPolicy(intent.agent_id, intent.policy_id);
+        if (!policy) {
+            return { allowed: false, reason: "policy_period_amount_invalid" };
+        }
+        const amountParts = parseDecimalAmount(amount);
+        const maxPeriod = parseDecimalAmount(policy.max_amount_per_period);
+        const currentSpend = parseDecimalAmount(currentPeriodSpend(policy));
+        if (!amountParts || !maxPeriod || !currentSpend) {
+            return { allowed: false, reason: "policy_period_amount_invalid" };
+        }
+        if (compareDecimal(addDecimalParts(currentSpend, amountParts), maxPeriod) > 0) {
+            return { allowed: false, reason: "policy_period_limit_exceeded" };
+        }
+        return { allowed: true };
+    }
+    async persistSettlementReceipt(intent, settlement, facilitatorUrl) {
+        await this.store.saveReceipt({
+            id: createPaymentReceiptId(),
+            payment_id: intent.id,
+            facilitator_url: facilitatorUrl ?? "unconfigured",
+            casper_transaction_hash: settlement.casper_transaction_hash,
+            settlement_status: settlement.status === "settled"
+                ? "settled"
+                : settlement.status === "failed"
+                    ? "failed"
+                    : "settlement_unavailable",
+            response_hash: settlement.receipt_json ? hashReceipt(settlement.receipt_json) : null,
+            response_status: settlement.response_status,
+            receipt_json: settlement.receipt_json,
+            created_at: new Date().toISOString()
+        });
+    }
+    resultFromIntent(intent, challenge, settlementBlocker) {
+        if (intent.status === "policy_denied") {
+            return {
+                allowed: false,
+                payment_id: intent.id,
+                status: "policy_denied",
+                reason: intent.denial_reason ?? "policy_not_found",
+                agent_id: intent.agent_id,
+                policy_id: intent.policy_id,
+                method: intent.method,
+                url: intent.url,
+                expected_amount: intent.amount,
+                idempotency_key: intent.idempotency_key,
+                persisted: true
+            };
+        }
+        const requirements = parseRequirementsJson(intent.requirements_json);
+        const result = {
+            allowed: true,
+            payment_id: intent.id,
+            status: intent.status === "created" ? "policy_checked" : intent.status,
+            next_state: nextStateFor(intent, challenge),
+            agent_id: intent.agent_id,
+            policy_id: intent.policy_id,
+            method: intent.method,
+            url: intent.url,
+            expected_amount: intent.amount,
+            policy_hash: intent.policy_hash ?? "",
+            idempotency_key: intent.idempotency_key,
+            persisted: true,
+            settlement: settlementFor(intent, challenge),
+            requirements_json: intent.requirements_json
+        };
+        if (requirements.parsed) {
+            result.requirements = requirements.value;
+        }
+        if (challenge) {
+            result.challenge = summarizeChallenge(challenge);
+        }
+        const blocker = settlementBlocker ?? intent.settlement_blocker ?? settlementBlockerFor(intent, challenge);
+        if (blocker) {
+            result.settlement_blocker = blocker;
+        }
+        return result;
+    }
+}
+function summarizeChallenge(challenge) {
+    const summary = {
+        status: challenge.status,
+        status_code: challenge.status_code,
+        facilitator_url: challenge.facilitator_url,
+        resource_url: challenge.resource_url,
+        request_url: challenge.request_url,
+        settlement_status: challenge.settlement_status
+    };
+    if (challenge.status === "payment_required") {
+        summary.requirements = challenge.requirements;
+        summary.requirements_json = challenge.requirements_json;
+        summary.requirements_source = challenge.requirements_source;
+    }
+    else {
+        summary.response_hash = challenge.response_hash;
+    }
+    return summary;
+}
+function parseRequirementsJson(requirementsJson) {
+    if (!requirementsJson) {
+        return { parsed: false };
+    }
+    try {
+        return { parsed: true, value: JSON.parse(requirementsJson) };
+    }
+    catch {
+        return { parsed: false };
+    }
+}
+function nextStateFor(intent, challenge) {
+    if (challenge?.status === "free_response") {
+        return null;
+    }
+    switch (intent.status) {
+        case "policy_checked":
+            return "challenge_received";
+        case "challenge_received":
+            return "settlement_unavailable";
+        case "created":
+        case "policy_denied":
+        case "settlement_unavailable":
+        case "settled":
+            return null;
+    }
+}
+function settlementFor(intent, challenge) {
+    if (intent.status === "settled") {
+        return "settled";
+    }
+    if (challenge?.status === "free_response") {
+        return "not_required";
+    }
+    if (intent.status === "settlement_unavailable") {
+        return "unavailable";
+    }
+    return "not_started";
+}
+function settlementBlockerFor(intent, challenge) {
+    if (challenge?.status === "free_response" || intent.status === "settled") {
+        return undefined;
+    }
+    if (intent.status === "challenge_received") {
+        return "x402_settlement_provider_unavailable";
+    }
+    if (intent.status === "settlement_unavailable") {
+        return "x402_settlement_unavailable";
+    }
+    return undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function amountFromRequirement(requirement) {
+    for (const key of ["maxAmountRequired", "amount", "max_amount_required"]) {
+        const value = requirement[key];
+        if (typeof value === "string" && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function validatePolicy(input, method, policy) {
+    if (!policy.enabled) {
+        return "policy_disabled";
+    }
+    const expectedAmount = input.expected_amount
+        ? parseDecimalAmount(input.expected_amount)
+        : null;
+    const maxPerCall = parseDecimalAmount(policy.max_amount_per_call);
+    if (input.expected_amount !== undefined && !expectedAmount) {
+        return "invalid_amount";
+    }
+    if (!maxPerCall) {
+        return "invalid_amount";
+    }
+    if (!policy.allowed_urls.includes(input.url)) {
+        return "url_not_allowed";
+    }
+    if (!policy.allowed_methods.includes(method)) {
+        return "method_not_allowed";
+    }
+    if (expectedAmount && compareDecimal(expectedAmount, maxPerCall) > 0) {
+        return "amount_over_limit";
+    }
+    if (expectedAmount) {
+        const maxPeriod = parseDecimalAmount(policy.max_amount_per_period);
+        const currentSpend = parseDecimalAmount(currentPeriodSpend(policy));
+        if (!maxPeriod || !currentSpend) {
+            return "invalid_amount";
+        }
+        if (compareDecimal(addDecimalParts(currentSpend, expectedAmount), maxPeriod) > 0) {
+            return "period_limit_exceeded";
+        }
+    }
+    return null;
+}
+function createPaymentId() {
+    return `pay_${randomUUID().replaceAll("-", "")}`;
+}
+function createPaymentReceiptId() {
+    return `receipt_${randomUUID().replaceAll("-", "")}`;
+}
+function hashReceipt(receiptJson) {
+    return createHash("sha256").update(receiptJson).digest("hex");
+}
+function compareDecimal(leftParts, rightParts) {
+    const scale = Math.max(leftParts.scale, rightParts.scale);
+    const leftValue = leftParts.value * 10n ** BigInt(scale - leftParts.scale);
+    const rightValue = rightParts.value * 10n ** BigInt(scale - rightParts.scale);
+    if (leftValue === rightValue) {
+        return 0;
+    }
+    return leftValue > rightValue ? 1 : -1;
+}
+function addDecimalParts(leftParts, rightParts) {
+    const scale = Math.max(leftParts.scale, rightParts.scale);
+    const leftValue = leftParts.value * 10n ** BigInt(scale - leftParts.scale);
+    const rightValue = rightParts.value * 10n ** BigInt(scale - rightParts.scale);
+    return {
+        value: leftValue + rightValue,
+        scale
+    };
+}
+function parseDecimalAmount(value) {
+    if (!/^\d+(\.\d+)?$/.test(value)) {
+        return null;
+    }
+    const [whole, fraction = ""] = value.split(".");
+    return {
+        value: BigInt(`${whole}${fraction}`),
+        scale: fraction.length
+    };
+}
+function currentPeriodSpend(policy, now = new Date()) {
+    const periodStartedAt = Date.parse(policy.period_started_at);
+    if (Number.isNaN(periodStartedAt) ||
+        now.getTime() - periodStartedAt >= policy.period_seconds * 1000) {
+        return "0";
+    }
+    return policy.current_period_spend;
+}

package/dist/payments/store.d.ts

@@ -0,0 +1,10 @@
+import type { PaymentIntentRecord, PaymentReceiptRecord, PaymentStore } from "./types.js";
+export declare class FilePaymentStore implements PaymentStore {
+    private readonly store;
+    constructor(dataDir: string);
+    saveIntent(intent: PaymentIntentRecord): Promise<void>;
+    getIntent(paymentId: string): Promise<PaymentIntentRecord | null>;
+    findIntentByIdempotencyKey(agentId: string, idempotencyKey: string): Promise<PaymentIntentRecord | null>;
+    saveReceipt(receipt: PaymentReceiptRecord): Promise<void>;
+    getReceipt(paymentId: string): Promise<PaymentReceiptRecord | null>;
+}

package/dist/payments/store.js

@@ -0,0 +1,64 @@
+import { join } from "node:path";
+import { JsonFileStore } from "../storage/json-file-store.js";
+export class FilePaymentStore {
+    store;
+    constructor(dataDir) {
+        this.store = new JsonFileStore({
+            filePath: join(dataDir, "payments.json"),
+            empty: emptyStore,
+            normalize: normalizeStore
+        });
+    }
+    async saveIntent(intent) {
+        await this.store.update((data) => {
+            const existingIndex = data.intents.findIndex((item) => item.id === intent.id);
+            if (existingIndex >= 0) {
+                data.intents[existingIndex] = intent;
+            }
+            else {
+                data.intents.push(intent);
+            }
+        });
+    }
+    async getIntent(paymentId) {
+        const data = await this.store.read();
+        return data.intents.find((intent) => intent.id === paymentId) ?? null;
+    }
+    async findIntentByIdempotencyKey(agentId, idempotencyKey) {
+        const data = await this.store.read();
+        return (data.intents.find((intent) => intent.agent_id === agentId && intent.idempotency_key === idempotencyKey) ?? null);
+    }
+    async saveReceipt(receipt) {
+        await this.store.update((data) => {
+            const existingIndex = data.receipts.findIndex((item) => item.id === receipt.id);
+            if (existingIndex >= 0) {
+                data.receipts[existingIndex] = receipt;
+            }
+            else {
+                data.receipts.push(receipt);
+            }
+        });
+    }
+    async getReceipt(paymentId) {
+        const data = await this.store.read();
+        return data.receipts.find((receipt) => receipt.payment_id === paymentId) ?? null;
+    }
+}
+function emptyStore() {
+    return {
+        schema_version: "sigil.payment-store.v1",
+        intents: [],
+        receipts: []
+    };
+}
+function normalizeStore(parsed) {
+    const data = asStoreObject(parsed);
+    return {
+        schema_version: "sigil.payment-store.v1",
+        intents: Array.isArray(data.intents) ? data.intents : [],
+        receipts: Array.isArray(data.receipts) ? data.receipts : []
+    };
+}
+function asStoreObject(parsed) {
+    return parsed && typeof parsed === "object" ? parsed : {};
+}