mrmainspring 0.1.0

package/dist/casper/anchorClient.js

@@ -0,0 +1,412 @@
+import { spawn } from "node:child_process";
+import { sha256Hex } from "../memory/hash.js";
+const HEX_64_PATTERN = /^[a-f0-9]{64}$/;
+const CASPER_HASH_PATTERN = /^(hash-)?[a-f0-9]{64}$/i;
+const CASPER_PACKAGE_HASH_PATTERN = /^(hash-|package-)?[a-f0-9]{64}$/i;
+export const REAL_CASPER_ANCHOR_ENV_VARS = [
+    "CASPER_RPC_URL",
+    "CASPER_NETWORK_NAME",
+    "MEMORY_ANCHOR_CONTRACT_HASH",
+    "MEMORY_ANCHOR_PACKAGE_HASH",
+    "CASPER_ACCOUNT_KEY_PATH",
+    "CASPER_ENABLE_REAL_SUBMISSION"
+];
+export class UnconfiguredCasperAnchorClient {
+    reason;
+    mode = "unconfigured";
+    submissions = [];
+    constructor(reason = "casper_contract_not_configured") {
+        this.reason = reason;
+    }
+    async anchorMemory(submission) {
+        assertValidAnchorSubmission(submission);
+        this.submissions.push(submission);
+        return createPendingAnchorResult(submission, this.reason);
+    }
+}
+export class ConfiguredCasperAnchorClient {
+    config;
+    commandRunner;
+    mode = "configured";
+    submissions = [];
+    constructor(config, commandRunner = runCasperCommand) {
+        this.config = config;
+        this.commandRunner = commandRunner;
+    }
+    async anchorMemory(submission) {
+        assertValidAnchorSubmission(submission);
+        this.submissions.push(submission);
+        if (!this.config.submissionEnabled) {
+            return createPendingAnchorResult(submission, "casper_transaction_submission_disabled");
+        }
+        const invocation = buildCasperAnchorCommand(this.config, submission);
+        let commandResult;
+        try {
+            commandResult = await this.commandRunner(invocation.command, invocation.args);
+        }
+        catch {
+            return createFailedAnchorResult(submission, "casper_transaction_submission_failed");
+        }
+        if (commandResult.exitCode !== 0) {
+            return createFailedAnchorResult(submission, "casper_transaction_submission_failed");
+        }
+        const transactionHash = extractCasperTransactionHash(commandResult);
+        if (!transactionHash) {
+            return createFailedAnchorResult(submission, "casper_transaction_hash_missing");
+        }
+        return createSubmittedAnchorResult(submission, transactionHash);
+    }
+}
+export class MockCasperAnchorClient extends UnconfiguredCasperAnchorClient {
+    constructor() {
+        super("casper_contract_not_configured");
+    }
+}
+export function createCasperAnchorClient(config, options = {}) {
+    const anchorConfig = validateCasperAnchorConfig(config);
+    if (!anchorConfig) {
+        return new UnconfiguredCasperAnchorClient();
+    }
+    return new ConfiguredCasperAnchorClient(anchorConfig, options.commandRunner);
+}
+export function validateCasperAnchorConfig(config) {
+    const contractHash = normalizeOptional(config.memoryAnchorContractHash);
+    if (!contractHash) {
+        return null;
+    }
+    assertCasperHash("MEMORY_ANCHOR_CONTRACT_HASH", contractHash);
+    const packageHash = requireNonEmpty(config.memoryAnchorPackageHash, "MEMORY_ANCHOR_PACKAGE_HASH when MEMORY_ANCHOR_CONTRACT_HASH is set");
+    assertCasperPackageHash("MEMORY_ANCHOR_PACKAGE_HASH", packageHash);
+    const networkName = requireNonEmpty(config.networkName, "CASPER_NETWORK_NAME");
+    const caip2ChainId = requireNonEmpty(config.caip2ChainId, "CASPER_CAIP2_CHAIN_ID");
+    const rpcUrl = requireNonEmpty(config.rpcUrl, "CASPER_RPC_URL when MEMORY_ANCHOR_CONTRACT_HASH is set");
+    const accountKeyPath = requireNonEmpty(config.accountKeyPath, "CASPER_ACCOUNT_KEY_PATH when MEMORY_ANCHOR_CONTRACT_HASH is set");
+    assertHttpUrl("CASPER_RPC_URL", rpcUrl);
+    assertUnsignedInteger("CASPER_GAS_PRICE_TOLERANCE", config.gasPriceTolerance ?? "10");
+    assertPricingMode("CASPER_PRICING_MODE", config.pricingMode ?? "classic");
+    assertUnsignedInteger("CASPER_ANCHOR_PAYMENT_AMOUNT_MOTES", config.anchorPaymentAmountMotes ?? "3000000000");
+    return {
+        networkName,
+        caip2ChainId,
+        rpcUrl,
+        accountKeyPath,
+        memoryAnchorContractHash: contractHash,
+        memoryAnchorPackageHash: packageHash,
+        submissionEnabled: config.submissionEnabled ?? false,
+        clientBin: requireNonEmpty(config.clientBin ?? "casper-client", "CASPER_CLIENT_BIN"),
+        clientWslDistro: normalizeOptional(config.clientWslDistro),
+        anchorSubmissionMode: config.anchorSubmissionMode ?? "transaction-package",
+        gasPriceTolerance: requireNonEmpty(config.gasPriceTolerance ?? "10", "CASPER_GAS_PRICE_TOLERANCE"),
+        pricingMode: requireNonEmpty(config.pricingMode ?? "classic", "CASPER_PRICING_MODE"),
+        anchorPaymentAmountMotes: requireNonEmpty(config.anchorPaymentAmountMotes ?? "3000000000", "CASPER_ANCHOR_PAYMENT_AMOUNT_MOTES")
+    };
+}
+export function createAnchorSubmission(input) {
+    assertNonEmpty("agent_id", input.agent_id);
+    assertNonEmpty("memory_id", input.memory_id);
+    assertHex64("content_hash", input.content_hash);
+    assertHex64("metadata_hash", input.metadata_hash);
+    if (input.prev_anchor_hash !== null) {
+        assertHex64("prev_anchor_hash", input.prev_anchor_hash);
+    }
+    return {
+        anchor_id: computeAnchorId(input),
+        agent_id_hash: sha256Hex(input.agent_id),
+        memory_id_hash: sha256Hex(input.memory_id),
+        content_hash: input.content_hash,
+        metadata_hash: input.metadata_hash,
+        prev_anchor_hash: input.prev_anchor_hash
+    };
+}
+export function createPendingAnchorResult(submission, reason) {
+    assertValidAnchorSubmission(submission);
+    return {
+        status: "pending",
+        anchor_id: submission.anchor_id,
+        casper_transaction_hash: null,
+        onchain_content_hash: null,
+        reason
+    };
+}
+export function createFailedAnchorResult(submission, reason) {
+    assertValidAnchorSubmission(submission);
+    return {
+        status: "failed",
+        anchor_id: submission.anchor_id,
+        casper_transaction_hash: null,
+        onchain_content_hash: null,
+        reason
+    };
+}
+export function createAnchoredAnchorResult(submission, casperTransactionHash) {
+    assertValidAnchorSubmission(submission);
+    assertHex64("casper_transaction_hash", casperTransactionHash);
+    return {
+        status: "anchored",
+        anchor_id: submission.anchor_id,
+        casper_transaction_hash: casperTransactionHash,
+        onchain_content_hash: submission.content_hash
+    };
+}
+export function createSubmittedAnchorResult(submission, casperTransactionHash) {
+    assertValidAnchorSubmission(submission);
+    assertHex64("casper_transaction_hash", casperTransactionHash);
+    return {
+        status: "pending",
+        anchor_id: submission.anchor_id,
+        casper_transaction_hash: casperTransactionHash,
+        onchain_content_hash: null
+    };
+}
+export function computeAnchorId(input) {
+    return sha256Hex([
+        input.agent_id,
+        input.memory_id,
+        input.content_hash,
+        input.prev_anchor_hash ?? ""
+    ].join(":"));
+}
+export function buildCasperAnchorCommand(config, submission) {
+    assertValidAnchorSubmission(submission);
+    const sessionArgs = [
+        "--session-args-json",
+        JSON.stringify([
+            sessionJsonArg("anchor_id", submission.anchor_id),
+            sessionJsonArg("agent_id_hash", submission.agent_id_hash),
+            sessionJsonArg("memory_id_hash", submission.memory_id_hash),
+            sessionJsonArg("content_hash", submission.content_hash),
+            sessionJsonArg("metadata_hash", submission.metadata_hash),
+            sessionJsonArg("prev_anchor_hash", submission.prev_anchor_hash ?? "")
+        ])
+    ];
+    if (config.anchorSubmissionMode === "deploy-contract-hash") {
+        return wrapCasperCommand(config, [
+            "put-deploy",
+            "--node-address",
+            config.rpcUrl,
+            "--chain-name",
+            config.networkName,
+            "--session-hash",
+            formatContractHash(config.memoryAnchorContractHash),
+            "--session-entry-point",
+            "anchor_memory",
+            "--payment-amount",
+            config.anchorPaymentAmountMotes,
+            "--secret-key",
+            config.accountKeyPath,
+            ...sessionArgs
+        ]);
+    }
+    return wrapCasperCommand(config, [
+        "put-transaction",
+        "package",
+        "--node-address",
+        config.rpcUrl,
+        "--chain-name",
+        config.networkName,
+        "--contract-package-hash",
+        formatContractPackageHash(config.memoryAnchorPackageHash),
+        "--session-entry-point",
+        "anchor_memory",
+        "--gas-price-tolerance",
+        config.gasPriceTolerance,
+        "--pricing-mode",
+        config.pricingMode,
+        "--payment-amount",
+        config.anchorPaymentAmountMotes,
+        "--standard-payment",
+        "true",
+        "--secret-key",
+        config.accountKeyPath,
+        ...sessionArgs
+    ]);
+}
+export function extractCasperTransactionHash(result) {
+    for (const output of [result.stdout, result.stderr]) {
+        const json = parseCasperClientJson(output);
+        const jsonHash = json ? findHashField(json) : null;
+        if (jsonHash) {
+            return jsonHash;
+        }
+        const labelledHash = findLabelledHash(output);
+        if (labelledHash) {
+            return labelledHash;
+        }
+    }
+    return null;
+}
+function assertValidAnchorSubmission(submission) {
+    assertHex64("anchor_id", submission.anchor_id);
+    assertHex64("agent_id_hash", submission.agent_id_hash);
+    assertHex64("memory_id_hash", submission.memory_id_hash);
+    assertHex64("content_hash", submission.content_hash);
+    assertHex64("metadata_hash", submission.metadata_hash);
+    if (submission.prev_anchor_hash !== null) {
+        assertHex64("prev_anchor_hash", submission.prev_anchor_hash);
+    }
+}
+function assertHex64(name, value) {
+    if (!HEX_64_PATTERN.test(value)) {
+        throw new Error(`${name} must be a lowercase 64-character hex string`);
+    }
+}
+function assertCasperHash(name, value) {
+    if (!CASPER_HASH_PATTERN.test(value)) {
+        throw new Error(`${name} must be a Casper hash value with optional hash- prefix`);
+    }
+}
+function assertCasperPackageHash(name, value) {
+    if (!CASPER_PACKAGE_HASH_PATTERN.test(value)) {
+        throw new Error(`${name} must be a Casper package hash value`);
+    }
+}
+function assertUnsignedInteger(name, value) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${name} must be an unsigned integer`);
+    }
+}
+function assertPricingMode(name, value) {
+    if (value !== "classic" && value !== "reserved" && value !== "fixed") {
+        throw new Error(`${name} must be classic, reserved, or fixed`);
+    }
+}
+function assertHttpUrl(name, value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`${name} must be an HTTP(S) URL`);
+    }
+}
+function requireNonEmpty(value, name) {
+    const normalized = normalizeOptional(value);
+    if (!normalized) {
+        throw new Error(`${name} is required`);
+    }
+    return normalized;
+}
+function assertNonEmpty(name, value) {
+    if (value.trim().length === 0) {
+        throw new Error(`${name} is required`);
+    }
+}
+function normalizeOptional(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : null;
+}
+function runCasperCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            shell: false,
+            windowsHide: true
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            resolve({
+                exitCode: code ?? 1,
+                stdout,
+                stderr
+            });
+        });
+    });
+}
+function wrapCasperCommand(config, args) {
+    if (!config.clientWslDistro) {
+        return {
+            command: config.clientBin,
+            args
+        };
+    }
+    return {
+        command: "wsl",
+        args: ["-d", config.clientWslDistro, "--", config.clientBin, ...args]
+    };
+}
+function sessionJsonArg(name, value) {
+    return { name, type: "String", value };
+}
+function formatContractPackageHash(value) {
+    const normalized = value.toLowerCase().replace(/^(hash-|package-)/, "");
+    return `hash-${normalized}`;
+}
+function formatContractHash(value) {
+    const normalized = value.toLowerCase().replace(/^hash-/, "");
+    return `hash-${normalized}`;
+}
+function parseCasperClientJson(output) {
+    const trimmed = output.trim();
+    if (!trimmed) {
+        return null;
+    }
+    for (const candidate of [trimmed, jsonObjectSlice(trimmed)]) {
+        if (!candidate) {
+            continue;
+        }
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function jsonObjectSlice(output) {
+    const firstBrace = output.indexOf("{");
+    const lastBrace = output.lastIndexOf("}");
+    if (firstBrace === -1 || lastBrace === -1 || lastBrace <= firstBrace) {
+        return null;
+    }
+    return output.slice(firstBrace, lastBrace + 1);
+}
+function findHashField(value) {
+    if (typeof value === "string") {
+        return HEX_64_PATTERN.test(value.toLowerCase()) ? value.toLowerCase() : null;
+    }
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const record = value;
+    for (const key of ["transaction_hash", "deploy_hash"]) {
+        const direct = record[key];
+        const hash = extractHashValue(direct);
+        if (hash) {
+            return hash;
+        }
+    }
+    for (const nested of Object.values(record)) {
+        const hash = findHashField(nested);
+        if (hash) {
+            return hash;
+        }
+    }
+    return null;
+}
+function extractHashValue(value) {
+    if (typeof value === "string") {
+        const normalized = value.toLowerCase();
+        return HEX_64_PATTERN.test(normalized) ? normalized : null;
+    }
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    for (const nested of Object.values(value)) {
+        const hash = extractHashValue(nested);
+        if (hash) {
+            return hash;
+        }
+    }
+    return null;
+}
+function findLabelledHash(output) {
+    const match = output.match(/(?:transaction_hash|deploy_hash)[\s"'=:{}A-Za-z0-9]*?([a-f0-9]{64})/i);
+    return match?.[1]?.toLowerCase() ?? null;
+}

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+export type CasperConfig = {
+    networkName: string;
+    caip2ChainId: string;
+    rpcUrl: string | null;
+    accountKeyPath: string | null;
+    memoryAnchorContractHash: string | null;
+    memoryAnchorPackageHash: string | null;
+    submissionEnabled: boolean;
+    clientBin: string;
+    clientWslDistro: string | null;
+    anchorSubmissionMode: "transaction-package" | "deploy-contract-hash";
+    gasPriceTolerance: string;
+    pricingMode: string;
+    anchorPaymentAmountMotes: string;
+};
+export type X402Config = {
+    facilitatorUrl: string;
+    resourceDemoUrl: string;
+    assetPackage: string | null;
+    assetName: string | null;
+    settlementEnabled: boolean;
+    settlementMode: "resource-retry" | "facilitator" | "casper-cli";
+    signerUrl: string | null;
+    signerAuthToken: string | null;
+    signerTimeoutMs: number;
+    paymentHeaderName: string;
+    casperSettlementPaymentAmountMotes: string;
+    casperConfirmationPollIntervalMs: number;
+    casperConfirmationTimeoutMs: number;
+};
+export type StorageConfig = {
+    backend: "file";
+} | {
+    backend: "supabase";
+    supabase: {
+        url: string;
+        key: string;
+        schema: string;
+        tablePrefix: string;
+    };
+};
+export type SigilConfig = {
+    dataDir: string;
+    grimoireMasterKey: Buffer;
+    serverName: string;
+    serverVersion: string;
+    storage: StorageConfig;
+    casper: CasperConfig;
+    x402: X402Config;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): SigilConfig;

package/dist/config.js

@@ -0,0 +1,215 @@
+import { createHash } from "node:crypto";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const CASPER_HASH_PATTERN = /^(hash-)?[a-f0-9]{64}$/i;
+const CASPER_PACKAGE_HASH_PATTERN = /^(hash-|package-)?[a-f0-9]{64}$/i;
+export function loadConfig(env = process.env) {
+    const casper = {
+        networkName: optionalEnv(env.CASPER_NETWORK_NAME) ?? "casper-test",
+        caip2ChainId: optionalEnv(env.CASPER_CAIP2_CHAIN_ID) ?? "casper:casper-test",
+        rpcUrl: optionalEnv(env.CASPER_RPC_URL),
+        accountKeyPath: normalizeCasperAccountKeyPath(optionalEnv(env.CASPER_ACCOUNT_KEY_PATH) ?? "./keys/backend.pem", optionalEnv(env.CASPER_CLIENT_WSL_DISTRO)),
+        memoryAnchorContractHash: optionalEnv(env.MEMORY_ANCHOR_CONTRACT_HASH),
+        memoryAnchorPackageHash: optionalEnv(env.MEMORY_ANCHOR_PACKAGE_HASH),
+        submissionEnabled: parseBoolean(env.CASPER_ENABLE_REAL_SUBMISSION),
+        clientBin: optionalEnv(env.CASPER_CLIENT_BIN) ?? "casper-client",
+        clientWslDistro: optionalEnv(env.CASPER_CLIENT_WSL_DISTRO),
+        anchorSubmissionMode: parseCasperAnchorSubmissionMode(env.CASPER_ANCHOR_SUBMISSION_MODE),
+        gasPriceTolerance: optionalEnv(env.CASPER_GAS_PRICE_TOLERANCE) ?? "10",
+        pricingMode: optionalEnv(env.CASPER_PRICING_MODE) ?? "classic",
+        anchorPaymentAmountMotes: optionalEnv(env.CASPER_ANCHOR_PAYMENT_AMOUNT_MOTES) ?? "3000000000"
+    };
+    validateCasperConfig(casper);
+    const x402 = {
+        facilitatorUrl: optionalEnv(env.X402_FACILITATOR_URL) ?? "http://localhost:4022",
+        resourceDemoUrl: optionalEnv(env.X402_RESOURCE_DEMO_URL) ?? "http://localhost:4021/weather",
+        assetPackage: optionalEnv(env.X402_ASSET_PACKAGE),
+        assetName: optionalEnv(env.X402_ASSET_NAME),
+        settlementEnabled: parseBoolean(env.X402_ENABLE_REAL_SETTLEMENT),
+        settlementMode: parseX402SettlementMode(env.X402_SETTLEMENT_MODE),
+        signerUrl: optionalEnv(env.X402_SIGNER_URL),
+        signerAuthToken: optionalEnv(env.X402_SIGNER_AUTH_TOKEN),
+        signerTimeoutMs: parsePositiveInteger(env.X402_SIGNER_TIMEOUT_MS, "X402_SIGNER_TIMEOUT_MS", 10_000),
+        paymentHeaderName: optionalEnv(env.X402_PAYMENT_HEADER_NAME) ?? "PAYMENT-SIGNATURE",
+        casperSettlementPaymentAmountMotes: optionalEnv(env.X402_CASPER_SETTLEMENT_PAYMENT_AMOUNT_MOTES) ?? "7000000000",
+        casperConfirmationPollIntervalMs: parsePositiveInteger(env.X402_CASPER_CONFIRMATION_POLL_INTERVAL_MS, "X402_CASPER_CONFIRMATION_POLL_INTERVAL_MS", 2_000),
+        casperConfirmationTimeoutMs: parsePositiveInteger(env.X402_CASPER_CONFIRMATION_TIMEOUT_MS, "X402_CASPER_CONFIRMATION_TIMEOUT_MS", 120_000)
+    };
+    validateX402Config(x402);
+    return {
+        dataDir: resolve(optionalEnv(env.SIGIL_DATA_DIR) ?? ".sigil"),
+        grimoireMasterKey: loadMasterKey(env.GRIMOIRE_MASTER_KEY),
+        serverName: optionalEnv(env.SIGIL_MCP_NAME) ?? "mr-mainspring",
+        serverVersion: optionalEnv(env.SIGIL_MCP_VERSION) ?? "0.1.0",
+        storage: loadStorageConfig(env),
+        casper,
+        x402
+    };
+}
+function loadStorageConfig(env) {
+    const backend = optionalEnv(env.SIGIL_STORAGE_BACKEND);
+    const supabaseUrl = optionalEnv(env.PROJECT_URL) ?? optionalEnv(env.SUPABASE_URL);
+    const supabaseKey = optionalEnv(env.SECRET_KEY) ??
+        optionalEnv(env.PUBLISHABLE_KEY) ??
+        optionalEnv(env.SUPABASE_SERVICE_ROLE_KEY) ??
+        optionalEnv(env.SUPABASE_ANON_KEY);
+    if (!backend && !supabaseUrl && !supabaseKey) {
+        return { backend: "file" };
+    }
+    if (backend && backend !== "file" && backend !== "supabase") {
+        throw new Error("SIGIL_STORAGE_BACKEND must be either file or supabase");
+    }
+    if (backend === "file") {
+        return { backend: "file" };
+    }
+    if (!supabaseUrl) {
+        throw new Error("PROJECT_URL is required when Supabase storage is enabled");
+    }
+    if (!supabaseKey) {
+        throw new Error("SECRET_KEY or PUBLISHABLE_KEY is required when Supabase storage is enabled");
+    }
+    assertHttpUrl("PROJECT_URL", supabaseUrl);
+    return {
+        backend: "supabase",
+        supabase: {
+            url: supabaseUrl,
+            key: supabaseKey,
+            schema: optionalEnv(env.SUPABASE_DB_SCHEMA) ?? "public",
+            tablePrefix: optionalEnv(env.SUPABASE_TABLE_PREFIX) ?? "sigil_"
+        }
+    };
+}
+function loadMasterKey(encodedKey) {
+    if (!encodedKey) {
+        return createHash("sha256").update("sigil-local-development-master-key").digest();
+    }
+    const key = Buffer.from(encodedKey, "base64");
+    if (key.byteLength !== 32) {
+        throw new Error("GRIMOIRE_MASTER_KEY must be a base64-encoded 32-byte key");
+    }
+    return key;
+}
+function validateCasperConfig(config) {
+    assertNonEmpty("CASPER_NETWORK_NAME", config.networkName);
+    assertNonEmpty("CASPER_CAIP2_CHAIN_ID", config.caip2ChainId);
+    if (config.memoryAnchorContractHash) {
+        assertCasperHash("MEMORY_ANCHOR_CONTRACT_HASH", config.memoryAnchorContractHash);
+        if (!config.memoryAnchorPackageHash) {
+            throw new Error("MEMORY_ANCHOR_PACKAGE_HASH is required when MEMORY_ANCHOR_CONTRACT_HASH is set");
+        }
+        if (!config.rpcUrl) {
+            throw new Error("CASPER_RPC_URL is required when MEMORY_ANCHOR_CONTRACT_HASH is set");
+        }
+        if (!config.accountKeyPath) {
+            throw new Error("CASPER_ACCOUNT_KEY_PATH is required when MEMORY_ANCHOR_CONTRACT_HASH is set");
+        }
+    }
+    if (config.memoryAnchorPackageHash) {
+        assertCasperPackageHash("MEMORY_ANCHOR_PACKAGE_HASH", config.memoryAnchorPackageHash);
+    }
+    if (config.rpcUrl) {
+        assertHttpUrl("CASPER_RPC_URL", config.rpcUrl);
+    }
+    assertNonEmpty("CASPER_CLIENT_BIN", config.clientBin);
+    if (config.clientWslDistro) {
+        assertNonEmpty("CASPER_CLIENT_WSL_DISTRO", config.clientWslDistro);
+    }
+    assertUnsignedInteger("CASPER_GAS_PRICE_TOLERANCE", config.gasPriceTolerance);
+    assertPricingMode("CASPER_PRICING_MODE", config.pricingMode);
+    assertUnsignedInteger("CASPER_ANCHOR_PAYMENT_AMOUNT_MOTES", config.anchorPaymentAmountMotes);
+}
+function validateX402Config(config) {
+    assertHttpUrl("X402_FACILITATOR_URL", config.facilitatorUrl);
+    assertHttpUrl("X402_RESOURCE_DEMO_URL", config.resourceDemoUrl);
+    if (config.signerUrl) {
+        assertHttpUrl("X402_SIGNER_URL", config.signerUrl);
+    }
+    assertNonEmpty("X402_PAYMENT_HEADER_NAME", config.paymentHeaderName);
+    assertUnsignedInteger("X402_CASPER_SETTLEMENT_PAYMENT_AMOUNT_MOTES", config.casperSettlementPaymentAmountMotes);
+}
+function assertNonEmpty(name, value) {
+    if (value.trim().length === 0) {
+        throw new Error(`${name} is required`);
+    }
+}
+function assertCasperHash(name, value) {
+    if (!CASPER_HASH_PATTERN.test(value)) {
+        throw new Error(`${name} must be a Casper hash value with optional hash- prefix`);
+    }
+}
+function assertCasperPackageHash(name, value) {
+    if (!CASPER_PACKAGE_HASH_PATTERN.test(value)) {
+        throw new Error(`${name} must be a Casper package hash value`);
+    }
+}
+function assertHttpUrl(name, value) {
+    const url = new URL(value);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`${name} must be an HTTP(S) URL`);
+    }
+}
+function assertUnsignedInteger(name, value) {
+    if (!/^\d+$/.test(value)) {
+        throw new Error(`${name} must be an unsigned integer`);
+    }
+}
+function assertPricingMode(name, value) {
+    if (value !== "classic" && value !== "reserved" && value !== "fixed") {
+        throw new Error(`${name} must be classic, reserved, or fixed`);
+    }
+}
+function parseBoolean(value) {
+    const normalized = optionalEnv(value)?.toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes";
+}
+function parseCasperAnchorSubmissionMode(value) {
+    const normalized = optionalEnv(value) ?? "transaction-package";
+    if (normalized === "transaction-package" || normalized === "deploy-contract-hash") {
+        return normalized;
+    }
+    throw new Error("CASPER_ANCHOR_SUBMISSION_MODE must be transaction-package or deploy-contract-hash");
+}
+function parseX402SettlementMode(value) {
+    const normalized = optionalEnv(value) ?? "resource-retry";
+    if (normalized === "resource-retry" ||
+        normalized === "facilitator" ||
+        normalized === "casper-cli") {
+        return normalized;
+    }
+    throw new Error("X402_SETTLEMENT_MODE must be resource-retry, facilitator, or casper-cli");
+}
+function parsePositiveInteger(value, name, defaultValue) {
+    const normalized = optionalEnv(value);
+    if (!normalized) {
+        return defaultValue;
+    }
+    if (!/^[1-9]\d*$/.test(normalized)) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return Number(normalized);
+}
+function normalizeCasperAccountKeyPath(value, clientWslDistro) {
+    if (!clientWslDistro) {
+        return value;
+    }
+    if (value.startsWith("/")) {
+        return value;
+    }
+    const absolutePath = isAbsolute(value) ? value : resolve(repoRoot(), value);
+    return toWslPath(absolutePath);
+}
+function repoRoot() {
+    const backendRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    return dirname(backendRoot);
+}
+function toWslPath(value) {
+    const match = value.match(/^([A-Za-z]):[\\/](.*)$/);
+    if (!match) {
+        return value.replaceAll("\\", "/");
+    }
+    return `/mnt/${match[1].toLowerCase()}/${match[2].replaceAll("\\", "/")}`;
+}
+function optionalEnv(value) {
+    const normalized = value?.trim();
+    return normalized ? normalized : null;
+}

package/dist/env-file.d.ts

@@ -0,0 +1 @@
+export declare function loadLocalEnvFile(env?: NodeJS.ProcessEnv): string | null;