s402 0.3.0 → 0.5.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "s402",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "type": "module",
-  "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for five payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
+  "description": "s402 — Chain-agnostic HTTP 402 wire format. Types, HTTP encoding, and scheme registry for six payment schemes. Wire-compatible with x402. Zero runtime dependencies.",
   "license": "Apache-2.0",
   "author": "SweeInc <daniel@sweeinc.com> (https://s402-protocol.org)",
   "repository": {
@@ -89,6 +89,13 @@
       },
       "default": "./dist/receipts.mjs"
     },
+    "./extensions": {
+      "import": {
+        "types": "./dist/extensions.d.mts",
+        "default": "./dist/extensions.mjs"
+      },
+      "default": "./dist/extensions.mjs"
+    },
     "./test-utils": {
       "import": {
         "types": "./dist/test-utils.d.mts",

package/test/conformance/vectors/body-transport.json

@@ -73,6 +73,48 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto requirements body with estimatedAmount",
+    "input": {
+      "type": "requirements",
+      "value": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "expected": {
+      "body": "{\"s402Version\":\"1\",\"accepts\":[\"upto\"],\"network\":\"sui:mainnet\",\"asset\":\"0x2::sui::SUI\",\"amount\":\"1000000\",\"payTo\":\"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890\",\"upto\":{\"maxAmount\":\"10000000\",\"settlementDeadlineMs\":\"1700000000000\",\"usageReportUrl\":\"https://api.example.com/usage\",\"estimatedAmount\":\"7500000\"}}",
+      "decoded": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Payload body encode/decode",
     "input": {

package/test/conformance/vectors/compat-normalize.json

@@ -18,7 +18,8 @@
       "network": "sui:mainnet",
       "asset": "0x2::sui::SUI",
       "amount": "1000000",
-      "payTo": "0xrecipient123"
+      "payTo": "0xrecipient123",
+      "expiresAt": 1700000060000
     },
     "shouldReject": false
   },

package/test/conformance/vectors/payload-decode.json

@@ -47,6 +47,39 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Decode upto payload with settlementCeiling",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "10000000",
+        "settlementCeiling": "8000000"
+      }
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Decode upto payload without settlementCeiling",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjUwMDAwMDAifX0="
+    },
+    "expected": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "5000000"
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Decode stream payload",
     "input": {

package/test/conformance/vectors/payload-encode.json

@@ -31,6 +31,39 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto payload with maxAmount and settlementCeiling",
+    "input": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "10000000",
+        "settlementCeiling": "8000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto payload without settlementCeiling (backwards compatible)",
+    "input": {
+      "s402Version": "1",
+      "scheme": "upto",
+      "payload": {
+        "transaction": "dXB0b190eA==",
+        "signature": "dXB0b19zaWc=",
+        "maxAmount": "5000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjUwMDAwMDAifX0="
+    },
+    "shouldReject": false
+  },
   {
     "description": "Stream payload",
     "input": {

package/test/conformance/vectors/requirements-decode.json

@@ -38,6 +38,50 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Decode upto scheme with estimatedAmount",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "10000000",
+        "settlementDeadlineMs": "1700000000000",
+        "usageReportUrl": "https://api.example.com/usage",
+        "estimatedAmount": "7500000"
+      }
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Decode upto scheme minimal",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiI1MDAwMDAwIiwic2V0dGxlbWVudERlYWRsaW5lTXMiOiIxNzAwMDAwMDAwMDAwIn19"
+    },
+    "expected": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "5000000",
+        "settlementDeadlineMs": "1700000000000"
+      }
+    },
+    "shouldReject": false
+  },
   {
     "description": "Decode escrow scheme",
     "input": {

package/test/conformance/vectors/requirements-encode.json

@@ -38,6 +38,50 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto scheme with estimatedAmount",
+    "input": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "10000000",
+        "settlementDeadlineMs": "1700000000000",
+        "usageReportUrl": "https://api.example.com/usage",
+        "estimatedAmount": "7500000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto scheme minimal (no estimatedAmount)",
+    "input": {
+      "s402Version": "1",
+      "accepts": [
+        "upto"
+      ],
+      "network": "sui:mainnet",
+      "asset": "0x2::sui::SUI",
+      "amount": "1000000",
+      "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+      "upto": {
+        "maxAmount": "5000000",
+        "settlementDeadlineMs": "1700000000000"
+      }
+    },
+    "expected": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiI1MDAwMDAwIiwic2V0dGxlbWVudERlYWRsaW5lTXMiOiIxNzAwMDAwMDAwMDAwIn19"
+    },
+    "shouldReject": false
+  },
   {
     "description": "Escrow scheme with extras",
     "input": {

package/test/conformance/vectors/roundtrip.json

@@ -123,6 +123,58 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Upto requirements with estimatedAmount roundtrip",
+    "input": {
+      "type": "requirements",
+      "transport": "header",
+      "value": {
+        "s402Version": "1",
+        "accepts": [
+          "upto"
+        ],
+        "network": "sui:mainnet",
+        "asset": "0x2::sui::SUI",
+        "amount": "1000000",
+        "payTo": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
+        "upto": {
+          "maxAmount": "10000000",
+          "settlementDeadlineMs": "1700000000000",
+          "usageReportUrl": "https://api.example.com/usage",
+          "estimatedAmount": "7500000"
+        }
+      }
+    },
+    "expected": {
+      "firstEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19",
+      "reEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiIweDI6OnN1aTo6U1VJIiwiYW1vdW50IjoiMTAwMDAwMCIsInBheVRvIjoiMHhhYmNkZWYxMjM0NTY3ODkwYWJjZGVmMTIzNDU2Nzg5MGFiY2RlZjEyMzQ1Njc4OTBhYmNkZWYxMjM0NTY3ODkwIiwidXB0byI6eyJtYXhBbW91bnQiOiIxMDAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsInVzYWdlUmVwb3J0VXJsIjoiaHR0cHM6Ly9hcGkuZXhhbXBsZS5jb20vdXNhZ2UiLCJlc3RpbWF0ZWRBbW91bnQiOiI3NTAwMDAwIn19",
+      "identical": true
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Upto payload with settlementCeiling roundtrip",
+    "input": {
+      "type": "payload",
+      "transport": "header",
+      "value": {
+        "s402Version": "1",
+        "scheme": "upto",
+        "payload": {
+          "transaction": "dXB0b190eA==",
+          "signature": "dXB0b19zaWc=",
+          "maxAmount": "10000000",
+          "settlementCeiling": "8000000"
+        }
+      }
+    },
+    "expected": {
+      "firstEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19",
+      "reEncode": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRYQjBiMTkwZUE9PSIsInNpZ25hdHVyZSI6ImRYQjBiMTl6YVdjPSIsIm1heEFtb3VudCI6IjEwMDAwMDAwIiwic2V0dGxlbWVudENlaWxpbmciOiI4MDAwMDAwIn19",
+      "identical": true
+    },
+    "shouldReject": false
+  },
   {
     "description": "Complex requirements with extensions roundtrip",
     "input": {

package/test/conformance/vectors/settle-decode.json

@@ -61,6 +61,20 @@
     },
     "shouldReject": false
   },
+  {
+    "description": "Decode success with actualAmount and depositId (upto)",
+    "input": {
+      "header": "eyJzdWNjZXNzIjp0cnVlLCJ0eERpZ2VzdCI6InVwdG9fZGVjb2RlX2RpZ2VzdCIsImFjdHVhbEFtb3VudCI6Ijc1MDAwMDAiLCJkZXBvc2l0SWQiOiIweGRlcG9zaXRfZGVjb2RlXzEyMyIsImZpbmFsaXR5TXMiOjI1MH0="
+    },
+    "expected": {
+      "success": true,
+      "txDigest": "upto_decode_digest",
+      "finalityMs": 250,
+      "actualAmount": "7500000",
+      "depositId": "0xdeposit_decode_123"
+    },
+    "shouldReject": false
+  },
   {
     "description": "Decode strips unknown top-level keys from settle response",
     "input": {

package/test/conformance/vectors/settle-encode.json

@@ -61,5 +61,33 @@
       "header": "eyJzdWNjZXNzIjp0cnVlLCJ0eERpZ2VzdCI6InByZXAxMjMiLCJiYWxhbmNlSWQiOiIweGJhbGFuY2U3ODkiLCJmaW5hbGl0eU1zIjozMDB9"
     },
     "shouldReject": false
+  },
+  {
+    "description": "Success with actualAmount and depositId (upto)",
+    "input": {
+      "success": true,
+      "txDigest": "upto_digest_abc",
+      "actualAmount": "7500000",
+      "depositId": "0xdeposit_upto_123",
+      "finalityMs": 250
+    },
+    "expected": {
+      "header": "eyJzdWNjZXNzIjp0cnVlLCJ0eERpZ2VzdCI6InVwdG9fZGlnZXN0X2FiYyIsImFjdHVhbEFtb3VudCI6Ijc1MDAwMDAiLCJkZXBvc2l0SWQiOiIweGRlcG9zaXRfdXB0b18xMjMiLCJmaW5hbGl0eU1zIjoyNTB9"
+    },
+    "shouldReject": false
+  },
+  {
+    "description": "Success with actualAmount at zero (upto full refund)",
+    "input": {
+      "success": true,
+      "txDigest": "upto_refund_xyz",
+      "actualAmount": "0",
+      "depositId": "0xdeposit_refund_456",
+      "finalityMs": 180
+    },
+    "expected": {
+      "header": "eyJzdWNjZXNzIjp0cnVlLCJ0eERpZ2VzdCI6InVwdG9fcmVmdW5kX3h5eiIsImFjdHVhbEFtb3VudCI6IjAiLCJkZXBvc2l0SWQiOiIweGRlcG9zaXRfcmVmdW5kXzQ1NiIsImZpbmFsaXR5TXMiOjE4MH0="
+    },
+    "shouldReject": false
   }
 ]

package/test/conformance/vectors/settlement-verification.json

@@ -0,0 +1,180 @@
+[
+  {
+    "description": "Matching digest — verified is true, digests equal",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "exact",
+      "payload": {
+        "transaction": "dHgtYnl0ZXMtaGVyZQ==",
+        "signature": "c2lnLWJ5dGVzLWhlcmU="
+      }
+    },
+    "settleResponse": {
+      "success": true,
+      "txDigest": "KNOWN_DIGEST_ABC123"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "IF verified === true THEN expectedDigest === actualDigest",
+      "actualDigest MUST equal settleResponse.txDigest"
+    ],
+    "notes": "The implementation derives expectedDigest from payload.payload.transaction using a chain-specific algorithm. If the facilitator returned the correct digest, verified MUST be true."
+  },
+  {
+    "description": "Mismatched digest — verified is false with DIGEST_MISMATCH reason",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "exact",
+      "payload": {
+        "transaction": "dHgtYnl0ZXMtaGVyZQ==",
+        "signature": "c2lnLWJ5dGVzLWhlcmU="
+      }
+    },
+    "settleResponse": {
+      "success": true,
+      "txDigest": "WRONG_DIGEST_XYZ789"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "verified MUST be false",
+      "expectedDigest MUST NOT equal actualDigest",
+      "actualDigest MUST equal settleResponse.txDigest",
+      "reason SHOULD contain 'DIGEST_MISMATCH' or indicate the mismatch"
+    ],
+    "notes": "A malicious facilitator returns a real but unrelated digest. The client detects the mismatch locally without any RPC call."
+  },
+  {
+    "description": "Settle failed — no txDigest available",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "exact",
+      "payload": {
+        "transaction": "dHgtYnl0ZXMtaGVyZQ==",
+        "signature": "c2lnLWJ5dGVzLWhlcmU="
+      }
+    },
+    "settleResponse": {
+      "success": false,
+      "error": "Insufficient gas"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "verified MUST be false",
+      "actualDigest MUST be null (no digest was returned)",
+      "reason SHOULD indicate no digest was available"
+    ],
+    "notes": "When settlement fails, there is no digest to verify. The implementation should handle this gracefully rather than throwing."
+  },
+  {
+    "description": "Settle succeeded but txDigest is undefined",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "exact",
+      "payload": {
+        "transaction": "dHgtYnl0ZXMtaGVyZQ==",
+        "signature": "c2lnLWJ5dGVzLWhlcmU="
+      }
+    },
+    "settleResponse": {
+      "success": true
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "verified MUST be false",
+      "actualDigest MUST be null",
+      "reason SHOULD indicate missing digest"
+    ],
+    "notes": "Edge case: facilitator reports success but omits the digest. This should be treated as unverifiable — the client cannot confirm settlement."
+  },
+  {
+    "description": "Invalid base64 in payload transaction bytes",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "exact",
+      "payload": {
+        "transaction": "!!!NOT-BASE64!!!",
+        "signature": "c2lnLWJ5dGVzLWhlcmU="
+      }
+    },
+    "settleResponse": {
+      "success": true,
+      "txDigest": "SOME_DIGEST"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "verified MUST be false",
+      "MUST NOT throw — return a verification result with reason"
+    ],
+    "notes": "Malformed input must fail gracefully. Implementations MUST catch decode errors and return { verified: false } rather than propagating exceptions."
+  },
+  {
+    "description": "Stream scheme — same verification contract applies",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "stream",
+      "payload": {
+        "transaction": "c3RyZWFtLXR4LWJ5dGVz",
+        "signature": "c3RyZWFtLXNpZw=="
+      }
+    },
+    "settleResponse": {
+      "success": true,
+      "txDigest": "STREAM_DIGEST_123"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "IF verified === true THEN expectedDigest === actualDigest",
+      "actualDigest MUST equal settleResponse.txDigest"
+    ],
+    "notes": "The S8 invariant applies to ALL client-signed schemes, not just exact. Stream, escrow, prepaid, and unlock-TX1 all sign full transactions before sending to the facilitator."
+  },
+  {
+    "description": "Scheme that cannot verify locally (e.g. unlock-TX2)",
+    "payload": {
+      "s402Version": "1",
+      "scheme": "unlock",
+      "payload": {
+        "transaction": "",
+        "signature": ""
+      }
+    },
+    "settleResponse": {
+      "success": true,
+      "txDigest": "FACILITATOR_BUILT_TX"
+    },
+    "expectedShape": {
+      "verified": "boolean",
+      "expectedDigest": "string",
+      "actualDigest": "string|null"
+    },
+    "invariants": [
+      "verified MUST be false",
+      "reason MUST be present and explain why verification is not possible"
+    ],
+    "notes": "For schemes where the facilitator constructs the transaction (e.g. unlock phase 2), the client has no signed bytes to derive a digest from. The implementation MUST return { verified: false } with a reason, not throw."
+  }
+]

package/test/conformance/vectors/validation-reject.json

@@ -175,6 +175,75 @@
     "shouldReject": true,
     "expectedErrorCode": "INVALID_PAYLOAD"
   },
+  {
+    "description": "Rejects upto.estimatedAmount exceeding maxAmount",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiJTVUkiLCJhbW91bnQiOiIxMDAwIiwicGF5VG8iOiIweGFiYyIsInVwdG8iOnsibWF4QW1vdW50IjoiNTAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsImVzdGltYXRlZEFtb3VudCI6IjUwMDAwMDEifX0="
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects upto payload with settlementCeiling of zero",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRIZz0iLCJzaWduYXR1cmUiOiJjMmxuIiwibWF4QW1vdW50IjoiMTAwMDAwMCIsInNldHRsZW1lbnRDZWlsaW5nIjoiMCJ9fQ==",
+      "decodeAs": "payload"
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects upto payload with settlementCeiling exceeding maxAmount",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRIZz0iLCJzaWduYXR1cmUiOiJjMmxuIiwibWF4QW1vdW50IjoiMTAwMDAwMCIsInNldHRsZW1lbnRDZWlsaW5nIjoiMTAwMDAwMSJ9fQ==",
+      "decodeAs": "payload"
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects upto.estimatedAmount as number (must be string)",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbInVwdG8iXSwibmV0d29yayI6InN1aTptYWlubmV0IiwiYXNzZXQiOiJTVUkiLCJhbW91bnQiOiIxMDAwIiwicGF5VG8iOiIweGFiYyIsInVwdG8iOnsibWF4QW1vdW50IjoiNTAwMDAwMCIsInNldHRsZW1lbnREZWFkbGluZU1zIjoiMTcwMDAwMDAwMDAwMCIsImVzdGltYXRlZEFtb3VudCI6MTIzfX0="
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects upto payload with numeric settlementCeiling (must be string)",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJ1cHRvIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRIZz0iLCJzaWduYXR1cmUiOiJjMmxuIiwibWF4QW1vdW50IjoiMTAwMDAwMCIsInNldHRsZW1lbnRDZWlsaW5nIjo1MDAwMDB9fQ==",
+      "decodeAs": "payload"
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects prepaid payload with negative ratePerCall",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJwcmVwYWlkIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRIZz0iLCJzaWduYXR1cmUiOiJjMmxuIiwicmF0ZVBlckNhbGwiOiItNSJ9fQ==",
+      "decodeAs": "payload"
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects prepaid payload with non-numeric maxCalls",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJzY2hlbWUiOiJwcmVwYWlkIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6ImRIZz0iLCJzaWduYXR1cmUiOiJjMmxuIiwicmF0ZVBlckNhbGwiOiIxMDAiLCJtYXhDYWxscyI6ImFiYyJ9fQ==",
+      "decodeAs": "payload"
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
+  {
+    "description": "Rejects mandate.minPerTx with leading zeros",
+    "input": {
+      "header": "eyJzNDAyVmVyc2lvbiI6IjEiLCJhY2NlcHRzIjpbImV4YWN0Il0sIm5ldHdvcmsiOiJzdWk6bWFpbm5ldCIsImFzc2V0IjoiU1VJIiwiYW1vdW50IjoiMTAwMCIsInBheVRvIjoiMHhhYmMiLCJtYW5kYXRlIjp7InJlcXVpcmVkIjp0cnVlLCJtaW5QZXJUeCI6IjAwNyJ9fQ=="
+    },
+    "shouldReject": true,
+    "expectedErrorCode": "INVALID_PAYLOAD"
+  },
   {
     "description": "Rejects invalid base64 header",
     "input": {