@stellar-agent-services/protocol 0.0.0-stage → 0.1.1

package/test-vectors/canonical-json.json

@@ -0,0 +1,94 @@
+{
+  "description": "RFC 8785 (JCS) canonical JSON. For each case, parse `json`, canonicalize it, and compare the result with `canonical` character for character; `sha256` is the lowercase hex SHA-256 of its UTF-8 bytes. For each number, the IEEE 754 double with bits `ieee754` canonicalizes to `canonical`. Every `invalid` entry must be rejected.",
+  "source": "RFC 8785 §3.2.2, §3.2.3 and Appendix B, plus cases for Provider Standard v1. Cross-checked with the canonicalize package by an RFC 8785 author.",
+  "cases": [
+    {
+      "name": "RFC 8785 §3.2.2 example",
+      "json": "{\n  \"numbers\": [333333333.33333329, 1E30, 4.50,\n              2e-3, 0.000000000000000000000000001],\n  \"string\": \"\\u20ac$\\u000F\\u000aA'\\u0042\\u0022\\u005c\\\\\\\"\\/\",\n  \"literals\": [null, true, false]\n}",
+      "canonical": "{\"literals\":[null,true,false],\"numbers\":[333333333.3333333,1e+30,4.5,0.002,1e-27],\"string\":\"€$\\u000f\\nA'B\\\"\\\\\\\\\\\"/\"}",
+      "sha256": "2d5e01a318d0f0879ab568c4be289c8b1f64ef8921a53c6277d5e069978baacb"
+    },
+    {
+      "name": "RFC 8785 §3.2.3 sorting example: keys are compared as UTF-16 code units",
+      "json": "{\n  \"\\u20ac\": \"Euro Sign\",\n  \"\\r\": \"Carriage Return\",\n  \"\\ufb33\": \"Hebrew Letter Dalet With Dagesh\",\n  \"1\": \"One\",\n  \"\\ud83d\\ude00\": \"Emoji: Grinning Face\",\n  \"\\u0080\": \"Control\",\n  \"\\u00f6\": \"Latin Small Letter O With Diaeresis\"\n}",
+      "canonical": "{\"\\r\":\"Carriage Return\",\"1\":\"One\",\"\u0080\":\"Control\",\"ö\":\"Latin Small Letter O With Diaeresis\",\"€\":\"Euro Sign\",\"😀\":\"Emoji: Grinning Face\",\"דּ\":\"Hebrew Letter Dalet With Dagesh\"}",
+      "sha256": "5e321556d22018a9656991a9e94f77ec175fa193e52a2429d312f8419ec8b08c"
+    },
+    {
+      "name": "whitespace and key order do not matter",
+      "json": "{ \"b\" : 2 , \"a\" : [ 1 , 2 ] , \"c\" : { \"z\" : null , \"y\" : true } }",
+      "canonical": "{\"a\":[1,2],\"b\":2,\"c\":{\"y\":true,\"z\":null}}",
+      "sha256": "a64f58f8aa2f3aba0ede6531306d8094ec11b12b1051b2929285a0f803b42c53"
+    },
+    {
+      "name": "empty containers",
+      "json": "{\"object\":{},\"array\":[],\"string\":\"\"}",
+      "canonical": "{\"array\":[],\"object\":{},\"string\":\"\"}",
+      "sha256": "160df1cb7c08864a4d113733fe02cfbc06a3e39c4ce0e0273ca7f2bb42e0facc"
+    },
+    {
+      "name": "objects are sorted at every depth; arrays keep their order",
+      "json": "{\"z\":{\"b\":{\"d\":1,\"c\":2},\"a\":[{\"y\":1,\"x\":2},3]},\"a\":0}",
+      "canonical": "{\"a\":0,\"z\":{\"a\":[{\"x\":2,\"y\":1},3],\"b\":{\"c\":2,\"d\":1}}}",
+      "sha256": "c90dff4558815659aa438ae7de17fa587e7b155aae5a4edb0bd73993176e1792"
+    },
+    {
+      "name": "number formatting",
+      "json": "[0, -0, 1, -1, 1.5, 0.1, 100.000, 1E+2, 123e-2, 1e20, 1e21, 0.000001, 1e-7]",
+      "canonical": "[0,0,1,-1,1.5,0.1,100,100,1.23,100000000000000000000,1e+21,0.000001,1e-7]",
+      "sha256": "95dad194c18706dc426c66239fc41371eba794d7e66476dd443379a4840bc2a3"
+    },
+    {
+      "name": "integers up to 2^53 - 1 stay exact",
+      "json": "[9007199254740991, -9007199254740991]",
+      "canonical": "[9007199254740991,-9007199254740991]",
+      "sha256": "84bad60c1793654a7cdca854230af90af531ecc8f7656e2c7b2bd91890017b37"
+    },
+    {
+      "name": "string escaping: only quote, backslash and C0 controls are escaped",
+      "json": "\"\\u0000\\u0001\\b\\t\\n\\u000b\\f\\r\\u001f\\u007f\\u2028\\/\\\\\\\"\"",
+      "canonical": "\"\\u0000\\u0001\\b\\t\\n\\u000b\\f\\r\\u001f\u007f\u2028/\\\\\\\"\"",
+      "sha256": "a5392ec3bf42164c717677e307656ec0bbe1d66acd6c71e03332208bb3785563"
+    },
+    {
+      "name": "escaped non-ASCII text is written as UTF-8",
+      "json": "{\"text\":\"Merhaba d\\u00fcnya \\ud83c\\udf0d \\u4e2d\\u6587\"}",
+      "canonical": "{\"text\":\"Merhaba dünya 🌍 中文\"}",
+      "sha256": "5c6d767ebe9d1b2c2ff28ee7294a682270405ea0a6d8bd89522c6b3593c0ec64"
+    }
+  ],
+  "numbers": [
+    { "ieee754": "0000000000000000", "canonical": "0" },
+    { "ieee754": "8000000000000000", "canonical": "0" },
+    { "ieee754": "0000000000000001", "canonical": "5e-324" },
+    { "ieee754": "8000000000000001", "canonical": "-5e-324" },
+    { "ieee754": "7fefffffffffffff", "canonical": "1.7976931348623157e+308" },
+    { "ieee754": "ffefffffffffffff", "canonical": "-1.7976931348623157e+308" },
+    { "ieee754": "4340000000000000", "canonical": "9007199254740992" },
+    { "ieee754": "c340000000000000", "canonical": "-9007199254740992" },
+    { "ieee754": "4430000000000000", "canonical": "295147905179352830000" },
+    { "ieee754": "44b52d02c7e14af5", "canonical": "9.999999999999997e+22" },
+    { "ieee754": "44b52d02c7e14af6", "canonical": "1e+23" },
+    { "ieee754": "44b52d02c7e14af7", "canonical": "1.0000000000000001e+23" },
+    { "ieee754": "444b1ae4d6e2ef4e", "canonical": "999999999999999700000" },
+    { "ieee754": "444b1ae4d6e2ef4f", "canonical": "999999999999999900000" },
+    { "ieee754": "444b1ae4d6e2ef50", "canonical": "1e+21" },
+    { "ieee754": "3eb0c6f7a0b5ed8c", "canonical": "9.999999999999997e-7" },
+    { "ieee754": "3eb0c6f7a0b5ed8d", "canonical": "0.000001" },
+    { "ieee754": "41b3de4355555553", "canonical": "333333333.3333332" },
+    { "ieee754": "41b3de4355555554", "canonical": "333333333.33333325" },
+    { "ieee754": "41b3de4355555555", "canonical": "333333333.3333333" },
+    { "ieee754": "41b3de4355555556", "canonical": "333333333.3333334" },
+    { "ieee754": "41b3de4355555557", "canonical": "333333333.33333343" },
+    { "ieee754": "becbf647612f3696", "canonical": "-0.0000033333333333333333" },
+    { "ieee754": "43143ff3c1cb0959", "canonical": "1424953923781206.2" }
+  ],
+  "invalid": [
+    { "name": "NaN", "ieee754": "7fffffffffffffff" },
+    { "name": "Infinity", "ieee754": "7ff0000000000000" },
+    { "name": "-Infinity", "ieee754": "fff0000000000000" },
+    { "name": "lone high surrogate", "json": "\"\\ud800\"" },
+    { "name": "lone low surrogate in a key", "json": "{\"\\udc00\":1}" },
+    { "name": "high surrogate followed by a letter", "json": "[\"\\ud83dA\"]" }
+  ]
+}

package/test-vectors/challenges.json

@@ -0,0 +1,245 @@
+{
+  "description": "Checking a decoded x402 PAYMENT-REQUIRED challenge against the approved manifest (provider-standard.md [P3], [P4], [P5]). Apply each case's `patch` (RFC 6902 add, replace and remove) to `challenge`, check it for `service` against `manifest`, and expect exactly `violations` (in any order). A client signs only when there are none [P7].",
+  "manifest": {
+    "standard": "stellar-agent-services/provider@1",
+    "provider": {
+      "name": "Example Text Tools",
+      "description": "Small, deterministic text utilities for agents.",
+      "homepage": "https://example.com",
+      "agentId": 42,
+      "termsUrl": "https://example.com/terms",
+      "dataUse": { "storesInputs": false, "trainsOnInputs": false }
+    },
+    "baseUrl": "https://api.example.com/agent",
+    "payment": {
+      "protocol": "x402",
+      "x402Version": 2,
+      "accepts": [
+        {
+          "scheme": "exact",
+          "network": "stellar:testnet",
+          "asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
+          "payTo": "GBZSBASBFMV5RGKPRIPCB5QQVAJ35IXKMTF2A2766MOA4ZHQ7MLSIPXU",
+          "maxTimeoutSeconds": 60,
+          "extra": { "areFeesSponsored": true }
+        }
+      ]
+    },
+    "jobs": { "retentionSeconds": 604800 },
+    "services": [
+      {
+        "name": "text-stats",
+        "title": "Text statistics",
+        "description": "Counts words, sentences and characters in English text. Use it to check length limits before publishing. Accepts up to 20,000 characters.",
+        "price": { "amount": "100000" },
+        "charge": "on-success",
+        "expectedDurationSeconds": 2,
+        "inputSchema": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "type": "object",
+          "properties": { "text": { "type": "string", "maxLength": 20000 } },
+          "required": ["text"],
+          "additionalProperties": false
+        },
+        "outputSchema": {
+          "$schema": "https://json-schema.org/draft/2020-12/schema",
+          "type": "object",
+          "properties": {
+            "words": { "type": "integer" },
+            "sentences": { "type": "integer" },
+            "characters": { "type": "integer" }
+          },
+          "required": ["words", "sentences", "characters"]
+        },
+        "examples": [{ "input": { "text": "Hello world." }, "output": { "words": 2, "sentences": 1, "characters": 12 } }],
+        "tags": ["text", "analysis"]
+      }
+    ]
+  },
+  "service": "text-stats",
+  "challenge": {
+    "x402Version": 2,
+    "resource": {
+      "url": "https://api.example.com/agent/services/text-stats/jobs",
+      "description": "Text statistics",
+      "mimeType": "application/json"
+    },
+    "accepts": [
+      {
+        "scheme": "exact",
+        "network": "stellar:testnet",
+        "asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
+        "amount": "100000",
+        "payTo": "GBZSBASBFMV5RGKPRIPCB5QQVAJ35IXKMTF2A2766MOA4ZHQ7MLSIPXU",
+        "maxTimeoutSeconds": 60,
+        "extra": { "areFeesSponsored": true }
+      }
+    ]
+  },
+  "cases": [
+    { "name": "equals the manifest option plus the price", "patch": [], "valid": true, "violations": [] },
+    {
+      "name": "unknown fields are ignored",
+      "patch": [
+        { "op": "add", "path": "/accepts/0/extra/version", "value": "1" },
+        { "op": "add", "path": "/extensions", "value": { "com.example.trace": "abc" } },
+        { "op": "add", "path": "/resource/serviceName", "value": "Example Text Tools" }
+      ],
+      "valid": true,
+      "violations": []
+    },
+    {
+      "name": "an error message is allowed",
+      "patch": [{ "op": "add", "path": "/error", "value": "Payment required" }],
+      "valid": true,
+      "violations": []
+    },
+    {
+      "name": "amount differs from the price",
+      "patch": [{ "op": "replace", "path": "/accepts/0/amount", "value": "200000" }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/amount" }]
+    },
+    {
+      "name": "amount is a number, not a string",
+      "patch": [{ "op": "replace", "path": "/accepts/0/amount", "value": 100000 }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/amount" }]
+    },
+    {
+      "name": "payTo differs",
+      "patch": [
+        {
+          "op": "replace",
+          "path": "/accepts/0/payTo",
+          "value": "GCMM7PUD2GTN7EJ4EAUQB2BF7B3LWL2UYSULRQE3WEYJ4EF6Y5665GP5"
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/payTo" }]
+    },
+    {
+      "name": "asset differs",
+      "patch": [
+        {
+          "op": "replace",
+          "path": "/accepts/0/asset",
+          "value": "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75"
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/asset" }]
+    },
+    {
+      "name": "network differs",
+      "patch": [{ "op": "replace", "path": "/accepts/0/network", "value": "stellar:pubnet" }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/network" }]
+    },
+    {
+      "name": "scheme differs",
+      "patch": [{ "op": "replace", "path": "/accepts/0/scheme", "value": "upto" }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/scheme" }]
+    },
+    {
+      "name": "maxTimeoutSeconds differs",
+      "patch": [{ "op": "replace", "path": "/accepts/0/maxTimeoutSeconds", "value": 120 }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/maxTimeoutSeconds" }]
+    },
+    {
+      "name": "fees are not sponsored",
+      "patch": [{ "op": "replace", "path": "/accepts/0/extra/areFeesSponsored", "value": false }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/extra/areFeesSponsored" }]
+    },
+    {
+      "name": "extra is missing",
+      "patch": [{ "op": "remove", "path": "/accepts/0/extra" }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/extra/areFeesSponsored" }]
+    },
+    {
+      "name": "two payment options",
+      "patch": [
+        {
+          "op": "add",
+          "path": "/accepts/-",
+          "value": {
+            "scheme": "exact",
+            "network": "stellar:testnet",
+            "asset": "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA",
+            "amount": "100000",
+            "payTo": "GBZSBASBFMV5RGKPRIPCB5QQVAJ35IXKMTF2A2766MOA4ZHQ7MLSIPXU",
+            "maxTimeoutSeconds": 60,
+            "extra": { "areFeesSponsored": true }
+          }
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts" }]
+    },
+    {
+      "name": "no payment option",
+      "patch": [{ "op": "replace", "path": "/accepts", "value": [] }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts" }]
+    },
+    {
+      "name": "accepts is missing",
+      "patch": [{ "op": "remove", "path": "/accepts" }],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts" }]
+    },
+    {
+      "name": "x402 version 1",
+      "patch": [{ "op": "replace", "path": "/x402Version", "value": 1 }],
+      "valid": false,
+      "violations": [{ "rule": "P3", "pointer": "/x402Version" }]
+    },
+    {
+      "name": "resource.url uses http",
+      "patch": [
+        {
+          "op": "replace",
+          "path": "/resource/url",
+          "value": "http://api.example.com/agent/services/text-stats/jobs"
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P5", "pointer": "/resource/url" }]
+    },
+    {
+      "name": "resource.url is another service's URL",
+      "patch": [
+        {
+          "op": "replace",
+          "path": "/resource/url",
+          "value": "https://api.example.com/agent/services/summarize/jobs"
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P5", "pointer": "/resource/url" }]
+    },
+    {
+      "name": "resource is missing",
+      "patch": [{ "op": "remove", "path": "/resource" }],
+      "valid": false,
+      "violations": [{ "rule": "P5", "pointer": "/resource/url" }]
+    },
+    {
+      "name": "several differences are all reported",
+      "patch": [
+        { "op": "replace", "path": "/accepts/0/amount", "value": "1" },
+        {
+          "op": "replace",
+          "path": "/accepts/0/payTo",
+          "value": "GCMM7PUD2GTN7EJ4EAUQB2BF7B3LWL2UYSULRQE3WEYJ4EF6Y5665GP5"
+        }
+      ],
+      "valid": false,
+      "violations": [{ "rule": "P4", "pointer": "/accepts/0/amount" }, { "rule": "P4", "pointer": "/accepts/0/payTo" }]
+    }
+  ]
+}

package/test-vectors/headers.json

@@ -0,0 +1,37 @@
+{
+  "description": "Header formats from provider-standard.md §5.2. A provider answers 400 invalid_request to a create-job request whose header doesn't match `pattern` (an ECMA-262 regular expression). `retryAfter` (§5.8) gives the whole seconds to wait for each Retry-After value, read at `now`; `invalid` values are ignored.",
+  "idempotencyKey": {
+    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
+    "valid": ["0192d3a4-7c1e-7b2a-9f00-3c5e8a1b2c3d", "f47ac10b-58cc-4372-a567-0e02b2c3d479"],
+    "invalid": [
+      "F47AC10B-58CC-4372-A567-0E02B2C3D479",
+      "{f47ac10b-58cc-4372-a567-0e02b2c3d479}",
+      "urn:uuid:f47ac10b-58cc-4372-a567-0e02b2c3d479",
+      "f47ac10b58cc4372a5670e02b2c3d479",
+      "f47ac10b-58cc-4372-a567-0e02b2c3d47",
+      ""
+    ]
+  },
+  "jobToken": {
+    "pattern": "^[A-Za-z0-9_-]{43}$",
+    "valid": ["q7Zt3m0bX0s8b6f5JmS2kQ9xg3Y1rZcV4nL8pW2eA0c", "lDgabH0XuZH0QvUHoZygLnzlIj45A193SL-aZNcnIiE"],
+    "invalid": [
+      "lDgabH0XuZH0QvUHoZygLnzlIj45A193SL-aZNcnIiE=",
+      "q7Zt3m0bX0s8b6f5JmS2kQ9xg3Y1rZcV4nL8pW2eA0+",
+      "lDgabH0XuZH0QvUHoZygLnzlIj45A193SL-aZNcnIi",
+      "lDgabH0XuZH0QvUHoZygLnzlIj45A193SL-aZNcnIiEA",
+      ""
+    ]
+  },
+  "retryAfter": {
+    "now": "2026-10-20T10:00:00Z",
+    "valid": [
+      { "value": "0", "seconds": 0 },
+      { "value": "5", "seconds": 5 },
+      { "value": " 30 ", "seconds": 30 },
+      { "value": "Tue, 20 Oct 2026 10:00:12 GMT", "seconds": 12 },
+      { "value": "Tue, 20 Oct 2026 09:59:00 GMT", "seconds": 0 }
+    ],
+    "invalid": ["", "-1", "1.5", "5s", "soon", "2026-10-20T10:00:12Z"]
+  }
+}

package/test-vectors/job-states.json

@@ -0,0 +1,39 @@
+{
+  "description": "Job states from provider-standard.md §5.6. `transitions` lists, per charge policy, every state a job may move to from each state, \"(new)\" being a job that does not exist yet. Every pair not listed is forbidden. `charged` gives the job view's `charged` value for each status, charge and failure code.",
+  "transitions": {
+    "upfront": {
+      "(new)": ["queued", "running", "payment_uncertain", "failed"],
+      "queued": ["running"],
+      "running": ["succeeded", "failed"],
+      "payment_uncertain": ["queued", "succeeded", "failed"],
+      "succeeded": [],
+      "failed": []
+    },
+    "on-success": {
+      "(new)": ["queued", "running", "payment_uncertain", "failed"],
+      "queued": ["running"],
+      "running": ["succeeded", "failed", "payment_uncertain"],
+      "payment_uncertain": ["queued", "succeeded", "failed"],
+      "succeeded": [],
+      "failed": []
+    }
+  },
+  "charged": [
+    { "status": "queued", "charge": "upfront", "charged": true },
+    { "status": "queued", "charge": "on-success", "charged": false },
+    { "status": "running", "charge": "upfront", "charged": true },
+    { "status": "running", "charge": "on-success", "charged": false },
+    { "status": "succeeded", "charge": "upfront", "charged": true },
+    { "status": "succeeded", "charge": "on-success", "charged": true },
+    { "status": "payment_uncertain", "charge": "upfront", "charged": "unknown" },
+    { "status": "payment_uncertain", "charge": "on-success", "charged": "unknown" },
+    { "status": "failed", "charge": "upfront", "failureCode": "service_failed", "charged": true },
+    { "status": "failed", "charge": "upfront", "failureCode": "output_invalid", "charged": true },
+    { "status": "failed", "charge": "upfront", "failureCode": "timeout", "charged": true },
+    { "status": "failed", "charge": "upfront", "failureCode": "payment_failed", "charged": false },
+    { "status": "failed", "charge": "on-success", "failureCode": "service_failed", "charged": false },
+    { "status": "failed", "charge": "on-success", "failureCode": "output_invalid", "charged": false },
+    { "status": "failed", "charge": "on-success", "failureCode": "timeout", "charged": false },
+    { "status": "failed", "charge": "on-success", "failureCode": "payment_failed", "charged": false }
+  ]
+}