cascrow-signer 0.1.0

package/dist/checks.js

@@ -0,0 +1,236 @@
+/**
+ * Every check the signer makes before a signature exists — pure functions, no
+ * I/O, one arm per property, each named in its refusal.
+ *
+ * WHY THESE AND NOT "RE-ENCODE AND COMPARE". Rebuilding `data` from `call.args`
+ * and comparing proves only that the server agrees with itself: `call.args`
+ * comes from the same server (design Rev. 10, finding 5). So the checks below
+ * compare the transaction against values the signer knows INDEPENDENTLY — its own
+ * address, the pinned chain and contract, its local policy and escrow book, the
+ * chain's own escrow record and clock, and the payee's signature under the
+ * pinned domain. Re-encoding is still done (an envelope whose `data` does not
+ * say what `call` says is refused outright), but it is the first arm, not the
+ * guarantee.
+ *
+ * The role × phase rule is the app's own matrix, byte-copied
+ * (generated/v3-actions.ts) — the signer and `prepare` cannot disagree about
+ * whether the payer may still object.
+ */
+import { ZeroAddress, getAddress, isAddress, verifyTypedData } from "ethers";
+import { refuse } from "./errors.js";
+import { ACCEPTANCE_TYPES, ACTION_FN, PER_ESCROW_ACTIONS, V3_LIMITS, acceptanceDomain, canonicalArgs, encodeCall, escrowIdFor, } from "./calldata.js";
+import { v3ActionBlocker, v3RoleOf } from "./generated/v3-actions.js";
+const lc = (s) => String(s).toLowerCase();
+function fail(code, reasons) {
+    if (reasons.length)
+        refuse(code, `refused before signing: ${reasons.join("; ")}`);
+}
+/**
+ * The envelope of a prepared transaction against what the signer knows: chain and
+ * contract from its own pinned config, the sender from its own key, the function
+ * from the action it was asked to perform, and `data` re-encoded from the ABI.
+ */
+export function checkPreparedEnvelope(p, action, pinned, me) {
+    const x = p;
+    const r = [];
+    if (!x || typeof x !== "object" || !x.call || typeof x.call !== "object" || !Array.isArray(x.call.args)) {
+        refuse("PREPARED_MISMATCH", "refused before signing: the prepared transaction has no call");
+    }
+    if (x.chainId !== pinned.chainId)
+        r.push(`chainId ${String(x.chainId)} is not the pinned ${pinned.chainId}`);
+    if (lc(x.to) !== lc(pinned.address))
+        r.push(`to ${String(x.to)} is not the pinned contract ${pinned.address}`);
+    if (x.action !== action)
+        r.push(`action ${String(x.action)} is not the requested ${action}`);
+    if (x.call.fn !== ACTION_FN[action])
+        r.push(`call.fn ${String(x.call.fn)} is not ${ACTION_FN[action]}`);
+    if (!x.expect || lc(x.expect.from) !== lc(me))
+        r.push(`expect.from ${String(x.expect?.from)} is not this key ${me}`);
+    if (!/^\d+$/.test(String(x.value)))
+        r.push("value is not a decimal wei string");
+    else if (action !== "fund" && BigInt(x.value) !== BigInt(0))
+        r.push(`value ${x.value} must be 0 for ${action}`);
+    fail("PREPARED_MISMATCH", r);
+    let encoded = null;
+    try {
+        encoded = encodeCall(x.call.fn, x.call.args);
+    }
+    catch {
+        r.push("call.args do not encode under the pinned ABI");
+    }
+    if (encoded !== null && encoded !== lc(x.data))
+        r.push("data is not what call.fn(call.args) encodes to");
+    if (PER_ESCROW_ACTIONS.has(action) && lc(x.call.args[0]) !== lc(x.escrowId))
+        r.push("call.args[0] is not the escrowId");
+    if (action === "withdraw" && lc(x.call.args[0]) !== lc(me))
+        r.push("withdraw pays an account that is not this key");
+    if (action === "withdraw" && lc(x.call.args[1]) !== lc(ZeroAddress))
+        r.push("withdraw names a token other than native XRP");
+    fail("PREPARED_MISMATCH", r);
+    return x;
+}
+/** A locally built call and the server's prepared one must be the same transaction. */
+export function checkMatchesLocal(local, p) {
+    const r = [];
+    if (lc(local.to) !== lc(p.to))
+        r.push("prepare names a different contract than the signer built for");
+    if (lc(local.data) !== lc(p.data))
+        r.push("prepare's data differs from the calldata the signer built itself");
+    if (BigInt(p.value) !== local.value)
+        r.push("prepare's value differs from the signer's");
+    fail("PREPARE_DISAGREES", r);
+}
+export function fundTermsFrom(p) {
+    const [ref, salt, t, payeeSig] = canonicalArgs("fund", p.call.args);
+    return {
+        ref,
+        salt,
+        t: {
+            payee: getAddress(t.payee),
+            token: getAddress(t.token),
+            amount: BigInt(t.amount),
+            deadline: BigInt(t.deadline),
+            reviewPeriod: Number(t.reviewPeriod),
+            arbiter: getAddress(t.arbiter),
+            arbitrationPeriod: Number(t.arbitrationPeriod),
+            acceptBy: BigInt(t.acceptBy),
+        },
+        payeeSig,
+    };
+}
+/** Who signed this acceptance, under the PINNED domain (never the server's). Null when it does not recover. */
+export function acceptanceSigner(pinned, escrowId, t, sig) {
+    try {
+        return verifyTypedData(acceptanceDomain(pinned.chainId, pinned.address), ACCEPTANCE_TYPES, { escrowId, ...t }, sig);
+    }
+    catch {
+        return null;
+    }
+}
+/** Seconds a fund needs between signing and `acceptBy` so it can still land. */
+export const ACCEPT_BY_MARGIN_SECONDS = 120;
+/** The local invariants for `fund` (design Rev. 10, "Lokale Invarianten für fund"). Returns whether the payee is a known counterparty. */
+export function checkFund(i) {
+    const { terms: f, policy: pol } = i;
+    const r = [];
+    const me = getAddress(i.me);
+    const id = escrowIdFor(me, f.ref, f.salt);
+    if (lc(id) !== lc(i.prepared.escrowId))
+        r.push("escrowIdFor(this key, ref, salt) is not the prepared escrowId");
+    if (i.slotStatus !== 0)
+        r.push("that escrow slot is already taken on chain");
+    if (f.t.token !== ZeroAddress)
+        r.push("token is not native XRP");
+    if (BigInt(i.prepared.value) !== f.t.amount)
+        r.push("value is not the escrowed amount");
+    if (f.t.amount <= BigInt(0))
+        r.push("amount is zero");
+    if (f.t.payee === ZeroAddress || f.t.payee === me)
+        r.push("payee is empty or this key");
+    const payeeKnown = pol.payees.includes(f.t.payee.toLowerCase());
+    const limitWei = BigInt(payeeKnown ? pol.perEscrowMaxWei : pol.unknownPayeePerEscrowMaxWei);
+    if (f.t.amount > limitWei) {
+        r.push(`amount exceeds the local per-escrow limit${payeeKnown ? "" : " for a payee not in the local counterparty book"}`);
+    }
+    if (i.maxAmountWei !== undefined && i.maxAmountWei !== null && f.t.amount > i.maxAmountWei)
+        r.push("amount exceeds the maximum named for this call");
+    if (i.daySumWei + f.t.amount > BigInt(pol.dailyMaxWei))
+        r.push("amount would exceed the local 24-hour limit");
+    if (f.t.arbiter !== ZeroAddress && !pol.arbiters.includes(f.t.arbiter.toLowerCase()))
+        r.push("the arbiter is not one the local policy accepts");
+    if (f.t.arbiter === ZeroAddress && f.t.arbitrationPeriod !== 0)
+        r.push("arbitrationPeriod without an arbiter");
+    if (f.t.arbiter !== ZeroAddress && (f.t.arbitrationPeriod < V3_LIMITS.MIN_ARBITRATION_SECONDS || f.t.arbitrationPeriod > V3_LIMITS.MAX_ARBITRATION_SECONDS)) {
+        r.push("arbitrationPeriod outside the contract's bounds");
+    }
+    if (f.t.reviewPeriod < pol.minReviewSeconds)
+        r.push("the review period is shorter than the local minimum");
+    if (f.t.reviewPeriod > V3_LIMITS.MAX_REVIEW_SECONDS)
+        r.push("the review period exceeds the contract's maximum");
+    const now = BigInt(i.chainNowSec);
+    if (f.t.deadline <= now)
+        r.push("the deadline has passed on chain");
+    if (f.t.deadline > now + BigInt(V3_LIMITS.MAX_DEADLINE_SECONDS))
+        r.push("the deadline is beyond the contract's maximum duration");
+    if (f.t.acceptBy < now + BigInt(ACCEPT_BY_MARGIN_SECONDS))
+        r.push("the acceptance has expired on chain (or expires within two minutes)");
+    const signer = acceptanceSigner(i.pinned, id, f.t, f.payeeSig);
+    if (!signer || signer !== f.t.payee)
+        r.push("payeeSig is not the payee's signature over these terms under the pinned domain");
+    fail("FUND_CHECK_FAILED", r);
+    return { payeeKnown, limitWei };
+}
+export function chainFacts(e) {
+    return {
+        funded: e.status === 1,
+        payer: e.payer,
+        payee: e.payee,
+        arbiter: e.arbiter === ZeroAddress ? null : e.arbiter,
+        deadline: e.deadline,
+        reviewPeriod: e.reviewPeriod,
+        arbitrationPeriod: e.arbitrationPeriod,
+        claimedAt: e.claimedAt,
+        objected: e.objected,
+        objectedAt: e.objectedAt,
+        claimCount: e.claimCount,
+    };
+}
+/**
+ * Actions the payer may only sign for an escrow in the local book: the two that
+ * move the payer's money TOWARDS the payee or lengthen its lock. `object` is not
+ * one of them: it is the payer's veto with a clock, it moves nothing, and it is
+ * gated on the CHAIN alone (the on-chain payer must be this key) — a deleted or
+ * tampered book must never cost a payer the objection window (post-review H1).
+ * Only these actions read the book at all; every other action reads it, if at
+ * all, only to find an escrow ID, and a broken book is a loud note there.
+ */
+export const BOOK_BOUND_ACTIONS = new Set(["release", "extendDeadline"]);
+/**
+ * A post-funding action against the CHAIN's record of the escrow and the chain's
+ * clock: the app's role × phase matrix, the local book for the payer's money
+ * moves, and the action's own argument.
+ */
+export function checkEscrowAction(action, me, e, chainNowSec, opts) {
+    const facts = chainFacts(e);
+    const role = v3RoleOf(me, facts);
+    const blocker = v3ActionBlocker(action, role, facts, chainNowSec);
+    if (blocker)
+        refuse("PHASE", `the escrow does not allow ${action} for you right now: ${blocker}`);
+    const r = [];
+    // The matrix already names the payer by the chain; say it in this module's words too,
+    // so the objection's only gate is visible where it is enforced.
+    if (action === "object" && lc(e.payer) !== lc(me))
+        r.push("the on-chain payer is not this key");
+    if (BOOK_BOUND_ACTIONS.has(action)) {
+        if (!opts.book)
+            r.push("this escrow is not in the local book — the signer only moves money on escrows it funded itself");
+        else {
+            if (opts.book.role !== "payer")
+                r.push("the local book records this key as payee, not payer");
+            if (lc(e.payer) !== lc(me))
+                r.push("the on-chain payer is not this key");
+            if (lc(e.payee) !== opts.book.payee)
+                r.push("the on-chain payee differs from the payee in the local book");
+        }
+    }
+    if (action === "extendDeadline") {
+        const nd = opts.newDeadline ?? null;
+        if (nd === null)
+            r.push("newDeadline is required");
+        else if (nd <= BigInt(e.deadline))
+            r.push("newDeadline must be after the current deadline");
+        else if (nd > BigInt(chainNowSec + V3_LIMITS.MAX_DEADLINE_SECONDS))
+            r.push("newDeadline is beyond the contract's maximum duration");
+    }
+    if (action === "submitClaim" && !/^0x[0-9a-f]{64}$/.test(lc(opts.proofHash ?? "")))
+        r.push("proofHash must be a 32-byte hex value (the manifestHash of a sealed submission)");
+    if (action === "object" && !/^0x[0-9a-f]{64}$/.test(lc(opts.reasonHash ?? "")))
+        r.push("reasonHash must be a 32-byte hex value");
+    fail("CHECK_FAILED", r);
+}
+export function checkWithdraw(me, credit) {
+    if (!isAddress(me))
+        refuse("CHECK_FAILED", "withdraw needs this key's address");
+    if (credit <= BigInt(0))
+        refuse("PHASE", "there is no credit to withdraw for this key: NothingToWithdraw");
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * cascrow-signer — command line. `cascrow-signer help` lists the commands.
+ *
+ * Output: one JSON object on stdout per command; diagnostics, warnings and
+ * alarms on stderr. Neither ever carries the key, the passphrase, the keystore
+ * or a signed transaction.
+ */
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+import { SignerError } from "./errors.js";
+import { SIGNER_VERSION, configFromEnv, createSigner, initSigner } from "./api.js";
+import { takePassphraseEnv } from "./keystore.js";
+import { signerHome } from "./files.js";
+import { serveStdio } from "./mcp.js";
+function parseArgs(argv) {
+    const out = { _: [], flags: {} };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith("--")) {
+            const [k, inline] = a.slice(2).split("=", 2);
+            const v = inline ?? (argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[++i] : "true");
+            (out.flags[k] ??= []).push(v);
+        }
+        else
+            out._.push(a);
+    }
+    return out;
+}
+const one = (a, k) => a.flags[k]?.[a.flags[k].length - 1];
+function ttyIo() {
+    const isTTY = !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const ask = (q, hidden = false) => new Promise((resolve) => {
+        let muted = false;
+        const output = new Writable({
+            write(chunk, _enc, cb) {
+                if (!muted)
+                    process.stderr.write(chunk);
+                cb();
+            },
+        });
+        const rl = createInterface({ input: process.stdin, output, terminal: true });
+        rl.question(q, (v) => {
+            rl.close();
+            if (hidden)
+                process.stderr.write("\n");
+            resolve(v);
+        });
+        muted = hidden;
+    });
+    return {
+        isTTY,
+        err: (l) => process.stderr.write(`${l}\n`),
+        prompt: isTTY ? ask : undefined,
+        confirm: isTTY ? async (q) => /^y(es)?$/i.test((await ask(`${q} [y/N] `)).trim()) : undefined,
+    };
+}
+const HELP = `cascrow-signer ${SIGNER_VERSION} — your MilestoneEscrowV3 key, on your machine.
+
+Setup
+  init                               create a key and its encrypted keystore (~/.cascrow/signer)
+  policy show | policy set --per-escrow-xrp N --daily-xrp N [--unknown-payee-xrp N]
+                           [--min-review-hours H] [--payee 0x…]… [--arbiter 0x…]…   (terminal only)
+  link                               link this address to your cascrow account (CASCROW_API_KEY)
+  status
+
+As payee                             As payer
+  accept --milestone ID              fund --milestone ID [--max-xrp N]
+  submit-claim --milestone ID        object --escrow ID --reason TEXT
+    --proof-hash 0x… | --file PATH   release --escrow ID
+  return-funds --escrow ID           extend-deadline --escrow ID --new-deadline UNIX
+                                     claims | watch [--interval S] [--exec CMD] [--webhook URL]
+Either party
+  claim --escrow ID   refund --escrow ID   withdraw   speed-up --tx HASH
+  mcp                                run as an MCP server on stdio
+
+Every command takes --network testnet|mainnet (or CASCROW_SIGNER_NETWORK) and --home DIR.
+The passphrase: a terminal prompt, CASCROW_KEYSTORE_PASSPHRASE_FILE (a 0600 file) or
+CASCROW_KEYSTORE_PASSPHRASE — read once, then removed from the environment.`;
+async function main() {
+    // FIRST, for every command: the passphrase variables leave the environment before
+    // anything else runs, so no child process (watch --exec) can inherit them (H3).
+    const envPassphrase = takePassphraseEnv(process.env);
+    const a = parseArgs(process.argv.slice(2));
+    const [cmd, sub] = a._;
+    // The MCP server is never a TTY for the policy, whatever its stdin is.
+    const io = cmd === "mcp" ? { isTTY: false, err: (l) => process.stderr.write(`${l}\n`) } : ttyIo();
+    if (!cmd || cmd === "help" || one(a, "help")) {
+        process.stdout.write(`${HELP}\n`);
+        return;
+    }
+    const home = one(a, "home") ?? signerHome();
+    const print = (v) => {
+        process.stdout.write(`${JSON.stringify(v, (_k, x) => (typeof x === "bigint" ? x.toString() : x), 2)}\n`);
+    };
+    if (cmd === "init") {
+        let pass = envPassphrase();
+        if (!pass && io.isTTY && io.prompt) {
+            pass = await io.prompt("New keystore passphrase (12+ characters): ", true);
+            if ((await io.prompt("Repeat it: ", true)) !== pass)
+                throw new SignerError("PASSPHRASE_MISMATCH", "the passphrases differ");
+        }
+        if (!pass)
+            throw new SignerError("PASSPHRASE_REQUIRED", "run init on a terminal, or set CASCROW_KEYSTORE_PASSPHRASE_FILE");
+        const r = await initSigner(home, pass);
+        print({ ...r, next: "Set your limits on this terminal: cascrow-signer policy set --per-escrow-xrp … --daily-xrp …" });
+        return;
+    }
+    // The passphrase was taken out of the environment above; it is read from that copy
+    // once, when a command first needs the key. The MCP server reads it at start. A
+    // terminal still gets the prompt when neither variable was set.
+    const mcpPassphrase = cmd === "mcp" ? envPassphrase() : undefined;
+    const passphrase = async () => {
+        if (cmd === "mcp")
+            return mcpPassphrase ?? null;
+        const p = envPassphrase();
+        if (p)
+            return p;
+        return io.isTTY && io.prompt ? io.prompt("Keystore passphrase: ", true) : null;
+    };
+    const s = createSigner(configFromEnv(process.env, io, {
+        home,
+        ...(one(a, "network") ? { network: one(a, "network") } : {}),
+        passphrase,
+    }));
+    const ref = { escrowId: one(a, "escrow"), milestoneId: one(a, "milestone") };
+    switch (cmd) {
+        case "status": return print(s.status());
+        case "link": return print(await s.link());
+        case "policy":
+            if (sub === "set") {
+                return print(await s.setPolicy({
+                    perEscrowMaxXrp: one(a, "per-escrow-xrp") ?? "",
+                    dailyMaxXrp: one(a, "daily-xrp") ?? "",
+                    unknownPayeePerEscrowMaxXrp: one(a, "unknown-payee-xrp"),
+                    minReviewHours: one(a, "min-review-hours") ? Number(one(a, "min-review-hours")) : undefined,
+                    payees: a.flags.payee,
+                    arbiters: a.flags.arbiter,
+                }));
+            }
+            return print(await s.policy());
+        case "accept": return print(await s.accept({ milestoneId: ref.milestoneId ?? "", minAmountXrp: one(a, "min-xrp") }));
+        case "fund": return print(await s.fund({ milestoneId: ref.milestoneId ?? "", maxAmountXrp: one(a, "max-xrp") }));
+        case "submit-claim": return print(await s.submitClaim({ ...ref, proofHash: one(a, "proof-hash"), evidence: { files: a.flags.file, texts: a.flags.text } }));
+        case "object": return print(await s.object({ ...ref, reason: one(a, "reason") }));
+        case "release": return print(await s.release(ref));
+        case "extend-deadline": return print(await s.extendDeadline({ ...ref, newDeadline: one(a, "new-deadline") }));
+        case "claim": return print(await s.claim(ref));
+        case "refund": return print(await s.refund(ref));
+        case "return-funds": return print(await s.returnFunds(ref));
+        case "withdraw": return print(await s.withdraw());
+        case "claims": return print(await s.onchainClaims());
+        case "watch": return s.watch({ intervalSec: Number(one(a, "interval") ?? 60), exec: one(a, "exec"), webhook: one(a, "webhook"), once: one(a, "once") === "true" });
+        case "speed-up": return print(await s.speedUp(one(a, "tx") ?? ""));
+        case "mcp": return serveStdio(s, SIGNER_VERSION);
+        default:
+            throw new SignerError("UNKNOWN_COMMAND", `unknown command ${cmd} — cascrow-signer help`);
+    }
+}
+main().catch((e) => {
+    process.stderr.write(`${e instanceof Error ? e.message : "error"}\n`);
+    process.exitCode = 1;
+});

package/dist/context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What every action needs: the pinned network and its RPC, the cascrow API
+ * client, the signer's home, the journal, how to reach the person (Io), and how
+ * to get the passphrase. Built once per CLI run or MCP server.
+ */
+import { Rpc } from "./network.js";
+import type { SignerNetwork, SignerNetworkName, TestnetOverride } from "./network.js";
+import { Remote } from "./remote.js";
+import { Journal } from "./journal.js";
+import type { UnlockedKey } from "./keystore.js";
+export type Io = {
+    /** True only for a human at a terminal. The MCP server is never a TTY. */
+    isTTY: boolean;
+    /** Diagnostics and alarms — stderr in the CLI and the MCP server. */
+    err(line: string): void;
+    /** Ask a yes/no question (TTY only). */
+    confirm?(question: string): Promise<boolean>;
+    /** Read a line, optionally without echo (TTY only). */
+    prompt?(question: string, hidden?: boolean): Promise<string>;
+};
+export type SignerConfig = {
+    home: string;
+    network: SignerNetworkName;
+    override?: TestnetOverride | null;
+    apiBaseUrl: string;
+    apiKey: string;
+    io: Io;
+    /** Where the passphrase comes from. Default: CASCROW_KEYSTORE_PASSPHRASE_FILE / _PASSPHRASE, then a TTY prompt. */
+    passphrase?: () => Promise<string | null>;
+    /** Keystore scrypt cost for `init` (tests use a small one). */
+    scryptN?: number;
+};
+export declare class SignerContext {
+    readonly cfg: SignerConfig;
+    readonly home: string;
+    readonly net: SignerNetwork;
+    readonly rpc: Rpc;
+    readonly remote: Remote;
+    readonly journal: Journal;
+    readonly io: Io;
+    private cachedPassphrase;
+    constructor(cfg: SignerConfig);
+    /** The keystore address, read without the passphrase. */
+    address(): string;
+    passphrase(): Promise<string | null>;
+    unlock(): Promise<UnlockedKey>;
+}

package/dist/context.js

@@ -0,0 +1,50 @@
+/**
+ * What every action needs: the pinned network and its RPC, the cascrow API
+ * client, the signer's home, the journal, how to reach the person (Io), and how
+ * to get the passphrase. Built once per CLI run or MCP server.
+ */
+import { Rpc, resolveNetwork } from "./network.js";
+import { Remote } from "./remote.js";
+import { Journal } from "./journal.js";
+import { ensureHome } from "./files.js";
+import { keystoreAddress, passphraseFromEnv, unlock } from "./keystore.js";
+export class SignerContext {
+    cfg;
+    home;
+    net;
+    rpc;
+    remote;
+    journal;
+    io;
+    cachedPassphrase;
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.home = ensureHome(cfg.home);
+        this.io = cfg.io;
+        this.net = resolveNetwork(cfg.network, cfg.override ?? null, (l) => cfg.io.err(l));
+        this.rpc = new Rpc(this.net.rpcUrl);
+        this.remote = new Remote({ baseUrl: cfg.apiBaseUrl, apiKey: cfg.apiKey });
+        this.journal = new Journal(this.home);
+    }
+    /** The keystore address, read without the passphrase. */
+    address() {
+        return keystoreAddress(this.home);
+    }
+    async passphrase() {
+        if (this.cachedPassphrase !== undefined)
+            return this.cachedPassphrase;
+        let p = null;
+        if (this.cfg.passphrase)
+            p = await this.cfg.passphrase();
+        else {
+            p = passphraseFromEnv();
+            if (!p && this.io.isTTY && this.io.prompt)
+                p = await this.io.prompt("Keystore passphrase: ", true);
+        }
+        this.cachedPassphrase = p;
+        return p;
+    }
+    async unlock() {
+        return unlock(this.home, await this.passphrase());
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One error type for every refusal the signer makes. `code` is stable (tools and
+ * scripts branch on it); `message` says what to do. A message never carries key
+ * material, a passphrase, a keystore or a signed transaction — the canary test
+ * (signer-canary.test.ts) reads every one of them.
+ */
+export declare class SignerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function refuse(code: string, message: string): never;

package/dist/errors.js

@@ -0,0 +1,17 @@
+/**
+ * One error type for every refusal the signer makes. `code` is stable (tools and
+ * scripts branch on it); `message` says what to do. A message never carries key
+ * material, a passphrase, a keystore or a signed transaction — the canary test
+ * (signer-canary.test.ts) reads every one of them.
+ */
+export class SignerError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${message} [${code}]`);
+        this.name = "SignerError";
+        this.code = code;
+    }
+}
+export function refuse(code, message) {
+    throw new SignerError(code, message);
+}

package/dist/files.d.ts

@@ -0,0 +1,13 @@
+export declare function signerHome(env?: Record<string, string | undefined>): string;
+/** Create (0700) or check the home directory. */
+export declare function ensureHome(dir: string): string;
+export declare function assertPrivateFile(p: string): void;
+/** Write a new 0600 file; refuse if it already exists (never overwrite a keystore). */
+export declare function writeNewPrivateFile(p: string, data: string): void;
+/** Replace a 0600 file atomically (temp file + rename). */
+export declare function replacePrivateFile(p: string, data: string): void;
+export declare function readPrivateFile(p: string): string;
+/** Deterministic JSON: object keys sorted, so a MAC does not depend on key order. */
+export declare function stableJson(v: unknown): string;
+export declare function macOf(key: Buffer, body: unknown): string;
+export declare function macMatches(key: Buffer, body: unknown, mac: unknown): boolean;

package/dist/files.js

@@ -0,0 +1,78 @@
+/**
+ * The signer's home directory and the rules for the files in it.
+ *
+ * `~/.cascrow/signer/` (or CASCROW_SIGNER_HOME) is 0700 and every file in it
+ * 0600. A file or directory that group or others can read is REFUSED, not
+ * repaired: a keystore that has been world-readable may already have been
+ * copied, and silently chmod-ing it would hide that. Windows has no POSIX mode
+ * bits, so the check is skipped there and the README says so.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { refuse } from "./errors.js";
+const POSIX = process.platform !== "win32";
+export function signerHome(env = process.env) {
+    const override = env.CASCROW_SIGNER_HOME?.trim();
+    return override ? path.resolve(override) : path.join(os.homedir(), ".cascrow", "signer");
+}
+function assertNotOpen(p, what) {
+    if (!POSIX)
+        return;
+    const st = fs.statSync(p);
+    if ((st.mode & 0o077) !== 0) {
+        refuse("KEYSTORE_PERMISSIONS", `${what} ${p} is readable or writable by other users (mode ${(st.mode & 0o777).toString(8)}). ` +
+            `The signer refuses to use it. If the key may have been copied, create a new one; otherwise run: chmod ${what === "directory" ? "700" : "600"} ${p}`);
+    }
+    if (typeof process.getuid === "function" && st.uid !== process.getuid()) {
+        refuse("KEYSTORE_PERMISSIONS", `${what} ${p} belongs to another user. The signer refuses to use it.`);
+    }
+}
+/** Create (0700) or check the home directory. */
+export function ensureHome(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    assertNotOpen(dir, "directory");
+    return dir;
+}
+export function assertPrivateFile(p) {
+    assertNotOpen(p, "file");
+}
+/** Write a new 0600 file; refuse if it already exists (never overwrite a keystore). */
+export function writeNewPrivateFile(p, data) {
+    const fd = fs.openSync(p, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+    try {
+        fs.writeSync(fd, data);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** Replace a 0600 file atomically (temp file + rename). */
+export function replacePrivateFile(p, data) {
+    const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+    writeNewPrivateFile(tmp, data);
+    fs.renameSync(tmp, p);
+}
+export function readPrivateFile(p) {
+    assertPrivateFile(p);
+    return fs.readFileSync(p, "utf8");
+}
+/** Deterministic JSON: object keys sorted, so a MAC does not depend on key order. */
+export function stableJson(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return `[${v.map(stableJson).join(",")}]`;
+    const o = v;
+    return `{${Object.keys(o).filter((k) => o[k] !== undefined).sort().map((k) => `${JSON.stringify(k)}:${stableJson(o[k])}`).join(",")}}`;
+}
+export function macOf(key, body) {
+    return createHmac("sha256", key).update(stableJson(body)).digest("hex");
+}
+export function macMatches(key, body, mac) {
+    if (typeof mac !== "string" || !/^[0-9a-f]{64}$/.test(mac))
+        return false;
+    return timingSafeEqual(Buffer.from(macOf(key, body), "hex"), Buffer.from(mac, "hex"));
+}

package/dist/generated/milestone-escrow-v3.deployments.json

@@ -0,0 +1,15 @@
+{
+  "1440000": {
+    "network": "mainnet",
+    "address": null,
+    "deployBlock": null,
+    "runtimeCodeHash": null
+  },
+  "1449000": {
+    "network": "testnet",
+    "address": "0xa1f10a285d9de4cb1ff613829e3a26222db65f45",
+    "deployBlock": 8816108,
+    "runtimeCodeHash": "0xdc62dd32622f11da841429a87e9c24cb84ba2151e783712457457027651fc974"
+  },
+  "$comment": "Where MilestoneEscrowV3 is deployed, per EVM chain ID. Owner-maintained: filled in by the deployer in the same commit as the deploy, never at runtime. cascrow-signer carries a byte copy (scripts/sync-signer-artifacts.mjs; signer-artifact-parity.test.ts) and REFUSES a network whose entry lacks address, deployBlock or runtimeCodeHash. runtimeCodeHash = keccak256 of eth_getCode at address; the signer compares it before every send. Empty until the contract is deployed."
+}