cascrow-signer 0.1.0

package/dist/generated/v3-actions.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Which MilestoneEscrowV3 call a party may make right now — ONE matrix, read by
+ * `prepare` (server) and by the V3 panel (browser), design Rev. 10.
+ *
+ * WHY ONE MODULE. "Role × state → allowed call" written twice is the dominant
+ * defect of this codebase by construction: the button would offer what prepare
+ * refuses, or prepare would build what the contract reverts. The rules below are
+ * the contract's own `require`s (MilestoneEscrowV3.sol `release`, `object`,
+ * `extendDeadline`, `submitClaim`, `returnFunds`, `claim`, `refund`), evaluated
+ * over CHAIN facts (a `getEscrow` read), never over the milestone's app status —
+ * the payer's objection window must not depend on how fresh cascrow's index is.
+ *
+ * `fund` is not here: before funding there is no escrow to read, and whether a
+ * payer may fund is the acceptance's question (terms, acceptBy, gates).
+ * `withdraw` is account-level (`credit(account, token)`), not per escrow.
+ * `resolve` belongs to the arbiter, who calls the contract directly; cascrow
+ * offers no path for it. Pure, no V3 root, no signer: browser- and I9-safe.
+ */
+export declare const V3_ESCROW_ACTIONS: readonly ["submitClaim", "claim", "release", "object", "refund", "extendDeadline", "returnFunds"];
+export type V3EscrowAction = (typeof V3_ESCROW_ACTIONS)[number];
+export type V3Role = "payer" | "payee" | "other";
+/** The chain facts the matrix needs — the shape of a `getEscrow` read, times in unix seconds. */
+export type V3ChainFacts = {
+    funded: boolean;
+    payer: string;
+    payee: string;
+    arbiter: string | null;
+    deadline: number;
+    reviewPeriod: number;
+    arbitrationPeriod: number;
+    claimedAt: number;
+    objected: boolean;
+    objectedAt: number;
+    claimCount: number;
+};
+export declare const V3_MAX_CLAIMS = 3;
+export declare function v3RoleOf(address: string | null | undefined, f: Pick<V3ChainFacts, "payer" | "payee">): V3Role;
+/** A claim is live: made and not objected (the contract's `_live`). */
+export declare function v3ClaimLive(f: Pick<V3ChainFacts, "claimedAt" | "objected">): boolean;
+/**
+ * Why `action` by `role` would revert at `nowSec`, or null if the contract accepts
+ * it. The reason strings are the contract's custom error names, so a client can
+ * map one vocabulary. `nowSec` is CHAIN time (latest block timestamp) — a local
+ * clock ahead of the chain would offer an objection the contract already refuses.
+ */
+export declare function v3ActionBlocker(action: V3EscrowAction, role: V3Role, f: V3ChainFacts, nowSec: number): string | null;
+export declare function allowedV3Actions(role: V3Role, f: V3ChainFacts, nowSec: number): V3EscrowAction[];
+/** When the payer's objection window closes (unix seconds), or null without a live claim. */
+export declare function v3ObjectionDeadline(f: Pick<V3ChainFacts, "claimedAt" | "objected" | "reviewPeriod">): number | null;

package/dist/generated/v3-actions.js

@@ -0,0 +1,102 @@
+/**
+ * Which MilestoneEscrowV3 call a party may make right now — ONE matrix, read by
+ * `prepare` (server) and by the V3 panel (browser), design Rev. 10.
+ *
+ * WHY ONE MODULE. "Role × state → allowed call" written twice is the dominant
+ * defect of this codebase by construction: the button would offer what prepare
+ * refuses, or prepare would build what the contract reverts. The rules below are
+ * the contract's own `require`s (MilestoneEscrowV3.sol `release`, `object`,
+ * `extendDeadline`, `submitClaim`, `returnFunds`, `claim`, `refund`), evaluated
+ * over CHAIN facts (a `getEscrow` read), never over the milestone's app status —
+ * the payer's objection window must not depend on how fresh cascrow's index is.
+ *
+ * `fund` is not here: before funding there is no escrow to read, and whether a
+ * payer may fund is the acceptance's question (terms, acceptBy, gates).
+ * `withdraw` is account-level (`credit(account, token)`), not per escrow.
+ * `resolve` belongs to the arbiter, who calls the contract directly; cascrow
+ * offers no path for it. Pure, no V3 root, no signer: browser- and I9-safe.
+ */
+export const V3_ESCROW_ACTIONS = [
+    "submitClaim",
+    "claim",
+    "release",
+    "object",
+    "refund",
+    "extendDeadline",
+    "returnFunds",
+];
+export const V3_MAX_CLAIMS = 3;
+export function v3RoleOf(address, f) {
+    const a = address?.toLowerCase();
+    if (!a)
+        return "other";
+    if (a === f.payer.toLowerCase())
+        return "payer";
+    if (a === f.payee.toLowerCase())
+        return "payee";
+    return "other";
+}
+/** A claim is live: made and not objected (the contract's `_live`). */
+export function v3ClaimLive(f) {
+    return f.claimedAt !== 0 && !f.objected;
+}
+/**
+ * Why `action` by `role` would revert at `nowSec`, or null if the contract accepts
+ * it. The reason strings are the contract's custom error names, so a client can
+ * map one vocabulary. `nowSec` is CHAIN time (latest block timestamp) — a local
+ * clock ahead of the chain would offer an objection the contract already refuses.
+ */
+export function v3ActionBlocker(action, role, f, nowSec) {
+    if (!f.funded)
+        return "NotFunded";
+    const live = v3ClaimLive(f);
+    const disputed = f.objected && f.arbiter !== null;
+    switch (action) {
+        case "release":
+            return role === "payer" ? null : "NotPayer";
+        case "extendDeadline":
+            return role === "payer" ? null : "NotPayer";
+        case "returnFunds":
+            return role === "payee" ? null : "NotPayee";
+        case "object":
+            if (role !== "payer")
+                return "NotPayer";
+            if (!live)
+                return "NoLiveClaim";
+            return nowSec >= f.claimedAt + f.reviewPeriod ? "TooLate" : null;
+        case "submitClaim":
+            if (role !== "payee")
+                return "NotPayee";
+            if (nowSec > f.deadline)
+                return "TooLate";
+            if (live)
+                return "ClaimLive";
+            if (disputed)
+                return "Disputed";
+            return f.claimCount >= V3_MAX_CLAIMS ? "ClaimLimitReached" : null;
+        case "claim":
+            // permissionless on chain; cascrow offers it to the parties only
+            if (role === "other")
+                return "NotParty";
+            if (!live)
+                return "NoLiveClaim";
+            return nowSec < f.claimedAt + f.reviewPeriod ? "TooEarly" : null;
+        case "refund":
+            if (role === "other")
+                return "NotParty";
+            if (nowSec <= f.deadline)
+                return "TooEarly";
+            if (live)
+                return "ClaimLive";
+            if (disputed && nowSec <= f.objectedAt + f.arbitrationPeriod)
+                return "TooEarly";
+            return null;
+    }
+}
+export function allowedV3Actions(role, f, nowSec) {
+    return V3_ESCROW_ACTIONS.filter((a) => v3ActionBlocker(a, role, f, nowSec) === null);
+}
+/** When the payer's objection window closes (unix seconds), or null without a live claim. */
+export function v3ObjectionDeadline(f) {
+    return v3ClaimLive(f) ? f.claimedAt + f.reviewPeriod : null;
+}

package/dist/generated/v3-proof-manifest.d.ts

@@ -0,0 +1,19 @@
+export type ManifestEvidence = {
+    kind: "file";
+    sha256: string;
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "github";
+    commitSha: string;
+    diffSha256: string;
+};
+/** Accepts "0x…" or bare hex in either case; returns lowercase 0x-bytes32 or throws. */
+export declare function normaliseBytes32(h: string): string;
+export declare function contentHashFor(e: ManifestEvidence): string;
+export declare function milestoneIdHash(milestoneId: string): string;
+/** Content hashes sorted and checked; throws on an empty set or a duplicate. */
+export declare function sortedContentHashes(hashes: readonly string[]): string[];
+export declare function manifestHash(milestoneId: string, contentHashes: readonly string[]): string;
+export declare function manifestHashForEvidence(milestoneId: string, evidence: readonly ManifestEvidence[]): string;

package/dist/generated/v3-proof-manifest.js

@@ -0,0 +1,79 @@
+/**
+ * The proofHash a MilestoneEscrowV3 payee puts on chain with `submitClaim`, and
+ * the one encoding every party recomputes it with (design Rev. 10, B2).
+ *
+ * WHY ONE MODULE. The server seals a V3Submission and stores this hash; the
+ * local signer (`cascrow-signer`) recomputes it from the files before it signs
+ * `submitClaim`; the browser recomputes it before it sends the transaction; a
+ * third party checking a claim recomputes it from the published evidence. Four
+ * implementations that disagree by one byte would make an honest claim match
+ * nothing — and the resolver treats "matches nothing" as `noVerdict`, which ends
+ * as the builder's failure. The vectors in `v3-proof-manifest.test.ts` are the
+ * contract the copies are tested against.
+ *
+ *   manifestHash = keccak256(abi.encode(bytes32 keccak256(utf8(milestoneId)),
+ *                                       bytes32[] sortedContentHashes))
+ *
+ * Content hash per evidence type (`contentHashFor`), each a lowercase 0x-bytes32:
+ *   file     sha256 of the bytes (Proof.fileHash)
+ *   text     sha256 of the UTF-8 evidence text (mcp/submit, agent-execution)
+ *   github   sha256(utf8(commitSha + ":" + diffSha256)) — never the URL, which
+ *            names a PR that can change after hashing
+ *
+ * Sorting is bytewise over the lowercase hex, duplicates are refused (one file
+ * twice is one piece of evidence, and counting it twice would change the hash of
+ * the same submission). Pure, no V3 root, no signer: safe on either side of the
+ * I9 import graph and in the browser.
+ */
+import { AbiCoder, keccak256, sha256, toUtf8Bytes } from "ethers";
+const BYTES32 = /^0x[0-9a-f]{64}$/;
+const HEX40 = /^[0-9a-f]{40}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+/** Accepts "0x…" or bare hex in either case; returns lowercase 0x-bytes32 or throws. */
+export function normaliseBytes32(h) {
+    const s = h.toLowerCase().startsWith("0x") ? h.toLowerCase() : `0x${h.toLowerCase()}`;
+    if (!BYTES32.test(s))
+        throw new Error(`not a 32-byte hex value: ${h.slice(0, 80)}`);
+    return s;
+}
+export function contentHashFor(e) {
+    switch (e.kind) {
+        case "file":
+            return normaliseBytes32(e.sha256);
+        case "text":
+            return sha256(toUtf8Bytes(e.text)).toLowerCase();
+        case "github": {
+            const commit = e.commitSha.toLowerCase();
+            const diff = e.diffSha256.toLowerCase().replace(/^0x/, "");
+            if (!HEX40.test(commit) && !HEX64.test(commit))
+                throw new Error("commitSha must be a 40- or 64-hex git object id");
+            if (!HEX64.test(diff))
+                throw new Error("diffSha256 must be 64 hex characters");
+            return sha256(toUtf8Bytes(`${commit}:${diff}`)).toLowerCase();
+        }
+    }
+}
+export function milestoneIdHash(milestoneId) {
+    if (!milestoneId)
+        throw new Error("milestoneId is required");
+    return keccak256(toUtf8Bytes(milestoneId)).toLowerCase();
+}
+/** Content hashes sorted and checked; throws on an empty set or a duplicate. */
+export function sortedContentHashes(hashes) {
+    if (hashes.length === 0)
+        throw new Error("a manifest needs at least one piece of evidence");
+    const out = hashes.map(normaliseBytes32).sort();
+    for (let i = 1; i < out.length; i++) {
+        if (out[i] === out[i - 1])
+            throw new Error(`duplicate evidence in manifest: ${out[i]}`);
+    }
+    return out;
+}
+export function manifestHash(milestoneId, contentHashes) {
+    const sorted = sortedContentHashes(contentHashes);
+    const encoded = AbiCoder.defaultAbiCoder().encode(["bytes32", "bytes32[]"], [milestoneIdHash(milestoneId), sorted]);
+    return keccak256(encoded).toLowerCase();
+}
+export function manifestHashForEvidence(milestoneId, evidence) {
+    return manifestHash(milestoneId, evidence.map(contentHashFor));
+}

package/dist/journal.d.ts

@@ -0,0 +1,41 @@
+export declare const JOURNAL_FILE = "journal.jsonl";
+export declare const LOCK_FILE = "journal.lock";
+export declare const DAY_SECONDS: number;
+export type Reservation = {
+    id: string;
+    action: string;
+    escrowId: string | null;
+    amountWei: bigint;
+    at: number;
+    released: boolean;
+    signed: {
+        hash: string;
+        nonce: number;
+        tx: Record<string, unknown>;
+    } | null;
+    sentHashes: string[];
+    unknown: boolean;
+};
+/** Run `fn` holding both locks. Every reservation, signature and send happens inside one of these. */
+export declare function withLock<T>(home: string, fn: () => Promise<T>, timeoutMs?: number): Promise<T>;
+export declare class Journal {
+    readonly home: string;
+    readonly file: string;
+    constructor(home: string);
+    exists(): boolean;
+    /** Create the journal (init, or after a deletion was reconciled against the chain). */
+    create(recreated?: boolean): void;
+    private append;
+    /** All reservations, folded. Throws JOURNAL_UNREADABLE on a corrupt line — a limit is never computed over a guess. */
+    read(): Reservation[];
+    reserve(action: string, escrowId: string | null, amountWei: bigint, nowSec: number): string;
+    signed(id: string, hash: string, nonce: number, tx: Record<string, unknown>): void;
+    sent(id: string, hash: string): void;
+    unknown(id: string, hash: string, reason: string): void;
+    release(id: string, reason: string): void;
+    /** Reservations that still count toward the rolling 24 h window. */
+    daySum(nowSec: number): {
+        sumWei: bigint;
+        escrowIds: Set<string>;
+    };
+}

package/dist/journal.js

@@ -0,0 +1,186 @@
+/**
+ * What this signer has committed to spend, and the lock every send happens under.
+ *
+ * ORDER, for every transaction: take the lock → reserve (the amount counts from
+ * here) → sign → send → record. A reservation is released only when it provably
+ * spent nothing: it failed before a signature existed, or its nonce was consumed
+ * by a different transaction. A transaction whose send answer was lost counts
+ * until its nonce is used — an unknown outcome is not a free one.
+ *
+ * TWO LOCKS. An in-process mutex (two tool calls of one MCP server) and an
+ * O_EXCL lockfile (two processes: the MCP server and a terminal). Without both,
+ * two parallel funds each read "0 spent today" and each pass the daily limit.
+ *
+ * THE DAY SUM is the journal's reservations in the last 24 h PLUS every
+ * `Funded(payer = me)` event in the same window that the journal does not know.
+ * A deleted journal therefore does not reset the limit: the chain still has the
+ * fundings. If the journal is gone AND the chain cannot be read, `fund` is
+ * refused — the limit is not guessed.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { refuse } from "./errors.js";
+import { ensureHome } from "./files.js";
+export const JOURNAL_FILE = "journal.jsonl";
+export const LOCK_FILE = "journal.lock";
+export const DAY_SECONDS = 24 * 3600;
+const inProcess = new Map();
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+async function acquireFileLock(home, timeoutMs) {
+    const lock = path.join(home, LOCK_FILE);
+    const started = Date.now();
+    for (;;) {
+        try {
+            const fd = fs.openSync(lock, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+            fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
+            fs.closeSync(fd);
+            return () => {
+                try {
+                    fs.unlinkSync(lock);
+                }
+                catch {
+                    /* already gone */
+                }
+            };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+        // Held. A lock whose owner is dead is stale; anything else is waited for.
+        try {
+            const held = JSON.parse(fs.readFileSync(lock, "utf8"));
+            if (typeof held.pid === "number" && !pidAlive(held.pid)) {
+                fs.unlinkSync(lock);
+                continue;
+            }
+        }
+        catch {
+            /* being written right now — wait */
+        }
+        if (Date.now() - started > timeoutMs) {
+            refuse("JOURNAL_LOCKED", `another cascrow-signer process holds ${lock}; nothing was signed. If no signer is running, delete that file.`);
+        }
+        await sleep(50);
+    }
+}
+/** Run `fn` holding both locks. Every reservation, signature and send happens inside one of these. */
+export async function withLock(home, fn, timeoutMs = 30_000) {
+    ensureHome(home);
+    const prev = inProcess.get(home) ?? Promise.resolve();
+    let release;
+    const mine = new Promise((r) => (release = r));
+    const chain = prev.then(() => mine);
+    inProcess.set(home, chain);
+    await prev.catch(() => undefined);
+    try {
+        const unlockFile = await acquireFileLock(home, timeoutMs);
+        try {
+            return await fn();
+        }
+        finally {
+            unlockFile();
+        }
+    }
+    finally {
+        release();
+        if (inProcess.get(home) === chain)
+            inProcess.delete(home);
+    }
+}
+export class Journal {
+    home;
+    file;
+    constructor(home) {
+        this.home = home;
+        this.file = path.join(home, JOURNAL_FILE);
+    }
+    exists() {
+        return fs.existsSync(this.file);
+    }
+    /** Create the journal (init, or after a deletion was reconciled against the chain). */
+    create(recreated = false) {
+        if (this.exists())
+            return;
+        const fd = fs.openSync(this.file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL, 0o600);
+        fs.writeSync(fd, JSON.stringify({ t: "header", v: 1, at: Math.floor(Date.now() / 1000), ...(recreated ? { recreated: true } : {}) }) + "\n");
+        fs.closeSync(fd);
+    }
+    append(e) {
+        fs.appendFileSync(this.file, JSON.stringify(e) + "\n", { mode: 0o600 });
+    }
+    /** All reservations, folded. Throws JOURNAL_UNREADABLE on a corrupt line — a limit is never computed over a guess. */
+    read() {
+        if (!this.exists())
+            return [];
+        const out = new Map();
+        const lines = fs.readFileSync(this.file, "utf8").split("\n").filter((l) => l.trim());
+        for (const [i, line] of lines.entries()) {
+            let e;
+            try {
+                e = JSON.parse(line);
+            }
+            catch {
+                refuse("JOURNAL_UNREADABLE", `the spending journal ${this.file} is corrupt at line ${i + 1}; funding is refused until it is repaired`);
+            }
+            if (e.t === "header")
+                continue;
+            if (e.t === "reserve") {
+                out.set(e.id, { id: e.id, action: e.action, escrowId: e.escrowId, amountWei: BigInt(e.amountWei), at: e.at, released: false, signed: null, sentHashes: [], unknown: false });
+                continue;
+            }
+            const r = out.get(e.id);
+            if (!r)
+                continue;
+            if (e.t === "signed")
+                r.signed = { hash: e.hash, nonce: e.nonce, tx: e.tx };
+            else if (e.t === "sent")
+                r.sentHashes.push(e.hash);
+            else if (e.t === "release")
+                r.released = true;
+            else if (e.t === "unknown")
+                r.unknown = true;
+        }
+        return [...out.values()];
+    }
+    reserve(action, escrowId, amountWei, nowSec) {
+        const id = randomUUID();
+        this.append({ t: "reserve", id, action, escrowId, amountWei: amountWei.toString(), at: nowSec });
+        return id;
+    }
+    signed(id, hash, nonce, tx) {
+        this.append({ t: "signed", id, hash, nonce, tx });
+    }
+    sent(id, hash) {
+        this.append({ t: "sent", id, hash });
+    }
+    unknown(id, hash, reason) {
+        this.append({ t: "unknown", id, hash, reason: reason.slice(0, 200) });
+    }
+    release(id, reason) {
+        this.append({ t: "release", id, reason: reason.slice(0, 200) });
+    }
+    /** Reservations that still count toward the rolling 24 h window. */
+    daySum(nowSec) {
+        let sum = BigInt(0);
+        const ids = new Set();
+        for (const r of this.read()) {
+            if (r.action !== "fund" || r.released || r.at <= nowSec - DAY_SECONDS)
+                continue;
+            sum += r.amountWei;
+            if (r.escrowId)
+                ids.add(r.escrowId.toLowerCase());
+        }
+        return { sumWei: sum, escrowIds: ids };
+    }
+}

package/dist/keystore.d.ts

@@ -0,0 +1,30 @@
+import type { TransactionLike, TypedDataDomain, TypedDataField } from "ethers";
+export declare const KEYSTORE_FILE = "keystore.json";
+export type PassphraseEnv = Record<string, string | undefined>;
+/** Read the passphrase from the environment (file first), then remove it from the environment. */
+export declare function passphraseFromEnv(env?: PassphraseEnv): string | null;
+/**
+ * Take both passphrase variables OUT of the environment now and read them later,
+ * once. The CLI calls this before it parses its command (post-review H3): every
+ * command, including `watch`, which needs no passphrase and so never read — and
+ * never deleted — the variables, while its `--exec` child inherited them.
+ */
+export declare function takePassphraseEnv(env?: PassphraseEnv): () => string | null;
+export type UnlockedKey = {
+    readonly address: string;
+    signTransaction(tx: TransactionLike): Promise<string>;
+    signTypedData(domain: TypedDataDomain, types: Record<string, TypedDataField[]>, value: Record<string, unknown>): Promise<string>;
+    signMessage(message: string): Promise<string>;
+    /** HMAC key for policy and book files, derived from the private key; never the key itself. */
+    readonly macKey: Buffer;
+};
+export declare function keystorePath(home: string): string;
+/** Generate a new key locally and store it encrypted. Refuses to overwrite an existing keystore. */
+export declare function createKeystore(home: string, passphrase: string, opts?: {
+    scryptN?: number;
+}): Promise<{
+    address: string;
+}>;
+/** The address stored in the keystore, read without the passphrase. */
+export declare function keystoreAddress(home: string): string;
+export declare function unlock(home: string, passphrase: string | null): Promise<UnlockedKey>;

package/dist/keystore.js

@@ -0,0 +1,119 @@
+/**
+ * The ONLY module that builds a `Wallet`. The key is generated here, encrypted
+ * here (ethers' scrypt keystore, `Wallet.encrypt`), and used here — it is never
+ * returned, logged, printed or sent. What leaves this module is an address, a
+ * signature, a signed transaction bound for the public RPC (network.ts), and a
+ * MAC key DERIVED from the private key for the policy file.
+ *
+ * Passphrase sources, in order: an explicit value (the CLI's TTY prompt passes
+ * it here), CASCROW_KEYSTORE_PASSPHRASE_FILE (must be 0600), then
+ * CASCROW_KEYSTORE_PASSPHRASE. Both variables are DELETED from process.env once
+ * read — and the CLI takes them out at start for every command
+ * (`takePassphraseEnv`), so a child process (`watch --exec`) never inherits them.
+ *
+ * No OS keychain on purpose: it needs a native dependency, and this package has
+ * exactly one runtime dependency so its supply chain can be read in an afternoon.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createHmac } from "node:crypto";
+import { Transaction, Wallet, encryptKeystoreJson, getBytes } from "ethers";
+import { refuse } from "./errors.js";
+import { assertPrivateFile, ensureHome, readPrivateFile, writeNewPrivateFile } from "./files.js";
+export const KEYSTORE_FILE = "keystore.json";
+/** Read the passphrase from the environment (file first), then remove it from the environment. */
+export function passphraseFromEnv(env = process.env) {
+    const file = env.CASCROW_KEYSTORE_PASSPHRASE_FILE?.trim();
+    const direct = env.CASCROW_KEYSTORE_PASSPHRASE;
+    delete env.CASCROW_KEYSTORE_PASSPHRASE_FILE;
+    delete env.CASCROW_KEYSTORE_PASSPHRASE;
+    if (file) {
+        assertPrivateFile(file);
+        const v = fs.readFileSync(file, "utf8").replace(/\r?\n$/, "");
+        if (!v)
+            refuse("PASSPHRASE_REQUIRED", `the passphrase file ${file} is empty`);
+        return v;
+    }
+    return direct && direct.length > 0 ? direct : null;
+}
+/**
+ * Take both passphrase variables OUT of the environment now and read them later,
+ * once. The CLI calls this before it parses its command (post-review H3): every
+ * command, including `watch`, which needs no passphrase and so never read — and
+ * never deleted — the variables, while its `--exec` child inherited them.
+ */
+export function takePassphraseEnv(env = process.env) {
+    const snapshot = {
+        CASCROW_KEYSTORE_PASSPHRASE_FILE: env.CASCROW_KEYSTORE_PASSPHRASE_FILE,
+        CASCROW_KEYSTORE_PASSPHRASE: env.CASCROW_KEYSTORE_PASSPHRASE,
+    };
+    delete env.CASCROW_KEYSTORE_PASSPHRASE_FILE;
+    delete env.CASCROW_KEYSTORE_PASSPHRASE;
+    let read = false;
+    let value = null;
+    return () => {
+        if (!read) {
+            value = passphraseFromEnv(snapshot);
+            read = true;
+        }
+        return value;
+    };
+}
+function wrap(w) {
+    const macKey = createHmac("sha256", Buffer.from(getBytes(w.privateKey))).update("cascrow-signer/local-files-mac/v1").digest();
+    return Object.freeze({
+        address: w.address,
+        signTransaction: (tx) => w.signTransaction(Transaction.from(tx)),
+        signTypedData: (d, t, v) => w.signTypedData(d, t, v),
+        signMessage: (m) => w.signMessage(m),
+        macKey,
+    });
+}
+export function keystorePath(home) {
+    return path.join(home, KEYSTORE_FILE);
+}
+/** Generate a new key locally and store it encrypted. Refuses to overwrite an existing keystore. */
+export async function createKeystore(home, passphrase, opts = {}) {
+    if (!passphrase || passphrase.length < 12)
+        refuse("PASSPHRASE_WEAK", "the passphrase must be at least 12 characters");
+    ensureHome(home);
+    const file = keystorePath(home);
+    if (fs.existsSync(file))
+        refuse("KEYSTORE_EXISTS", `a keystore already exists at ${file}; the signer never overwrites one`);
+    const w = Wallet.createRandom();
+    const json = opts.scryptN
+        ? await encryptKeystoreJson({ address: w.address, privateKey: w.privateKey }, passphrase, { scrypt: { N: opts.scryptN } })
+        : await w.encrypt(passphrase);
+    writeNewPrivateFile(file, json);
+    return { address: w.address };
+}
+/** The address stored in the keystore, read without the passphrase. */
+export function keystoreAddress(home) {
+    const raw = readKeystore(home);
+    const addr = JSON.parse(raw).address;
+    if (!addr || !/^(0x)?[0-9a-fA-F]{40}$/.test(addr))
+        refuse("KEYSTORE_UNREADABLE", "the keystore has no address field");
+    return addr.startsWith("0x") ? addr : `0x${addr}`;
+}
+function readKeystore(home) {
+    ensureHome(home);
+    const file = keystorePath(home);
+    if (!fs.existsSync(file))
+        refuse("KEYSTORE_MISSING", `no keystore at ${file} — run: cascrow-signer init`);
+    return readPrivateFile(file);
+}
+export async function unlock(home, passphrase) {
+    if (!passphrase) {
+        refuse("PASSPHRASE_REQUIRED", "the keystore passphrase is required (TTY prompt, CASCROW_KEYSTORE_PASSPHRASE_FILE or CASCROW_KEYSTORE_PASSPHRASE)");
+    }
+    const raw = readKeystore(home);
+    let w;
+    try {
+        const decrypted = await Wallet.fromEncryptedJson(raw, passphrase);
+        w = decrypted instanceof Wallet ? decrypted : new Wallet(decrypted.privateKey);
+    }
+    catch {
+        refuse("PASSPHRASE_WRONG", "the keystore could not be decrypted with this passphrase");
+    }
+    return wrap(w);
+}

package/dist/link.d.ts

@@ -0,0 +1,17 @@
+import type { SignerContext } from "./context.js";
+export declare 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 declare function challengeNonce(token: string): string;
+/** Refuses anything but the exact challenge sentence for this token's nonce. */
+export declare function checkChallenge(message: unknown, token: unknown): string;
+export declare function link(ctx: SignerContext): Promise<{
+    linked: boolean;
+    walletAddress: string;
+    changed: boolean;
+    message: string;
+} | {
+    linked: boolean;
+    walletAddress: string;
+    changed: boolean;
+    message?: undefined;
+}>;