cascrow-signer 0.1.0 → 0.2.0

package/dist/actions.js

@@ -15,13 +15,13 @@
  * refusal, never read as "down" (post-review G1/H2).
  */
 import fs from "node:fs";
-import { getAddress, keccak256, parseEther, sha256, toUtf8Bytes } from "ethers";
+import { ZeroAddress, formatEther, getAddress, keccak256, parseEther, sha256, toUtf8Bytes } from "ethers";
 import { SignerError, refuse } from "./errors.js";
-import { PER_ESCROW_ACTIONS, encodeCall } from "./calldata.js";
+import { ACTION_FN, PER_ESCROW_ACTIONS, decodeCall, encodeCall } from "./calldata.js";
 import { BOOK_BOUND_ACTIONS, checkEscrowAction, checkFund, checkMatchesLocal, checkPreparedEnvelope, checkWithdraw, fundTermsFrom } from "./checks.js";
-import { fundedByMeLastDay, latestBlock, readCredit, readEscrow, sendSigned, settleUnknown } from "./chain.js";
-import { withLock } from "./journal.js";
-import { loadPolicy, savePolicy } from "./policy.js";
+import { fundedByMeLastDay, latestBlock, readCredit, readEscrow, resendWithHigherFee, sendSigned, settleUnknown } from "./chain.js";
+import { daySum, standsAlone, withLock } from "./journal.js";
+import { effectivePolicy, loadPolicy, loadPolicyIfSet, savePolicy } from "./policy.js";
 import { Book } from "./book.js";
 import { RemoteError } from "./remote.js";
 import { verifyEndpoint } from "./network.js";
@@ -43,6 +43,37 @@ async function report(ctx, milestoneId, txHash, notes) {
         return false;
     }
 }
+// ─── the person at the terminal ──────────────────────────────────────────────
+const iso = (sec) => new Date(Number(sec) * 1000).toISOString();
+const inDays = (sec) => `${((Number(sec) - Date.now() / 1000) / 86400).toFixed(1)} days from now`;
+/**
+ * On a terminal: show what is about to be signed and ask y/N; a "no" signs nothing
+ * (DECLINED). Off a terminal (the MCP server) this does nothing — the policy is what
+ * bounds an agent. A terminal Io without a way to ask is refused, not waved through.
+ */
+export async function confirmOnTerminal(ctx, question, lines) {
+    if (!ctx.io.isTTY)
+        return;
+    if (!ctx.io.confirm)
+        refuse("CONFIRM_UNAVAILABLE", "this terminal session cannot ask for confirmation; nothing was signed");
+    for (const l of lines)
+        ctx.io.err(l);
+    if (!(await ctx.io.confirm(question)))
+        refuse("DECLINED", "you declined; nothing was signed");
+}
+/** What a payer's `fund` commits to, in the words a person checks (S-02). */
+export function fundSummary(ctx, f, payeeKnown) {
+    const t = f.t;
+    return [
+        `You are about to FUND an escrow on ${ctx.net.name} (chain ${ctx.net.chainId}, contract ${ctx.net.address}):`,
+        `  amount:          ${formatEther(t.amount)} XRP — leaves your account in this transaction`,
+        `  payee:           ${t.payee}${payeeKnown ? " (in your counterparty book)" : " (NOT in your counterparty book)"}`,
+        `  deadline:        ${iso(t.deadline)} (${inDays(t.deadline)}) — until then the money is locked unless you release it, the payee claims or returns it`,
+        `  review period:   ${(t.reviewPeriod / 3600).toFixed(1)} h — the time you have to object to a claim`,
+        `  arbiter:         ${t.arbiter === ZeroAddress ? "none" : `${t.arbiter} (arbitration period ${(t.arbitrationPeriod / 86400).toFixed(1)} days)`}`,
+        `  offer open until ${iso(t.acceptBy)}`,
+    ];
+}
 export async function fund(ctx, input) {
     if (!input.milestoneId)
         refuse("INPUT", "milestoneId is required");
@@ -73,45 +104,47 @@ export async function fund(ctx, input) {
             savePolicy(ctx.home, key.macKey, policy, ctx.io);
         }
     }
+    // A person at a terminal sees the terms and says yes before anything is signed (S-02).
+    // Before the lock: a human reading must not hold up the MCP server's own sends.
+    await confirmOnTerminal(ctx, "Sign and send this funding?", fundSummary(ctx, terms, policy.payees.includes(terms.t.payee.toLowerCase())));
     const c = chainCtx(ctx);
+    const journal = ctx.journal.keyed(key.macKey);
     return withLock(ctx.home, async () => {
         await verifyEndpoint(ctx.rpc, ctx.net);
         const head = await latestBlock(c);
-        const journalPresent = ctx.journal.exists();
-        const fromJournal = ctx.journal.daySum(head.timestamp);
+        // JOURNAL_TAMPERED here, before anything else: a limit is never computed over a journal that was changed.
+        const v = journal.verifyForSpending();
+        const alone = standsAlone(v, head.timestamp);
         let fromChain;
         try {
             fromChain = await fundedByMeLastDay(c, me, head);
         }
         catch (e) {
-            if (!journalPresent) {
-                refuse("JOURNAL_UNREADABLE", "the spending journal is missing and the chain's Funded events could not be read to rebuild today's total — funding is refused rather than guessing the daily limit");
+            if (!alone) {
+                refuse("JOURNAL_UNREADABLE", `the spending journal is ${v.state === "missing" ? "missing" : v.state === "v1" ? "a 0.1.0 journal, not yet protected" : "younger than 24 hours (recreated or migrated)"} and the chain's Funded events could not be read to rebuild today's total — funding is refused rather than guessing the daily limit; retry when the RPC answers`);
             }
             notes.push(`could not cross-check today's total against the chain (${e instanceof Error ? e.message : "error"}); used the local journal`);
             fromChain = new Map();
         }
-        let day = fromJournal.sumWei;
-        for (const [id, amt] of fromChain)
-            if (!fromJournal.escrowIds.has(id))
-                day += amt;
-        if (!journalPresent)
+        if (v.state === "missing")
             notes.push("the spending journal was missing; today's total was rebuilt from Funded events on chain");
+        if (v.state === "v1")
+            notes.push("the spending journal was written by 0.1.0; it is now protected by a MAC chain — its reservations still count, its releases do not");
         try {
-            await settleUnknown(c, me, ctx.journal);
+            await settleUnknown(c, me, journal, v);
         }
         catch {
             /* unknown outcomes keep counting — the safe direction */
         }
+        const day = daySum(journal.verifyForSpending(), fromChain, head.timestamp);
         const slot = await readEscrow(c, p.escrowId);
         const { payeeKnown } = checkFund({ prepared: p, terms, me, pinned: ctx.net, policy, daySumWei: day, chainNowSec: head.timestamp, slotStatus: slot.status, maxAmountWei });
         if (!payeeKnown)
             notes.push("payee not in your counterparty book — the lower limit for unknown payees applied");
-        if (!journalPresent)
-            ctx.journal.create(true);
-        const rid = ctx.journal.reserve("fund", p.escrowId, terms.t.amount, head.timestamp);
+        const rid = journal.reserve("fund", p.escrowId, terms.t.amount, head.timestamp);
         book.add({ escrowId: p.escrowId, role: "payer", milestoneId: input.milestoneId, payer: me, payee: terms.t.payee, amountWei: terms.t.amount.toString(), chainId: ctx.net.chainId, contract: ctx.net.address, at: head.timestamp });
         const data = encodeCall("fund", p.call.args);
-        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: terms.t.amount });
+        const sent = await sendSigned(c, key, journal, rid, { to: ctx.net.address, data, value: terms.t.amount });
         if (sent.note)
             notes.push(sent.note);
         const reported = await report(ctx, input.milestoneId, sent.txHash, notes);
@@ -191,6 +224,49 @@ function readBookLoosely(ctx, book, notes) {
         return [];
     }
 }
+/**
+ * An action that does not read the journal for a decision still says so loudly when the
+ * journal fails its check — it is the signal that something wrote into the signer's
+ * directory — and goes ahead: the objection window does not wait for a repair.
+ */
+function noteJournalIntegrity(ctx, journal, notes) {
+    let state;
+    let at = null;
+    try {
+        const v = journal.verify();
+        state = v.state;
+        at = v.brokenAt;
+    }
+    catch {
+        state = "unreadable";
+    }
+    if (state !== "tampered" && state !== "unreadable")
+        return;
+    const n = `WARNING: the spending journal ${journal.file} ${state === "tampered" ? `failed its integrity check at line ${at}` : "could not be read"}. This action went ahead (it needs no journal); fund stays refused until the journal is moved aside.`;
+    notes.push(n);
+    ctx.io.err(n);
+}
+/**
+ * `returnFunds` gives the escrow to the payer for good (S-03). On a terminal the person
+ * confirms it; off a terminal it is signed only when the policy says so — set on a
+ * terminal, never through MCP. The refusal names both ways out, and an agent can pass
+ * either on to the person.
+ */
+async function gateReturnFunds(ctx, escrowId, limits) {
+    if (ctx.io.isTTY) {
+        const e = await readEscrow(chainCtx(ctx), escrowId);
+        await confirmOnTerminal(ctx, "Give this money back to the payer?", [
+            `You are about to RETURN escrow ${escrowId} to its payer ${e.payer}:`,
+            `  ${formatEther(e.amount)} XRP go back to the payer for good — you cannot claim this escrow afterwards.`,
+        ]);
+        return;
+    }
+    if (!limits.allowReturnFundsWithoutTerminal) {
+        refuse("RETURN_FUNDS_NEEDS_TERMINAL", "returnFunds gives the escrowed money back to the payer for good, and this signer is not on a terminal — nothing was signed. " +
+            "The person who owns this key can run `cascrow-signer return-funds --escrow " + escrowId + "` on a terminal, or allow it for agents there: " +
+            "cascrow-signer policy set … --allow-agent-return-funds");
+    }
+}
 export async function escrowAction(ctx, action, input) {
     const key = await ctx.unlock();
     const me = key.address;
@@ -269,15 +345,22 @@ export async function escrowAction(ctx, action, input) {
     const data = encodeCall(action, args);
     if (prepared)
         checkMatchesLocal({ to: ctx.net.address, data, value: BigInt(0) }, prepared);
+    // Only the two actions the policy bounds read it (S-03). `object` never does: a damaged
+    // policy must not cost a payer the objection window.
+    const limits = action === "extendDeadline" || action === "returnFunds" ? effectivePolicy(loadPolicyIfSet(ctx.home, key.macKey, me)) : null;
+    if (action === "returnFunds")
+        await gateReturnFunds(ctx, escrowId, limits);
+    const journal = ctx.journal.keyed(key.macKey);
     return withLock(ctx.home, async () => {
         await verifyEndpoint(ctx.rpc, ctx.net);
         const head = await latestBlock(c);
         const e = await readEscrow(c, escrowId);
         const findIn = (entries) => entries.find((x) => x.escrowId === escrowId && x.chainId === ctx.net.chainId && x.contract === ctx.net.address.toLowerCase()) ?? null;
         const entry = bookBound ? book.find(escrowId, ctx.net.chainId, ctx.net.address) : input.milestoneId ? null : findIn(readBookLoosely(ctx, book, notes));
-        checkEscrowAction(action, me, e, head.timestamp, { book: entry, newDeadline, proofHash, reasonHash });
-        const rid = ctx.journal.exists() ? ctx.journal.reserve(action, escrowId, BigInt(0), head.timestamp) : (ctx.journal.create(true), ctx.journal.reserve(action, escrowId, BigInt(0), head.timestamp));
-        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
+        checkEscrowAction(action, me, e, head.timestamp, { book: entry, newDeadline, proofHash, reasonHash, ...(limits ? { maxDeadlineSeconds: limits.maxDeadlineSeconds } : {}) });
+        noteJournalIntegrity(ctx, journal, notes);
+        const rid = journal.reserve(action, escrowId, BigInt(0), head.timestamp);
+        const sent = await sendSigned(c, key, journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
         if (sent.note)
             notes.push(sent.note);
         const milestoneId = input.milestoneId ?? entry?.milestoneId ?? null;
@@ -306,14 +389,85 @@ export async function withdraw(ctx) {
         const head = await latestBlock(c);
         const credit = await readCredit(c, me);
         checkWithdraw(me, credit);
-        if (!ctx.journal.exists())
-            ctx.journal.create(true);
-        const rid = ctx.journal.reserve("withdraw", null, BigInt(0), head.timestamp);
+        const journal = ctx.journal.keyed(key.macKey);
+        noteJournalIntegrity(ctx, journal, notes);
+        const rid = journal.reserve("withdraw", null, BigInt(0), head.timestamp);
         const data = encodeCall("withdraw", [me, "0x0000000000000000000000000000000000000000"]);
-        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
+        const sent = await sendSigned(c, key, journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
         if (sent.note)
             notes.push(sent.note);
         return { action: "withdraw", escrowId: "", txHash: sent.txHash, sent: sent.sent, reported: false, from: me, creditWei: credit.toString(), notes };
     });
 }
+/**
+ * Replace one of this signer's pending transactions with the same nonce and a 25 % higher
+ * fee — the way to get a pending objection mined. Call inside `withLock`.
+ *
+ * Re-signing is signing, so it is checked like a first signature (S-01): the entry must
+ * be AUTHENTIC (in the verified part of the journal — never a 0.1.0 line, never a line
+ * after a break), it must move no value (a funding is never replaced: its limit was
+ * checked for the transaction as signed), its calldata must decode to the action it was
+ * reserved for and name the same escrow, and the action is checked against the chain and
+ * the policy again exactly as `escrowAction` checks it. Only then is it re-signed.
+ */
+export async function speedUp(ctx, key, txHash) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txHash))
+        refuse("INPUT", "txHash must be 0x + 64 hex characters");
+    const me = getAddress(key.address);
+    const journal = ctx.journal.keyed(key.macKey);
+    const v = journal.verify();
+    const h = txHash.toLowerCase();
+    const r = v.reservations.find((x) => !x.legacy && x.signed && (x.signed.hash.toLowerCase() === h || x.sentHashes.some((y) => y.toLowerCase() === h)));
+    if (!r || !r.signed) {
+        refuse("NOT_IN_JOURNAL", v.state === "tampered"
+            ? `this transaction is not in the verified part of the spending journal (it fails its integrity check at line ${v.brokenAt}); nothing was signed`
+            : v.state === "v1"
+                ? "the spending journal was written by 0.1.0 and its entries are not re-signed; nothing was signed"
+                : "this transaction was not signed by this signer; nothing was signed");
+    }
+    if (r.action === "fund" || r.amountWei !== BigInt(0) || String(r.signed.tx.value) !== "0") {
+        refuse("SPEEDUP_REFUSED", "a funding is never replaced by the signer — wait for it to be mined or dropped; its reservation keeps counting toward your 24-hour limit until its nonce is used. Nothing was signed");
+    }
+    if (!Object.prototype.hasOwnProperty.call(ACTION_FN, r.action))
+        refuse("SPEEDUP_REFUSED", `the journal entry names an unknown action ${r.action}`);
+    const action = r.action;
+    let decoded;
+    try {
+        decoded = decodeCall(String(r.signed.tx.data));
+    }
+    catch {
+        refuse("SPEEDUP_REFUSED", "the journal entry's calldata does not decode under the pinned ABI; nothing was signed");
+    }
+    if (decoded.fn !== ACTION_FN[action])
+        refuse("SPEEDUP_REFUSED", `the journal entry's calldata calls ${decoded.fn}, not the ${action} it was reserved for; nothing was signed`);
+    const c = chainCtx(ctx);
+    await verifyEndpoint(ctx.rpc, ctx.net);
+    const head = await latestBlock(c);
+    if (action === "withdraw") {
+        if (String(decoded.args[0]).toLowerCase() !== me.toLowerCase() || String(decoded.args[1]).toLowerCase() !== ZeroAddress.toLowerCase()) {
+            refuse("SPEEDUP_REFUSED", "the journal entry's withdraw does not pay this key in native XRP; nothing was signed");
+        }
+        checkWithdraw(me, await readCredit(c, me));
+    }
+    else if (PER_ESCROW_ACTIONS.has(action)) {
+        const escrowId = String(decoded.args[0]).toLowerCase();
+        if (!r.escrowId || r.escrowId.toLowerCase() !== escrowId)
+            refuse("SPEEDUP_REFUSED", "the journal entry's calldata names a different escrow than its reservation; nothing was signed");
+        const e = await readEscrow(c, escrowId);
+        const entry = BOOK_BOUND_ACTIONS.has(action) ? new Book(ctx.home, key.macKey).find(escrowId, ctx.net.chainId, ctx.net.address) : null;
+        const arg1 = decoded.args[1] === undefined ? null : String(decoded.args[1]);
+        const limits = action === "extendDeadline" ? effectivePolicy(loadPolicyIfSet(ctx.home, key.macKey, me)) : null;
+        checkEscrowAction(action, me, e, head.timestamp, {
+            book: entry,
+            newDeadline: action === "extendDeadline" && arg1 !== null ? BigInt(arg1) : null,
+            proofHash: action === "submitClaim" ? arg1 : null,
+            reasonHash: action === "object" ? arg1 : null,
+            ...(limits ? { maxDeadlineSeconds: limits.maxDeadlineSeconds } : {}),
+        });
+    }
+    else {
+        refuse("SPEEDUP_REFUSED", `${action} is not an action the signer replaces; nothing was signed`);
+    }
+    return resendWithHigherFee(c, key, journal, r);
+}
 export { PER_ESCROW_ACTIONS };

package/dist/api.d.ts

@@ -3,16 +3,18 @@ import type { Io, SignerConfig } from "./context.js";
 import type { PolicyInput } from "./policy.js";
 import type { EscrowActionInput, FundInput } from "./actions.js";
 import type { AcceptInput } from "./acceptance.js";
+import type { LinkOptions } from "./link.js";
 import type { WatchOptions } from "./watch.js";
 export { SignerError } from "./errors.js";
 export { SignerContext } from "./context.js";
 export type { Io, SignerConfig } from "./context.js";
 export { LOCAL_ONLY_TOOLS } from "./tools.js";
 export { checkAcceptance } from "./acceptance.js";
-export { checkChallenge, CHALLENGE_PREFIX } from "./link.js";
+export { checkChallenge, buildChallengeMessage, challengeStatement, CHALLENGE_AUDIENCE } from "./link.js";
+export type { ChallengeExpectation, ChallengeFields, ChallengePurpose, LinkOptions } from "./link.js";
 export { localProofHash } from "./actions.js";
 export { resolveNetwork, PUBLIC_NETWORKS } from "./network.js";
-export declare const SIGNER_VERSION = "0.1.0";
+export declare const SIGNER_VERSION = "0.2.0";
 /** Create the keystore and the spending journal. Does not need a network or cascrow. */
 export declare function initSigner(home: string, passphrase: string, opts?: {
     scryptN?: number;
@@ -25,12 +27,13 @@ export declare function configFromEnv(env: Env, io: Io, overrides?: Partial<Sign
 export declare function createSigner(cfg: SignerConfig): {
     ctx: SignerContext;
     address: () => string;
-    link: () => Promise<{
+    link: (o?: LinkOptions) => Promise<{
         linked: boolean;
         walletAddress: string;
         changed: boolean;
         message: string;
     } | {
+        previous?: string | undefined;
         linked: boolean;
         walletAddress: string;
         changed: boolean;
@@ -67,7 +70,19 @@ export declare function createSigner(cfg: SignerConfig): {
     }>;
     watch: (o?: WatchOptions) => Promise<void>;
     speedUp: (txHash: string) => Promise<import("./chain.js").SendResult>;
-    policy: () => Promise<import("./policy.js").Policy>;
+    /** The stored policy with the limits it ENFORCES — a policy written before 0.2.0 shows the defaults it now gets. */
+    policy: () => Promise<{
+        maxDeadlineSeconds: number;
+        allowReturnFundsWithoutTerminal: boolean;
+        v: 1;
+        address: string;
+        perEscrowMaxWei: string;
+        unknownPayeePerEscrowMaxWei: string;
+        dailyMaxWei: string;
+        minReviewSeconds: number;
+        payees: string[];
+        arbiters: string[];
+    }>;
     setPolicy: (input: PolicyInput) => Promise<import("./policy.js").Policy>;
     status: () => {
         address: string;

package/dist/api.js

@@ -12,29 +12,35 @@
  */
 import { refuse } from "./errors.js";
 import { SignerContext } from "./context.js";
-import { createKeystore } from "./keystore.js";
+import fs from "node:fs";
+import { createKeystore, keystorePath } from "./keystore.js";
 import { Journal } from "./journal.js";
-import { buildPolicy, loadPolicy, savePolicy } from "./policy.js";
-import { escrowAction, fund, withdraw } from "./actions.js";
+import { buildPolicy, effectivePolicy, loadPolicy, savePolicy } from "./policy.js";
+import { escrowAction, fund, speedUp, withdraw } from "./actions.js";
 import { accept } from "./acceptance.js";
 import { link } from "./link.js";
 import { onchainClaims, watch } from "./watch.js";
-import { speedUp } from "./chain.js";
 import { withLock } from "./journal.js";
 import { ensureHome, signerHome } from "./files.js";
 export { SignerError } from "./errors.js";
 export { SignerContext } from "./context.js";
 export { LOCAL_ONLY_TOOLS } from "./tools.js";
 export { checkAcceptance } from "./acceptance.js";
-export { checkChallenge, CHALLENGE_PREFIX } from "./link.js";
+export { checkChallenge, buildChallengeMessage, challengeStatement, CHALLENGE_AUDIENCE } from "./link.js";
 export { localProofHash } from "./actions.js";
 export { resolveNetwork, PUBLIC_NETWORKS } from "./network.js";
-export const SIGNER_VERSION = "0.1.0";
+export const SIGNER_VERSION = "0.2.0";
 /** Create the keystore and the spending journal. Does not need a network or cascrow. */
 export async function initSigner(home, passphrase, opts = {}) {
     ensureHome(home);
-    const { address } = await createKeystore(home, passphrase, opts);
-    new Journal(home).create();
+    const journal = new Journal(home);
+    // A journal left by an earlier key carries that key's MACs: the new key could never
+    // verify it, and every fund would be refused as tampered. Refused before a key exists.
+    if (journal.exists() && !fs.existsSync(keystorePath(home))) {
+        refuse("JOURNAL_EXISTS", `a spending journal from an earlier key is in ${home}; move it aside (or use another --home) before creating a new key`);
+    }
+    const { address, macKey } = await createKeystore(home, passphrase, opts);
+    journal.keyed(macKey).create(Math.floor(Date.now() / 1000));
     return { address, home };
 }
 export function configFromEnv(env, io, overrides = {}) {
@@ -64,7 +70,7 @@ export function createSigner(cfg) {
     return {
         ctx,
         address: () => ctx.address(),
-        link: () => link(ctx),
+        link: (o) => link(ctx, o),
         accept: (i) => accept(ctx, i),
         fund: (i) => fund(ctx, i),
         submitClaim: act("submitClaim"),
@@ -79,11 +85,13 @@ export function createSigner(cfg) {
         watch: (o) => watch(ctx, o),
         speedUp: async (txHash) => {
             const key = await ctx.unlock();
-            return withLock(ctx.home, () => speedUp({ rpc: ctx.rpc, net: ctx.net }, key, ctx.journal, txHash));
+            return withLock(ctx.home, () => speedUp(ctx, key, txHash));
         },
+        /** The stored policy with the limits it ENFORCES — a policy written before 0.2.0 shows the defaults it now gets. */
         policy: async () => {
             const key = await ctx.unlock();
-            return loadPolicy(ctx.home, key.macKey, key.address);
+            const p = loadPolicy(ctx.home, key.macKey, key.address);
+            return { ...p, ...effectivePolicy(p) };
         },
         setPolicy: async (input) => {
             const key = await ctx.unlock();

package/dist/chain.d.ts

@@ -1,7 +1,7 @@
 import type { ChainEscrow } from "./calldata.js";
 import { Rpc } from "./network.js";
 import type { SignerNetwork } from "./network.js";
-import { Journal } from "./journal.js";
+import type { KeyedJournal, Reservation, VerifiedJournal } from "./journal.js";
 import type { UnlockedKey } from "./keystore.js";
 export type ChainCtx = {
     rpc: Rpc;
@@ -41,19 +41,25 @@ export type SendResult = {
  * this function's scope and in the RPC request body — it is never returned,
  * logged or sent anywhere else.
  */
-export declare function sendSigned(c: ChainCtx, key: UnlockedKey, journal: Journal, reservationId: string, tx: {
+export declare function sendSigned(c: ChainCtx, key: UnlockedKey, journal: KeyedJournal, reservationId: string, tx: {
     to: string;
     data: string;
     value: bigint;
 }): Promise<SendResult>;
 /**
- * Replace a pending transaction of this key with the same nonce and fees raised by
- * 25 % — the way to speed up an objection, instead of waiting. Refused once the
- * nonce is used.
+ * Re-sign an AUTHENTIC journal entry with the same nonce and fees raised by 25 % and
+ * send it. The caller (actions.ts `speedUp`) has already decided the entry may be
+ * re-signed: verified, value 0, its calldata decoded and checked against the chain
+ * again. This function only refuses what it can see itself: a used nonce, a target
+ * other than the pinned contract, a value other than 0.
  */
-export declare function speedUp(c: ChainCtx, key: UnlockedKey, journal: Journal, txHash: string): Promise<SendResult>;
+export declare function resendWithHigherFee(c: ChainCtx, key: UnlockedKey, journal: KeyedJournal, r: Reservation & {
+    signed: NonNullable<Reservation["signed"]>;
+}): Promise<SendResult>;
 /**
  * Release reservations whose transaction provably spent nothing: signed, outcome
- * unknown, its nonce now used, and no receipt for any of its hashes.
+ * unknown, its nonce now used, and no receipt for any of its hashes. Only over an
+ * AUTHENTIC entry of an unbroken journal (`verifyForSpending`) — a legacy (0.1.0) line
+ * is never released, so an unauthenticated "unknown" line cannot free a reservation.
  */
-export declare function settleUnknown(c: ChainCtx, me: string, journal: Journal): Promise<void>;
+export declare function settleUnknown(c: ChainCtx, me: string, journal: KeyedJournal, v: VerifiedJournal): Promise<void>;

package/dist/chain.js

@@ -154,7 +154,7 @@ export async function sendSigned(c, key, journal, reservationId, tx) {
     const fields = { chainId: c.net.chainId, nonce, to: tx.to, data: tx.data, value: tx.value, gasLimit: pct(gas, 125), ...fees };
     const signed = await key.signTransaction(fields);
     const hash = keccak256(signed);
-    journal.signed(reservationId, hash, nonce, Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "bigint" ? v.toString() : v])));
+    journal.signed(reservationId, hash, nonce, fields);
     try {
         const answered = await c.rpc.call("eth_sendRawTransaction", [signed]);
         if (typeof answered === "string" && answered.toLowerCase() !== hash.toLowerCase()) {
@@ -172,34 +172,35 @@ export async function sendSigned(c, key, journal, reservationId, tx) {
     }
 }
 /**
- * Replace a pending transaction of this key with the same nonce and fees raised by
- * 25 % — the way to speed up an objection, instead of waiting. Refused once the
- * nonce is used.
+ * Re-sign an AUTHENTIC journal entry with the same nonce and fees raised by 25 % and
+ * send it. The caller (actions.ts `speedUp`) has already decided the entry may be
+ * re-signed: verified, value 0, its calldata decoded and checked against the chain
+ * again. This function only refuses what it can see itself: a used nonce, a target
+ * other than the pinned contract, a value other than 0.
  */
-export async function speedUp(c, key, journal, txHash) {
+export async function resendWithHigherFee(c, key, journal, r) {
     await verifyEndpoint(c.rpc, c.net);
-    const r = journal.read().find((x) => x.signed && (x.signed.hash.toLowerCase() === txHash.toLowerCase() || x.sentHashes.some((h) => h.toLowerCase() === txHash.toLowerCase())));
-    if (!r || !r.signed)
-        refuse("NOT_IN_JOURNAL", "this transaction was not signed by this signer");
     const used = Number(BigInt(await c.rpc.call("eth_getTransactionCount", [key.address, "latest"])));
     if (used > r.signed.nonce)
         refuse("NONCE_USED", "that transaction's nonce is already used — it was mined or replaced");
     const prev = r.signed.tx;
+    if (getAddress(String(prev.to)) !== getAddress(c.net.address))
+        refuse("WRONG_TARGET", "the journal entry does not target the pinned contract");
+    if (BigInt(prev.value ?? "x") !== BigInt(0))
+        refuse("SPEEDUP_REFUSED", "only a transaction that moves no value is replaced by the signer");
     const fees = await feeFields(c, prev);
     const fields = {
         chainId: c.net.chainId,
         nonce: r.signed.nonce,
         to: prev.to,
         data: prev.data,
-        value: BigInt(prev.value),
+        value: BigInt(0),
         gasLimit: BigInt(prev.gasLimit),
         ...fees,
     };
-    if (getAddress(fields.to) !== getAddress(c.net.address))
-        refuse("WRONG_TARGET", "the journal entry does not target the pinned contract");
     const signed = await key.signTransaction(fields);
     const hash = keccak256(signed);
-    journal.signed(r.id, hash, r.signed.nonce, Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, typeof v === "bigint" ? v.toString() : v])));
+    journal.signed(r.id, hash, r.signed.nonce, fields);
     try {
         await c.rpc.call("eth_sendRawTransaction", [signed]);
         journal.sent(r.id, hash);
@@ -212,10 +213,14 @@ export async function speedUp(c, key, journal, txHash) {
 }
 /**
  * Release reservations whose transaction provably spent nothing: signed, outcome
- * unknown, its nonce now used, and no receipt for any of its hashes.
+ * unknown, its nonce now used, and no receipt for any of its hashes. Only over an
+ * AUTHENTIC entry of an unbroken journal (`verifyForSpending`) — a legacy (0.1.0) line
+ * is never released, so an unauthenticated "unknown" line cannot free a reservation.
  */
-export async function settleUnknown(c, me, journal) {
-    const open = journal.read().filter((r) => r.unknown && !r.released && r.signed);
+export async function settleUnknown(c, me, journal, v) {
+    if (v.state !== "intact")
+        return;
+    const open = v.reservations.filter((r) => !r.legacy && r.unknown && !r.released && r.signed);
     if (!open.length)
         return;
     const used = Number(BigInt(await c.rpc.call("eth_getTransactionCount", [me, "latest"])));

package/dist/checks.d.ts

@@ -97,5 +97,7 @@ export declare function checkEscrowAction(action: V3EscrowAction, me: string, e:
     newDeadline?: bigint | null;
     proofHash?: string | null;
     reasonHash?: string | null;
+    /** extendDeadline: the policy's longest term (`effectivePolicy`). Absent → the 365-day default, never the contract's five years. */
+    maxDeadlineSeconds?: number;
 }): void;
 export declare function checkWithdraw(me: string, credit: bigint): void;

package/dist/checks.js

@@ -20,6 +20,7 @@ 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";
+import { DEFAULT_MAX_DEADLINE_SECONDS, effectivePolicy } from "./policy.js";
 const lc = (s) => String(s).toLowerCase();
 function fail(code, reasons) {
     if (reasons.length)
@@ -152,6 +153,11 @@ export function checkFund(i) {
         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");
+    else {
+        const cap = effectivePolicy(pol).maxDeadlineSeconds;
+        if (f.t.deadline > now + BigInt(cap))
+            r.push(`the deadline is more than ${Math.floor(cap / 86400)} days away — beyond your local policy's maximum (cascrow-signer policy set --max-deadline-days, on a terminal)`);
+    }
     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);
@@ -221,6 +227,11 @@ export function checkEscrowAction(action, me, e, chainNowSec, opts) {
             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");
+        else {
+            const cap = opts.maxDeadlineSeconds ?? DEFAULT_MAX_DEADLINE_SECONDS;
+            if (nd > BigInt(chainNowSec + cap))
+                r.push(`newDeadline is more than ${Math.floor(cap / 86400)} days away — beyond your local policy's maximum (cascrow-signer policy set --max-deadline-days, on a terminal)`);
+        }
     }
     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)");

package/dist/cli.js

@@ -60,8 +60,11 @@ const HELP = `cascrow-signer ${SIGNER_VERSION} — your MilestoneEscrowV3 key, o
 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)
+                           [--min-review-hours H] [--max-deadline-days D (365)]
+                           [--payee 0x…]… [--arbiter 0x…]… [--allow-agent-return-funds]
+                                     (terminal only; replaces the whole policy)
+  link [--old-home DIR]              link this address to your cascrow account (CASCROW_API_KEY);
+                                     replacing a linked wallet needs its keystore: --old-home
   status
 
 As payee                             As payer
@@ -70,6 +73,7 @@ As payee                             As payer
     --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]
+                                       [--blind-after N (3)] [--once]
 Either party
   claim --escrow ID   refund --escrow ID   withdraw   speed-up --tx HASH
   mcp                                run as an MCP server on stdio
@@ -126,7 +130,15 @@ async function main() {
     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 "link": {
+            const oldHome = one(a, "old-home");
+            return print(await s.link(oldHome
+                ? {
+                    oldHome,
+                    oldPassphrase: async () => (io.isTTY && io.prompt ? io.prompt("Passphrase of the keystore in --old-home: ", true) : null),
+                }
+                : {}));
+        }
         case "policy":
             if (sub === "set") {
                 return print(await s.setPolicy({
@@ -134,8 +146,10 @@ async function main() {
                     dailyMaxXrp: one(a, "daily-xrp") ?? "",
                     unknownPayeePerEscrowMaxXrp: one(a, "unknown-payee-xrp"),
                     minReviewHours: one(a, "min-review-hours") ? Number(one(a, "min-review-hours")) : undefined,
+                    maxDeadlineDays: one(a, "max-deadline-days") ? Number(one(a, "max-deadline-days")) : undefined,
                     payees: a.flags.payee,
                     arbiters: a.flags.arbiter,
+                    allowReturnFundsWithoutTerminal: one(a, "allow-agent-return-funds") === "true",
                 }));
             }
             return print(await s.policy());
@@ -150,7 +164,14 @@ async function main() {
         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 "watch":
+            return s.watch({
+                intervalSec: Number(one(a, "interval") ?? 60),
+                exec: one(a, "exec"),
+                webhook: one(a, "webhook"),
+                once: one(a, "once") === "true",
+                ...(one(a, "blind-after") ? { blindAfter: Number(one(a, "blind-after")) } : {}),
+            });
         case "speed-up": return print(await s.speedUp(one(a, "tx") ?? ""));
         case "mcp": return serveStdio(s, SIGNER_VERSION);
         default: