cascrow-signer 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 0.1.0 — unreleased (owner publishes)
+
+- 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
+  allowlists, minimum review period — terminal only, MAC-protected), `link`, `accept`,
+  `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).
+- 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
+  milestone; a hash computed from a local file must be confirmed the same way
+  (`CLAIM_PROOF_UNKNOWN` otherwise, no override).
+- A cascrow `prepare` that answers with a refusal (4xx and its code) is surfaced as that
+  refusal, with its remedy; only an unreachable cascrow, a 5xx, a non-JSON answer, 401, 408
+  or 429 count as "not available" and let a post-funding action proceed from the chain.
+- `object` is gated on the chain alone (the on-chain payer is this key); only `release` and
+  `extend-deadline` need the local book, and a damaged book is a loud note, not an abort,
+  for every other action.
+- The CLI removes `CASCROW_KEYSTORE_PASSPHRASE` and `_FILE` from its environment at start
+  for every command; a `watch --exec` command gets an allowlisted environment.
+- `accept` refuses an offer that leaves the payee less than max(review period, 72 h, 25 %
+  of the term) between `acceptBy` and the deadline.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cascrow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,35 @@
+# Migrating to cascrow-signer
+
+## 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.
+They were removed in cascrow-mcp 2.0.0, cascrow-sdk 0.5.0 and cascrow-cli 2.0.0.
+**If you ever used one, treat that key as exposed**: move its funds to a new wallet, and
+do not link the old address again (cascrow refuses it anyway).
+
+| Before | Now |
+|---|---|
+| `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>` |
+| the wallet cascrow generated at registration | `cascrow-signer init` + `cascrow-signer link` |
+
+## v2 (RLUSD) escrows
+
+Unchanged: `GET /api/agent/escrow-prepare` returns the two unsigned transactions (approve,
+fund); sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. This
+package signs MilestoneEscrowV3 only.
+
+## MilestoneEscrowV3, step by step
+
+1. Payer: `cascrow_v3_offer` (remote, cascrow-mcp / SDK `v3.offer` / `cascrow v3 offer`).
+2. Payee: `cascrow-signer accept --milestone <id>`.
+3. Payer: `cascrow-signer fund --milestone <id>`.
+4. Payee: work, submit evidence to cascrow for the AI recommendation, then
+   `cascrow-signer submit-claim --milestone <id> --file …`.
+5. Payer: within the review period, `release` — or `object` with a reason. `watch` makes
+   sure you see the claim; cascrow's notifications are a convenience, not the guarantee.
+
+A cascrow verification of `YES` on a V3 milestone is a **recommendation** and moves no
+money: only the payer's `release`, an unobjected claim running out its review period
+(`claim`), or the arbiter pays the payee.

package/README.md

@@ -0,0 +1,130 @@
+# cascrow-signer
+
+Your key for cascrow's **MilestoneEscrowV3** escrows — generated, encrypted and used on
+your machine only. cascrow verifies work, keeps the audit trail and prepares transactions;
+it never holds, receives or uses your key, and it never sends, relays or pays for a
+transaction on your behalf. This package is the part that signs, and it checks everything
+it signs against what it knows independently of cascrow.
+
+- One runtime dependency (`ethers`, pinned exactly) and a shrinkwrap, so the code that
+  touches your key can be read end to end.
+- The chain, the public RPC and the escrow contract's address and code hash are **pinned in
+  the package**. A network without a pinned deployment is refused.
+- Transactions go to the network's **public RPC**, never to cascrow.
+
+Install a pinned version — never `@latest` for a tool that holds money:
+
+```sh
+npx cascrow-signer@0.1.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*).
+
+## 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
+export CASCROW_API_KEY=csk_…                    # your cascrow account
+cascrow-signer link                             # proves this address is yours to cascrow
+```
+
+`~/.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.
+
+**Passphrase**: a terminal prompt, `CASCROW_KEYSTORE_PASSPHRASE_FILE` (a `0600` file), or
+`CASCROW_KEYSTORE_PASSPHRASE`. Either variable is removed from the process environment once
+read. There is no OS-keychain integration on purpose (native dependency, supply chain).
+
+## As payer
+
+```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 release --escrow 0x…
+cascrow-signer extend-deadline --escrow 0x… --new-deadline 1767225600
+```
+
+Before `fund` signs, it checks — against values it knows itself, not the server's word:
+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.
+
+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
+to be reachable** for you to object. `object` is signed whenever the chain names you as
+the escrow's payer — it does not need the local book, so a lost or damaged book never
+costs you an objection window. `release` and `extend-deadline` are signed only for
+escrows in your local book whose on-chain payer is you. When cascrow is reachable and
+**refuses** to prepare an action (an answer with a code, e.g. `WRONG_PHASE` or
+`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".
+
+A pending objection that is not being mined: `cascrow-signer speed-up --tx <hash>`
+(same nonce, fee +25%). Never send the same action twice.
+
+## As payee
+
+```sh
+cascrow-signer accept --milestone <id>           # checks and signs the payer's offer
+cascrow-signer submit-claim --milestone <id> --proof-hash 0x…    # the manifestHash the upload returned
+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
+cascrow revokes it.
+
+`submit-claim` claims with ONE sealed submission. Every evidence upload (one request —
+today one file, one text or one GitHub item) is its own submission, and its answer carries
+the submission's `manifestHash`: pass that as `--proof-hash`. Instead you can pass the one
+file of that submission (`--file report.pdf`) and the hash is computed here with the same
+manifest encoding cascrow uses. Either way cascrow must confirm the hash is a sealed
+submission of the milestone (`CLAIM_PROOF_UNKNOWN` otherwise) before anything is signed — a
+claim naming evidence cascrow never assessed has no recommendation and invites an
+objection. Claim with a submission whose verdict is YES (`claimReady`); with NO or PENDING
+the payer is likely to object.
+
+## As an MCP server
+
+```json
+{ "mcpServers": { "cascrow-signer": {
+    "command": "npx", "args": ["cascrow-signer@0.1.0", "mcp"],
+    "env": { "CASCROW_SIGNER_NETWORK": "testnet", "CASCROW_API_KEY": "csk_…",
+             "CASCROW_KEYSTORE_PASSPHRASE_FILE": "/home/me/.cascrow/pass" } } } }
+```
+
+Tools: `cascrow_signer_status`, `_link`, `_accept`, `_fund`, `_submit_claim`, `_object`,
+`_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.
+
+Use it next to `cascrow-mcp` (or the hosted server), which carries the remote
+`cascrow_v3_*` tools: offers, acceptance data, prepared transactions, attestations.
+
+## Testnet override
+
+For a testnet deployment the package does not pin yet — only one you deployed or verified
+yourself:
+
+```sh
+CASCROW_SIGNER_TESTNET_CONTRACT=0x… CASCROW_SIGNER_TESTNET_DEPLOY_BLOCK=123 \
+CASCROW_SIGNER_TESTNET_CODE_HASH=0x… [CASCROW_SIGNER_TESTNET_RPC_URL=…] cascrow-signer status
+```
+
+Every use prints a warning. There is no override for mainnet.
+
+## Windows
+
+POSIX permission checks are skipped on Windows; protect `%USERPROFILE%\.cascrow\signer`
+yourself. See [SECURITY.md](SECURITY.md) for what this package does and does not protect.

package/SECURITY.md

@@ -0,0 +1,71 @@
+# Security — what cascrow-signer protects, and what it does not
+
+## The boundary
+
+cascrow (the service) prepares, reads and recommends. It never creates, holds, receives
+or uses a party's key, and never sends, relays or pays for a transaction to the escrow
+contract (rule I9). This package is where the key lives. The line between the two:
+
+| Leaves this machine for cascrow | Never leaves this machine |
+|---|---|
+| the wallet-link signature over cascrow's fixed challenge sentence | 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 |
+
+Signed transactions go to the network's public RPC only (pinned in the package). The
+complete list of calls to cascrow is in `src/remote.ts`. A test in the cascrow repository
+(`signer-canary.test.ts`) runs every action with a random key and passphrase against a fake
+cascrow and a fake RPC and fails if any URL, header, body, stdout/stderr line or tool
+result contains the key, the passphrase, the keystore ciphertext or a raw signed
+transaction.
+
+## What the checks protect against
+
+- **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
+  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
+  carries a MAC under a key derived from your private key.
+- **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
+  cascrow's confirmation that the proof hash is a sealed submission of the milestone.
+- **Cheating the payee on time.** `accept` refuses an offer whose `acceptBy` leaves less
+  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.
+
+## What it does NOT protect against
+
+- **A compromised cascrow server, on the payee's side, within your own limits.** A payee's
+  acceptance signature can be funded by the payer until `acceptBy`; the server only relays
+  it. A compromised server can therefore get a fund to a payee who signed an acceptance —
+  never different terms, never above your local limits. In MCP mode (no terminal) a payee
+  not in your counterparty book is funded only up to `unknownPayeePerEscrowMaxWei`, so that
+  is the most a compromised server plus a driven agent can place with an unknown payee per
+  escrow (and your 24-hour limit across escrows). Set it low, or add payees on a terminal.
+  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
+  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).
+- **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
+  is short.
+- **Windows file permissions** — not checked there.
+
+## Reporting
+
+security@cascrow.com. Please do not open a public issue for a vulnerability.

package/dist/acceptance.d.ts

@@ -0,0 +1,70 @@
+import type { SignerNetwork } from "./network.js";
+import type { SignerContext } from "./context.js";
+export type AcceptanceOffer = {
+    offerId: string;
+    escrowId: string;
+    payer: string;
+    ref: string;
+    salt: string;
+    amountWei: string;
+    acceptBy: string | number;
+    typedData: {
+        domain: Record<string, unknown>;
+        types: Record<string, {
+            name: string;
+            type: string;
+        }[]>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    };
+};
+export type AcceptanceMessage = {
+    escrowId: string;
+    payee: string;
+    token: string;
+    amount: bigint;
+    deadline: bigint;
+    reviewPeriod: number;
+    arbiter: string;
+    arbitrationPeriod: number;
+    acceptBy: bigint;
+};
+/** The floor of the payee's work window, whatever the review period and term (the app's MIN_WORK_FLOOR_SEC). */
+export declare const MIN_WORK_FLOOR_SECONDS: number;
+/**
+ * The least time the payee must have between the last moment the payer can fund
+ * (`acceptBy`) and the deadline: max(review period, 72 h, 25 % of the remaining
+ * term). The same formula cascrow applies when it issues the offer
+ * (`minWorkWindowSec` in the app's v3-terms.ts). Checked HERE as well, because the
+ * payer holds a free fund-or-lapse option until `acceptBy`: a compromised server
+ * could otherwise hand the payee an offer whose acceptBy sits right before the
+ * deadline, and a funding at the last moment would leave no time to deliver.
+ */
+export declare function minWorkWindowSeconds(reviewPeriodSec: number, deadlineSec: bigint | number, nowSec: bigint | number): number;
+/** Every check on an offer before the payee signs it. Pure. Returns the message to sign, rebuilt from checked values. */
+export declare function checkAcceptance(o: AcceptanceOffer, ctx: {
+    me: string;
+    net: Pick<SignerNetwork, "chainId" | "address">;
+    chainNowSec: number;
+    arbiters: readonly string[];
+    minAmountWei?: bigint | null;
+}): AcceptanceMessage;
+export type AcceptInput = {
+    milestoneId: string;
+    minAmountXrp?: string;
+};
+export declare function accept(ctx: SignerContext, input: AcceptInput): Promise<{
+    accepted: boolean;
+    escrowId: string;
+    payer: string;
+    amountWei: string;
+    acceptBy: string;
+    deadline: string;
+    reviewPeriod: number;
+    arbiter: string;
+    server: {
+        escrowId: {} | null;
+        acceptBy: {} | null;
+    };
+    note: string;
+}>;

package/dist/acceptance.js

@@ -0,0 +1,169 @@
+/**
+ * The payee's acceptance, signed on this machine after checking it against what
+ * the payee knows independently of cascrow.
+ *
+ * The signature is irrevocable until `acceptBy`: whoever holds it can fund the
+ * escrow with exactly these terms, and deleting anything in cascrow does not take
+ * it back. So nothing from the server's typed data is signed as-is — the message
+ * 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 { refuse } from "./errors.js";
+import { ACCEPTANCE_PRIMARY_TYPE, ACCEPTANCE_TYPES, V3_LIMITS, acceptanceDomain, escrowIdFor } from "./calldata.js";
+import { latestBlock } from "./chain.js";
+import { ACCEPT_BY_MARGIN_SECONDS } from "./checks.js";
+import { Book } from "./book.js";
+import { loadPolicy } from "./policy.js";
+import { verifyEndpoint } from "./network.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;
+/**
+ * The least time the payee must have between the last moment the payer can fund
+ * (`acceptBy`) and the deadline: max(review period, 72 h, 25 % of the remaining
+ * term). The same formula cascrow applies when it issues the offer
+ * (`minWorkWindowSec` in the app's v3-terms.ts). Checked HERE as well, because the
+ * payer holds a free fund-or-lapse option until `acceptBy`: a compromised server
+ * could otherwise hand the payee an offer whose acceptBy sits right before the
+ * deadline, and a funding at the last moment would leave no time to deliver.
+ */
+export function minWorkWindowSeconds(reviewPeriodSec, deadlineSec, nowSec) {
+    const term = Number(BigInt(deadlineSec) - BigInt(nowSec));
+    return Math.max(reviewPeriodSec, MIN_WORK_FLOOR_SECONDS, Math.floor(Math.max(0, term) * 0.25));
+}
+/** Every check on an offer before the payee signs it. Pure. Returns the message to sign, rebuilt from checked values. */
+export function checkAcceptance(o, ctx) {
+    const r = [];
+    if (!o || typeof o !== "object" || !o.typedData || typeof o.typedData !== "object")
+        refuse("ACCEPTANCE_CHECK_FAILED", "refused before signing: no typed data");
+    const d = o.typedData.domain ?? {};
+    const pinned = acceptanceDomain(ctx.net.chainId, ctx.net.address);
+    if (d.name !== pinned.name || d.version !== pinned.version)
+        r.push("the domain name/version is not the contract's");
+    if (String(d.chainId) !== String(pinned.chainId))
+        r.push("the domain chainId is not the pinned chain");
+    if (lc(d.verifyingContract) !== lc(pinned.verifyingContract))
+        r.push("the domain verifyingContract is not the pinned contract");
+    const types = { ...(o.typedData.types ?? {}) };
+    delete types.EIP712Domain;
+    if (JSON.stringify(types) !== JSON.stringify(ACCEPTANCE_TYPES))
+        r.push("the types are not the contract's PayeeAcceptance");
+    if (o.typedData.primaryType !== ACCEPTANCE_PRIMARY_TYPE)
+        r.push("primaryType is not PayeeAcceptance");
+    const m = o.typedData.message ?? {};
+    let msg = null;
+    try {
+        msg = {
+            escrowId: lc(m.escrowId),
+            payee: getAddress(String(m.payee)),
+            token: getAddress(String(m.token)),
+            amount: BigInt(String(m.amount)),
+            deadline: BigInt(String(m.deadline)),
+            reviewPeriod: Number(m.reviewPeriod),
+            arbiter: getAddress(String(m.arbiter)),
+            arbitrationPeriod: Number(m.arbitrationPeriod),
+            acceptBy: BigInt(String(m.acceptBy)),
+        };
+    }
+    catch {
+        refuse("ACCEPTANCE_CHECK_FAILED", "refused before signing: the message does not parse");
+    }
+    if (msg.payee !== getAddress(ctx.me))
+        r.push("the payee is not this key");
+    if (!isAddress(o.payer) || getAddress(o.payer) === getAddress(ctx.me))
+        r.push("the payer is missing or is this key");
+    else if (lc(escrowIdFor(o.payer, o.ref, o.salt)) !== msg.escrowId)
+        r.push("escrowId is not escrowIdFor(payer, ref, salt)");
+    if (lc(o.escrowId) !== msg.escrowId)
+        r.push("the offer's escrowId and the message's differ");
+    if (msg.token !== ZeroAddress)
+        r.push("the token is not native XRP");
+    if (msg.amount <= BigInt(0) || String(o.amountWei) !== msg.amount.toString())
+        r.push("the amount is zero or differs from the offer's amountWei");
+    if (ctx.minAmountWei && msg.amount < ctx.minAmountWei)
+        r.push("the amount is below the minimum you named");
+    if (String(o.acceptBy) !== msg.acceptBy.toString() && String(Math.floor(Date.parse(String(o.acceptBy)) / 1000)) !== msg.acceptBy.toString()) {
+        r.push("the offer's acceptBy and the message's differ");
+    }
+    const now = BigInt(ctx.chainNowSec);
+    if (msg.acceptBy < now + BigInt(ACCEPT_BY_MARGIN_SECONDS))
+        r.push("acceptBy has passed on chain (or is within two minutes)");
+    if (msg.deadline <= msg.acceptBy)
+        r.push("the deadline is not after acceptBy");
+    else {
+        const minWork = minWorkWindowSeconds(msg.reviewPeriod, msg.deadline, now);
+        if (msg.acceptBy > msg.deadline - BigInt(minWork)) {
+            r.push(`a funding at acceptBy would leave less than ${Math.ceil(minWork / 3600)} h before the deadline to do the work (max of the review period, 72 h and 25 % of the term)`);
+        }
+    }
+    if (msg.deadline > now + BigInt(V3_LIMITS.MAX_DEADLINE_SECONDS))
+        r.push("the deadline is beyond the contract's maximum duration");
+    if (msg.reviewPeriod < V3_LIMITS.MIN_REVIEW_SECONDS || msg.reviewPeriod > V3_LIMITS.MAX_REVIEW_SECONDS)
+        r.push("the review period is outside the contract's bounds");
+    if (msg.arbiter === ZeroAddress) {
+        if (msg.arbitrationPeriod !== 0)
+            r.push("arbitrationPeriod without an arbiter");
+    }
+    else {
+        if (!ctx.arbiters.includes(msg.arbiter.toLowerCase()))
+            r.push("the arbiter is not one your local policy accepts");
+        if (msg.arbiter === msg.payee || msg.arbiter === getAddress(o.payer))
+            r.push("the arbiter is a party");
+    }
+    if (typeof o.offerId !== "string" || !o.offerId)
+        r.push("no offerId");
+    if (r.length)
+        refuse("ACCEPTANCE_CHECK_FAILED", `refused before signing: ${r.join("; ")}`);
+    return msg;
+}
+export async function accept(ctx, input) {
+    if (!input.milestoneId)
+        refuse("INPUT", "milestoneId is required");
+    const key = await ctx.unlock();
+    const me = key.address;
+    let arbiters = [];
+    try {
+        arbiters = loadPolicy(ctx.home, key.macKey, me).arbiters;
+    }
+    catch (e) {
+        // A payee without a policy accepts only escrows without an arbiter; a TAMPERED policy is never read as empty.
+        if (!(e instanceof Error && /POLICY_MISSING/.test(e.message)))
+            throw e;
+    }
+    const offer = (await ctx.remote.acceptance(input.milestoneId));
+    await verifyEndpoint(ctx.rpc, ctx.net);
+    const head = await latestBlock({ rpc: ctx.rpc, net: ctx.net });
+    const msg = checkAcceptance(offer, {
+        me,
+        net: ctx.net,
+        chainNowSec: head.timestamp,
+        arbiters,
+        minAmountWei: input.minAmountXrp ? parseEther(input.minAmountXrp) : null,
+    });
+    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({
+        escrowId: msg.escrowId,
+        role: "payee",
+        milestoneId: input.milestoneId,
+        payer: offer.payer,
+        payee: me,
+        amountWei: msg.amount.toString(),
+        chainId: ctx.net.chainId,
+        contract: ctx.net.address,
+        at: head.timestamp,
+    });
+    return {
+        accepted: true,
+        escrowId: msg.escrowId,
+        payer: getAddress(offer.payer),
+        amountWei: msg.amount.toString(),
+        acceptBy: msg.acceptBy.toString(),
+        deadline: msg.deadline.toString(),
+        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.",
+    };
+}

package/dist/actions.d.ts

@@ -0,0 +1,60 @@
+import { PER_ESCROW_ACTIONS } from "./calldata.js";
+import type { SignerAction } from "./calldata.js";
+import { RemoteError } from "./remote.js";
+import type { V3EscrowAction } from "./generated/v3-actions.js";
+import type { SignerContext } from "./context.js";
+export type ActionResult = {
+    action: SignerAction;
+    escrowId: string;
+    txHash: string;
+    sent: boolean;
+    reported: boolean;
+    from: string;
+    notes: string[];
+    [k: string]: unknown;
+};
+export type FundInput = {
+    milestoneId: string;
+    maxAmountXrp?: string;
+};
+export declare function fund(ctx: SignerContext, input: FundInput): Promise<ActionResult>;
+export type EvidenceInput = {
+    files?: string[];
+    texts?: string[];
+    github?: {
+        commitSha: string;
+        diffSha256: string;
+    }[];
+};
+/**
+ * The manifest hash of evidence the payee holds locally, computed HERE with the
+ * one manifest encoding. A submission is what ONE evidence-door request sealed —
+ * today one file, one text or one GitHub item — so the hash of several items only
+ * matches a submission that sealed exactly those items. It is never trusted on
+ * its own: `submitClaim` sends it only after cascrow's prepare confirms it is a
+ * sealed submission of the milestone (post-review G2).
+ */
+export declare function localProofHash(milestoneId: string, ev: EvidenceInput): string;
+export type EscrowActionInput = {
+    escrowId?: string;
+    milestoneId?: string;
+    /** object: the objection reason; its keccak256 goes on chain. */
+    reason?: string;
+    /** extendDeadline: unix seconds. */
+    newDeadline?: string | number;
+    /** submitClaim: the manifestHash the evidence door returned for the sealed submission. */
+    proofHash?: string;
+    /** submitClaim: evidence to hash locally instead (must equal a sealed submission). */
+    evidence?: EvidenceInput;
+};
+/**
+ * The fields of a refusal body a recipient can act on, as one line. The same
+ * fields every cascrow client appends (post-review G5).
+ */
+export declare function refusalDetail(body: Record<string, unknown>): string;
+/** True when prepare's failure is cascrow saying no (a verdict), not cascrow being unavailable. */
+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>;
+export { PER_ESCROW_ACTIONS };