cascrow-signer 0.1.0

package/dist/link.js

@@ -0,0 +1,65 @@
+/**
+ * Link this key's address to the cascrow account — the signed challenge
+ * `POST /api/user/wallet` requires.
+ *
+ * A signature over arbitrary text a server hands you can be anything (a
+ * permit, a login elsewhere). So the challenge is signed only if it is EXACTLY
+ * the known sentence with the nonce that the challenge token itself carries —
+ * checked here, before `signMessage` is reached. And an account that already has
+ * a different wallet linked is never re-pointed without a person confirming it
+ * on a terminal: on V3 the linked wallet is where an acceptance must come from,
+ * and a silent re-point breaks every open offer (design Rev. 10, step 5).
+ */
+import { getAddress, isAddress } from "ethers";
+import { refuse } from "./errors.js";
+export const CHALLENGE_PREFIX = "Sign this message to prove wallet ownership for Cascrow: ";
+/** The nonce the challenge token carries, read from its payload (the server verifies the token; we only read it). */
+export function challengeNonce(token) {
+    const parts = String(token).split(".");
+    if (parts.length !== 3)
+        refuse("CHALLENGE_MISMATCH", "the challenge token is not a JWT");
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8"));
+    }
+    catch {
+        refuse("CHALLENGE_MISMATCH", "the challenge token's payload does not parse");
+    }
+    if (payload.purpose !== "wallet-ownership")
+        refuse("CHALLENGE_MISMATCH", "the challenge token is not a wallet-ownership challenge");
+    if (typeof payload.nonce !== "string" || !/^[0-9a-f]{32}$/.test(payload.nonce))
+        refuse("CHALLENGE_MISMATCH", "the challenge token carries no valid nonce");
+    return payload.nonce;
+}
+/** Refuses anything but the exact challenge sentence for this token's nonce. */
+export function checkChallenge(message, token) {
+    if (typeof message !== "string" || typeof token !== "string")
+        refuse("CHALLENGE_MISMATCH", "the challenge is incomplete");
+    const nonce = challengeNonce(token);
+    if (message !== `${CHALLENGE_PREFIX}${nonce}`)
+        refuse("CHALLENGE_MISMATCH", "the text to sign is not the wallet-ownership challenge — nothing was signed");
+    return message;
+}
+export async function link(ctx) {
+    const key = await ctx.unlock();
+    const me = getAddress(key.address);
+    const current = (await ctx.remote.me()).walletAddress;
+    const known = typeof current === "string" || current === null;
+    if (typeof current === "string" && isAddress(current) && getAddress(current) === me) {
+        return { linked: true, walletAddress: me, changed: false, message: "This key's address is already the account's wallet." };
+    }
+    if (!known || current !== null) {
+        const what = known ? `replaces the linked wallet ${String(current)}` : "may replace a wallet already linked to this account (cascrow did not say which)";
+        if (!ctx.io.isTTY || !ctx.io.confirm) {
+            refuse("REPOINT_NEEDS_TTY", `linking ${me} ${what}; that is only done after confirming on a terminal: cascrow-signer link`);
+        }
+        if (!(await ctx.io.confirm(`Linking ${me} ${what}. Open offers and acceptances naming the old wallet will fail. Continue?`))) {
+            refuse("CANCELLED", "not linked");
+        }
+    }
+    const ch = await ctx.remote.walletChallenge();
+    const message = checkChallenge(ch.message, ch.token);
+    const signature = await key.signMessage(message);
+    await ctx.remote.linkWallet(me, signature, ch.token);
+    return { linked: true, walletAddress: me, changed: true };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,10 @@
+import type { Signer } from "./api.js";
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+/** Dispatch one tool call. Exported for tests: every result an agent sees comes from here. */
+export declare function handleToolCall(s: Signer, name: string, args: Record<string, unknown>): Promise<unknown>;
+export declare function answer(s: Signer, msg: {
+    id?: unknown;
+    method?: string;
+    params?: Record<string, unknown>;
+}, version: string): Promise<unknown | null>;
+export declare function serveStdio(s: Signer, version: string): void;

package/dist/mcp.js

@@ -0,0 +1,81 @@
+/**
+ * The signer as an MCP server over stdio — a small JSON-RPC 2.0 loop, written
+ * out here instead of pulling in the MCP SDK, so this package keeps exactly one
+ * runtime dependency (design Rev. 10, finding 10).
+ *
+ * Protocol surface: `initialize`, `notifications/initialized`, `ping`,
+ * `tools/list`, `tools/call`. Messages are newline-delimited JSON on stdin and
+ * stdout; diagnostics and alarms go to stderr. The process is never a TTY for
+ * the policy (policy.ts): a model cannot raise its own limits through a tool.
+ */
+import { createInterface } from "node:readline";
+import { SIGNER_TOOLS } from "./tools.js";
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+const str = (v) => (typeof v === "string" && v.length ? v : undefined);
+const strList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === "string") : undefined);
+/** Dispatch one tool call. Exported for tests: every result an agent sees comes from here. */
+export async function handleToolCall(s, name, args) {
+    const ref = { escrowId: str(args.escrowId), milestoneId: str(args.milestoneId) };
+    switch (name) {
+        case "cascrow_signer_status": return s.status();
+        case "cascrow_signer_link": return s.link();
+        case "cascrow_signer_accept": return s.accept({ milestoneId: String(args.milestoneId ?? ""), minAmountXrp: str(args.minAmountXrp) });
+        case "cascrow_signer_fund": return s.fund({ milestoneId: String(args.milestoneId ?? ""), maxAmountXrp: str(args.maxAmountXrp) });
+        case "cascrow_signer_submit_claim": return s.submitClaim({ ...ref, proofHash: str(args.proofHash), evidence: { files: strList(args.files), texts: strList(args.texts) } });
+        case "cascrow_signer_object": return s.object({ ...ref, reason: str(args.reason) });
+        case "cascrow_signer_release": return s.release(ref);
+        case "cascrow_signer_extend_deadline": return s.extendDeadline({ ...ref, newDeadline: str(args.newDeadline) });
+        case "cascrow_signer_claim": return s.claim(ref);
+        case "cascrow_signer_refund": return s.refund(ref);
+        case "cascrow_signer_return_funds": return s.returnFunds(ref);
+        case "cascrow_signer_withdraw": return s.withdraw();
+        case "cascrow_signer_onchain_claims": return s.onchainClaims();
+        case "cascrow_signer_speed_up": return s.speedUp(String(args.txHash ?? ""));
+        default: throw new Error(`Unknown tool: ${name}`);
+    }
+}
+const json = (v) => JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x), 2);
+export async function answer(s, msg, version) {
+    const id = msg.id ?? null;
+    const reply = (result) => ({ jsonrpc: "2.0", id, result });
+    switch (msg.method) {
+        case "initialize":
+            return reply({ protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: { name: "cascrow-signer", version } });
+        case "notifications/initialized":
+            return null;
+        case "ping":
+            return reply({});
+        case "tools/list":
+            return reply({ tools: SIGNER_TOOLS });
+        case "tools/call": {
+            const name = String(msg.params?.name ?? "");
+            const args = (msg.params?.arguments ?? {});
+            try {
+                return reply({ content: [{ type: "text", text: json(await handleToolCall(s, name, args)) }] });
+            }
+            catch (e) {
+                return reply({ content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : "unknown error"}` }], isError: true });
+            }
+        }
+        default:
+            return id === null ? null : { jsonrpc: "2.0", id, error: { code: -32601, message: `Method not found: ${String(msg.method)}` } };
+    }
+}
+export function serveStdio(s, version) {
+    const rl = createInterface({ input: process.stdin });
+    rl.on("line", async (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }) + "\n");
+            return;
+        }
+        const out = await answer(s, msg, version);
+        if (out)
+            process.stdout.write(JSON.stringify(out) + "\n");
+    });
+}

package/dist/network.d.ts

@@ -0,0 +1,53 @@
+type DeploymentRow = {
+    network: string;
+    address: string | null;
+    deployBlock: number | null;
+    runtimeCodeHash: string | null;
+};
+export declare const DEPLOYMENTS: Record<string, DeploymentRow | string>;
+export type SignerNetworkName = "testnet" | "mainnet";
+/** Chain ID and public RPC per network — the same values as EVM_NETWORKS in the app. */
+export declare const PUBLIC_NETWORKS: Readonly<Record<SignerNetworkName, {
+    chainId: number;
+    rpcUrl: string;
+}>>;
+export type SignerNetwork = {
+    name: SignerNetworkName;
+    chainId: number;
+    rpcUrl: string;
+    address: string;
+    deployBlock: number;
+    runtimeCodeHash: string;
+    overridden: boolean;
+};
+/** Testnet only: a deployment the table does not (yet) name. Every field that is set replaces the pinned one. */
+export type TestnetOverride = {
+    rpcUrl?: string;
+    address?: string;
+    deployBlock?: number;
+    runtimeCodeHash?: string;
+};
+export declare function resolveNetwork(name: string, override?: TestnetOverride | null, warn?: (line: string) => void): SignerNetwork;
+export declare class RpcError extends Error {
+    readonly rpcCode: number | null;
+    readonly data: unknown;
+    constructor(message: string, rpcCode: number | null, data?: unknown);
+}
+/**
+ * A JSON-RPC client bound to ONE URL. There is no way to send through it to
+ * anywhere else — the send path of the whole package goes through `call`, and
+ * the URL is the network's.
+ */
+export declare class Rpc {
+    private readonly timeoutMs;
+    readonly url: string;
+    private id;
+    constructor(url: string, timeoutMs?: number);
+    call<T = unknown>(method: string, params?: unknown[]): Promise<T>;
+}
+/**
+ * The RPC is on this chain, and the contract at the pinned address is the pinned
+ * code. Run before every send and before every chain read a decision rests on.
+ */
+export declare function verifyEndpoint(rpc: Rpc, net: SignerNetwork): Promise<void>;
+export {};

package/dist/network.js

@@ -0,0 +1,122 @@
+/**
+ * Which chain, which RPC, which contract — pinned in the package, never taken
+ * from cascrow's API.
+ *
+ * The deployment table is a byte copy of the app's
+ * src/lib/abi/milestone-escrow-v3.deployments.json (scripts/sync-signer-artifacts.mjs;
+ * signer-artifact-parity.test.ts). A network without an address, a deploy block
+ * and a runtime code hash is REFUSED: a `fund()` with value sent to an address
+ * with no contract behind it is a plain transfer, and the XRP is gone.
+ *
+ * The RPC is the PUBLIC endpoint of the network (the same constants as the app's
+ * src/lib/evm-network.ts; parity-tested). Every transaction goes there and only
+ * there — never to cascrow, which neither sends nor relays (rule I9). An override
+ * exists for testnet only, and it is announced on stderr every time it is used.
+ */
+import { createRequire } from "node:module";
+import { getAddress, isAddress, keccak256 } from "ethers";
+import { refuse } from "./errors.js";
+const require = createRequire(import.meta.url);
+export const DEPLOYMENTS = require("./generated/milestone-escrow-v3.deployments.json");
+/** Chain ID and public RPC per network — the same values as EVM_NETWORKS in the app. */
+export const PUBLIC_NETWORKS = Object.freeze({
+    testnet: Object.freeze({ chainId: 1449000, rpcUrl: "https://rpc.testnet.xrplevm.org" }),
+    mainnet: Object.freeze({ chainId: 1440000, rpcUrl: "https://rpc.xrplevm.org" }),
+});
+const HASH = /^0x[0-9a-f]{64}$/;
+export function resolveNetwork(name, override, warn = () => { }) {
+    if (name !== "testnet" && name !== "mainnet")
+        refuse("NETWORK_UNKNOWN", `network must be "testnet" or "mainnet" (got ${JSON.stringify(name)})`);
+    const pub = PUBLIC_NETWORKS[name];
+    const row = DEPLOYMENTS[String(pub.chainId)];
+    const pinned = row && typeof row === "object" ? row : null;
+    const hasOverride = !!override && Object.values(override).some((v) => v !== undefined && v !== "");
+    if (hasOverride && name !== "testnet") {
+        refuse("OVERRIDE_MAINNET", "a deployment override is accepted on testnet only — on mainnet the pinned table is the only source");
+    }
+    const address = (hasOverride && override.address) || pinned?.address || null;
+    const deployBlock = hasOverride && override.deployBlock !== undefined ? override.deployBlock : pinned?.deployBlock ?? null;
+    const codeHash = ((hasOverride && override.runtimeCodeHash) || pinned?.runtimeCodeHash || "").toLowerCase();
+    const rpcUrl = (hasOverride && override.rpcUrl) || pub.rpcUrl;
+    if (!address || !isAddress(address) || deployBlock === null || !Number.isSafeInteger(deployBlock) || deployBlock < 0 || !HASH.test(codeHash)) {
+        refuse("NETWORK_NOT_DEPLOYED", `MilestoneEscrowV3 has no pinned deployment on ${name} (chain ${pub.chainId}) in this version of cascrow-signer. ` +
+            "The signer refuses to send to an address it cannot verify. Upgrade cascrow-signer once the contract is deployed.");
+    }
+    if (hasOverride) {
+        warn(`WARNING: using a TESTNET deployment override (contract ${getAddress(address)}, rpc ${rpcUrl}). ` +
+            "It is not the pinned deployment — only use it against a contract you deployed or verified yourself.");
+    }
+    return { name, chainId: pub.chainId, rpcUrl, address: getAddress(address), deployBlock, runtimeCodeHash: codeHash, overridden: hasOverride };
+}
+export class RpcError extends Error {
+    rpcCode;
+    data;
+    constructor(message, rpcCode, data) {
+        super(message);
+        this.name = "RpcError";
+        this.rpcCode = rpcCode;
+        this.data = data;
+    }
+}
+/**
+ * A JSON-RPC client bound to ONE URL. There is no way to send through it to
+ * anywhere else — the send path of the whole package goes through `call`, and
+ * the URL is the network's.
+ */
+export class Rpc {
+    timeoutMs;
+    url;
+    id = 0;
+    constructor(url, timeoutMs = 20_000) {
+        this.timeoutMs = timeoutMs;
+        this.url = url;
+    }
+    async call(method, params = []) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let text;
+        try {
+            const res = await fetch(this.url, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ jsonrpc: "2.0", id: ++this.id, method, params }),
+                signal: controller.signal,
+            });
+            text = await res.text();
+            if (!res.ok)
+                throw new RpcError(`RPC answered HTTP ${res.status} to ${method}`, null);
+        }
+        catch (e) {
+            if (e instanceof RpcError)
+                throw e;
+            throw new RpcError(`RPC ${method} failed: ${e instanceof Error && e.name === "AbortError" ? "timeout" : "network error"}`, null);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new RpcError(`RPC ${method} answered with non-JSON`, null);
+        }
+        if (body.error)
+            throw new RpcError(`RPC ${method}: ${String(body.error.message ?? "error").slice(0, 200)}`, body.error.code ?? null, body.error.data);
+        return body.result;
+    }
+}
+/**
+ * The RPC is on this chain, and the contract at the pinned address is the pinned
+ * code. Run before every send and before every chain read a decision rests on.
+ */
+export async function verifyEndpoint(rpc, net) {
+    const chainId = await rpc.call("eth_chainId");
+    if (typeof chainId !== "string" || !/^0x[0-9a-fA-F]+$/.test(chainId) || BigInt(chainId) !== BigInt(net.chainId)) {
+        refuse("CHAIN_MISMATCH", `the RPC answered chain ID ${String(chainId)}, expected ${net.chainId} (${net.name}) — nothing was signed`);
+    }
+    const code = await rpc.call("eth_getCode", [net.address, "latest"]);
+    if (typeof code !== "string" || code.length <= 2 || keccak256(code).toLowerCase() !== net.runtimeCodeHash) {
+        refuse("CODE_HASH_MISMATCH", `the code at ${net.address} is not the pinned MilestoneEscrowV3 runtime code — nothing was signed`);
+    }
+}

package/dist/policy.d.ts

@@ -0,0 +1,31 @@
+export declare const POLICY_FILE = "policy.json";
+/** The floor below which no local minimum review period may be set: 24 h. */
+export declare const MIN_REVIEW_FLOOR_SECONDS: number;
+export type Policy = {
+    v: 1;
+    /** The keystore address this policy belongs to (lowercase). */
+    address: string;
+    perEscrowMaxWei: string;
+    unknownPayeePerEscrowMaxWei: string;
+    dailyMaxWei: string;
+    minReviewSeconds: number;
+    /** Payees confirmed on a TTY (lowercase). */
+    payees: string[];
+    /** Arbiters the owner accepts (lowercase). Empty = only escrows without an arbiter. */
+    arbiters: string[];
+};
+export type PolicyInput = {
+    perEscrowMaxXrp: string;
+    unknownPayeePerEscrowMaxXrp?: string;
+    dailyMaxXrp: string;
+    minReviewHours?: number;
+    payees?: string[];
+    arbiters?: string[];
+};
+export declare function buildPolicy(address: string, input: PolicyInput): Policy;
+/** The policy, or a refusal: missing, tampered, or bound to a different key. */
+export declare function loadPolicy(home: string, macKey: Buffer, address: string): Policy;
+/** Write the policy. Only from a terminal: an agent driving the MCP tools must not be able to raise its own limits. */
+export declare function savePolicy(home: string, macKey: Buffer, policy: Policy, io: {
+    isTTY: boolean;
+}): void;

package/dist/policy.js

@@ -0,0 +1,92 @@
+/**
+ * The payer's local limits, and the counterparty/arbiter allowlists.
+ *
+ * Limits are in XRP and stored in WEI — never in dollars: the chain moves XRP,
+ * and a limit in a currency the signer cannot observe is a limit on a number the
+ * server supplies. The file carries an HMAC under a key derived from the
+ * keystore's private key (keystore.ts `macKey`), so a policy edited by hand, or
+ * by a process that can write the directory but not unlock the key, is REFUSED
+ * rather than obeyed. Changing it takes `cascrow-signer policy set` on a TTY.
+ *
+ * WHAT THIS DOES NOT PROTECT AGAINST, stated plainly (SECURITY.md): a process
+ * that can read the passphrase can unlock the key, recompute the MAC and write
+ * any policy it likes. The policy stops a confused or prompt-injected agent that
+ * drives the MCP tools; it does not stop one that owns the machine.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAddress, isAddress, parseEther } from "ethers";
+import { refuse } from "./errors.js";
+import { ensureHome, macMatches, macOf, readPrivateFile, replacePrivateFile } from "./files.js";
+import { V3_LIMITS } from "./calldata.js";
+export const POLICY_FILE = "policy.json";
+/** The floor below which no local minimum review period may be set: 24 h. */
+export const MIN_REVIEW_FLOOR_SECONDS = 24 * 3600;
+function xrp(label, v) {
+    if (!/^\d+(\.\d{1,18})?$/.test(v.trim()))
+        refuse("POLICY_INVALID", `${label} must be a decimal XRP amount`);
+    return parseEther(v.trim());
+}
+function addrList(label, list) {
+    const out = new Set();
+    for (const a of list ?? []) {
+        if (!isAddress(a))
+            refuse("POLICY_INVALID", `${label}: ${a} is not an address`);
+        out.add(getAddress(a).toLowerCase());
+    }
+    return [...out].sort();
+}
+export function buildPolicy(address, input) {
+    const per = xrp("perEscrowMaxXrp", input.perEscrowMaxXrp);
+    const unknown = input.unknownPayeePerEscrowMaxXrp !== undefined ? xrp("unknownPayeePerEscrowMaxXrp", input.unknownPayeePerEscrowMaxXrp) : per / BigInt(10);
+    const daily = xrp("dailyMaxXrp", input.dailyMaxXrp);
+    if (unknown > per)
+        refuse("POLICY_INVALID", "the limit for an unknown payee cannot exceed the per-escrow limit");
+    if (per > daily)
+        refuse("POLICY_INVALID", "the per-escrow limit cannot exceed the daily limit");
+    const minReviewSeconds = Math.round((input.minReviewHours ?? 72) * 3600);
+    if (!(minReviewSeconds >= MIN_REVIEW_FLOOR_SECONDS))
+        refuse("POLICY_INVALID", "the minimum review period cannot be below 24 hours");
+    if (minReviewSeconds > V3_LIMITS.MAX_REVIEW_SECONDS)
+        refuse("POLICY_INVALID", "the minimum review period exceeds the contract's maximum");
+    return {
+        v: 1,
+        address: getAddress(address).toLowerCase(),
+        perEscrowMaxWei: per.toString(),
+        unknownPayeePerEscrowMaxWei: unknown.toString(),
+        dailyMaxWei: daily.toString(),
+        minReviewSeconds,
+        payees: addrList("payees", input.payees),
+        arbiters: addrList("arbiters", input.arbiters),
+    };
+}
+function file(home) {
+    return path.join(home, POLICY_FILE);
+}
+/** The policy, or a refusal: missing, tampered, or bound to a different key. */
+export function loadPolicy(home, macKey, address) {
+    ensureHome(home);
+    const f = file(home);
+    if (!fs.existsSync(f))
+        refuse("POLICY_MISSING", "no local policy — set limits first on a terminal: cascrow-signer policy set");
+    let parsed;
+    try {
+        parsed = JSON.parse(readPrivateFile(f));
+    }
+    catch {
+        refuse("POLICY_TAMPERED", "the local policy file is not valid JSON — the signer refuses to guess limits");
+    }
+    if (!parsed.policy || !macMatches(macKey, parsed.policy, parsed.mac)) {
+        refuse("POLICY_TAMPERED", "the local policy file was changed outside `cascrow-signer policy set` — the signer refuses to use it");
+    }
+    if (parsed.policy.address !== address.toLowerCase())
+        refuse("POLICY_TAMPERED", "the local policy belongs to a different key");
+    return parsed.policy;
+}
+/** Write the policy. Only from a terminal: an agent driving the MCP tools must not be able to raise its own limits. */
+export function savePolicy(home, macKey, policy, io) {
+    if (!io.isTTY)
+        refuse("POLICY_TTY_REQUIRED", "the policy can only be changed on an interactive terminal: cascrow-signer policy set");
+    ensureHome(home);
+    replacePrivateFile(file(home), JSON.stringify({ policy, mac: macOf(macKey, policy) }, null, 2));
+}

package/dist/remote.d.ts

@@ -0,0 +1,31 @@
+export type RemoteConfig = {
+    baseUrl: string;
+    apiKey: string;
+    timeoutMs?: number;
+};
+export declare class RemoteError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly body: Record<string, unknown>;
+    constructor(message: string, status: number, code: string | null, body: Record<string, unknown>);
+}
+export declare class Remote {
+    private readonly cfg;
+    constructor(cfg: RemoteConfig);
+    get configured(): boolean;
+    private call;
+    prepare(q: {
+        milestoneId: string;
+        action: string;
+        proofHash?: string;
+        reasonHash?: string;
+        newDeadline?: string;
+    }): Promise<Record<string, unknown>>;
+    acceptance(milestoneId: string): Promise<Record<string, unknown>>;
+    submitAcceptance(offerId: string, signature: string): Promise<Record<string, unknown>>;
+    walletChallenge(): Promise<Record<string, unknown>>;
+    linkWallet(walletAddress: string, signature: string, token: string): Promise<Record<string, unknown>>;
+    me(): Promise<Record<string, unknown>>;
+    /** A transaction HASH as a hint to re-read the chain. Never a signed transaction. */
+    reportTx(milestoneId: string, txHash: string): Promise<Record<string, unknown>>;
+}

package/dist/remote.js

@@ -0,0 +1,104 @@
+/**
+ * The signer's calls to cascrow — the complete list, in one place, so what
+ * leaves this machine for cascrow can be read in one screen:
+ *
+ *   GET  /api/escrow/v3/prepare        a prepared transaction (a cross-check; fund needs it)
+ *   GET  /api/escrow/v3/acceptance     the payer's frozen offer, for the payee to check and sign
+ *   POST /api/escrow/v3/acceptance     { offerId, signature } — the payee's acceptance signature
+ *   GET  /api/user/wallet/challenge    the wallet-link challenge
+ *   POST /api/user/wallet              { walletAddress, signature, token } — the link signature
+ *   GET  /api/agent/me                 which wallet the account has linked now
+ *   POST /api/escrow/v3/sync           { milestoneId, txHash } — a HASH, best effort, never a transaction
+ *
+ * Two signatures ever reach cascrow: the wallet-link signature and the payee's
+ * acceptance signature. Never a transaction, signed or not; never a key,
+ * keystore or passphrase. signer-canary.test.ts records every request and holds
+ * that.
+ */
+import { refuse } from "./errors.js";
+export class RemoteError extends Error {
+    status;
+    code;
+    body;
+    constructor(message, status, code, body) {
+        super(message);
+        this.name = "RemoteError";
+        this.status = status;
+        this.code = code;
+        this.body = body;
+    }
+}
+export class Remote {
+    cfg;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get configured() {
+        return !!this.cfg.apiKey;
+    }
+    async call(method, path, body) {
+        if (!this.cfg.apiKey)
+            refuse("API_KEY_REQUIRED", "CASCROW_API_KEY is not set — this step needs your cascrow account");
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.cfg.timeoutMs ?? 30_000);
+        let status = 0;
+        let text = "";
+        try {
+            const res = await fetch(`${this.cfg.baseUrl.replace(/\/+$/, "")}${path}`, {
+                method,
+                headers: { Authorization: `Bearer ${this.cfg.apiKey}`, ...(body !== undefined ? { "Content-Type": "application/json" } : {}) },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: controller.signal,
+            });
+            status = res.status;
+            text = await res.text();
+        }
+        catch (e) {
+            throw new RemoteError(`cascrow did not answer ${path} (${e instanceof Error && e.name === "AbortError" ? "timeout" : "network error"})`, 0, "API_UNREACHABLE", {});
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new RemoteError(`cascrow answered HTTP ${status} with non-JSON`, status, "UPSTREAM_NON_JSON", {});
+        }
+        if (status < 200 || status >= 300) {
+            const code = typeof data.code === "string" ? data.code : null;
+            const msg = typeof data.error === "string" ? data.error : `HTTP ${status}`;
+            throw new RemoteError(`${msg}${code ? ` [${code}]` : ""}`, status, code, data);
+        }
+        return data;
+    }
+    prepare(q) {
+        const p = new URLSearchParams();
+        for (const [k, v] of Object.entries(q))
+            if (v !== undefined)
+                p.set(k, v);
+        return this.call("GET", `/api/escrow/v3/prepare?${p.toString()}`);
+    }
+    acceptance(milestoneId) {
+        return this.call("GET", `/api/escrow/v3/acceptance?milestoneId=${encodeURIComponent(milestoneId)}`);
+    }
+    submitAcceptance(offerId, signature) {
+        return this.call("POST", "/api/escrow/v3/acceptance", { offerId, signature });
+    }
+    walletChallenge() {
+        return this.call("GET", "/api/user/wallet/challenge");
+    }
+    linkWallet(walletAddress, signature, token) {
+        return this.call("POST", "/api/user/wallet", { walletAddress, signature, token });
+    }
+    me() {
+        return this.call("GET", "/api/agent/me");
+    }
+    /** A transaction HASH as a hint to re-read the chain. Never a signed transaction. */
+    reportTx(milestoneId, txHash) {
+        if (!/^0x[0-9a-fA-F]{64}$/.test(txHash))
+            refuse("NOT_A_HASH", "only a 32-byte transaction hash is ever reported");
+        return this.call("POST", "/api/escrow/v3/sync", { milestoneId, txHash });
+    }
+}

package/dist/tools.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The MCP tools of the LOCAL signer. Every name carries the `cascrow_signer_`
+ * namespace, and none of them exists on cascrow's hosted MCP server or in the
+ * cascrow-mcp package: `LOCAL_ONLY_TOOLS` ∩ hosted tools = ∅
+ * (signer-tool-parity.test.ts). A tool that signs must never be answerable by a
+ * server that holds no key — a same-named hosted tool would make "which server
+ * answered?" decide whether money moved.
+ *
+ * No input names a key, secret, passphrase, mnemonic or seed: the passphrase
+ * comes from the environment of the process (CASCROW_KEYSTORE_PASSPHRASE_FILE),
+ * never from a model.
+ */
+export type ToolDef = {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+};
+export declare const SIGNER_TOOLS: readonly ToolDef[];
+/** The tools only this package offers — disjoint from the hosted cascrow MCP tools. */
+export declare const LOCAL_ONLY_TOOLS: readonly string[];