cascrow-mcp 1.8.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 3.1.0 — 2026-10-20
+
+Not published yet when the second half of these changes landed; everything below ships in one 3.1.0.
+
+- **New tools `cascrow_request_human_review` and `cascrow_human_reviews`.** Either party of a contract can ask for a person at cascrow to review a verification outcome (Art. 22(3) GDPR), with an optional `reason`; a person decides within one month and both parties receive the decision with its reasons (`human_review.decided`). `cascrow_human_reviews` lists the requests on a contract with their status, deadline, outcome and the reviewer's statement. A second request while one is open comes back as `status: "ALREADY_OPEN"` with its `dueAt`, not as an error.
+- **New tool `cascrow_rotate_callback_secret`.** Callbacks to your `callbackUrl` are now signed with a secret of your own account (`X-Cascrow-Signature: sha256=HMAC-SHA256(secret, "t=" + <unix ms of X-Cascrow-Timestamp> + "." + <raw body>)`). Two steps: without `confirm` the tool only returns the warning; with `confirm: true` it rotates and returns the new secret — the previous one stops verifying at once, and the new one enters the conversation. `cascrow_set_discoverable` never relays the secret into the model's context (it says a secret exists and points to the rotate tool).
+- **`cascrow_create_contract` takes `reviewWindowDays` (2–30, default 14; under 7 only between two businesses) and `panelDecidesAlone`**, and returns the server's `reviewTerms` — what the builder sees before joining. The `agentReviewMode` description says what happens since 2026-10-20: without the funder's decision a milestone completes only when the panel's own verdict opened the review with a YES; any other review goes to cascrow's human review.
+- **`cascrow_get_reputation` reads `stats: null`**: a builder who has not consented to publishing their figures shows "Figures: not published" and only the milestones they published one by one — never read as "no track record". An address that publishes nothing at all answers like an unknown one.
+- **`cascrow_v3_acceptance_get` names the free veto** of an escrow without an arbiter — in its description and in its result whenever the signed typed data names the zero address as arbiter: the payer can object to every claim at no cost, and an objected claim ends in a refund after the deadline.
+- New hint for **`SCREENING_UNAVAILABLE`**: the new-money sanctions screen fails closed — nothing was created, retry in a few minutes; existing escrows are not affected.
+- **`cascrow_set_discoverable` takes `showNameOnCertificates` and `consentVersion`.** `showNameOnCertificates` shows the company name (or name) as "Delivered by" on the public check page of the account's certificates. Turning it or `discoverable` ON publishes the account holder's name and needs their consent: without `consentVersion` nothing changes, and the tool returns `code: "CONSENT_REQUIRED"` with the server's exact consent text and the `consentVersion` to send once they agree. The text is passed on as the server sends it, never kept in this package. Turning either off needs nothing. The reply also says whether the name is shown on certificate check pages.
+- **Wallet linking follows cascrow's Sign-In with Ethereum challenge:** `GET /api/user/wallet/challenge?address=<your wallet>`, sign the returned message with that wallet, `POST /api/user/wallet`. The old one-line challenge is refused by the server. Every `cascrow-signer` pin is now `cascrow-signer@0.2.0` — 0.1.0 can no longer link a wallet (its other commands keep working).
+- `cascrow_verify`'s description names the panel's OpenAI model correctly (GPT-4o-mini).
+- `@modelcontextprotocol/sdk` `^1.32.1` (was `^1.15.0`, a range that admitted versions affected by GHSA-6qxp-vccf-f47h).
+- The package now carries its MIT `LICENSE` and ships only `index.js`, `README.md`, `CHANGELOG.md` and `LICENSE`; `server.json`, `smithery.yaml` and `REMOTE_HTTP_SERVER.md` stay in the repository, where the MCP registry and Smithery read them.
+
+## 3.0.0 — 2026-09-27
+
+- **`cascrow_join_contract` says what the builder can do now.** The server's answer carries `status` and `activated`, returned as well as rendered: a $0 verification contract is active at once — submit proof; a contract with an amount waits for the payer's MilestoneEscrowV3 offer, which you accept with your own key (`npx cascrow-signer@0.1.0 accept --milestone <id>`). It used to say "Contract is now AWAITING_ESCROW — ready to receive proof once funded" for both, so a $0 builder waited for money that never comes.
+- **New outcome `NOT_COMPLETABLE_WITHOUT_ESCROW`.** When the panel approves a milestone that carries an amount without a MilestoneEscrowV3 escrow, nothing can complete it: `cascrow_verify` renders "⛔ NOT COMPLETED — … no money moved; contact support", `cascrow_mcp_submit` surfaces the server's 409 with the same hint, and `cascrow_get_proof_status` / `cascrow_watch_verification` read the new `notCompletableWithoutEscrow` field and stop polling. Such a milestone used to read as "approved, the automatic payout did not go through — the release can be retried", a retry that no longer exists.
+- **Breaking: `releaseHoldUntil` / `release_hold_until` are gone** from every result, with the v2 release window they reported. A bare `VERIFIED` no longer promises a retried release.
+- New hint for `RELEASE_HOLD_REMOVED` (the server refuses `releaseHoldHours` on contract creation).
+- **Breaking: `cascrow_fund_milestone` is removed** (cascrow Phase 6 — the v2 RLUSD escrow is gone). A $0 verification contract is active by itself once the builder has joined; there is nothing to fund. A milestone with an amount is a MilestoneEscrowV3 escrow in native XRP: the payer offers terms (`cascrow_v3_offer`), the builder accepts with their own key, and the payer funds it with one transaction from their own machine — `npx cascrow-signer@0.1.0 fund --milestone <milestoneId>`. A host that still calls the old tool gets an error that says exactly this (`[TOOL_REMOVED]`).
+- The `cascrow_escrow_fund` refusal names only the V3 flow and `cascrow-signer`; the pointers to `escrow-prepare` and `escrow/sync` are gone with those endpoints.
+- `amountUSD` in `cascrow_create_contract`: 0 (or absent) = verification only; above 0 = MilestoneEscrowV3 offer flow.
+- `cascrow_review_queue` / `cascrow_review_contract` describe what a funder verdict does now: it completes or hands back a verification-only milestone and moves no money. A COMPLETED milestone no longer reads "funds released" — it says whether no money was held or a MilestoneEscrowV3 escrow paid out on chain.
+- `cascrow_get_reputation` prints `totalReleasedUsd` (and the XRP released by MilestoneEscrowV3 escrows) instead of "RLUSD released". `totalRlusdReleased` is still in the response, deprecated.
+
+## 2.1.0 — not published on its own, released as part of 3.0.0
+
+- **MilestoneEscrowV3, remote half.** New tools: `cascrow_v3_offer` (payer offers terms), `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` (builder reads the frozen terms and hands over the acceptance signature), `cascrow_v3_prepare` (an UNSIGNED transaction — rebuild `data` and check `to`/`chainId` yourself), `cascrow_v3_report_tx` (a transaction HASH only; a signed transaction is refused before anything is sent) and `cascrow_v3_attestation` (the non-binding AI recommendation for a claim). cascrow never signs, sends or relays: signing happens in the separate, pinned local signer, `npx cascrow-signer@0.1.0`.
+- `cascrow_fund_milestone` refuses a MilestoneEscrowV3 milestone with the way to fund it (`npx cascrow-signer@0.1.0 fund`), and every V3 refusal code (`V3_DISABLED`, `RATE_UNAVAILABLE`, `V3_NOT_OFFERED`, `OFFER_EXISTS`, `V3_OFFER_OPEN`, `ATTESTATION_PENDING`, `CLAIM_PROOF_UNKNOWN`, `V3_ESCROW`, `INVALID_SIGNATURE`, `V3_INDEX_STALE`, …) comes with what the recipient can do.
+- A verification of a V3 milestone reads as `V3_RECOMMENDATION` — "moves NO money" — in `cascrow_verify` and `cascrow_mcp_submit`, never as approved/paid or rejected.
+
+## 2.0.0 — not published on its own, released as part of 3.0.0
+
+- **Breaking: `cascrow_escrow_fund` is removed.** It sent the agent's EVM private key to cascrow, which signed the deposit server-side; cascrow no longer accepts, stores or signs with anyone's key. A host that still calls the tool by name gets an error that says so, and nothing it passed is read. Fund a v2 escrow by signing locally: `GET /api/agent/escrow-prepare` returns the two unsigned transactions, you sign and broadcast them with your own wallet, then `POST /api/escrow/sync`. Funding a MilestoneEscrowV3 contract from an API client is not available yet. **If you ever passed a private key to this tool, treat that key as exposed and move its funds to a new wallet.**
+- The anonymous-mode message states the real number of tools (it said 18).
+- Includes the unreleased 1.8.1 changes below, which were never published on their own.
+
+## 1.8.1 — unreleased, folded into 2.0.0
+
+- `cascrow_mcp_submit`'s description names `V3_ESCROW` as final: a 409 with that code means the milestone is held in a MilestoneEscrowV3 escrow that only its payer, payee or arbiter moves on chain — retrying will not help.
+- `cascrow_get_proof_status` and `cascrow_watch_verification` narrate the MilestoneEscrowV3 terminal reasons (`ARBITER_REFUNDED`, `REFUNDED_AFTER_OBJECTION_AI_NO`, `REFUNDED_AFTER_OBJECTION_DISPUTED`, `RETURNED_BY_PAYEE`, `RETURNED_BEFORE_WORK`) instead of "the reason was not recorded".
+
 ## 1.8.0 — 2026-09-25
 
 - **Verification starts by itself after `cascrow_submit_proof`.** Wait for the verdict with `cascrow_watch_verification { proofId }` — the tool now has an attach mode — instead of calling `cascrow_verify`, which only raced the run already going.

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/README.md

@@ -1,15 +1,15 @@
 # cascrow-mcp
 
-MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger.
+MCP server for [Cascrow](https://cascrow.com) — trust infrastructure for the agent economy: AI verification, on-chain reputation, and — for work that is paid — a non-custodial milestone escrow (MilestoneEscrowV3, native XRP; testnet for now).
 
-AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote**, with every verdict anchored on the XRP Ledger. For a paid milestone the AI result is a signed, non-binding recommendation: the money sits in a MilestoneEscrowV3 smart contract that only the payer, the builder or an arbiter they chose can move — cascrow holds no key that can move escrowed funds and never signs an escrow transaction.
 
 ## Quick Start
 
 **No API key yet?** Every setup below works without `CASCROW_API_KEY` too — the server starts either
 way, but only `cascrow_verify_work` (verify AI-generated work, no escrow) is available until you set
 one, at the same 3-free-per-IP-per-day tier as [cascrow.com/verify](https://cascrow.com/verify). Set
-`CASCROW_API_KEY` (see Agent Registration below) once you want the other 17 tools — it also anchors
+`CASCROW_API_KEY` (see Agent Registration below) once you want the other tools — it also anchors
 `cascrow_verify_work` verdicts on the XRP Ledger mainnet (anonymous calls never are); see below.
 
 ### Claude Desktop
@@ -126,21 +126,30 @@ Rate limit: 3 registrations per IP per hour.
 | `cascrow_verify` | Start or re-run 5-model AI verification. If a run is already going (e.g. the one upload started), waits for it instead of failing. |
 | `cascrow_get_proof_status` | Poll a submitted proof's verification result. |
 | `cascrow_watch_verification` | Block until verification completes — either submit + wait (`milestoneId` + `content`) or wait for an existing proof (`proofId`). Stops early and says why when waiting cannot help. |
-| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call — auto-releases funds and mints the NFT on approval. |
+| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call. A verification-only milestone completes on approval (NFT certificate minted); for a MilestoneEscrowV3 milestone the verdict is a recommendation that moves no money. |
 | `cascrow_verify_work` | Verify AI work with no escrow contract, from a GitHub PR, pasted code, or a base64-encoded screenshot. Returns a public report URL. With `CASCROW_API_KEY` set, the verdict is also anchored on the XRP Ledger mainnet — anonymous calls are not. |
-| `cascrow_escrow_fund` | Fund a milestone with an EVM private key (fully autonomous). |
-| `cascrow_fund_milestone` | Fund via MetaMask (browser flow). |
 | `cascrow_get_contract` | Get contract status and all milestone states. |
 | `cascrow_list_my_contracts` | List all contracts for this agent, as Requester and/or Builder. |
-| `cascrow_review_queue` | As funder: list milestones still waiting for your verdict. Poll it — an undecided milestone auto-approves after 48h. |
-| `cascrow_review_contract` | As funder: approve or reject a milestone the AI panel scored 60–85. |
-| `cascrow_join_contract` | Join a contract as Builder agent via invite code. |
+| `cascrow_review_queue` | As funder of a verification-only contract: list milestones still waiting for your verdict. Poll it — an undecided milestone is completed automatically when its review window closes only when the panel's own verdict opened the review with a YES — any other review goes to cascrow's human review instead; the window is the contract's `reviewWindowDays` (default 14 days; 48h on an agent contract created before 2026-10-20 in review mode `MANUAL_AUTO` or `AUTO`). |
+| `cascrow_v3_claims` | As payer of a MilestoneEscrowV3 escrow: list claims that release it unless your own wallet calls `object()` before `objectionDeadline`. cascrow cannot object for you. |
+| `cascrow_v3_offer` | As payer: offer MilestoneEscrowV3 terms (native XRP) for a milestone. The builder accepts with their own key. |
+| `cascrow_v3_acceptance_get` / `cascrow_v3_acceptance_submit` | As builder: read the frozen terms, hand over your EIP-712 acceptance signature (binding until `acceptBy`). |
+| `cascrow_v3_prepare` | An UNSIGNED transaction for any escrow action. Rebuild `data` and check `to`/`chainId` against your own config before signing. |
+| `cascrow_v3_report_tx` | After you broadcast: the transaction **hash** (never a signed transaction), so the index re-reads now. |
+| `cascrow_v3_attestation` | cascrow's signed, non-binding AI recommendation for a claim. |
+
+**Signing is never done here.** cascrow holds no key of yours and relays nothing. For MilestoneEscrowV3 use the separate local signer — `npx cascrow-signer@0.2.0` (CLI or its own MCP server, tools `cascrow_signer_*`) — which checks every prepared transaction against its own pinned chain and contract.
+| `cascrow_review_contract` | As funder of a verification-only contract: approve (completes it) or reject (hands it back) a milestone the AI panel scored 60–85. Moves no money. |
+| `cascrow_request_human_review` | As funder or builder: ask for a person at cascrow to review a verification outcome (Art. 22(3) GDPR). Decided within one month, sent to both parties with reasons. |
+| `cascrow_human_reviews` | The human-review requests on a contract: status, deadline, outcome and the reviewer's statement. |
+| `cascrow_join_contract` | Join a contract as Builder agent via invite code. The answer says whether it is active now (`activated: true`, a $0 contract — submit proof) or waits for the payer's MilestoneEscrowV3 offer (accept it with your own key: `npx cascrow-signer@0.2.0 accept --milestone <id>`). |
 | `cascrow_handoff` | Send a contract to another agent by Agent ID. |
 | `cascrow_get_agent_id` | Get this agent's own Agent ID. |
 | `cascrow_check_invites` | Check pending contract invites. |
-| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed and success rate over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
+| `cascrow_get_reputation` | Look up any agent's on-chain track record by wallet address — completed, failed, success rate and value released (`totalReleasedUsd`, plus XRP for MilestoneEscrowV3; `totalRlusdReleased` is deprecated) over every eligible milestone, plus the milestone records the builder has published (opt-in, default private) with their proof hashes. No auth required. |
 | `cascrow_discover_agents` | Search discoverable Builder agents by skill tag and minimum success rate. |
-| `cascrow_set_discoverable` | Opt into the agent marketplace, set skill tags, register a callback URL. |
+| `cascrow_set_discoverable` | Opt into the agent marketplace or into being named on certificate check pages, set skill tags, register a callback URL. Turning a name on needs the account holder's consent: the first call changes nothing and returns the text to show and the `consentVersion` to send. |
+| `cascrow_rotate_callback_secret` | Replace the callback signing secret and return the new one (callbacks carry `X-Cascrow-Timestamp` and `X-Cascrow-Signature: sha256=HMAC-SHA256(secret, "t=" + <unix ms of the timestamp> + "." + <raw body>)`; reject a timestamp more than 5 minutes off). The first call changes nothing and returns a warning — the old secret stops verifying and the new one enters the conversation; call again with `confirm: true`. `cascrow_set_discoverable` never returns a secret. |
 
 ## How Verification Works
 
@@ -156,7 +165,7 @@ Five AI models vote in parallel on submitted proof:
 
 | Confidence | Outcome |
 |------------|---------|
-| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically |
+| > 85% + 3/5 YES | **VERIFIED** — a verification-only milestone completes; for a MilestoneEscrowV3 milestone this is a recommendation (every file needs a definite yes), and the money moves only by the parties' own on-chain calls |
 | 60–85% | **PENDING_REVIEW** — human review triggered |
 | < 60% | **REJECTED** — submitter can improve and resubmit |
 
@@ -182,28 +191,25 @@ Claude will:
 
 > Set `amountUSD: 0` for **verification-only mode** — the full 5-model AI pipeline runs without locking any funds. Useful for trustless proof of work without payment.
 
-## Agent-to-Agent Payment Flow
+## Agent-to-Agent Payment Flow (MilestoneEscrowV3, testnet)
 
-Cascrow supports fully autonomous agent-to-agent payments:
+1. **Requester (payer)** creates the contract (`cascrow_create_contract`) with an `amountUSD` above 0 and hands it to the **Builder** (`cascrow_handoff`); the builder joins (`cascrow_check_invites` + `cascrow_join_contract`).
+2. The payer offers the escrow terms — amount in native XRP at a frozen XRP/USD rate, review period, optional arbiter — with `cascrow_v3_offer`.
+3. The builder reads the frozen terms (`cascrow_v3_acceptance_get`), checks them and signs the acceptance with its own key (`npx cascrow-signer@0.2.0 accept`, or `cascrow_v3_acceptance_submit` with a signature made elsewhere). The signature binds until `acceptBy`.
+4. The payer funds the escrow with **one transaction from its own machine**: `npx cascrow-signer@0.2.0 fund --milestone <id>` (or the signer's MCP tool `cascrow_signer_fund`).
+5. The builder delivers → `cascrow_submit_proof` → `cascrow_watch_verification`. The AI result is a signed, non-binding recommendation (`cascrow_v3_attestation`).
+6. The builder claims on chain with the submission's `manifestHash`. The payer releases, or objects before the objection deadline (`cascrow_v3_claims` lists open claims); without an objection the builder can take the money after the review period.
 
-1. **Requester** creates contract (`cascrow_create_contract`) + funds it (`cascrow_escrow_fund` with EVM private key)
-2. Requester sends work to **Builder** via `cascrow_handoff` using the Builder's Agent ID
-3. Builder accepts via `cascrow_check_invites` + `cascrow_join_contract`
-4. Builder completes work → `cascrow_submit_proof` → `cascrow_watch_verification`
-5. On 3/5 YES: RLUSD released to Builder's wallet + NFT certificate minted on XRP Ledger
-
-No humans required at any step.
+cascrow never accepts, creates, stores or signs with a private key and is never the arbiter (`cascrow_escrow_fund`, which took a key, was removed in 2.0.0 — if you ever passed a key to it, treat that key as exposed and move its funds). Each agent links its own wallet once — `GET /api/user/wallet/challenge?address=<your wallet>` → sign the Sign-In with Ethereum message → `POST /api/user/wallet` (or `npx cascrow-signer@0.2.0 link`). Replacing a linked wallet by API key also needs the current wallet's signature (`cascrow-signer link --old-home …`). A contract without an amount needs none of this: it is active once the builder has joined.
 
 ## Blockchain Architecture
 
 | Chain | Purpose |
 |-------|---------|
-| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRPL EVM Sidechain (Chain ID 1449000, testnet) | MilestoneEscrowV3 — non-custodial escrow in native XRP, no platform role |
 | XRP Ledger Mainnet | NFT completion certificates + audit trail |
 
-Every verified milestone produces:
-- An on-chain RLUSD transfer to the recipient
-- A non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion
+Every completed milestone produces a non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion; a MilestoneEscrowV3 payout is the escrow contract's own on-chain transfer to the builder.
 
 ## Links