twin3-sdk 0.2.19-pre-alpha → 0.2.20-pre-alpha

package/README.md

@@ -116,7 +116,7 @@ pip install -e /path/to/twin3-sdk
 * Any protocol or algorithm improvement in `twin3-sdk` is reflected in both applications in **0 milliseconds**.
 
 #### 2. Production Distribution
-`v0.2.19-pre-alpha` is the current release candidate: `0.2.19-pre-alpha` for npm and `0.2.19a0` for PyPI. It is published from reviewed main through the existing Cloud Build tag trigger. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
+`v0.2.20-pre-alpha` is the current release candidate: `0.2.20-pre-alpha` for npm and `0.2.20a0` for PyPI. It is published from reviewed main through the existing Cloud Build tag trigger. Consumers must pin the exact released version and lock its registry integrity; never use a mutable range for a cryptographic protocol dependency. This release stays pre-alpha. Marketplace or sales copy may offer it for evaluation; it is not a stable release, and the npm dist-tag is `next`, not `latest`.
 
 The additive `twin3-sdk/runtime` subpath provides a single-action Agent runtime candidate. Products retain authenticated authority, context egress consent, durable storage and trusted tool brokers. Python `twin3.runtime` provides compatible contracts and digests only. OpenShell, ADK and Hermes adapters are not included. See [runtime scope and limits](docs/architecture/PERSONAL-AGENT-RUNTIME-V1.md).
 
@@ -125,15 +125,15 @@ The additive `twin3-sdk/runtime` subpath provides a single-action Agent runtime
 After publication, install the exact released version from the registry:
 
 ```bash
-npm install twin3-sdk@0.2.19-pre-alpha
-pip install twin3-sdk==0.2.19a0
+npm install twin3-sdk@0.2.20-pre-alpha
+pip install twin3-sdk==0.2.20a0
 ```
 
 For local evaluation, you can also use the packed npm tarball. Do not install from a git URL or a version range:
 
 ```bash
 npm pack --ignore-scripts
-npm install ./twin3-sdk-0.2.19-pre-alpha.tgz
+npm install ./twin3-sdk-0.2.20-pre-alpha.tgz
 ```
 
 ---
@@ -146,6 +146,9 @@ Agent ID consumes Twin3 SDK to execute the **5-Stage A2A Autonomous Commercial L
 2. **Understand**: Uses `twin3.matrix` to compute tolerance matching against industrial RFQs.
 3. **Negotiate**: Uses `twin3.comm` and `twin3.shield` to exchange signed quotes without prompt-tampering risks.
 4. **Settle**: Uses the Twin3 signed-receipt adapter at an HTTP 402 gate. Acceptance additionally requires a trusted signer key, a chain-specific finality verifier, and a shared replay store.
+
+Settlement integrations must follow the [x402 security boundaries](docs/x402-security-boundaries.md),
+including case-sensitive wallet binding, canonical network names and durable payment recovery.
 5. **Dispute**: Invokes `twin3.governance` to resolve contractual non-performance.
 
 ### 👤 Human ID (Personal Sovereignty Projection)

package/js/internal/comm.js

@@ -822,7 +822,7 @@ function x402ChainAdapter(chainVerifier, demand, receipt) {
                 : (chainVerifier && (chainVerifier.verifyPayment || chainVerifier.verify_payment));
             if (typeof method !== "function")
                 core.fail("chain_verifier_invalid");
-            const evidence = await method.call(chainVerifier, demand, receipt);
+            const evidence = await method.call(chainVerifier, structuredClone(demand), structuredClone(receipt));
             if (!evidence || typeof evidence !== "object")
                 return evidence;
             return {
@@ -960,21 +960,24 @@ class TaskInbox {
         const payout = String(policy.payout_address || "").trim();
         if (!payout)
             core.fail("payment_payout_address_required");
-        if (demand.recipient.trim().toLowerCase() !== payout.toLowerCase())
+        if (settlement.chainIdentifier(demand.recipient, demand.network) !== settlement.chainIdentifier(payout, demand.network))
             core.fail("payment_demand_recipient_mismatch");
         const price = core.isPlainObject(policy.price) ? policy.price : {};
-        if (Number(demand.amount) < Number(price.amount || 0))
+        settlement.positiveProtocolAmount(demand.amount, "invalid_demand_amount");
+        if (settlement.money(demand.amount).compare(settlement.money(price.amount || "0")) < 0)
             core.fail("payment_demand_amount_insufficient");
         const policyCurrency = String(price.currency || "").trim().toUpperCase();
         if (!policyCurrency || demand.currency.toUpperCase() !== policyCurrency)
             core.fail("payment_demand_currency_mismatch");
         const partyRow = this._parties.get(identity, { now: at }) || {};
-        const boundWallet = String(partyRow.bound_wallet || "").trim().toLowerCase();
-        const payer = receipt.payer.trim().toLowerCase();
-        const senderValue = String(identity.value || "").trim().toLowerCase();
-        const senderKey = counterpartyKey(identity).toLowerCase();
+        const boundWallet = String(partyRow.bound_wallet || "").trim();
+        const payer = settlement.chainIdentifier(receipt.payer, demand.network);
+        const senderValue = settlement.chainIdentifier(String(identity.value || ""), demand.network);
+        const senderKey = settlement.chainIdentifier(counterpartyKey(identity), demand.network);
         if (boundWallet) {
-            if (payer !== boundWallet)
+            if (settlement.chainIdentifier("A", demand.network) === "A" && partyRow.bound_wallet_case_preserved !== true)
+                core.fail("payment_wallet_rebinding_required");
+            if (payer !== settlement.chainIdentifier(boundWallet, demand.network))
                 core.fail("payment_payer_mismatch");
         }
         else if (payer !== senderValue && payer !== senderKey) {
@@ -2578,11 +2581,14 @@ function createCounterpartyTable({ store, owner, now, ownerPublicKey, legacyTier
         },
         bindWallet(identity, walletAddress, { actor = "owner", reason = "wallet_binding", now: when } = {}) {
             const [row, when_] = mutate(identity, when);
-            const wallet = (core.pythonTruthy(walletAddress) ? core.pythonText(walletAddress, "wallet_address_required") : "")
-                .trim().toLowerCase();
+            let wallet = (core.pythonTruthy(walletAddress) ? core.pythonText(walletAddress, "wallet_address_required") : "")
+                .trim();
+            if (/^0x/i.test(wallet))
+                wallet = wallet.toLowerCase();
             if (!wallet)
                 core.fail("wallet_address_required");
             row.bound_wallet = wallet;
+            row.bound_wallet_case_preserved = true;
             audit(row, "bind_wallet", row.tier, row.tier, actor, `${reason}:${wallet}`, when_);
             return structuredClone(row);
         },

package/js/internal/discovery.js

@@ -903,7 +903,7 @@ function x402Facilitator(value, host) {
     if (!endpoints || typeof endpoints !== "object" || Array.isArray(endpoints))
         core.fail("x402_facilitator_endpoints_invalid");
     for (const name of ["supported", "verify", "settle"]) {
-        if (typeof endpoints[name] !== "string" || !endpoints[name].startsWith("/"))
+        if (typeof endpoints[name] !== "string" || !endpoints[name].startsWith("/") || endpoints[name].startsWith("//") || /[\\\s\x00-\x1f\x7f#]/.test(endpoints[name]))
             core.fail("x402_facilitator_endpoints_invalid");
     }
     const kinds = value.kinds;
@@ -1041,6 +1041,8 @@ function parseX402DnsTxt(records, host) {
 }
 function x402AddressIsUnsafe(address) {
     const text = String(address).trim();
+    if (require("node:net").isIP(text) === 0 || text.includes("%"))
+        core.fail("x402_fetch_address_invalid");
     const v4 = text.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
     if (v4) {
         const [a, b] = [Number(v4[1]), Number(v4[2])];
@@ -1052,15 +1054,11 @@ function x402AddressIsUnsafe(address) {
             || a >= 224;
     }
     if (text.includes(":")) {
-        const lower = text.toLowerCase();
-        if (!/^[0-9a-f:.]+$/.test(lower))
-            core.fail("x402_fetch_address_invalid");
-        if (lower === "::" || lower === "::1")
-            return true;
-        if (lower.startsWith("::ffff:"))
-            return x402AddressIsUnsafe(lower.slice("::ffff:".length));
-        return lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb")
-            || lower.startsWith("fc") || lower.startsWith("fd") || lower.startsWith("ff") || lower.startsWith("2001:db8") || lower.startsWith("2001:0db8");
+        const lower = new URL(`https://[${text}]/`).hostname.slice(1, -1);
+        const [first, second] = lower.split(":").map((part) => parseInt(part || "0", 16));
+        return first < 0x2000 || first > 0x3fff || first === 0x2002
+            || (first === 0x2001 && (second < 0x200 || second === 0xdb8))
+            || (first === 0x3fff && second < 0x1000);
     }
     core.fail("x402_fetch_address_invalid");
 }
@@ -1079,6 +1077,8 @@ function checkX402FetchTarget(url, host, { resolvedAddresses = [], hop = 0, maxR
         if (targetHost === "localhost" || targetHost.endsWith(".localhost"))
             core.fail("x402_fetch_private_address");
         const unbracketed = targetHost.replace(/^\[|\]$/g, "");
+        if (/^(?:\d+|0x[0-9a-f]*)$/.test(unbracketed.split(".").at(-1)) && !/^(\d{1,3}\.){3}\d{1,3}$/.test(unbracketed))
+            core.fail("x402_fetch_private_address");
         if ((/^(\d{1,3}\.){3}\d{1,3}$/.test(unbracketed) || unbracketed.includes(":")) && x402AddressIsUnsafe(unbracketed)) {
             core.fail("x402_fetch_private_address");
         }

package/js/internal/settlement.js

@@ -216,6 +216,16 @@ function positiveProtocolInteger(value, code) {
         core.fail(code);
     return value;
 }
+function paymentNetworkKey(value) {
+    value = requiredProtocolText(value, "network_required");
+    return value.includes(":") ? value : value.toLowerCase();
+}
+function chainIdentifier(value, network) {
+    value = requiredProtocolText(value, "chain_evidence_invalid");
+    network = paymentNetworkKey(network);
+    return network.startsWith("eip155:") || ["base", "base-sepolia", "ethereum", "ethereum-sepolia", "polygon", "arbitrum", "optimism"].includes(network)
+        ? value.toLowerCase() : value;
+}
 function computeReceiptDigest({ demandId, txHash, payer, amount, currency, settledAt, recipient, network }) {
     demandId = requiredProtocolText(demandId, "demand_id_required");
     txHash = requiredProtocolText(txHash, "tx_hash_required");
@@ -259,7 +269,7 @@ function verifySignedPaymentReceipt({ demandAmount, receiptAmount, demandRecipie
         core.fail("payment_currency_mismatch");
     demandNetwork = requiredProtocolText(demandNetwork, "network_required");
     receiptNetwork = requiredProtocolText(receiptNetwork, "network_required");
-    if (receiptNetwork.toLowerCase() !== demandNetwork.toLowerCase())
+    if (paymentNetworkKey(receiptNetwork) !== paymentNetworkKey(demandNetwork))
         core.fail("payment_network_mismatch");
     demandExpiresAt = positiveProtocolInteger(demandExpiresAt, "demand_expiry_required");
     if (typeof now !== "number" || !Number.isFinite(now))
@@ -271,7 +281,7 @@ function verifySignedPaymentReceipt({ demandAmount, receiptAmount, demandRecipie
         core.fail("settled_at_in_future");
     receiptRecipient = requiredProtocolText(receiptRecipient, "recipient_required");
     demandRecipient = requiredProtocolText(demandRecipient, "expected_recipient_required");
-    if (receiptRecipient.toLowerCase() !== demandRecipient.toLowerCase())
+    if (chainIdentifier(receiptRecipient, demandNetwork) !== chainIdentifier(demandRecipient, demandNetwork))
         core.fail("payment_recipient_mismatch");
     signature = requiredProtocolText(signature, "receipt_signature_required");
     txHash = requiredProtocolText(txHash, "tx_hash_required");
@@ -314,6 +324,12 @@ function isReservationStore(store) {
         typeof store.release === "function");
 }
 async function verifyX402Payment(params) {
+    params = { ...params };
+    for (const name of ["demandRecipient", "receiptRecipient", "demandCurrency", "receiptCurrency", "demandNetwork", "receiptNetwork", "txHash", "payer", "signature", "demandId", "receiptDemandId"])
+        if (typeof params[name] === "string") params[name] = params[name].trim();
+    if (params.tokenAddress !== undefined && params.tokenAddress !== null)
+        params.tokenAddress = requiredProtocolText(params.tokenAddress, "token_address_invalid");
+    Object.freeze(params);
     verifySignedPaymentReceipt(params);
     const { chainVerifier, replayStore, minimumConfirmations = 1 } = params;
     if (!chainVerifier)
@@ -327,7 +343,7 @@ async function verifyX402Payment(params) {
     if (!reservationMode) {
         core.fail("reservation_capable_store_required");
     }
-    if (typeof minimumConfirmations !== "number" || !Number.isInteger(minimumConfirmations) || minimumConfirmations < 1) {
+    if (typeof minimumConfirmations !== "number" || !Number.isSafeInteger(minimumConfirmations) || minimumConfirmations < 1) {
         core.fail("minimum_confirmations_invalid");
     }
     const requiredConfirmations = minimumConfirmations;
@@ -372,20 +388,20 @@ async function verifyX402Payment(params) {
         }
         if (!evidence || typeof evidence !== "object")
             core.fail("chain_evidence_invalid");
-        if (typeof evidence.confirmations !== "number" || !Number.isInteger(evidence.confirmations) || evidence.confirmations < 0) {
+        if (typeof evidence.confirmations !== "number" || !Number.isSafeInteger(evidence.confirmations) || evidence.confirmations < 0) {
             core.fail("chain_evidence_invalid");
         }
         if (evidence.finalized !== true || evidence.confirmations < requiredConfirmations) {
             core.fail("payment_not_finalized");
         }
         const exact = [
-            [evidence.txHash, params.txHash],
-            [evidence.network, params.demandNetwork],
-            [evidence.payer, params.payer],
-            [evidence.recipient, params.demandRecipient],
-            [String(evidence.currency || "").toUpperCase(), String(params.demandCurrency).toUpperCase()],
+            [chainIdentifier(evidence.txHash, params.demandNetwork), chainIdentifier(params.txHash, params.demandNetwork)],
+            [paymentNetworkKey(evidence.network), paymentNetworkKey(params.demandNetwork)],
+            [chainIdentifier(evidence.payer, params.demandNetwork), chainIdentifier(params.payer, params.demandNetwork)],
+            [chainIdentifier(evidence.recipient, params.demandNetwork), chainIdentifier(params.demandRecipient, params.demandNetwork)],
+            [requiredProtocolText(evidence.currency, "chain_evidence_invalid").toUpperCase(), params.demandCurrency.toUpperCase()],
         ];
-        if (exact.some(([actual, expected]) => String(actual || "").toLowerCase() !== String(expected || "").toLowerCase())) {
+        if (exact.some(([actual, expected]) => actual !== expected)) {
             core.fail("chain_evidence_mismatch");
         }
         let evidenceAmount;
@@ -397,7 +413,7 @@ async function verifyX402Payment(params) {
         }
         if (evidenceAmount !== params.receiptAmount)
             core.fail("chain_evidence_mismatch");
-        if (params.tokenAddress && String(evidence.tokenAddress || "").toLowerCase() !== String(params.tokenAddress).toLowerCase()) {
+        if (params.tokenAddress && (!evidence.tokenAddress || chainIdentifier(evidence.tokenAddress, params.demandNetwork) !== chainIdentifier(params.tokenAddress, params.demandNetwork))) {
             core.fail("chain_token_mismatch");
         }
         let committed;
@@ -461,6 +477,7 @@ module.exports = {
   requiredProtocolText,
   positiveProtocolAmount,
   positiveProtocolInteger,
+  chainIdentifier,
   computeReceiptDigest,
   verifySignedPaymentReceipt,
   REPLAY_RESERVATION_SECONDS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twin3-sdk",
-  "version": "0.2.19-pre-alpha",
+  "version": "0.2.20-pre-alpha",
   "description": "Universal Capability Motherboard for Autonomous AI Agents and Self-Sovereign Humans (JS/Node runtime)",
   "type": "commonjs",
   "main": "./js/index.js",