cascrow-signer 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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

package/MIGRATION.md

@@ -1,13 +1,21 @@
 # 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.2.0 (npx cascrow-signer@0.2.0 link) … [CHALLENGE_ADDRESS_REQUIRED]`
+`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.2.0 link`. The keystore, the escrow book and your policy file are
+`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
@@ -46,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.2.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,7 +15,7 @@ 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.2.0 help
+npx cascrow-signer@0.3.0 help
 ```
 
 > **Status: released (0.1.0, on npm since 2026-09-27).** MilestoneEscrowV3 is deployed on
@@ -58,7 +58,7 @@ read. There is no OS-keychain integration on purpose (native dependency, supply
 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 — and when it is blind
-cascrow-signer object --escrow 0x… --reason "Criterion 2 is not met: …"
+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
 ```
@@ -134,7 +134,7 @@ on a terminal with `cascrow-signer policy set … --allow-agent-return-funds`.
 
 ```json
 { "mcpServers": { "cascrow-signer": {
-    "command": "npx", "args": ["cascrow-signer@0.2.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" } } } }
 ```

package/dist/actions.d.ts

@@ -49,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;

package/dist/actions.js

@@ -15,7 +15,8 @@
  * refusal, never read as "down" (post-review G1/H2).
  */
 import fs from "node:fs";
-import { ZeroAddress, formatEther, getAddress, keccak256, parseEther, sha256, toUtf8Bytes } from "ethers";
+import { ZeroAddress, formatEther, getAddress, parseEther, sha256 } from "ethers";
+import { newReasonSalt, objectionReasonHash } from "./reason.js";
 import { SignerError, refuse } from "./errors.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";
@@ -275,7 +276,12 @@ export async function escrowAction(ctx, action, input) {
     const notes = [];
     const c = chainCtx(ctx);
     // Arguments, computed locally.
-    const reasonHash = action === "object" ? (input.reason ? keccak256(toUtf8Bytes(input.reason)) : refuse("INPUT", "object needs a reason")) : null;
+    // object: a fresh salt per objection, made here, never sent — only the salted hash
+    // goes to prepare and on chain, and the result and the journal keep the salt.
+    if (action === "object" && !input.reason)
+        refuse("INPUT", "object needs a reason");
+    const reasonSalt = action === "object" ? newReasonSalt() : null;
+    const reasonHash = action === "object" ? objectionReasonHash(input.reason, reasonSalt) : null;
     const newDeadline = action === "extendDeadline" ? (input.newDeadline !== undefined ? BigInt(input.newDeadline) : refuse("INPUT", "extendDeadline needs newDeadline")) : null;
     let proofHash = null;
     if (action === "submitClaim") {
@@ -359,10 +365,14 @@ export async function escrowAction(ctx, action, input) {
         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, ...(limits ? { maxDeadlineSeconds: limits.maxDeadlineSeconds } : {}) });
         noteJournalIntegrity(ctx, journal, notes);
-        const rid = journal.reserve(action, escrowId, BigInt(0), head.timestamp);
+        const objection = reasonHash && reasonSalt ? { reason: input.reason, reasonSalt, reasonHash } : undefined;
+        const rid = journal.reserve(action, escrowId, BigInt(0), head.timestamp, objection);
         const sent = await sendSigned(c, key, journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
         if (sent.note)
             notes.push(sent.note);
+        if (objection) {
+            notes.push("Keep reasonSalt with your reason (also in this signer's journal): only keccak256(reasonSalt ‖ utf8(reason)) went on chain, and without the salt nobody can show later that it is this reason. cascrow received neither.");
+        }
         const milestoneId = input.milestoneId ?? entry?.milestoneId ?? null;
         const reported = await report(ctx, milestoneId, sent.txHash, notes);
         return {
@@ -373,7 +383,7 @@ export async function escrowAction(ctx, action, input) {
             reported,
             from: me,
             ...(proofHash ? { proofHash } : {}),
-            ...(reasonHash ? { reasonHash } : {}),
+            ...(objection ?? {}),
             notes,
         };
     });

package/dist/api.d.ts

@@ -14,7 +14,7 @@ export { checkChallenge, buildChallengeMessage, challengeStatement, CHALLENGE_AU
 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.2.0";
+export declare const SIGNER_VERSION = "0.3.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;

package/dist/api.js

@@ -29,7 +29,7 @@ export { checkAcceptance } from "./acceptance.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.2.0";
+export const SIGNER_VERSION = "0.3.0";
 /** Create the keystore and the spending journal. Does not need a network or cascrow. */
 export async function initSigner(home, passphrase, opts = {}) {
     ensureHome(home);

package/dist/checks.js

@@ -236,7 +236,7 @@ export function checkEscrowAction(action, me, e, chainNowSec, opts) {
     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)");
     if (action === "object" && !/^0x[0-9a-f]{64}$/.test(lc(opts.reasonHash ?? "")))
-        r.push("reasonHash must be a 32-byte hex value");
+        r.push("reasonHash must be a 32-byte hex value (keccak256(salt ‖ utf8(reason)))");
     fail("CHECK_FAILED", r);
 }
 export function checkWithdraw(me, credit) {

package/dist/journal.d.ts

@@ -4,6 +4,12 @@ export declare const DAY_SECONDS: number;
 export declare const JOURNAL_VERSION = 2;
 /** The only transaction fields a `signed` line may carry — what was signed, never the signature. */
 export declare const UNSIGNED_TX_FIELDS: readonly string[];
+/** What `object` committed to on chain: reasonHash = keccak256(reasonSalt ‖ utf8(reason)). */
+export type ObjectionRecord = {
+    reason: string;
+    reasonSalt: string;
+    reasonHash: string;
+};
 export type Reservation = {
     id: string;
     action: string;
@@ -20,6 +26,8 @@ export type Reservation = {
     unknown: boolean;
     /** A v1 line: unauthenticated. Counts toward the limit, never releases, never re-signed. */
     legacy: boolean;
+    /** object (0.3.0 on): the reason, salt and hash it committed to; null otherwise. */
+    objection: ObjectionRecord | null;
 };
 export type JournalState = 
 /** No journal file. */
@@ -92,7 +100,7 @@ export declare class KeyedJournal {
     verify(): VerifiedJournal;
     /** The verified journal for a decision about money: refused unless the chain is unbroken. */
     verifyForSpending(): VerifiedJournal;
-    reserve(action: string, escrowId: string | null, amountWei: bigint, nowSec: number): string;
+    reserve(action: string, escrowId: string | null, amountWei: bigint, nowSec: number, objection?: ObjectionRecord): string;
     signed(id: string, hash: string, nonce: number, tx: Record<string, unknown>): void;
     sent(id: string, hash: string): void;
     unknown(id: string, hash: string, reason: string): void;

package/dist/journal.js

@@ -42,7 +42,9 @@
  * is refused — the limit is not guessed.
  *
  * The journal never holds a signature or a signed transaction: `signed` keeps the
- * unsigned fields only (`UNSIGNED_TX_FIELDS`).
+ * unsigned fields only (`UNSIGNED_TX_FIELDS`). An `object` reservation carries the
+ * objection's reason, its salt and its hash (`objection`, 0.3.0): the salt exists
+ * nowhere else, and without it the on-chain hash proves nothing.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -58,6 +60,15 @@ const ZERO_MAC = "0".repeat(64);
 export const UNSIGNED_TX_FIELDS = Object.freeze([
     "chainId", "nonce", "to", "data", "value", "gasLimit", "type", "maxFeePerGas", "maxPriorityFeePerGas", "gasPrice",
 ]);
+/** A reserve line's `objection`, if it is well-formed; anything else reads as none (it decides no money). */
+function objectionOf(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    return typeof o.reason === "string" && typeof o.reasonSalt === "string" && typeof o.reasonHash === "string"
+        ? { reason: o.reason, reasonSalt: o.reasonSalt, reasonHash: o.reasonHash }
+        : null;
+}
 const inProcess = new Map();
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function pidAlive(pid) {
@@ -285,6 +296,7 @@ export class KeyedJournal {
                 sentHashes: [],
                 unknown: false,
                 legacy,
+                objection: objectionOf(e.objection),
             });
             return;
         }
@@ -382,9 +394,9 @@ export class KeyedJournal {
         }
         return v;
     }
-    reserve(action, escrowId, amountWei, nowSec) {
+    reserve(action, escrowId, amountWei, nowSec, objection) {
         const id = randomUUID();
-        this.append({ t: "reserve", id, action, escrowId, amountWei: amountWei.toString(), at: nowSec }, nowSec);
+        this.append({ t: "reserve", id, action, escrowId, amountWei: amountWei.toString(), at: nowSec, ...(objection ? { objection } : {}) }, nowSec);
         return id;
     }
     signed(id, hash, nonce, tx) {

package/dist/reason.d.ts

@@ -0,0 +1,4 @@
+/** 32 fresh random bytes (ethers' randomBytes: node:crypto on Node), lowercase 0x hex. */
+export declare function newReasonSalt(): string;
+/** keccak256(salt ‖ utf8(reason)), lowercase. */
+export declare function objectionReasonHash(reason: string, salt: string): string;

package/dist/reason.js

@@ -0,0 +1,27 @@
+/**
+ * The objection's reasonHash — keccak256(salt ‖ utf8(reason)), with a salt of 32
+ * random bytes made HERE, on the payer's machine, and never sent to cascrow.
+ *
+ * The hash goes on two public ledgers for good (the `Objected` event; cascrow's
+ * CLAIM_OBJECTED audit memo on the XRP Ledger). 0.2.0 sent keccak256(utf8(reason)),
+ * which anyone can test guessed reasons against; with the salt only its holder can
+ * link a text to the hash. The salt is returned in the action's result and written
+ * to the local journal, next to the reason — keep it, it is the only way to show
+ * later which reason the hash commits to.
+ *
+ * A port of cascrow's src/lib/v3-reason-hash.ts (this package cannot import the
+ * app). The same fixed vector is asserted against both
+ * (src/__tests__/helpers/reason-hash-vector.ts).
+ */
+import { concat, getBytes, hexlify, keccak256, randomBytes, toUtf8Bytes } from "ethers";
+const SALT = /^0x[0-9a-f]{64}$/;
+/** 32 fresh random bytes (ethers' randomBytes: node:crypto on Node), lowercase 0x hex. */
+export function newReasonSalt() {
+    return hexlify(randomBytes(32)).toLowerCase();
+}
+/** keccak256(salt ‖ utf8(reason)), lowercase. */
+export function objectionReasonHash(reason, salt) {
+    if (!SALT.test(salt))
+        throw new Error("reason salt must be 0x + 64 lowercase hex characters (32 bytes)");
+    return keccak256(concat([getBytes(salt), toUtf8Bytes(reason)])).toLowerCase();
+}

package/dist/remote.d.ts

@@ -14,6 +14,7 @@ export declare class Remote {
     constructor(cfg: RemoteConfig);
     get configured(): boolean;
     private call;
+    /** `reasonHash` is the salted keccak256(salt ‖ utf8(reason)) made in reason.ts; the reason and the salt are never sent. */
     prepare(q: {
         milestoneId: string;
         action: string;

package/dist/remote.js

@@ -75,6 +75,7 @@ export class Remote {
         }
         return data;
     }
+    /** `reasonHash` is the salted keccak256(salt ‖ utf8(reason)) made in reason.ts; the reason and the salt are never sent. */
     prepare(q) {
         const p = new URLSearchParams();
         for (const [k, v] of Object.entries(q))

package/dist/tools.js

@@ -66,7 +66,7 @@ export const SIGNER_TOOLS = Object.freeze([
         name: "cascrow_signer_object",
         description: "As the PAYER, object to the live claim before its objection deadline — this stops the release. Only for escrows whose on-chain payer is this key " +
             "(read from the chain; the local book is not needed). cascrow's server is not needed; the transaction is built from the chain. If the objection is pending too long, use cascrow_signer_speed_up.",
-        inputSchema: { type: "object", required: ["reason"], properties: { ...escrowRef, reason: { type: "string", description: "Why; its keccak256 goes on chain." } } },
+        inputSchema: { type: "object", required: ["reason"], properties: { ...escrowRef, reason: { type: "string", description: "Why. Only keccak256(salt ‖ utf8(reason)) goes on chain, with a salt of 32 random bytes made on this machine; the result returns reasonSalt (also kept in the local journal) — keep it with the reason, without it the hash proves nothing. Neither the reason nor the salt is sent to cascrow." } } },
     },
     {
         name: "cascrow_signer_release",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-signer",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local signer for cascrow MilestoneEscrowV3 escrows — your key is generated, encrypted and used only on your machine; cascrow prepares, you check and sign",
   "type": "module",
   "main": "./dist/api.js",