cascrow-signer 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,71 @@
 # Changelog
 
-## 0.1.0 — unreleased (owner publishes)
+## 0.3.0 — 2026-10-21
+
+- **`object` commits to a salted hash of the reason.** What goes on chain is now
+  `keccak256(salt ‖ utf8(reason))` (= `solidityPackedKeccak256(["bytes32","string"], [salt, reason])`),
+  with a salt of 32 random bytes made on this machine; 0.2.0 sent `keccak256(utf8(reason))`,
+  and that hash stands on two public ledgers for good (the `Objected` event, and cascrow's
+  audit memo on the XRP Ledger), where a short reason could be confirmed by hashing guesses.
+  The result of `object` carries `reason`, `reasonSalt` and `reasonHash`, and the spending
+  journal keeps the same three on the `object` reservation (`objection`). Keep the salt with
+  the reason: without it nobody, you included, can show later which reason the hash commits
+  to. Neither the reason nor the salt is sent to cascrow — `prepare` still gets only the hash.
+  The contract does not read the hash; nothing else changes. Every `cascrow-signer` pin is now
+  `cascrow-signer@0.3.0`.
+
+## 0.2.0 — 2026-10-19
+
+- **Upgrade required to link a wallet** (cascrow SEC-145). cascrow's wallet challenge is now a
+  Sign-In with Ethereum (EIP-4361) message that names cascrow's host, the address being linked
+  and the chain; the old one-line sentence named none of them. `link` rebuilds the message from
+  the challenge token's fields and signs only on an exact match with the configured
+  `CASCROW_BASE_URL` host, this key's address, the pinned chain ID and an unexpired time
+  (`CHALLENGE_MISMATCH` / `CHALLENGE_EXPIRED` otherwise — nothing is signed). 0.1.0's `link`
+  asks for the challenge without the address it now has to name, and cascrow answers that with
+  HTTP 400 `CHALLENGE_ADDRESS_REQUIRED` ("address is required … update to 0.2.0"), so 0.1.0 never
+  gets a message to sign — the safe failure; every other command of 0.1.0 keeps working.
+- `link --old-home DIR` (API: `link({ oldHome, oldPassphrase })`): replacing a wallet already
+  linked to the account signs cascrow's `wallet-repoint` challenge with the OLD key in that
+  keystore — checked to be the linked wallet — because cascrow re-points an API-key account only
+  with the current wallet's consent. Without it, a known re-point is refused up front with
+  `REPOINT_NEEDS_OLD_KEY`, before anything is signed.
+- API: `CHALLENGE_PREFIX` is gone (there is no fixed sentence any more); `checkChallenge(message,
+  token, expectation)` takes what the message must name, and `buildChallengeMessage` /
+  `challengeStatement` / `CHALLENGE_AUDIENCE` are exported.
+- **The spending journal is integrity-protected** (cascrow SEC-149). Every line carries a MAC
+  chained to the line before it, under a key derived from the keystore key (the one the policy
+  and the escrow book already use). 0.1.0 obeyed whatever the file said: a hand-written
+  `release` line freed the 24-hour limit, an edited amount hid a funding, a forged
+  `signed`/`unknown` pair made the signer release a reservation, and `speed-up` re-signed the
+  `data`, `value` and `gasLimit` of the line it found. Now `fund` refuses a journal whose chain
+  breaks (`JOURNAL_TAMPERED`, with the way out); `speed-up` re-signs only an authentic entry
+  that moves no value (`SPEEDUP_REFUSED` for a funding), after decoding its calldata and
+  re-running the same checks against the chain and the policy; and the journal never holds a
+  signature. A 0.1.0 journal is migrated on the first transaction: its reservations still
+  count, its releases are ignored. The day sum is, per escrow, the larger of the journal's
+  reservation and the chain's `Funded` event, and a journal that cannot stand alone for the
+  last 24 hours (missing, 0.1.0, recreated less than a day ago) refuses `fund` when the chain
+  cannot be read. `object` and every other non-funding action go ahead over a damaged journal,
+  with a warning. A garbage line no longer blinds `watch` / `claims`
+  (`JOURNAL_UNREADABLE` there is gone — the watcher reads the journal only as hints).
+- **A maximum deadline in the policy** (SEC-150): `fund` and `extend-deadline` refuse a
+  deadline more than `--max-deadline-days` away (default 365; the contract allows five years).
+  On a terminal, `fund` and `accept` print the terms and ask y/N before signing (`DECLINED`).
+- **`return-funds` through MCP needs an opt-in** (SEC-151): off a terminal it is refused
+  (`RETURN_FUNDS_NEEDS_TERMINAL`) unless the policy was set with `--allow-agent-return-funds`;
+  on a terminal it asks first.
+- **`watch` keeps a cursor and says when it is blind** (SEC-152): Funded events are read from
+  the last block read (with a 64-block reorg overlap) instead of from the deploy block every
+  round; after `--blind-after` failed rounds in a row (default 3) a `watch.blind` alarm goes
+  through `--exec` and the webhook, and `watch.recovered` when it reads again. The `--exec`
+  command now also gets `CASCROW_ALARM` (`claim.open`, `watch.blind`, `watch.recovered`).
+  `watch --once` exits non-zero (`WATCH_BLIND`) when it could not read the chain. A failed
+  alarm delivery is reported on stderr.
+- `init` refuses a home that still holds an earlier key's journal (`JOURNAL_EXISTS`).
+- **`accept` names the free veto** when the offer has no arbiter (the signed arbiter is the zero address): the terminal summary shows a `WARNING:` line before the y/N — the payer can object to every claim at no cost, and an objected claim ends in a refund after the deadline, so the escrow protects you only against an inactive payer — and the result's `note` carries the same sentence for an MCP host. The words are cascrow's (`V3_CLIENT_TEXT.noArbiterVeto`), held equal by a test.
+
+## 0.1.0 — 2026-09-27
 
 - First version. A local signer for cascrow's MilestoneEscrowV3 escrows: `init` (key and
   encrypted keystore on this machine), `policy` (limits in XRP, counterparty and arbiter
@@ -8,9 +73,10 @@
   `fund`, `submit-claim`, `claim`, `release`, `object`, `refund`, `extend-deadline`,
   `return-funds`, `withdraw`, `claims`, `watch`, `speed-up`, and an MCP server (`mcp`)
   with the `cascrow_signer_*` tools.
-- Chain, public RPC, contract address and runtime code hash are pinned in the package; no
-  deployment is pinned yet, so every network is refused until the contract is deployed
-  (testnet accepts an explicit, announced override).
+- Chain, public RPC, contract address and runtime code hash are pinned in the package:
+  testnet (1449000) is `0xa1f10a285d9de4cb1ff613829e3a26222db65f45`, deployed in block
+  8816108; mainnet has no deployment and is refused (testnet accepts an explicit,
+  announced override).
 - One runtime dependency, `ethers` 6.17.0, pinned exactly, with `npm-shrinkwrap.json`.
 - `submit-claim` takes `--proof-hash` (MCP: `proofHash`) — the `manifestHash` the evidence
   door returned — and signs only after cascrow confirms it is a sealed submission of the

package/MIGRATION.md

@@ -1,5 +1,48 @@
 # Migrating to cascrow-signer
 
+## From 0.2.0 to 0.3.0
+
+Nothing to do: the keystore, the escrow book, the policy and the journal are compatible both
+ways (0.2.0 reads a 0.3.0 journal and ignores the new field). What changes is `object`: the
+hash it puts on chain is salted — `keccak256(salt ‖ utf8(reason))` — and its result returns
+`reasonSalt`. Keep the salt with the reason (the journal keeps a copy); an objection made with
+0.2.0 committed to the unsalted `keccak256(utf8(reason))`, which stays as it is on chain.
+
+## From 0.1.0 to 0.2.0
+
+cascrow's wallet challenge changed to a Sign-In with Ethereum (EIP-4361) message (SEC-145)
+that names the wallet being linked, so the challenge request has to carry that address. 0.1.0
+asks without it, and `link` fails with
+`address is required: … update to 0.3.0 (npx cascrow-signer@0.3.0 link) … [CHALLENGE_ADDRESS_REQUIRED]`
+(HTTP 400) before anything is signed — safe, but `link` no longer works until you upgrade:
+`npx cascrow-signer@0.3.0 link`. The keystore, the escrow book and your policy file are
+compatible; what else changes:
+
+- **The spending journal** (`journal.jsonl`) is upgraded to a MAC-chained format on the first
+  transaction 0.2.0 signs — nothing to do. Its existing reservations keep counting toward the
+  24-hour limit; its `release` lines are ignored, so a funding 0.1.0 had released may count
+  for up to a day longer. For that first day, `fund` needs the chain's `Funded` events to be
+  readable. Do not edit the journal by hand: `fund` refuses one that was changed
+  (`JOURNAL_TAMPERED`). If that happens and you did not do it, check the machine; to go on,
+  move the file aside — the next `fund` rebuilds today's total from the chain.
+- **Your policy** gains two fields with safe defaults: a maximum deadline of 365 days for
+  `fund` and `extend-deadline` (raise it with `policy set … --max-deadline-days N`, up to the
+  contract's five years), and `return-funds` through MCP is off (`--allow-agent-return-funds`
+  turns it on). `policy set` replaces the whole policy, so repeat every flag you want to keep.
+- **On a terminal**, `fund`, `accept` and `return-funds` show the terms and ask y/N. Scripts
+  that ran them with a TTY attached now wait for an answer; run them through the MCP server
+  or without a terminal if no person is there.
+- **`speed-up`** replaces only transactions that move no value; a stuck `fund` is never
+  replaced (`SPEEDUP_REFUSED`) — it keeps counting toward the limit until its nonce is used.
+  An entry from a 0.1.0 journal is not sped up.
+- **`watch`**: the `--exec` command gets `CASCROW_ALARM` (`claim.open`, `watch.blind`,
+  `watch.recovered`) — check it in your script if it should only page on claims. `--once`
+  exits non-zero when it could not read the chain.
+
+Replacing a wallet that is already linked now needs the current wallet's consent when you use
+an API key: `cascrow-signer link --old-home <directory of the old keystore>`. If the old key is
+lost, change the wallet from a signed-in cascrow session (password or 2FA), or contact support.
+
 ## From `cascrow_escrow_fund` / `escrowFund()` / `cascrow escrow-fund --private-key`
 
 Those paths sent your private key to cascrow, which signed the deposit on its servers.
@@ -11,7 +54,7 @@ do not link the old address again (cascrow refuses it anyway).
 |---|---|
 | `cascrow_escrow_fund { agentPrivateKey, … }` | `cascrow_signer_fund { milestoneId }` in this package's MCP server |
 | `client.escrowFund({ privateKey, … })` | `createSigner(configFromEnv(process.env, io)).fund({ milestoneId })` |
-| `cascrow escrow-fund --private-key …` | `npx cascrow-signer@0.1.0 fund --milestone <id>` |
+| `cascrow escrow-fund --private-key …` | `npx cascrow-signer@0.3.0 fund --milestone <id>` |
 | the wallet cascrow generated at registration | `cascrow-signer init` + `cascrow-signer link` |
 
 ## v2 (RLUSD) escrows

package/README.md

@@ -15,23 +15,36 @@ it signs against what it knows independently of cascrow.
 Install a pinned version — never `@latest` for a tool that holds money:
 
 ```sh
-npx cascrow-signer@0.1.0 help
+npx cascrow-signer@0.3.0 help
 ```
 
-> **Status: unreleased.** The MilestoneEscrowV3 contract is not deployed yet, so every
-> network is refused until a version with a pinned deployment ships. On testnet a
-> deployment can be named explicitly (see *Testnet override*).
+> **Status: released (0.1.0, on npm since 2026-09-27).** MilestoneEscrowV3 is deployed on
+> the XRPL EVM testnet (chain 1449000) and pinned in this package. Mainnet has no
+> deployment yet, so mainnet stays refused until a version with a pinned mainnet
+> deployment ships. On testnet a deployment can also be named explicitly (see
+> *Testnet override*).
 
 ## Setup
 
 ```sh
 export CASCROW_SIGNER_NETWORK=testnet          # or mainnet — never guessed
 cascrow-signer init                             # new key, encrypted keystore in ~/.cascrow/signer
-cascrow-signer policy set --per-escrow-xrp 500 --daily-xrp 2000 --min-review-hours 72
+cascrow-signer policy set --per-escrow-xrp 500 --daily-xrp 2000 --min-review-hours 72 --max-deadline-days 365
 export CASCROW_API_KEY=csk_…                    # your cascrow account
 cascrow-signer link                             # proves this address is yours to cascrow
 ```
 
+`link` signs cascrow's Sign-In with Ethereum (EIP-4361) challenge only after rebuilding it
+from the challenge token: it must name the host of `CASCROW_BASE_URL`, this key's address and
+the pinned chain, and must not have expired. To REPLACE a wallet already linked to the
+account, cascrow wants the current wallet's signature too: keep its keystore and run
+`cascrow-signer link --old-home <its directory>` on a terminal (or change the wallet from a
+signed-in cascrow session, which asks for your password or 2FA).
+
+`policy set` replaces the whole policy (limits in XRP, counterparty and arbiter lists, minimum
+review period, maximum deadline — default 365 days — and `--allow-agent-return-funds`, off by
+default). It works on a terminal only.
+
 `~/.cascrow/signer` is created `0700`, every file in it `0600`; a file other users can
 read is refused, not repaired. Set `CASCROW_SIGNER_HOME` to use another directory.
 
@@ -44,8 +57,8 @@ read. There is no OS-keychain integration on purpose (native dependency, supply
 ```sh
 cascrow-signer fund --milestone <id>             # one transaction, value = amount, no approve
 cascrow-signer claims                            # live claims on your escrows, read from the chain
-cascrow-signer watch --exec ./page-me.sh         # alarm for every claim whose window is open
-cascrow-signer object --escrow 0x… --reason "Criterion 2 is not met: …"
+cascrow-signer watch --exec ./page-me.sh         # alarm for every claim whose window is open — and when it is blind
+cascrow-signer object --escrow 0x… --reason "Criterion 2 is not met: …"   # result: reasonHash + reasonSalt — keep the salt
 cascrow-signer release --escrow 0x…
 cascrow-signer extend-deadline --escrow 0x… --new-deadline 1767225600
 ```
@@ -54,9 +67,18 @@ Before `fund` signs, it checks — against values it knows itself, not the serve
 the escrow ID is `escrowIdFor(your address, ref, salt)`; the token is native XRP; `value`
 equals the amount; the amount is within your per-escrow limit (a lower one for a payee not
 in your counterparty book) and your rolling 24-hour limit; the arbiter is absent or one you
-listed; the review period is at least your minimum; the deadline is within the contract's
-maximum and `acceptBy` still open **by chain time**; and the payee's signature verifies
-under the pinned chain and contract. The escrow is then written to your local book.
+listed; the review period is at least your minimum; the deadline is within your policy's
+maximum (default 365 days; the contract allows five years) and `acceptBy` still open **by
+chain time**; and the payee's signature verifies under the pinned chain and contract. On a
+terminal it then shows you the terms and asks before it signs. The escrow is then written
+to your local book.
+
+The 24-hour limit is kept in a local spending journal whose every line carries a MAC chained
+to the one before it (a key derived from your private key, like the policy's). A journal that
+was changed by anything but this signer is refused for `fund` (`JOURNAL_TAMPERED`, with the
+way out: move it aside, and the next fund rebuilds today's total from the chain). It never
+blocks an objection. A 0.1.0 journal is upgraded on the first transaction: its reservations
+keep counting, its releases do not.
 
 After funding, `object`, `release`, `refund`, `extend-deadline`, `claim`, `withdraw` and
 `return-funds` are built from the escrow ID and the chain alone — **cascrow does not need
@@ -68,8 +90,18 @@ escrows in your local book whose on-chain payer is you. When cascrow is reachabl
 `COMPLIANCE_BLOCK`), the signer stops and shows that refusal instead of sending anyway;
 only an unreachable cascrow, a 5xx, a rate limit or a bad API key count as "not available".
 
+`extend-deadline` never moves the deadline further than your policy's maximum from now.
+
 A pending objection that is not being mined: `cascrow-signer speed-up --tx <hash>`
-(same nonce, fee +25%). Never send the same action twice.
+(same nonce, fee +25%). Only a transaction this signer recorded in its intact journal and
+that moves no value is replaced — a funding never is — and it is checked against the chain
+again first. Never send the same action twice.
+
+`watch` keeps a cursor and reads only new blocks after its first round. When it cannot read
+the chain for `--blind-after` rounds in a row (default 3) it raises a `watch.blind` alarm
+through the same `--exec` command and webhook (the command sees `CASCROW_ALARM=watch.blind`;
+a claim is `CASCROW_ALARM=claim.open`), and a `watch.recovered` one when it reads again.
+`watch --once` exits non-zero when it could not read the chain.
 
 ## As payee
 
@@ -80,8 +112,8 @@ cascrow-signer return-funds --escrow 0x…
 ```
 
 `accept` refuses an offer whose payee is not your address, whose token is not native XRP,
-whose arbiter you have not listed, or whose `acceptBy` has passed. **Your acceptance binds
-you until `acceptBy`** — the payer can fund these exact terms until then, and nothing in
+whose arbiter you have not listed, or whose `acceptBy` has passed; on a terminal it shows the
+terms and asks first. **Your acceptance binds you until `acceptBy`** — the payer can fund these exact terms until then, and nothing in
 cascrow revokes it.
 
 `submit-claim` claims with ONE sealed submission. Every evidence upload (one request —
@@ -94,11 +126,15 @@ claim naming evidence cascrow never assessed has no recommendation and invites a
 objection. Claim with a submission whose verdict is YES (`claimReady`); with NO or PENDING
 the payer is likely to object.
 
+`return-funds` gives the escrow back to the payer for good. On a terminal it asks first;
+through the MCP server it is refused (`RETURN_FUNDS_NEEDS_TERMINAL`) unless you allowed it
+on a terminal with `cascrow-signer policy set … --allow-agent-return-funds`.
+
 ## As an MCP server
 
 ```json
 { "mcpServers": { "cascrow-signer": {
-    "command": "npx", "args": ["cascrow-signer@0.1.0", "mcp"],
+    "command": "npx", "args": ["cascrow-signer@0.3.0", "mcp"],
     "env": { "CASCROW_SIGNER_NETWORK": "testnet", "CASCROW_API_KEY": "csk_…",
              "CASCROW_KEYSTORE_PASSPHRASE_FILE": "/home/me/.cascrow/pass" } } } }
 ```
@@ -107,7 +143,9 @@ Tools: `cascrow_signer_status`, `_link`, `_accept`, `_fund`, `_submit_claim`, `_
 `_release`, `_extend_deadline`, `_claim`, `_refund`, `_return_funds`, `_withdraw`,
 `_onchain_claims`, `_speed_up`. They are all local; cascrow's hosted MCP server and the
 `cascrow-mcp` package offer none of them, and no tool takes a key or a passphrase. The
-policy cannot be changed through MCP — only on a terminal.
+policy cannot be changed through MCP — only on a terminal. The MCP server never asks a
+question: what bounds it is the policy (limits, maximum deadline, and `_return_funds` only
+with the opt-in).
 
 Use it next to `cascrow-mcp` (or the hosted server), which carries the remote
 `cascrow_v3_*` tools: offers, acceptance data, prepared transactions, attestations.

package/SECURITY.md

@@ -8,7 +8,7 @@ contract (rule I9). This package is where the key lives. The line between the tw
 
 | Leaves this machine for cascrow | Never leaves this machine |
 |---|---|
-| the wallet-link signature over cascrow's fixed challenge sentence | the private key |
+| wallet-challenge signatures (link; on a re-point, the old wallet's consent) over a Sign-In with Ethereum message the signer rebuilt and checked | the private key |
 | the payee's acceptance signature (EIP-712, pinned domain) | the passphrase |
 | a transaction **hash**, as a hint to re-read the chain | the keystore file |
 | your API key, as the `Authorization` header | any signed transaction |
@@ -24,14 +24,30 @@ transaction.
 
 - **A wrong or compromised cascrow API.** Chain ID, contract address and runtime code hash
   come from the package, not from the server; every term of a `fund` is checked against
-  your address, your policy, the chain's clock and the payee's signature under the pinned
+  your address, your policy (amount limits, counterparty book, arbiter list, minimum review
+  period, maximum deadline), the chain's clock and the payee's signature under the pinned
   domain; `data` is rebuilt from the ABI. A server can refuse to help you, but it cannot
   make this signer fund different terms, pay a different contract or sign a message that is
   not the wallet challenge.
 - **A confused or prompt-injected agent driving the MCP tools.** Limits per escrow and per
-  24 hours, a lower limit for unknown payees, the arbiter allowlist and the minimum review
-  period are enforced locally; the policy can only be changed on a terminal, and its file
+  24 hours, a lower limit for unknown payees, the arbiter allowlist, the minimum review
+  period and the maximum deadline (default 365 days, for `fund` and `extend-deadline`; the
+  contract itself allows five years) are enforced locally; `return-funds` — which gives the
+  escrow back for good — is refused through MCP unless you allowed it on a terminal
+  (`--allow-agent-return-funds`). The policy can only be changed on a terminal, and its file
   carries a MAC under a key derived from your private key.
+- **A person at the terminal signing what they did not read.** On a terminal, `fund`,
+  `accept` and `return-funds` print the terms (amount, counterparty, deadline, review period,
+  arbiter) and ask y/N before anything is signed; a "no" signs nothing.
+- **A process that can write the signer's directory but cannot unlock the key** — for the
+  spending journal too, not only the policy and the escrow book. Every journal line carries
+  a MAC chained to the line before it, under a key derived from your private key. A line
+  that was forged, edited, reordered or removed in the middle breaks the chain, and `fund`
+  is then refused (`JOURNAL_TAMPERED`) instead of computing your 24-hour limit over it;
+  `speed-up` re-signs only an authentic entry, only one that moves no value, and only after
+  decoding its calldata and checking the action against the chain again. The journal never
+  holds a signature or a signed transaction. Actions that do not spend from the limit
+  (`object` above all) are never blocked by a damaged journal; they say so in a warning.
 - **Losing cascrow.** Every action after funding but `submitClaim` works from the chain
   alone; the watcher reads your escrows from the chain. `object` needs neither cascrow nor
   the local book — only that the chain names this key as the payer. `submitClaim` needs
@@ -40,8 +56,15 @@ transaction.
   than max(review period, 72 h, 25 % of the remaining term) before the deadline: the payer
   can fund at any moment up to `acceptBy`, so what follows `acceptBy` is the payee's
   guaranteed time to deliver.
-- **A deleted journal.** Today's spending is rebuilt from `Funded(payer = you)` events; if
-  neither is readable, `fund` is refused.
+- **A deleted, cut or rolled-back journal.** Today's spending is, per escrow, the larger of
+  what the journal reserved and what the chain's `Funded(payer = you)` events of the last
+  24 hours say. A journal that cannot stand alone for the whole window — missing, written by
+  0.1.0, or recreated less than 24 hours ago — needs the chain: if the chain cannot be read,
+  `fund` is refused.
+- **A blind watcher.** `watch` raises an alarm through your `--exec` command and webhook not
+  only for an open claim but also when it could not read the chain for `--blind-after`
+  rounds in a row (default 3), and again when it can read again; `watch --once` exits
+  non-zero when it could not read the chain.
 
 ## What it does NOT protect against
 
@@ -55,11 +78,15 @@ transaction.
   And until `acceptBy` the payer holds a free option to fund or let the offer lapse; the
   payee's minimum work window (above) bounds what that option can cost the payee.
 - **A process that can read your passphrase.** It can unlock the key, recompute the policy
-  MAC and write any limits it likes. If an agent runs with `CASCROW_KEYSTORE_PASSPHRASE` in
+  and journal MACs and write any limits it likes. If an agent runs with `CASCROW_KEYSTORE_PASSPHRASE` in
   its environment or can read the passphrase file, the policy stops honest mistakes, not
   that agent. Run the signer as a separate user or on a separate machine if that matters.
 - **Malware on the machine**, a compromised Node.js, or a compromised `ethers` (pinned
   exactly and shrinkwrapped, so an upgrade is a visible change — not a guarantee).
+- **The newest lines of the journal being cut off, or an older copy put back.** The MAC chain
+  cannot see that the tail is missing. A funding that is already on chain is still counted
+  (the chain's `Funded` events); a funding still in flight when its lines were cut is not,
+  so the 24-hour limit can be exceeded by at most the amounts in flight at that moment.
 - **A compromised release of this package.** Install a pinned version and check it.
 - **The public RPC lying about chain state** (it cannot forge your signature, but it could
   hide a claim from `watch`). Point `watch` at a second RPC you trust if the review window

package/dist/acceptance.d.ts

@@ -53,6 +53,13 @@ export type AcceptInput = {
     milestoneId: string;
     minAmountXrp?: string;
 };
+/**
+ * The free veto of an escrow without an arbiter (cascrow S-05, accepted on the
+ * condition that the payee knows before signing). The same words as cascrow's
+ * V3_CLIENT_TEXT.noArbiterVeto, which this package cannot import —
+ * v3-acceptance-veto-disclosure.test.ts holds the two equal.
+ */
+export declare const NO_ARBITER_VETO = "No arbiter is named. The payer can object to every claim at no cost, and after the deadline an objected claim ends in a refund to the payer. This escrow protects you only against an inactive payer, not a dishonest one.";
 export declare function accept(ctx: SignerContext, input: AcceptInput): Promise<{
     accepted: boolean;
     escrowId: string;

package/dist/acceptance.js

@@ -8,7 +8,7 @@
  * is rebuilt here from checked values, under the PINNED domain (this package's
  * chain ID and contract), with the contract's own types.
  */
-import { ZeroAddress, getAddress, isAddress, parseEther } from "ethers";
+import { ZeroAddress, formatEther, getAddress, isAddress, parseEther } from "ethers";
 import { refuse } from "./errors.js";
 import { ACCEPTANCE_PRIMARY_TYPE, ACCEPTANCE_TYPES, V3_LIMITS, acceptanceDomain, escrowIdFor } from "./calldata.js";
 import { latestBlock } from "./chain.js";
@@ -16,6 +16,7 @@ import { ACCEPT_BY_MARGIN_SECONDS } from "./checks.js";
 import { Book } from "./book.js";
 import { loadPolicy } from "./policy.js";
 import { verifyEndpoint } from "./network.js";
+import { confirmOnTerminal } from "./actions.js";
 const lc = (s) => String(s ?? "").toLowerCase();
 /** The floor of the payee's work window, whatever the review period and term (the app's MIN_WORK_FLOOR_SEC). */
 export const MIN_WORK_FLOOR_SECONDS = 72 * 3600;
@@ -117,6 +118,13 @@ export function checkAcceptance(o, ctx) {
         refuse("ACCEPTANCE_CHECK_FAILED", `refused before signing: ${r.join("; ")}`);
     return msg;
 }
+/**
+ * The free veto of an escrow without an arbiter (cascrow S-05, accepted on the
+ * condition that the payee knows before signing). The same words as cascrow's
+ * V3_CLIENT_TEXT.noArbiterVeto, which this package cannot import —
+ * v3-acceptance-veto-disclosure.test.ts holds the two equal.
+ */
+export const NO_ARBITER_VETO = "No arbiter is named. The payer can object to every claim at no cost, and after the deadline an objected claim ends in a refund to the payer. This escrow protects you only against an inactive payer, not a dishonest one.";
 export async function accept(ctx, input) {
     if (!input.milestoneId)
         refuse("INPUT", "milestoneId is required");
@@ -141,6 +149,17 @@ export async function accept(ctx, input) {
         arbiters,
         minAmountWei: input.minAmountXrp ? parseEther(input.minAmountXrp) : null,
     });
+    // A person at a terminal sees the terms that will bind them and says yes (S-02).
+    await confirmOnTerminal(ctx, "Sign this acceptance?", [
+        `You are about to ACCEPT an escrow offer on ${ctx.net.name} (chain ${ctx.net.chainId}, contract ${ctx.net.address}):`,
+        `  payer:           ${getAddress(offer.payer)}`,
+        `  amount:          ${formatEther(msg.amount)} XRP`,
+        `  deadline:        ${new Date(Number(msg.deadline) * 1000).toISOString()} — your work must be claimed before then`,
+        `  review period:   ${(msg.reviewPeriod / 3600).toFixed(1)} h — the payer's time to object to your claim`,
+        `  arbiter:         ${msg.arbiter === ZeroAddress ? "none" : `${msg.arbiter} (arbitration period ${(msg.arbitrationPeriod / 86400).toFixed(1)} days)`}`,
+        `  binding until    ${new Date(Number(msg.acceptBy) * 1000).toISOString()} — the payer can fund these exact terms until then, and nothing in cascrow revokes it`,
+        ...(msg.arbiter === ZeroAddress ? [`  WARNING:         ${NO_ARBITER_VETO}`] : []),
+    ]);
     const signature = await key.signTypedData(acceptanceDomain(ctx.net.chainId, ctx.net.address), ACCEPTANCE_TYPES, { ...msg });
     const answer = await ctx.remote.submitAcceptance(offer.offerId, signature);
     new Book(ctx.home, key.macKey).add({
@@ -164,6 +183,7 @@ export async function accept(ctx, input) {
         reviewPeriod: msg.reviewPeriod,
         arbiter: msg.arbiter,
         server: { escrowId: answer.escrowId ?? null, acceptBy: answer.acceptBy ?? null },
-        note: "Your signature binds you until acceptBy: the payer can fund these exact terms until then, and nothing in cascrow revokes it.",
+        note: "Your signature binds you until acceptBy: the payer can fund these exact terms until then, and nothing in cascrow revokes it." +
+            (msg.arbiter === ZeroAddress ? ` ${NO_ARBITER_VETO}` : ""),
     };
 }

package/dist/actions.d.ts

@@ -1,5 +1,8 @@
 import { PER_ESCROW_ACTIONS } from "./calldata.js";
 import type { SignerAction } from "./calldata.js";
+import type { FundTerms } from "./checks.js";
+import type { SendResult } from "./chain.js";
+import type { UnlockedKey } from "./keystore.js";
 import { RemoteError } from "./remote.js";
 import type { V3EscrowAction } from "./generated/v3-actions.js";
 import type { SignerContext } from "./context.js";
@@ -13,6 +16,14 @@ export type ActionResult = {
     notes: string[];
     [k: string]: unknown;
 };
+/**
+ * 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 declare function confirmOnTerminal(ctx: SignerContext, question: string, lines: string[]): Promise<void>;
+/** What a payer's `fund` commits to, in the words a person checks (S-02). */
+export declare function fundSummary(ctx: Pick<SignerContext, "net">, f: FundTerms, payeeKnown: boolean): string[];
 export type FundInput = {
     milestoneId: string;
     maxAmountXrp?: string;
@@ -38,7 +49,10 @@ export declare function localProofHash(milestoneId: string, ev: EvidenceInput):
 export type EscrowActionInput = {
     escrowId?: string;
     milestoneId?: string;
-    /** object: the objection reason; its keccak256 goes on chain. */
+    /**
+     * object: the objection reason. On chain goes keccak256(salt ‖ utf8(reason)) with a
+     * salt made here (reason.ts); the reason and the salt never leave this machine.
+     */
     reason?: string;
     /** extendDeadline: unix seconds. */
     newDeadline?: string | number;
@@ -57,4 +71,16 @@ export declare function isPrepareRefusal(e: unknown): e is RemoteError;
 export declare function escrowAction(ctx: SignerContext, action: V3EscrowAction, input: EscrowActionInput): Promise<ActionResult>;
 /** withdraw(own account, native XRP): pays this key's credit to this key. No escrow, no cascrow. */
 export declare function withdraw(ctx: SignerContext): Promise<ActionResult>;
+/**
+ * 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 declare function speedUp(ctx: SignerContext, key: UnlockedKey, txHash: string): Promise<SendResult>;
 export { PER_ESCROW_ACTIONS };