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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stellar Agent Services contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @stellar-agent-services/protocol
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Provider Standard v1 as code. It holds the manifest, job, receipt and header definitions that every other
+package shares. Specification: [docs/provider-standard.md](../../docs/provider-standard.md).
+
+| Path | Contents |
+| --- | --- |
+| [`schemas/manifest.schema.json`](schemas/manifest.schema.json) | The manifest JSON Schema (2020-12) |
+| [`schemas/verification-receipt.schema.json`](schemas/verification-receipt.schema.json), [`schemas/validation-request.schema.json`](schemas/validation-request.schema.json) | The two Validation Registry documents: the verifier's receipt and the owner's request |
+| [`test-vectors/`](test-vectors) | Known-answer tests that implementations in any language can use |
+| `src/` | Types (manifest, `JobView`, `Problem`, `PaymentReceipt`, `VerificationReceipt`, `ValidationRequest`), constants and the reference checks: `canonicalJson`, `bindingHash`, `checkManifestRules`, `checkChallenge`, `stellarAddressKind`, `canTransition`, `chargedFor`, `conformanceLevel`, `validationRequestHash`, `validationRequestDataUri` |
+
+- No runtime dependencies and no signing code, so the read-only discovery server can import it safely.
+- It ships the schema rather than a validator. To validate a manifest, run any JSON Schema 2020-12 validator,
+  then `checkManifestRules()` (spec §2.4).

package/dist/canonical-json.d.ts

@@ -0,0 +1,18 @@
+/** A JSON value as JSON.parse produces it. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * Serializes a JSON value the RFC 8785 way: no whitespace, object keys sorted by UTF-16 code units,
+ * ECMAScript number and string formatting.
+ *
+ * Throws on anything that is not I-JSON (RFC 7493): NaN, Infinity, lone surrogates, undefined,
+ * functions, cycles, sparse arrays and non-plain objects.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Lowercase hex SHA-256 of a string (as UTF-8) or of bytes. Uses Web Crypto: Node, Workers, Deno, Bun. */
+export declare function sha256Hex(data: string | Uint8Array): Promise<string>;
+/** sha256Hex(canonicalJson(value)): the hash used for binding hashes and shared documents. */
+export declare function canonicalSha256(value: unknown): Promise<string>;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../src/canonical-json.ts"],"names":[],"mappings":"AAOA,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG,UAAU,CAAC;AACpF,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAKD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEpD;AAED,2GAA2G;AAC3G,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAI1E;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/D"}

package/dist/canonical-json.js

@@ -0,0 +1,86 @@
+// Canonical JSON (RFC 8785, JCS) and SHA-256.
+//
+// Used for the job binding hash (service + input), manifest hashes and verification receipt
+// hashes, so that key order or whitespace can never change a hash. Other projects (e.g. ERC-8126 on
+// Stellar) must produce the same bytes for shared Validation Registry documents, so this follows
+// RFC 8785 exactly and is pinned by test-vectors/canonical-json.json.
+// With the `u` flag a valid surrogate pair is one code point, so this matches only lone surrogates.
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+/**
+ * Serializes a JSON value the RFC 8785 way: no whitespace, object keys sorted by UTF-16 code units,
+ * ECMAScript number and string formatting.
+ *
+ * Throws on anything that is not I-JSON (RFC 7493): NaN, Infinity, lone surrogates, undefined,
+ * functions, cycles, sparse arrays and non-plain objects.
+ */
+export function canonicalJson(value) {
+    return serialize(value, new Set());
+}
+/** Lowercase hex SHA-256 of a string (as UTF-8) or of bytes. Uses Web Crypto: Node, Workers, Deno, Bun. */
+export async function sha256Hex(data) {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : new Uint8Array(data);
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+    return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** sha256Hex(canonicalJson(value)): the hash used for binding hashes and shared documents. */
+export function canonicalSha256(value) {
+    return sha256Hex(canonicalJson(value));
+}
+function serialize(value, ancestors) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new TypeError("canonicalJson: NaN and Infinity are not JSON");
+            // ECMAScript Number-to-String, as RFC 8785 §3.2.2.3 requires. -0 becomes "0".
+            return JSON.stringify(value);
+        case "string":
+            return serializeString(value);
+        case "object":
+            break;
+        default:
+            throw new TypeError(`canonicalJson: a ${typeof value} is not JSON`);
+    }
+    if (ancestors.has(value))
+        throw new TypeError("canonicalJson: circular structure");
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            const items = [];
+            for (let i = 0; i < value.length; i++) {
+                if (!(i in value))
+                    throw new TypeError("canonicalJson: sparse arrays are not JSON");
+                items.push(serialize(value[i], ancestors));
+            }
+            return `[${items.join(",")}]`;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("canonicalJson: only plain objects and arrays are JSON");
+        }
+        const record = value;
+        // The default sort compares UTF-16 code units, which is the order RFC 8785 §3.2.3 requires.
+        const members = Object.keys(record)
+            .sort()
+            .map((key) => {
+            const member = record[key];
+            if (member === undefined)
+                throw new TypeError(`canonicalJson: "${key}" is undefined`);
+            return `${serializeString(key)}:${serialize(member, ancestors)}`;
+        });
+        return `{${members.join(",")}}`;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function serializeString(value) {
+    if (LONE_SURROGATE.test(value))
+        throw new TypeError("canonicalJson: string contains a lone surrogate");
+    // JSON.stringify escapes exactly what RFC 8785 §3.2.2.2 requires and nothing more.
+    return JSON.stringify(value);
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../src/canonical-json.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,85 @@
+export declare const PROBLEM_CONTENT_TYPE = "application/problem+json";
+/** Codes for HTTP error responses, with their status and default title (§6). */
+export declare const PROBLEMS: {
+    readonly invalid_request: {
+        readonly status: 400;
+        readonly title: "The request is malformed";
+    };
+    readonly invalid_input: {
+        readonly status: 400;
+        readonly title: "Input does not match the service's inputSchema";
+    };
+    readonly service_not_found: {
+        readonly status: 404;
+        readonly title: "No service with that name";
+    };
+    readonly job_not_found: {
+        readonly status: 404;
+        readonly title: "Job not found";
+    };
+    readonly request_in_progress: {
+        readonly status: 409;
+        readonly title: "The job is still being claimed or settled";
+        readonly retryAfter: true;
+    };
+    readonly payload_too_large: {
+        readonly status: 413;
+        readonly title: "The input is larger than maxInputBytes";
+    };
+    readonly idempotency_key_reused: {
+        readonly status: 422;
+        readonly title: "The job id is bound to a different request";
+    };
+    readonly rate_limited: {
+        readonly status: 429;
+        readonly title: "Too many requests";
+        readonly retryAfter: true;
+    };
+    readonly unavailable: {
+        readonly status: 503;
+        readonly title: "The service is unavailable";
+        readonly retryAfter: true;
+    };
+};
+export type ProblemCode = keyof typeof PROBLEMS;
+/** Codes for a failed job, in the job view's `error.code` (§6). */
+export declare const JOB_FAILURES: {
+    readonly service_failed: {
+        readonly title: "The work failed";
+    };
+    readonly output_invalid: {
+        readonly title: "The output did not match outputSchema";
+    };
+    readonly timeout: {
+        readonly title: "The work did not finish in time";
+    };
+    readonly payment_failed: {
+        readonly title: "Settlement did not happen";
+    };
+};
+export type JobFailureCode = keyof typeof JOB_FAILURES;
+/** An RFC 9457 problem. `status` is present on HTTP errors and absent on a failed job's `error`. */
+export interface Problem<Code extends string = ProblemCode> {
+    type: string;
+    title: string;
+    status?: number;
+    detail?: string;
+    code: Code;
+    /** invalid_input only: where the input fails its schema. */
+    errors?: InputError[];
+}
+export interface InputError {
+    /** JSON Pointer (RFC 6901) into the input. */
+    pointer: string;
+    message: string;
+}
+/** The problem `type` URI for a problem or job failure code. */
+export declare function problemType(code: ProblemCode | JobFailureCode): string;
+/** Builds the body of an HTTP error response. Send it as PROBLEM_CONTENT_TYPE with PROBLEMS[code].status. */
+export declare function problem(code: ProblemCode, options?: {
+    detail?: string;
+    errors?: InputError[];
+}): Problem;
+/** Builds a failed job's `error`. */
+export declare function jobError(code: JobFailureCode, detail?: string): Problem<JobFailureCode>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,gFAAgF;AAChF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAUoE,CAAC;AAE1F,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,QAAQ,CAAC;AAEhD,mEAAmE;AACnE,eAAO,MAAM,YAAY;;;;;;;;;;;;;CAK6B,CAAC;AAEvD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,YAAY,CAAC;AAEvD,oGAAoG;AACpG,MAAM,WAAW,OAAO,CAAC,IAAI,SAAS,MAAM,GAAG,WAAW;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,IAAI,CAAC;IACX,4DAA4D;IAC5D,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gEAAgE;AAChE,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,cAAc,GAAG,MAAM,CAEtE;AAED,6GAA6G;AAC7G,wBAAgB,OAAO,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CAAO,GAAG,OAAO,CAG5G;AAED,qCAAqC;AACrC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAIvF"}

package/dist/errors.js

@@ -0,0 +1,46 @@
+// Error responses (docs/provider-standard.md §6).
+//
+// Every error other than 402 is an RFC 9457 problem with a stable `code`, which is what clients act
+// on [E1]. A failed job carries the same shape in its job view, with a job failure code. 402
+// responses use x402's own format, not this one.
+//
+// Problems never contain request headers, payment payloads or job tokens [E2]: `detail` and
+// `errors[].message` are written by the provider, never copied from the request.
+import { SPEC_URL } from "./standard.js";
+export const PROBLEM_CONTENT_TYPE = "application/problem+json";
+/** Codes for HTTP error responses, with their status and default title (§6). */
+export const PROBLEMS = {
+    invalid_request: { status: 400, title: "The request is malformed" },
+    invalid_input: { status: 400, title: "Input does not match the service's inputSchema" },
+    service_not_found: { status: 404, title: "No service with that name" },
+    job_not_found: { status: 404, title: "Job not found" },
+    request_in_progress: { status: 409, title: "The job is still being claimed or settled", retryAfter: true },
+    payload_too_large: { status: 413, title: "The input is larger than maxInputBytes" },
+    idempotency_key_reused: { status: 422, title: "The job id is bound to a different request" },
+    rate_limited: { status: 429, title: "Too many requests", retryAfter: true },
+    unavailable: { status: 503, title: "The service is unavailable", retryAfter: true },
+};
+/** Codes for a failed job, in the job view's `error.code` (§6). */
+export const JOB_FAILURES = {
+    service_failed: { title: "The work failed" },
+    output_invalid: { title: "The output did not match outputSchema" },
+    timeout: { title: "The work did not finish in time" },
+    payment_failed: { title: "Settlement did not happen" },
+};
+/** The problem `type` URI for a problem or job failure code. */
+export function problemType(code) {
+    return `${SPEC_URL}#error-${code}`;
+}
+/** Builds the body of an HTTP error response. Send it as PROBLEM_CONTENT_TYPE with PROBLEMS[code].status. */
+export function problem(code, options = {}) {
+    const { status, title } = PROBLEMS[code];
+    return { type: problemType(code), title, status, code, ...options };
+}
+/** Builds a failed job's `error`. */
+export function jobError(code, detail) {
+    const error = { type: problemType(code), title: JOB_FAILURES[code].title, code };
+    if (detail !== undefined)
+        error.detail = detail;
+    return error;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,oGAAoG;AACpG,6FAA6F;AAC7F,iDAAiD;AACjD,EAAE;AACF,4FAA4F;AAC5F,iFAAiF;AAEjF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,0BAA0B,CAAC;AAE/D,gFAAgF;AAChF,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,eAAe,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,0BAA0B,EAAE;IACnE,aAAa,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,gDAAgD,EAAE;IACvF,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,2BAA2B,EAAE;IACtE,aAAa,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,EAAE;IACtD,mBAAmB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,2CAA2C,EAAE,UAAU,EAAE,IAAI,EAAE;IAC1G,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,wCAAwC,EAAE;IACnF,sBAAsB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,4CAA4C,EAAE;IAC5F,YAAY,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,IAAI,EAAE;IAC3E,WAAW,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,4BAA4B,EAAE,UAAU,EAAE,IAAI,EAAE;CACI,CAAC;AAI1F,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,cAAc,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE;IAC5C,cAAc,EAAE,EAAE,KAAK,EAAE,uCAAuC,EAAE;IAClE,OAAO,EAAE,EAAE,KAAK,EAAE,iCAAiC,EAAE;IACrD,cAAc,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE;CACF,CAAC;AAqBvD,gEAAgE;AAChE,MAAM,UAAU,WAAW,CAAC,IAAkC;IAC5D,OAAO,GAAG,QAAQ,UAAU,IAAI,EAAE,CAAC;AACrC,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,OAAO,CAAC,IAAiB,EAAE,UAAsD,EAAE;IACjG,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IACzC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC;AACtE,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,QAAQ,CAAC,IAAoB,EAAE,MAAe;IAC5D,MAAM,KAAK,GAA4B,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1G,IAAI,MAAM,KAAK,SAAS;QAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;IAChD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/headers.d.ts

@@ -0,0 +1,15 @@
+/** IETF Idempotency-Key (draft-07). Its value becomes the job id. */
+export declare const IDEMPOTENCY_KEY = "Idempotency-Key";
+/** The job's bearer secret. No "X-" prefix (RFC 6648). */
+export declare const JOB_TOKEN = "Job-Token";
+/** A lowercase RFC 9562 UUID of any version. Clients SHOULD use v4 or v7. */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/** 32 random bytes, base64url without padding. The provider stores only its SHA-256 [J3]. */
+export declare const JOB_TOKEN_PATTERN: RegExp;
+/**
+ * Reads Retry-After (RFC 9110 §10.2.3) as whole seconds from `now`: delay-seconds, or an HTTP-date
+ * (0 once it has passed). Returns undefined for a missing or malformed value. Providers send
+ * delay-seconds (§5.8); the date form is read for HTTP proxies in front of them.
+ */
+export declare function parseRetryAfter(value: string | null | undefined, now?: number): number | undefined;
+//# sourceMappingURL=headers.d.ts.map

package/dist/headers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.ts","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAKA,qEAAqE;AACrE,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,0DAA0D;AAC1D,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,QAAmE,CAAC;AAExG,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,QAAwB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,SAAS,CAO9G"}

package/dist/headers.js

@@ -0,0 +1,29 @@
+// HTTP header names used by the standard (docs/provider-standard.md §5.2), and reading Retry-After (§5.8).
+//
+// The x402 v2 headers (PAYMENT-REQUIRED, PAYMENT-SIGNATURE, PAYMENT-RESPONSE) come from @x402/core
+// and are not redefined here. Location and Retry-After are used as HTTP defines them.
+/** IETF Idempotency-Key (draft-07). Its value becomes the job id. */
+export const IDEMPOTENCY_KEY = "Idempotency-Key";
+/** The job's bearer secret. No "X-" prefix (RFC 6648). */
+export const JOB_TOKEN = "Job-Token";
+/** A lowercase RFC 9562 UUID of any version. Clients SHOULD use v4 or v7. */
+export const IDEMPOTENCY_KEY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** 32 random bytes, base64url without padding. The provider stores only its SHA-256 [J3]. */
+export const JOB_TOKEN_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+/**
+ * Reads Retry-After (RFC 9110 §10.2.3) as whole seconds from `now`: delay-seconds, or an HTTP-date
+ * (0 once it has passed). Returns undefined for a missing or malformed value. Providers send
+ * delay-seconds (§5.8); the date form is read for HTTP proxies in front of them.
+ */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value === null || value === undefined)
+        return undefined;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    if (!/^[A-Z][a-z]{2}, \d{2} [A-Z][a-z]{2} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(trimmed))
+        return undefined;
+    const date = Date.parse(trimmed);
+    return Number.isNaN(date) ? undefined : Math.max(0, Math.ceil((date - now) / 1000));
+}
+//# sourceMappingURL=headers.js.map

package/dist/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../src/headers.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,EAAE;AACF,mGAAmG;AACnG,sFAAsF;AAEtF,qEAAqE;AACrE,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAEjD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,SAAS,GAAG,WAAW,CAAC;AAErC,6EAA6E;AAC7E,MAAM,CAAC,MAAM,uBAAuB,GAAG,gEAAgE,CAAC;AAExG,6FAA6F;AAC7F,MAAM,CAAC,MAAM,iBAAiB,GAAG,qBAAqB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAgC,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IACxF,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5D,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,CAAC,kEAAkE,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACxG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACtF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./standard.js";
+export * from "./manifest.js";
+export * from "./jobs.js";
+export * from "./headers.js";
+export * from "./receipts.js";
+export * from "./validation-request.js";
+export * from "./networks.js";
+export * from "./canonical-json.js";
+export * from "./errors.js";
+export * from "./strkey.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+// @stellar-agent-services/protocol
+//
+// Provider Standard v1 as code. Every other package (provider-kit, payment-client, verifier) and,
+// read-only, stellar-agent-search import their shared definitions from here.
+//
+// Rule: this package has NO runtime dependencies and never imports signing code, so the read-only
+// discovery server can depend on it without breaking its "no signer imports" invariant.
+export * from "./standard.js";
+export * from "./manifest.js";
+export * from "./jobs.js";
+export * from "./headers.js";
+export * from "./receipts.js";
+export * from "./validation-request.js";
+export * from "./networks.js";
+export * from "./canonical-json.js";
+export * from "./errors.js";
+export * from "./strkey.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,EAAE;AACF,kGAAkG;AAClG,6EAA6E;AAC7E,EAAE;AACF,kGAAkG;AAClG,wFAAwF;AAExF,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,yBAAyB,CAAC;AACxC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/dist/jobs.d.ts

@@ -0,0 +1,62 @@
+import { type JsonObject } from "./canonical-json.js";
+import type { JobFailureCode, Problem } from "./errors.js";
+import type { PaymentReceipt } from "./receipts.js";
+/** When the user is charged (§3.2). The manifest default is "upfront". */
+export type Charge = "on-success" | "upfront";
+/** POST {baseUrl}/services/{name}/jobs (§5.1). */
+export declare function createJobUrl(baseUrl: string, service: string): string;
+/** GET {baseUrl}/jobs/{jobId} (§5.1). */
+export declare function jobStatusUrl(baseUrl: string, jobId: string): string;
+/** GET {baseUrl}/jobs/{jobId}/result (§5.1). */
+export declare function jobResultUrl(baseUrl: string, jobId: string): string;
+/** hex(sha256(JCS({ service, input }))): binds a job id to one request (§5.3). */
+export declare function bindingHash(service: string, input: unknown): Promise<string>;
+export type JobStatus = "queued" | "running" | "succeeded" | "failed" | "payment_uncertain";
+export declare const JOB_STATUSES: readonly JobStatus[];
+/** `succeeded` and `failed` never change again [J12]. */
+export declare const FINAL_JOB_STATUSES: readonly JobStatus[];
+/** Whether the user paid: "unknown" exactly while the job is payment_uncertain (§5.6). */
+export type Charged = boolean | "unknown";
+/** The one response body of create-job, check-status and get-result (§5.5). */
+export interface JobView {
+    jobId: string;
+    service: string;
+    status: JobStatus;
+    charge: Charge;
+    charged: Charged;
+    /** RFC 3339 timestamps. */
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string;
+    /** create-job and get-result, when succeeded. Withheld while payment_uncertain [J14]. */
+    output?: JsonObject;
+    /** When failed. */
+    error?: Problem<JobFailureCode>;
+    /** When charged is true. */
+    payment?: PaymentReceipt;
+    /** While queued [Q5]. */
+    queue?: QueuePosition;
+    /** Only in the create-job response, and only when the provider created the token [J2]. */
+    jobToken?: string;
+}
+/** Where a queued job stands (§5.8). A hint, not a promise. */
+export interface QueuePosition {
+    /** 1 for the next job to start. */
+    position: number;
+    /** RFC 3339. */
+    estimatedStartAt: string;
+}
+/** The states a job may start in: (new) → queued | running | payment_uncertain | failed (§5.6). */
+export declare const INITIAL_JOB_STATUSES: readonly JobStatus[];
+/** Allowed transitions between states (§5.6). Final states have none [J12]. */
+export declare const JOB_TRANSITIONS: Readonly<Record<JobStatus, readonly JobStatus[]>>;
+/**
+ * Whether a job may move from `from` (undefined for a new job) to `to`. running → payment_uncertain
+ * happens only with charge "on-success", where settlement follows the work (§5.6).
+ */
+export declare function canTransition(from: JobStatus | undefined, to: JobStatus, charge: Charge): boolean;
+/** The `charged` value the §5.6 table requires for a job's status, charge and failure code. */
+export declare function chargedFor(status: JobStatus, charge: Charge, failureCode?: JobFailureCode): Charged;
+/** 200 once the job has finished, otherwise 202 with Retry-After [J8]. */
+export declare function jobViewHttpStatus(status: JobStatus): 200 | 202;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,0EAA0E;AAC1E,MAAM,MAAM,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;AAE9C,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrE;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,gDAAgD;AAChD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAE5E;AAED,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,mBAAmB,CAAC;AAC5F,eAAO,MAAM,YAAY,EAAE,SAAS,SAAS,EAAsE,CAAC;AAEpH,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,EAAE,SAAS,SAAS,EAA4B,CAAC;AAEhF,0FAA0F;AAC1F,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,mBAAmB;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,yBAAyB;IACzB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,0FAA0F;IAC1F,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB;IAChB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,mGAAmG;AACnG,eAAO,MAAM,oBAAoB,EAAE,SAAS,SAAS,EAAyD,CAAC;AAE/G,+EAA+E;AAC/E,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,SAAS,EAAE,CAAC,CAM7E,CAAC;AAEF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIjG;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,cAAc,GAAG,OAAO,CAWnG;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,GAAG,GAAG,GAAG,CAE9D"}

package/dist/jobs.js

@@ -0,0 +1,66 @@
+// Job model: create-job, check-status, get-result (docs/provider-standard.md §5).
+import { canonicalSha256 } from "./canonical-json.js";
+import { IDEMPOTENCY_KEY_PATTERN } from "./headers.js";
+import { SERVICE_NAME_PATTERN } from "./standard.js";
+/** POST {baseUrl}/services/{name}/jobs (§5.1). */
+export function createJobUrl(baseUrl, service) {
+    if (!SERVICE_NAME_PATTERN.test(service))
+        throw new TypeError(`invalid service name: ${service}`);
+    return `${baseUrl}/services/${service}/jobs`;
+}
+/** GET {baseUrl}/jobs/{jobId} (§5.1). */
+export function jobStatusUrl(baseUrl, jobId) {
+    if (!IDEMPOTENCY_KEY_PATTERN.test(jobId))
+        throw new TypeError(`invalid job id: ${jobId}`);
+    return `${baseUrl}/jobs/${jobId}`;
+}
+/** GET {baseUrl}/jobs/{jobId}/result (§5.1). */
+export function jobResultUrl(baseUrl, jobId) {
+    return `${jobStatusUrl(baseUrl, jobId)}/result`;
+}
+/** hex(sha256(JCS({ service, input }))): binds a job id to one request (§5.3). */
+export function bindingHash(service, input) {
+    return canonicalSha256({ service, input });
+}
+export const JOB_STATUSES = ["queued", "running", "succeeded", "failed", "payment_uncertain"];
+/** `succeeded` and `failed` never change again [J12]. */
+export const FINAL_JOB_STATUSES = ["succeeded", "failed"];
+/** The states a job may start in: (new) → queued | running | payment_uncertain | failed (§5.6). */
+export const INITIAL_JOB_STATUSES = ["queued", "running", "payment_uncertain", "failed"];
+/** Allowed transitions between states (§5.6). Final states have none [J12]. */
+export const JOB_TRANSITIONS = {
+    queued: ["running"],
+    running: ["succeeded", "failed", "payment_uncertain"],
+    payment_uncertain: ["queued", "succeeded", "failed"],
+    succeeded: [],
+    failed: [],
+};
+/**
+ * Whether a job may move from `from` (undefined for a new job) to `to`. running → payment_uncertain
+ * happens only with charge "on-success", where settlement follows the work (§5.6).
+ */
+export function canTransition(from, to, charge) {
+    if (from === undefined)
+        return INITIAL_JOB_STATUSES.includes(to);
+    if (from === "running" && to === "payment_uncertain" && charge !== "on-success")
+        return false;
+    return JOB_TRANSITIONS[from].includes(to);
+}
+/** The `charged` value the §5.6 table requires for a job's status, charge and failure code. */
+export function chargedFor(status, charge, failureCode) {
+    switch (status) {
+        case "payment_uncertain":
+            return "unknown";
+        case "succeeded":
+            return true;
+        case "failed":
+            return charge === "upfront" && failureCode !== "payment_failed";
+        default:
+            return charge === "upfront";
+    }
+}
+/** 200 once the job has finished, otherwise 202 with Retry-After [J8]. */
+export function jobViewHttpStatus(status) {
+    return FINAL_JOB_STATUSES.includes(status) ? 200 : 202;
+}
+//# sourceMappingURL=jobs.js.map

package/dist/jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.js","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"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"}

package/dist/manifest.d.ts

@@ -0,0 +1,95 @@
+import { type JsonObject, type JsonValue } from "./canonical-json.js";
+import { type Charge } from "./jobs.js";
+import type { StellarNetwork } from "./networks.js";
+export interface ProviderManifest {
+    standard: "stellar-agent-services/provider@1";
+    provider: ProviderInfo;
+    baseUrl: string;
+    payment: PaymentInfo;
+    jobs?: {
+        retentionSeconds?: number;
+    };
+    services: ServiceDescriptor[];
+    extensions?: JsonObject;
+}
+export interface ProviderInfo {
+    name: string;
+    description?: string;
+    homepage?: string;
+    agentId?: number;
+    termsUrl?: string;
+    dataUse?: {
+        storesInputs?: boolean;
+        trainsOnInputs?: boolean;
+    };
+}
+export interface PaymentInfo {
+    protocol: "x402";
+    x402Version: 2;
+    /** Exactly one option in v1 [P1]. */
+    accepts: [PaymentOption];
+}
+/** x402 v2 PaymentRequirements field names, without `amount` (§4.1). */
+export interface PaymentOption {
+    scheme: "exact";
+    network: StellarNetwork;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        areFeesSponsored: true;
+        [key: string]: JsonValue;
+    };
+}
+/** One service. Field names follow MCP tools, so a service maps 1:1 to an MCP tool (Appendix B). */
+export interface ServiceDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    price: {
+        amount: string;
+    };
+    charge?: Charge;
+    expectedDurationSeconds?: number;
+    inputSchema: JsonObject;
+    outputSchema: JsonObject;
+    examples?: {
+        input: JsonObject;
+        output: JsonObject;
+    }[];
+    maxInputBytes?: number;
+    tags?: string[];
+    capacity?: ServiceCapacity;
+    extensions?: JsonObject;
+}
+/** How much load a service takes (§5.8). Hints only: the provider's 429, 503 and queue answers are what count. */
+export interface ServiceCapacity {
+    /** Jobs the service runs at the same time. */
+    concurrency?: number;
+    /** Longest a new job may expect to wait in the queue; beyond it, create-job answers 503. 0: no queue. */
+    maxQueueWaitSeconds?: number;
+}
+/** A broken rule: its id in provider-standard.md and a JSON Pointer to the offending value. */
+export interface RuleViolation {
+    rule: string;
+    pointer: string;
+    message: string;
+}
+export interface ManifestRuleOptions {
+    /** The URL the manifest was fetched from. */
+    manifestUrl: string;
+    /** Validates a value against a JSON Schema. Without it, examples are not checked [S9]. */
+    validateExample?: (schema: JsonObject, value: JsonValue) => boolean;
+}
+/**
+ * Checks the manifest rules that JSON Schema can't express: M1 (HTTPS manifest URL), M3 (I-JSON),
+ * M5 (same origin), M7 (unique service names), S6 (schema size), S9 (examples) and P11 (address
+ * checksum). Call it only on a manifest that passed the JSON Schema.
+ */
+export declare function checkManifestRules(manifest: ProviderManifest, options: ManifestRuleOptions): RuleViolation[];
+/**
+ * Checks a decoded x402 PAYMENT-REQUIRED challenge for one service against the manifest the user
+ * approved ([P3], [P4], [P5]). A client refuses to sign if this returns any violation [P7].
+ */
+export declare function checkChallenge(manifest: ProviderManifest, serviceName: string, challenge: unknown): RuleViolation[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}