402mob-merchant-sdk 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,16 @@
 # Changelog
 
-## 0.4.2 — prepared, unpublished
+## 0.5.0
+
+- Add `ProtectedWorkClient` for the separate experimental JSON escrow HTTP API, generated request/response types and schema checks. Pin contract/verifier; validate read challenges, signing domains and transaction targets. No signing, broadcasting, automatic retry or replica management. Includes protocol integration tests and an example. Earlier versions do not include these methods.
+
+- Require an authenticated-read binding for dispute writes. Reject unexpected signing origins/consent, contradictory payment and delivery states, and immutable binding drift across evidence events. Challenge issuance reveals no operation or case state.
+
+- Require stateless dispute challenge tokens; distinguish write acknowledgments from authenticated evidence reads. Validate operation, statement, binding and lifecycle consistency; preserve settlement status and post-closure seller evidence.
+
+- Add wallet-signed delivery complaint, seller response, buyer closure and evidence-read methods and types. No automatic payment or refund.
+
+## 0.4.2 — published
 
 - Add optional `artifact` commitment and `share` fields to resolved resources. Validate supplied commitments and preserve compatibility with older servers that omit them.
 

package/README.md

@@ -1,6 +1,6 @@
 # 402Mob Merchant SDK
 
-Source 0.4.2 is prepared locally with optional Payment Links commitment/share types and validation. Published 0.4.1 remains unchanged; these additions require the new source build until publication.
+Version 0.5.0 adds wallet-signed delivery complaints and the separate `ProtectedWorkClient` for experimental JSON escrow. Install `402mob-merchant-sdk@0.5.0` for these methods; earlier versions do not include them.
 
 **Version 0.4.0** adds worker profiles and discovery, public buyer requests and newest-first Work Ticket reads. Upgrade from 0.3.1 to use these additions. Check the target server's `/v1/capabilities` first; new worker routes require `workerDiscovery`. See [CHANGELOG.md](./CHANGELOG.md).
 
@@ -282,3 +282,33 @@ The supported states are `open`, `claimed`, `quoted`, `accepted`, `paying`, `pai
 SDK requests reject HTTP redirects and never retry automatically. An interrupted mutation may have completed. Read the ticket before repeating a claim or quote; quote and claim creation are not idempotent. Repeating identical result content is supported while retained. For payment recovery through HTTP or MCP, reuse the original checkout key and authorization, including after delivery or a buyer receipt. The SDK does not submit payments.
 
 These methods are available from version 0.3.0.
+
+
+## Delivery complaints (unreleased source)
+
+`createDeliveryDisputeChallenge(operationId, request)` and `submitDeliveryDisputeAction(operationId, {challengeId, challengeToken, signature})` support buyer complaints, original-recipient responses, buyer closure and private reads. These methods require version 0.5.0 or later.
+
+```ts
+const challenge = await client.createDeliveryDisputeChallenge(operationId, {
+  wallet: account.address, action: "read"
+});
+const signature = await account.signMessage({ message: challenge.message });
+const response = await client.submitDeliveryDisputeAction(operationId, {
+  challengeId: challenge.challengeId, challengeToken: challenge.challengeToken, signature
+});
+if (response.kind === "evidence") {
+  // Inspect response.dispute and response.payment.
+}
+```
+
+No API key or payment is sent. Sign with the original payer or recipient wallet; keep proofs private. Retry exact signed writes after interruption; reads need fresh challenges. This records statements, not arbitration or refunds. See [the complete workflow](https://evidence.contact/delivery-disputes.md).
+
+Dispute writes (including retries) return `kind: "acknowledgment"` and the original action receipt only. Fresh wallet-signed reads return `kind: "evidence"` with the current case. Return the opaque `challengeToken` unchanged; it is required for submission. Buyer closure preserves the seller’s right to append evidence. Settlement status is independent of operation/result expiry. SDK checks enforce structural and lifecycle consistency, not cryptographic verification of exported signatures.
+
+Dispute writes require `binding` from a fresh signed read. Read challenges contain no private operation data and do not confirm that an operation or case exists. Check the returned origin and consent text before signing; `dispute_binding_conflict` requires a new read and signed statement. The SDK rejects origin/consent changes, contradictory delivery/payment states and inconsistent immutable bindings across events.
+
+## Protected work (0.5.0)
+
+`ProtectedWorkClient` covers all primary protected-work HTTP endpoints with generated OpenAPI types and request/response validation. It requires a pinned contract and verifier hash for job operations, checks signing domains, exact read challenges, transaction targets and approval amounts, and sends no merchant credential. It does not hold keys, sign, broadcast, decode every transaction, verify cryptographic commitments or automatically retry. A configured server may relay signed actions; funding is never relayed.
+
+Start with `new ProtectedWorkClient({baseUrl}).getCapabilities()` and stop when `configured` is false. The isolated Base test does not activate production. SDK helpers have HTTP integration coverage with simulated chain state; the Base test used direct HTTP. Use version 0.5.0 for these helpers. See [the full client guide](https://evidence.contact/merchant-sdk.md#protected-json-work-source-050), [protocol](https://evidence.contact/protected-work.md) and [source examples](examples/protected-work.ts). Replica consent/upload/decision calls remain separate verifier HTTP calls; there are no protected-work CLI, Python wallet or hosted MCP action helpers.

package/dist/index.d.ts

@@ -4,6 +4,119 @@ export type TransactionHash = `0x${string}`;
 export type ProofMethod = "approve_zero" | "transfer_zero";
 export type ArtifactContentType = "application/json" | "text/plain; charset=utf-8";
 export type WorkTicketState = "open" | "claimed" | "quoted" | "accepted" | "paying" | "paid" | "delivered" | "accepted_by_buyer" | "disputed" | "expired";
+export interface DeliveryDisputeBinding {
+    payer: EvmAddress;
+    recipient: EvmAddress;
+    requestHash: string;
+    workTicketId: string | null;
+    quoteTermsHash: string | null;
+    resultHashAtOpen: string | null;
+    transaction: string | null;
+    amountAtomic: string;
+    asset: EvmAddress;
+    network: "eip155:8453";
+}
+export type DeliveryDisputeRequest = {
+    wallet: EvmAddress;
+    action: "open";
+    expectedRevision: 0;
+    binding: DeliveryDisputeBinding;
+    reason: "not_delivered" | "unreadable" | "terms_mismatch";
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "respond";
+    expectedRevision: number;
+    binding: DeliveryDisputeBinding;
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "close";
+    expectedRevision: number;
+    binding: DeliveryDisputeBinding;
+    outcome: "resolved" | "unresolved";
+    detail: string;
+    evidenceHashes: string[];
+} | {
+    wallet: EvmAddress;
+    action: "read";
+};
+export interface DeliveryDisputeChallenge {
+    challengeToken: string;
+    challengeId: string;
+    message: string;
+    expiresAt: string;
+    submit: string;
+}
+export interface DeliveryDisputeEvent {
+    revision: number;
+    action: "open" | "respond" | "close";
+    wallet: string;
+    createdAt: string;
+    statement: Exclude<DeliveryDisputeRequest, {
+        action: "read";
+    }>;
+    message: string;
+    signature: string;
+    challengeId: string;
+}
+export interface DeliveryDisputeEvidence {
+    protocol: "402mob.delivery-dispute.v1";
+    kind: "evidence";
+    operationId: string;
+    operationState: string;
+    binding: DeliveryDisputeBinding;
+    dispute: null | {
+        operationId: string;
+        buyer: string;
+        seller: string;
+        status: "open" | "responded" | "closed";
+        outcome: "resolved" | "unresolved" | null;
+        revision: number;
+        openedAt: string;
+        expiresAt: string;
+        responseDueAt: string;
+        buyerReviewDueAt: string | null;
+        binding: {
+            requestHash: string;
+            workTicketId: string | null;
+            quoteTermsHash: string | null;
+            resultHashAtOpen: string | null;
+            transaction: string | null;
+            amountAtomic: string;
+            asset: string;
+            network: string;
+        };
+        events: DeliveryDisputeEvent[];
+    };
+    payment: {
+        state: "settled" | "pending" | "failed" | "unconfirmed";
+        transaction: string | null;
+    };
+    delivery: {
+        resultHash: string | null;
+        resultAvailable: boolean;
+    };
+    responseOverdue: boolean;
+    buyerReviewOverdue: boolean;
+    scope: string;
+    replay: boolean;
+}
+export interface DeliveryDisputeAcknowledgment {
+    protocol: "402mob.delivery-dispute.v1";
+    kind: "acknowledgment";
+    operationId: string;
+    receipt: {
+        challengeId: string;
+        action: "open" | "respond" | "close";
+        revision: number;
+        createdAt: string;
+    };
+    replay: boolean;
+}
+export type DeliveryDisputeResponse = DeliveryDisputeEvidence | DeliveryDisputeAcknowledgment;
 export interface EnrollmentChallenge {
     challengeId: string;
     message: string;
@@ -529,6 +642,16 @@ export declare class MerchantClient {
     }): Promise<BuyerRequestDetail & {
         replay: boolean;
     }>;
+    /** Free, wallet-signed complaint/response/closure/read. No bearer key or payment is sent. */
+    createDeliveryDisputeChallenge(operationId: string, input: DeliveryDisputeRequest): Promise<DeliveryDisputeChallenge>;
+    /** Retry the same signed write after interruption; private reads require a fresh challenge. */
+    submitDeliveryDisputeAction(operationId: string, input: {
+        challengeId: string;
+        challengeToken: string;
+        signature: EvmSignature;
+    }): Promise<DeliveryDisputeResponse>;
     private request;
 }
-export {};
+export { ProtectedWorkClient, ProtectedWorkApiError } from "./protected-work.js";
+export type { ProtectedWorkClientOptions } from "./protected-work.js";
+export type * from "./protected-work-types.js";

package/dist/index.js

@@ -4,6 +4,7 @@ function requireEip191Signature(signature) {
     }
     return signature;
 }
+const disputeConsent = "This signature authorizes only this statement or private read. It does not authorize payment, refund or adjudication. Response targets: seller 48 hours after opening; buyer 7 days after first response. Silence is not acceptance.";
 function buyerRequestKey(key) {
     if (!/^[A-Za-z0-9_-]{16,128}$/.test(key))
         throw new TypeError("Persist an idempotency key of 16–128 letters, digits, underscores or hyphens.");
@@ -274,6 +275,18 @@ export class MerchantClient {
     selectBuyerRequestOffer(requestId, input) {
         return this.request("POST", `/v1/buyer-requests/${checkedWorkTicketId(requestId)}/selections`, { ...input, signature: requireEip191Signature(input.signature) });
     }
+    /** Free, wallet-signed complaint/response/closure/read. No bearer key or payment is sent. */
+    createDeliveryDisputeChallenge(operationId, input) {
+        if (!isDisputeRequest(input))
+            throw new TypeError("Provide a participant wallet, supported action, current revision and bounded statement/evidence hashes.");
+        return this.request("POST", `/v1/operations/${checkedWorkTicketId(operationId)}/dispute-challenges`, input);
+    }
+    /** Retry the same signed write after interruption; private reads require a fresh challenge. */
+    submitDeliveryDisputeAction(operationId, input) {
+        if (!digest(input.challengeId) || !disputeToken(input.challengeToken))
+            throw new TypeError("Return the exact challengeId and challengeToken from the challenge response.");
+        return this.request("POST", `/v1/operations/${checkedWorkTicketId(operationId)}/dispute-actions`, { ...input, signature: requireEip191Signature(input.signature) });
+    }
     async request(method, path, body, authenticated = false, extraHeaders = {}) {
         if (authenticated && !this.#apiKey) {
             throw new Error("This request requires a merchant API key. Use client.withApiKey(apiKey).");
@@ -305,6 +318,17 @@ export class MerchantClient {
         const invalidResponse = () => new MerchantApiError(response.status, "invalid_response", "402Mob returned an incomplete response. The request may have completed; preserve recovery data. If enrollment or rotation completed without a usable key, use credential rotation.");
         if (!isRecord(payload))
             throw invalidResponse();
+        if (path.endsWith("/dispute-challenges")) {
+            const expected = path.replace(/dispute-challenges$/, "dispute-actions"), id = path.split("/")[3];
+            if (!digest(payload.challengeId) || !disputeToken(payload.challengeToken) || !nonempty(payload.message) || !timestamp(payload.expiresAt) || payload.submit !== expected || !isDisputeRequest(body))
+                throw invalidResponse();
+            const statement = { ...body, wallet: body.wallet.toLowerCase(), ...(body.action !== "read" ? { detail: body.detail.trim(), binding: { ...body.binding, payer: body.binding.payer.toLowerCase(), recipient: body.binding.recipient.toLowerCase(), asset: body.binding.asset.toLowerCase() } } : {}) };
+            const fields = disputeMessage(payload.message);
+            if (!fields || fields.origin !== new URL(this.baseUrl).origin || fields.operation !== id || fields.nonce !== payload.challengeId || fields.expires !== payload.expiresAt || stableJson(fields.statement) !== stableJson(statement) || stableJson(fields.binding) !== stableJson(body.action === "read" ? null : statement.binding))
+                throw invalidResponse();
+        }
+        if (path.endsWith("/dispute-actions") && !isDisputeResponse(payload, path.split("/")[3], body, new URL(this.baseUrl).origin))
+            throw invalidResponse();
         if (path.startsWith("/v1/worker-directory?")) {
             if (!Array.isArray(payload.items) || !payload.items.every(item => isWorkerProfileView(item) && item.workerProfile.discoverable && item.workerProfile.availability === "accepting") || !(payload.nextCursor === null || Number.isSafeInteger(payload.nextCursor) && Number(payload.nextCursor) >= 0))
                 throw invalidResponse();
@@ -479,3 +503,127 @@ function checkedWorkTicketId(id) {
     }
     return id;
 }
+function isDisputeRequest(v) {
+    if (!isRecord(v) || !address(v.wallet))
+        return false;
+    if (v.action === "read")
+        return onlyKeys(v, ["wallet", "action"]);
+    if (!["open", "respond", "close"].includes(String(v.action)) || !Number.isInteger(v.expectedRevision) || Number(v.expectedRevision) < 0 || Number(v.expectedRevision) > 32 || !boundedWorkerText(v.detail, 2000) || !isRecord(v.binding) || !validMessageBinding(v.binding) || !Array.isArray(v.evidenceHashes) || v.evidenceHashes.length > 8 || !v.evidenceHashes.every(digest))
+        return false;
+    const common = ["wallet", "action", "expectedRevision", "binding", "detail", "evidenceHashes"];
+    if (v.action === "open")
+        return v.expectedRevision === 0 && ["not_delivered", "unreadable", "terms_mismatch"].includes(String(v.reason)) && onlyKeys(v, [...common, "reason"]);
+    if (v.action === "close")
+        return ["resolved", "unresolved"].includes(String(v.outcome)) && onlyKeys(v, [...common, "outcome"]);
+    return onlyKeys(v, common);
+}
+function disputeToken(v) { return typeof v === "string" && /^[A-Za-z0-9_-]{40,40000}$/.test(v); }
+function stableJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map(stableJson).join(",")}]`;
+    if (isRecord(v))
+        return `{${Object.keys(v).sort().map(k => JSON.stringify(k) + ":" + stableJson(v[k])).join(",")}}`;
+    return JSON.stringify(v);
+}
+function disputeMessage(v) {
+    if (typeof v !== "string")
+        return;
+    const lines = v.split("\n");
+    if (lines.length !== 8 || lines[7] !== disputeConsent || lines[0] !== "402Mob delivery dispute authorization" || !lines[1]?.startsWith("Origin: ") || !lines[2]?.startsWith("Operation: ") || !lines[3]?.startsWith("Statement: ") || !lines[4]?.startsWith("Binding: ") || !lines[5]?.startsWith("Nonce: ") || !lines[6]?.startsWith("Expires: "))
+        return;
+    try {
+        const binding = JSON.parse(lines[4].slice(9));
+        if (binding !== null && !isRecord(binding))
+            return;
+        return { origin: lines[1].slice(8), operation: lines[2].slice(11), nonce: lines[5].slice(7), expires: lines[6].slice(9), statement: JSON.parse(lines[3].slice(11)), binding };
+    }
+    catch {
+        return;
+    }
+}
+function validDisputeBinding(b) {
+    return isRecord(b) && onlyKeys(b, ["requestHash", "workTicketId", "quoteTermsHash", "resultHashAtOpen", "transaction", "amountAtomic", "asset", "network"]) && digest(b.requestHash) &&
+        ((b.workTicketId === null && b.quoteTermsHash === null) || (uuid(b.workTicketId) && digest(b.quoteTermsHash))) && (b.resultHashAtOpen === null || digest(b.resultHashAtOpen)) &&
+        (b.transaction === null || typeof b.transaction === "string" && /^0x[0-9a-fA-F]{64}$/.test(b.transaction)) && atomicAmount(b.amountAtomic) && address(b.asset) && b.asset.toLowerCase() === baseUsdc && b.network === "eip155:8453";
+}
+function validMessageBinding(b) {
+    const { payer, recipient, ...rest } = b;
+    return address(payer) && address(recipient) && validDisputeBinding(rest);
+}
+function isDisputeResponse(v, operationId, proof, origin) {
+    if (v.protocol !== "402mob.delivery-dispute.v1" || v.operationId !== operationId || !isRecord(proof) || typeof v.replay !== "boolean")
+        return false;
+    if (v.kind === "acknowledgment") {
+        const r = v.receipt;
+        return onlyKeys(v, ["protocol", "kind", "operationId", "receipt", "replay"]) && isRecord(r) && onlyKeys(r, ["challengeId", "action", "revision", "createdAt"]) && r.challengeId === proof.challengeId && ["open", "respond", "close"].includes(String(r.action)) && Number.isInteger(r.revision) && Number(r.revision) >= 1 && Number(r.revision) <= 32 && timestamp(r.createdAt);
+    }
+    if (v.kind !== "evidence" || v.replay !== false || !onlyKeys(v, ["protocol", "kind", "operationId", "operationState", "binding", "dispute", "payment", "delivery", "responseOverdue", "buyerReviewOverdue", "scope", "replay"]) || !["executing", "staged", "settling", "pending", "settled", "failed", "expired"].includes(String(v.operationState)) || !isRecord(v.payment) || !onlyKeys(v.payment, ["state", "transaction"]) || !["settled", "pending", "failed", "unconfirmed"].includes(String(v.payment.state)) || !(v.payment.transaction === null || typeof v.payment.transaction === "string" && /^0x[0-9a-fA-F]{64}$/.test(v.payment.transaction)) || !isRecord(v.delivery) || !onlyKeys(v.delivery, ["resultHash", "resultAvailable"]) || typeof v.delivery.resultAvailable !== "boolean" || !(v.delivery.resultHash === null || digest(v.delivery.resultHash)) || typeof v.responseOverdue !== "boolean" || typeof v.buyerReviewOverdue !== "boolean" || !nonempty(v.scope))
+        return false;
+    if (!isRecord(v.binding) || !validMessageBinding(v.binding) || v.binding.transaction !== v.payment.transaction || v.binding.resultHashAtOpen !== v.delivery.resultHash)
+        return false;
+    if (v.payment.state === "settled" && v.payment.transaction === null)
+        return false;
+    const expectedPayment = { executing: "unconfirmed", staged: "unconfirmed", settling: "pending", pending: "pending", settled: "settled", failed: "failed" };
+    if (v.operationState !== "expired" && v.payment.state !== expectedPayment[String(v.operationState)])
+        return false;
+    if (v.operationState === "expired" && !["settled", "unconfirmed"].includes(String(v.payment.state)))
+        return false;
+    if (v.delivery.resultAvailable && (v.delivery.resultHash === null || v.payment.state !== "settled"))
+        return false;
+    if (v.binding.workTicketId === null && v.delivery.resultAvailable && v.operationState !== "settled")
+        return false;
+    if (v.dispute === null)
+        return !v.responseOverdue && !v.buyerReviewOverdue;
+    const d = v.dispute;
+    if (!isRecord(d) || d.operationId !== operationId || !address(d.buyer) || !address(d.seller) || !["open", "responded", "closed"].includes(String(d.status)) || !(d.outcome === null || ["resolved", "unresolved"].includes(String(d.outcome))) || !Number.isInteger(d.revision) || Number(d.revision) < 1 || Number(d.revision) > 32 || !timestamp(d.openedAt) || !timestamp(d.expiresAt) || !timestamp(d.responseDueAt) || !(d.buyerReviewDueAt === null || timestamp(d.buyerReviewDueAt)) || !validDisputeBinding(d.binding) || !Array.isArray(d.events) || d.events.length !== d.revision || v.payment.state !== "settled" || d.binding.transaction !== v.payment.transaction)
+        return false;
+    const currentBinding = v.binding, caseBinding = d.binding;
+    const immutable = ["requestHash", "workTicketId", "quoteTermsHash", "transaction", "amountAtomic", "asset", "network"];
+    if (v.binding.payer !== d.buyer || v.binding.recipient !== d.seller || immutable.some(k => currentBinding[k] !== caseBinding[k]))
+        return false;
+    if (Date.parse(d.expiresAt) !== Date.parse(d.openedAt) + 2592000000 || Date.parse(d.responseDueAt) !== Date.parse(d.openedAt) + 172800000)
+        return false;
+    let closed, firstResponse, lastTime = Date.parse(d.openedAt);
+    const seen = new Set();
+    for (let i = 0; i < d.events.length; i++) {
+        const e = d.events[i];
+        if (!isRecord(e) || e.revision !== i + 1 || !address(e.wallet) || !timestamp(e.createdAt) || !isDisputeRequest(e.statement) || e.statement.action === "read" || e.statement.action !== e.action || e.statement.expectedRevision !== i || e.wallet.toLowerCase() !== e.statement.wallet.toLowerCase() || typeof e.signature !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(e.signature) || !digest(e.challengeId) || seen.has(e.challengeId))
+            return false;
+        seen.add(e.challengeId);
+        const at = Date.parse(e.createdAt);
+        if (at < lastTime || at >= Date.parse(d.expiresAt))
+            return false;
+        lastTime = at;
+        const m = disputeMessage(e.message);
+        if (!m || m.origin !== origin || m.operation !== operationId || m.nonce !== e.challengeId || !timestamp(m.expires) || !isRecord(m.binding) || !validMessageBinding(m.binding) || m.binding.payer !== d.buyer || m.binding.recipient !== d.seller || m.binding.requestHash !== d.binding.requestHash || m.binding.quoteTermsHash !== d.binding.quoteTermsHash || immutable.some(k => m.binding[k] !== caseBinding[k]) || stableJson(m.binding) !== stableJson(e.statement.binding) || stableJson(m.statement) !== stableJson(e.statement))
+            return false;
+        if (i === 0) {
+            const { payer: _payer, recipient: _recipient, ...binding } = m.binding;
+            if (e.action !== "open" || e.wallet.toLowerCase() !== d.buyer.toLowerCase() || e.createdAt !== d.openedAt || stableJson(binding) !== stableJson(d.binding))
+                return false;
+        }
+        else if (e.action === "respond") {
+            if (e.wallet.toLowerCase() !== d.seller.toLowerCase())
+                return false;
+            if (!closed)
+                firstResponse ??= e;
+        }
+        else if (e.action === "close") {
+            if (closed || e.wallet.toLowerCase() !== d.buyer.toLowerCase())
+                return false;
+            closed = e;
+        }
+        else
+            return false;
+    }
+    if (d.status !== (closed ? "closed" : firstResponse ? "responded" : "open"))
+        return false;
+    if (d.outcome !== (closed ? closed.statement.outcome : null))
+        return false;
+    if (d.buyerReviewDueAt !== (firstResponse ? new Date(Date.parse(firstResponse.createdAt) + 604800000).toISOString() : null))
+        return false;
+    if ((d.status !== "open" && v.responseOverdue) || (d.status !== "responded" && v.buyerReviewOverdue))
+        return false;
+    return true;
+}
+export { ProtectedWorkClient, ProtectedWorkApiError } from "./protected-work.js";

package/dist/protected-work-schemas.d.ts

@@ -0,0 +1,2 @@
+export declare const protectedSchemaHash = "5c69849fb52f35cf29367043b58156d274955a79ef7ee52f0c78d6b4561e1b40";
+export declare const protectedSchemas: Record<string, unknown>;