mrmainspring 0.1.0

package/dist/payments/supabase-store.d.ts

@@ -0,0 +1,13 @@
+import { SupabaseRestClient } from "../storage/supabase-rest.js";
+import type { PaymentIntentRecord, PaymentReceiptRecord, PaymentStore } from "./types.js";
+export declare class SupabasePaymentStore implements PaymentStore {
+    private readonly client;
+    private readonly intentsTable;
+    private readonly receiptsTable;
+    constructor(client: SupabaseRestClient);
+    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/supabase-store.js

@@ -0,0 +1,51 @@
+export class SupabasePaymentStore {
+    client;
+    intentsTable;
+    receiptsTable;
+    constructor(client) {
+        this.client = client;
+        this.intentsTable = client.table("payment_intents");
+        this.receiptsTable = client.table("payment_receipts");
+    }
+    async saveIntent(intent) {
+        await this.client.upsert(this.intentsTable, {
+            id: intent.id,
+            agent_id: intent.agent_id,
+            idempotency_key: intent.idempotency_key,
+            created_at: intent.created_at,
+            updated_at: intent.updated_at,
+            record: intent
+        }, "id");
+    }
+    async getIntent(paymentId) {
+        const [record] = await this.client.selectRecords(this.intentsTable, {
+            filters: { id: paymentId },
+            limit: 1
+        });
+        return record ?? null;
+    }
+    async findIntentByIdempotencyKey(agentId, idempotencyKey) {
+        const [record] = await this.client.selectRecords(this.intentsTable, {
+            filters: { agent_id: agentId, idempotency_key: idempotencyKey },
+            order: { column: "created_at" },
+            limit: 1
+        });
+        return record ?? null;
+    }
+    async saveReceipt(receipt) {
+        await this.client.upsert(this.receiptsTable, {
+            id: receipt.id,
+            payment_id: receipt.payment_id,
+            created_at: receipt.created_at,
+            record: receipt
+        }, "id");
+    }
+    async getReceipt(paymentId) {
+        const [record] = await this.client.selectRecords(this.receiptsTable, {
+            filters: { payment_id: paymentId },
+            order: { column: "created_at" },
+            limit: 1
+        });
+        return record ?? null;
+    }
+}

package/dist/payments/types.d.ts

@@ -0,0 +1,101 @@
+export type PaymentFetchInput = {
+    agent_id: string;
+    policy_id: string;
+    method: string;
+    url: string;
+    expected_amount?: string;
+    idempotency_key?: string;
+    request_challenge?: boolean;
+};
+export type PaymentPreflightInput = PaymentFetchInput;
+export type PaymentDenialReason = "policy_not_found" | "policy_disabled" | "url_not_allowed" | "method_not_allowed" | "amount_over_limit" | "period_limit_exceeded" | "invalid_amount";
+export type PaymentStatus = "created" | "policy_denied" | "policy_checked" | "challenge_received" | "settlement_unavailable" | "settled";
+export type PaymentNextState = "ready_for_x402_challenge" | "challenge_received" | "settlement_unavailable" | null;
+export type PaymentSettlementState = "not_started" | "not_required" | "unavailable" | "settled";
+export type PaymentChallengeSummary = {
+    status: "payment_required" | "free_response" | "unexpected_response";
+    status_code: number;
+    facilitator_url: string | null;
+    resource_url: string | null;
+    request_url: string;
+    settlement_status: "not_started" | "not_required";
+    requirements_json?: string | null;
+    requirements?: unknown;
+    requirements_source?: string;
+    response_hash?: string;
+};
+export type PaymentIntentRecord = {
+    id: string;
+    agent_id: string;
+    policy_id: string;
+    method: string;
+    url: string;
+    amount: string | null;
+    status: PaymentStatus;
+    idempotency_key: string | null;
+    policy_hash: string | null;
+    denial_reason: PaymentDenialReason | null;
+    requirements_json: string | null;
+    signed_payload_hash: string | null;
+    settlement_blocker: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type PaymentReceiptRecord = {
+    id: string;
+    payment_id: string;
+    facilitator_url: string;
+    casper_transaction_hash: string | null;
+    settlement_status: "pending" | "settled" | "failed" | "settlement_unavailable";
+    response_hash: string | null;
+    response_status: number | null;
+    receipt_json: string;
+    created_at: string;
+};
+export type PaymentStore = {
+    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>;
+};
+export type PaymentFetchAllowed = {
+    allowed: true;
+    payment_id: string;
+    status: "policy_checked" | "challenge_received" | "settlement_unavailable" | "settled";
+    next_state: PaymentNextState;
+    agent_id: string;
+    policy_id: string;
+    method: string;
+    url: string;
+    expected_amount: string | null;
+    policy_hash: string;
+    idempotency_key: string | null;
+    persisted: true;
+    settlement: PaymentSettlementState;
+    requirements_json: string | null;
+    requirements?: unknown;
+    challenge?: PaymentChallengeSummary;
+    settlement_blocker?: string;
+};
+export type PaymentFetchDenied = {
+    allowed: false;
+    payment_id: string;
+    status: "policy_denied";
+    reason: PaymentDenialReason;
+    agent_id: string;
+    policy_id: string;
+    method: string;
+    url: string;
+    expected_amount: string | null;
+    idempotency_key: string | null;
+    persisted: true;
+};
+export type PaymentFetchResult = PaymentFetchAllowed | PaymentFetchDenied;
+export type PaymentPreflightResult = PaymentFetchResult;
+export type PaymentReceiptResult = {
+    found: boolean;
+    payment_id: string;
+    intent?: PaymentIntentRecord;
+    receipt?: PaymentReceiptRecord | null;
+};

package/dist/payments/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server.d.ts

@@ -0,0 +1,5 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SigilConfig } from "./config.js";
+import { type X402SettlementProvider } from "./x402/settlement.js";
+export declare function createSigilServer(config: SigilConfig): McpServer;
+export declare function createX402SettlementProvider(config: SigilConfig): X402SettlementProvider;

package/dist/server.js

@@ -0,0 +1,68 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { AuditService } from "./audit/service.js";
+import { createCasperAnchorClient } from "./casper/anchorClient.js";
+import { GrimoireService } from "./grimoire/service.js";
+import { registerAuditTools } from "./mcp/auditTools.js";
+import { registerGrimoireTools } from "./mcp/grimoireTools.js";
+import { registerMemoryTools } from "./mcp/memoryTools.js";
+import { registerPaymentTools } from "./mcp/paymentTools.js";
+import { MemoryService } from "./memory/service.js";
+import { PaymentService } from "./payments/service.js";
+import { createBackendStores } from "./storage/store-factory.js";
+import { X402ChallengeClient } from "./x402/client.js";
+import { CasperCliX402SettlementProvider, DisabledX402SettlementProvider, FacilitatorX402SettlementProvider, HttpX402SigningProvider, ResourceRetryX402SettlementProvider } from "./x402/settlement.js";
+export function createSigilServer(config) {
+    const server = new McpServer({
+        name: config.serverName,
+        version: config.serverVersion
+    });
+    const stores = createBackendStores(config);
+    const auditService = new AuditService(stores.audit);
+    const anchorClient = createCasperAnchorClient(config.casper);
+    const memoryService = new MemoryService(stores.memory, auditService, anchorClient);
+    const grimoireService = new GrimoireService(stores.grimoire, config.grimoireMasterKey, auditService);
+    const paymentService = new PaymentService(grimoireService, stores.payments, auditService, new X402ChallengeClient({
+        facilitatorUrl: config.x402.facilitatorUrl,
+        resourceUrl: config.x402.resourceDemoUrl
+    }), createX402SettlementProvider(config));
+    registerMemoryTools(server, memoryService);
+    registerGrimoireTools(server, grimoireService);
+    registerPaymentTools(server, paymentService);
+    registerAuditTools(server, auditService);
+    return server;
+}
+export function createX402SettlementProvider(config) {
+    if (!config.x402.settlementEnabled) {
+        return new DisabledX402SettlementProvider("x402_settlement_disabled");
+    }
+    if (!config.x402.signerUrl) {
+        return new DisabledX402SettlementProvider("x402_signing_provider_not_configured");
+    }
+    const signer = new HttpX402SigningProvider({
+        signerUrl: config.x402.signerUrl,
+        authToken: config.x402.signerAuthToken,
+        timeoutMs: config.x402.signerTimeoutMs
+    });
+    if (config.x402.settlementMode === "facilitator") {
+        return new FacilitatorX402SettlementProvider(signer);
+    }
+    if (config.x402.settlementMode === "casper-cli") {
+        return new CasperCliX402SettlementProvider(signer, {
+            networkName: config.casper.networkName,
+            caip2ChainId: config.casper.caip2ChainId,
+            rpcUrl: config.casper.rpcUrl,
+            accountKeyPath: config.casper.accountKeyPath,
+            submissionEnabled: config.casper.submissionEnabled,
+            clientBin: config.casper.clientBin,
+            clientWslDistro: config.casper.clientWslDistro,
+            gasPriceTolerance: config.casper.gasPriceTolerance,
+            pricingMode: config.casper.pricingMode,
+            paymentAmountMotes: config.x402.casperSettlementPaymentAmountMotes,
+            confirmationPollIntervalMs: config.x402.casperConfirmationPollIntervalMs,
+            confirmationTimeoutMs: config.x402.casperConfirmationTimeoutMs
+        });
+    }
+    return new ResourceRetryX402SettlementProvider(signer, undefined, {
+        paymentHeaderName: config.x402.paymentHeaderName
+    });
+}

package/dist/storage/json-file-store.d.ts

@@ -0,0 +1,17 @@
+type JsonFileStoreOptions<T> = {
+    filePath: string;
+    empty: () => T;
+    normalize: (parsed: unknown) => T;
+};
+export declare class JsonFileStore<T> {
+    private readonly filePath;
+    private readonly lockKey;
+    private readonly empty;
+    private readonly normalize;
+    constructor(options: JsonFileStoreOptions<T>);
+    read(): Promise<T>;
+    update(mutator: (data: T) => void | Promise<void>): Promise<void>;
+    private readUnlocked;
+    private writeUnlocked;
+}
+export {};

package/dist/storage/json-file-store.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+const fileLocks = new Map();
+export class JsonFileStore {
+    filePath;
+    lockKey;
+    empty;
+    normalize;
+    constructor(options) {
+        this.filePath = options.filePath;
+        this.lockKey = resolve(options.filePath);
+        this.empty = options.empty;
+        this.normalize = options.normalize;
+    }
+    async read() {
+        return this.readUnlocked();
+    }
+    async update(mutator) {
+        await withFileLock(this.lockKey, async () => {
+            const data = await this.readUnlocked();
+            await mutator(data);
+            await this.writeUnlocked(data);
+        });
+    }
+    async readUnlocked() {
+        let raw;
+        try {
+            raw = await readFile(this.filePath, "utf8");
+        }
+        catch (error) {
+            if (isMissingFile(error)) {
+                return this.empty();
+            }
+            throw error;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new Error(`Failed to parse JSON store file at ${this.filePath}: ${formatErrorMessage(error)}`, { cause: error });
+        }
+        return this.normalize(parsed);
+    }
+    async writeUnlocked(data) {
+        const fileDir = dirname(this.filePath);
+        const tempPath = join(fileDir, `.${basename(this.filePath)}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`);
+        await mkdir(fileDir, { recursive: true });
+        try {
+            await writeFile(tempPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+            await rename(tempPath, this.filePath);
+        }
+        catch (error) {
+            await rm(tempPath, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+async function withFileLock(lockKey, action) {
+    const previous = fileLocks.get(lockKey) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolveCurrent) => {
+        release = resolveCurrent;
+    });
+    const next = previous.catch(() => undefined).then(() => current);
+    fileLocks.set(lockKey, next);
+    await previous.catch(() => undefined);
+    try {
+        return await action();
+    }
+    finally {
+        release();
+        if (fileLocks.get(lockKey) === next) {
+            fileLocks.delete(lockKey);
+        }
+    }
+}
+function isMissingFile(error) {
+    return Boolean(error &&
+        typeof error === "object" &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function formatErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/storage/store-factory.d.ts

@@ -0,0 +1,12 @@
+import type { AuditStore } from "../audit/types.js";
+import type { SigilConfig } from "../config.js";
+import type { GrimoireStore } from "../grimoire/types.js";
+import type { MemoryStore } from "../memory/types.js";
+import type { PaymentStore } from "../payments/types.js";
+export type BackendStores = {
+    audit: AuditStore;
+    grimoire: GrimoireStore;
+    memory: MemoryStore;
+    payments: PaymentStore;
+};
+export declare function createBackendStores(config: SigilConfig): BackendStores;

package/dist/storage/store-factory.js

@@ -0,0 +1,26 @@
+import { SupabaseAuditStore } from "../audit/supabase-store.js";
+import { FileAuditStore } from "../audit/store.js";
+import { SupabaseGrimoireStore } from "../grimoire/supabase-store.js";
+import { FileGrimoireStore } from "../grimoire/store.js";
+import { SupabaseMemoryStore } from "../memory/supabase-store.js";
+import { FileMemoryStore } from "../memory/store.js";
+import { SupabasePaymentStore } from "../payments/supabase-store.js";
+import { FilePaymentStore } from "../payments/store.js";
+import { SupabaseRestClient } from "./supabase-rest.js";
+export function createBackendStores(config) {
+    if (config.storage.backend === "supabase") {
+        const client = new SupabaseRestClient(config.storage.supabase);
+        return {
+            audit: new SupabaseAuditStore(client),
+            grimoire: new SupabaseGrimoireStore(client),
+            memory: new SupabaseMemoryStore(client),
+            payments: new SupabasePaymentStore(client)
+        };
+    }
+    return {
+        audit: new FileAuditStore(config.dataDir),
+        grimoire: new FileGrimoireStore(config.dataDir),
+        memory: new FileMemoryStore(config.dataDir),
+        payments: new FilePaymentStore(config.dataDir)
+    };
+}

package/dist/storage/supabase-rest.d.ts

@@ -0,0 +1,26 @@
+export type SupabaseRestConfig = {
+    url: string;
+    key: string;
+    schema: string;
+    tablePrefix: string;
+};
+type SupabaseSelectOptions = {
+    filters?: Record<string, string | null>;
+    order?: {
+        column: string;
+        ascending?: boolean;
+    };
+    limit?: number;
+};
+type SupabaseRecord = Record<string, unknown>;
+export declare class SupabaseRestClient {
+    private readonly config;
+    private readonly baseUrl;
+    constructor(config: SupabaseRestConfig);
+    table(name: string): string;
+    upsert(table: string, row: SupabaseRecord, onConflict: string): Promise<void>;
+    insert(table: string, row: SupabaseRecord): Promise<void>;
+    selectRecords<T>(table: string, options?: SupabaseSelectOptions): Promise<T[]>;
+    private request;
+}
+export {};

package/dist/storage/supabase-rest.js

@@ -0,0 +1,85 @@
+export class SupabaseRestClient {
+    config;
+    baseUrl;
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = `${config.url.replace(/\/+$/, "")}/rest/v1`;
+    }
+    table(name) {
+        return `${this.config.tablePrefix}${name}`;
+    }
+    async upsert(table, row, onConflict) {
+        const url = new URL(`${this.baseUrl}/${table}`);
+        url.searchParams.set("on_conflict", onConflict);
+        await this.request(url, {
+            method: "POST",
+            headers: {
+                Prefer: "resolution=merge-duplicates,return=minimal"
+            },
+            body: JSON.stringify(row)
+        });
+    }
+    async insert(table, row) {
+        await this.request(new URL(`${this.baseUrl}/${table}`), {
+            method: "POST",
+            headers: {
+                Prefer: "return=minimal"
+            },
+            body: JSON.stringify(row)
+        });
+    }
+    async selectRecords(table, options = {}) {
+        const url = new URL(`${this.baseUrl}/${table}`);
+        url.searchParams.set("select", "record");
+        for (const [column, value] of Object.entries(options.filters ?? {})) {
+            url.searchParams.set(column, value === null ? "is.null" : `eq.${value}`);
+        }
+        if (options.order) {
+            const direction = options.order.ascending === true ? "asc" : "desc";
+            url.searchParams.set("order", `${options.order.column}.${direction}`);
+        }
+        if (options.limit !== undefined) {
+            url.searchParams.set("limit", String(options.limit));
+        }
+        const rows = await this.request(url, { method: "GET" });
+        if (!Array.isArray(rows)) {
+            throw new Error(`Supabase table ${table} returned a non-array response`);
+        }
+        return rows.map((row) => {
+            const record = asRecord(row).record;
+            if (!record || typeof record !== "object" || Array.isArray(record)) {
+                throw new Error(`Supabase table ${table} returned a row without a JSON record`);
+            }
+            return record;
+        });
+    }
+    async request(url, init) {
+        const response = await fetch(url, {
+            ...init,
+            headers: {
+                apikey: this.config.key,
+                Authorization: `Bearer ${this.config.key}`,
+                "Content-Type": "application/json",
+                Accept: "application/json",
+                "Accept-Profile": this.config.schema,
+                "Content-Profile": this.config.schema,
+                ...init.headers
+            }
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`Supabase request failed: ${response.status} ${response.statusText}${body ? ` ${body}` : ""}`);
+        }
+        if (response.status === 204) {
+            return null;
+        }
+        const body = await response.text();
+        return body ? JSON.parse(body) : null;
+    }
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Expected Supabase row object");
+    }
+    return value;
+}

package/dist/x402/client.d.ts

@@ -0,0 +1,44 @@
+export type PaymentRequirements = unknown;
+export type X402ChallengeClientConfig = {
+    facilitatorUrl?: string | null;
+    resourceUrl?: string | null;
+};
+export type X402ChallengeRequest = {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+};
+export type X402RequirementsSource = "payment-required-header" | "x-payment-required-header" | "json-body" | "raw-body";
+type X402ChallengeMetadata = {
+    facilitator_url: string | null;
+    resource_url: string | null;
+    request_url: string;
+};
+export type X402ChallengeResult = {
+    status: "payment_required";
+    status_code: 402;
+    requirements: PaymentRequirements;
+    requirements_json: string;
+    requirements_source: X402RequirementsSource;
+    raw_body: string;
+    settlement_status: "not_started";
+} & X402ChallengeMetadata | {
+    status: "free_response";
+    status_code: number;
+    body_text: string;
+    response_hash: string;
+    settlement_status: "not_required";
+} & X402ChallengeMetadata | {
+    status: "unexpected_response";
+    status_code: number;
+    body_text: string;
+    response_hash: string;
+    settlement_status: "not_started";
+} & X402ChallengeMetadata;
+export declare class X402ChallengeClient {
+    private readonly config;
+    constructor(config?: X402ChallengeClientConfig);
+    requestChallenge(input: X402ChallengeRequest): Promise<X402ChallengeResult>;
+    private metadata;
+}
+export {};

package/dist/x402/client.js

@@ -0,0 +1,95 @@
+import { sha256Hex } from "../memory/hash.js";
+import { redactX402Value } from "./redaction.js";
+export class X402ChallengeClient {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+    }
+    async requestChallenge(input) {
+        const response = await fetch(input.url, {
+            method: input.method.toUpperCase(),
+            headers: input.headers
+        });
+        const bodyText = await response.text();
+        const metadata = this.metadata(input.url);
+        if (response.status === 402) {
+            const requirements = parseRequirements(response.headers, bodyText);
+            const redactedRequirements = redactX402Value(requirements.value);
+            return {
+                ...metadata,
+                status: "payment_required",
+                status_code: 402,
+                requirements: redactedRequirements,
+                requirements_json: JSON.stringify(redactedRequirements),
+                requirements_source: requirements.source,
+                raw_body: bodyText,
+                settlement_status: "not_started"
+            };
+        }
+        if (response.ok) {
+            return {
+                ...metadata,
+                status: "free_response",
+                status_code: response.status,
+                body_text: bodyText,
+                response_hash: sha256Hex(bodyText),
+                settlement_status: "not_required"
+            };
+        }
+        return {
+            ...metadata,
+            status: "unexpected_response",
+            status_code: response.status,
+            body_text: bodyText,
+            response_hash: sha256Hex(bodyText),
+            settlement_status: "not_started"
+        };
+    }
+    metadata(requestUrl) {
+        return {
+            facilitator_url: this.config.facilitatorUrl ?? null,
+            resource_url: this.config.resourceUrl ?? requestUrl,
+            request_url: requestUrl
+        };
+    }
+}
+const PAYMENT_REQUIRED_HEADERS = [
+    { name: "PAYMENT-REQUIRED", source: "payment-required-header" },
+    { name: "X-PAYMENT-REQUIRED", source: "x-payment-required-header" }
+];
+function parseRequirements(headers, bodyText) {
+    for (const header of PAYMENT_REQUIRED_HEADERS) {
+        const value = headers.get(header.name);
+        if (!value) {
+            continue;
+        }
+        const parsed = parseBase64Json(value);
+        if (parsed.ok) {
+            return { value: parsed.value, source: header.source };
+        }
+    }
+    const parsedBody = parseJson(bodyText);
+    if (parsedBody.ok) {
+        return { value: parsedBody.value, source: "json-body" };
+    }
+    return { value: { raw: bodyText }, source: "raw-body" };
+}
+function parseBase64Json(value) {
+    try {
+        return parseJson(Buffer.from(value.trim(), "base64").toString("utf8"));
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function parseJson(value) {
+    if (!value.trim()) {
+        return { ok: false };
+    }
+    try {
+        return { ok: true, value: JSON.parse(value) };
+    }
+    catch {
+        return { ok: false };
+    }
+}