@stellar-agent-services/provider-kit 0.0.0-stage → 0.1.0

package/dist/validation-request.js

@@ -0,0 +1,101 @@
+// Asking a verifier for validation (docs/verification.md): the provider's owner names a verifier in the
+// Stellar 8004 Validation Registry with validation_request, and the verifier answers with a verification
+// receipt, validation_response. `provider-kit request-validation` is the command.
+//
+// prepareValidationRequest() checks everything the request depends on before anything is signed:
+// - a verifier can validate the provider: it is served over HTTPS, and its registration passes [I1]–[I3],
+//   as the verifier's C2 will check;
+// - the signer may ask: the registry takes a request only from the agent's owner, the address approved for
+//   the agent, or an operator of the owner's;
+// - the validator is someone else: not the agent's owner, its wallet or the signer. The registry would let a
+//   provider name itself, but such an answer would prove nothing.
+// The request document is RFC 8785 canonical JSON. request_hash is its SHA-256, and request_uri a data: URI
+// holding exactly those bytes, so the request lives on chain and needs no hosting. Nothing here signs: the
+// CLI has the owner's wallet sign the invocation, or hands it to the Stellar CLI keychain (--source).
+import { PROVIDER_STANDARD, stellarAddressKind, VALIDATION_REQUEST_TYPE, validationRequestDataUri, validationRequestHash, } from "@stellar-agent-services/protocol";
+import { checkRegistration, mayActFor } from "./registration.js";
+export class ValidationRequestError extends Error {
+    problems;
+    name = "ValidationRequestError";
+    constructor(problems) {
+        super(`no validation is requested:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`);
+        this.problems = problems;
+    }
+}
+/** Checks everything a validation_request depends on, then builds it. Throws a ValidationRequestError listing every problem. */
+export async function prepareValidationRequest(manifest, manifestUrl, options) {
+    const { registry, validator, signer } = options;
+    const { network, payTo } = manifest.payment.accepts[0];
+    const agentId = manifest.provider.agentId;
+    const problems = [];
+    if (!manifestUrl.startsWith("https://"))
+        problems.push("a dev-mode provider (http://localhost) can't be validated: deploy it on HTTPS first");
+    if (agentId === undefined)
+        problems.push("provider.agentId is not set [I2]: provider-kit launch registers the provider and saves its agent id");
+    if (stellarAddressKind(validator) !== "account")
+        problems.push("the validator must be a G... account address");
+    if (registry.network !== network)
+        problems.push(`the provider is on ${network}, but the registry is on ${registry.network}`);
+    if (problems.length > 0 || agentId === undefined)
+        throw new ValidationRequestError(problems);
+    try {
+        // Without what C2 checks, the verifier's answer could never earn "8004 validated".
+        const findings = await checkRegistration(manifest, manifestUrl, { registry, ...(options.fetch === undefined ? {} : { fetch: options.fetch }) });
+        for (const finding of findings)
+            if (!finding.ok)
+                problems.push(`[${finding.rule}] ${finding.message}`);
+        const owner = await registry.agentOwner(agentId);
+        if ([owner, payTo, signer].includes(validator)) {
+            problems.push("the validator is the provider itself (its owner, its wallet or the signing key): name an independent verifier's account");
+        }
+        if (owner !== undefined && signer !== undefined && !(await mayActFor(registry, agentId, owner, signer))) {
+            problems.push(`${signer} may not ask for agent ${agentId}'s validation: only its owner ${owner}, the address approved for the agent, or an operator of the owner's may`);
+        }
+    }
+    catch (error) {
+        problems.push(`the Stellar 8004 registries can't be read: ${error.message}`);
+    }
+    if (problems.length > 0)
+        throw new ValidationRequestError(problems);
+    const request = {
+        standard: PROVIDER_STANDARD,
+        type: VALIDATION_REQUEST_TYPE,
+        agentId,
+        network,
+        manifest: { url: manifestUrl },
+        validator,
+        requestedAt: (options.now?.() ?? new Date()).toISOString(),
+    };
+    return {
+        request,
+        requestHash: await validationRequestHash(request),
+        requestUri: validationRequestDataUri(request),
+        contractId: registry.contracts.validation,
+    };
+}
+/** The arguments of `stellar` that send the request: a contract invocation of validation_request. `caller` is the --source key's address. */
+export function validationRequestArguments(prepared, options) {
+    return [
+        "contract",
+        "invoke",
+        "--id",
+        prepared.contractId,
+        "--source-account",
+        options.source,
+        "--network",
+        options.network,
+        "--",
+        "validation_request",
+        "--caller",
+        options.caller,
+        "--validator_address",
+        prepared.request.validator,
+        "--agent_id",
+        String(prepared.request.agentId),
+        "--request_uri",
+        prepared.requestUri,
+        "--request_hash",
+        prepared.requestHash,
+    ];
+}
+//# sourceMappingURL=validation-request.js.map

package/dist/validation-request.js.map

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

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "@stellar-agent-services/provider-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turn a function, or an existing HTTP API in any language, into a paid Stellar service: Provider Standard v1 manifest, x402 USDC payments, job recovery, capacity.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlgoriaLabs/stellar-agent-services.git",
+    "directory": "packages/provider-kit"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "!dist/.tsbuildinfo"
+  ],
+  "scripts": {
+    "build": "tsc -b && npm run build:approve",
+    "build:approve": "vite build --config approve/vite.config.ts",
+    "dev:approve": "vite --config approve/vite.config.ts",
+    "check": "svelte-check --workspace ./approve --tsconfig ./tsconfig.json --fail-on-warnings"
+  },
+  "dependencies": {
+    "@stellar-agent-services/payment-client": "0.1.0",
+    "@stellar-agent-services/protocol": "0.1.0",
+    "@stellar/stellar-sdk": "16.4.1",
+    "@trionlabs/stellar8004": "0.0.11",
+    "@x402/core": "2.28.0",
+    "@x402/stellar": "2.28.0",
+    "ajv": "8.20.0",
+    "yaml": "2.9.1"
+  },
+  "bin": {
+    "provider-kit": "./dist/cli/index.js"
+  },
+  "devDependencies": {
+    "@creit.tech/stellar-wallets-kit": "2.7.1",
+    "@sveltejs/vite-plugin-svelte": "7.3.1",
+    "buffer": "6.0.3",
+    "svelte": "5.57.2",
+    "svelte-check": "4.7.6",
+    "vite": "8.3.4"
+  }
+}

package/schemas/gateway-config.schema.json

@@ -0,0 +1,140 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://algorialabs.github.io/stellar-agent-services/schemas/provider-kit/gateway-config.schema.json",
+  "title": "Provider Kit gateway config",
+  "description": "Puts an existing HTTP API, in any language, behind Provider Standard v1: manifest, x402 payment, job recovery and capacity. Run it with `provider-kit serve --config <file>`. Values written \"env:NAME\" are read from the environment variable NAME, in the fields that say so. The gateway holds no Stellar secret key.",
+  "type": "object",
+  "required": ["baseUrl", "network", "payTo", "facilitator", "provider", "services"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "baseUrl": {
+      "description": "The public HTTPS URL job paths are under, such as https://api.example.com/agent. http://localhost only with dev. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "network": { "enum": ["stellar:testnet", "stellar:pubnet"] },
+    "payTo": {
+      "description": "The G... or C... address that receives payments: public, never a secret key. Use the agent wallet of your 8004 registration [I3]. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "facilitator": {
+      "description": "The x402 facilitator URL, such as https://x402.org/facilitator on testnet. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "facilitatorHeaders": {
+      "description": "Headers sent to the facilitator, for one that wants an API key. Values may be \"env:NAME\".",
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "provider": {
+      "description": "Who you are, as the manifest shows it (§2.3).",
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1, "maxLength": 120 },
+        "description": { "type": "string", "maxLength": 500 },
+        "homepage": { "type": "string" },
+        "agentId": { "description": "Your Stellar 8004 agent id, after `provider-kit launch` or `register`. May be \"env:NAME\": an unset or empty variable leaves it out, as before registering.", "type": ["integer", "string"] },
+        "termsUrl": { "type": "string" },
+        "dataUse": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": { "storesInputs": { "type": "boolean" }, "trainsOnInputs": { "type": "boolean" } }
+        }
+      }
+    },
+    "rpcUrl": {
+      "description": "The Soroban RPC the gateway reads the chain with, to decide payment_uncertain jobs and time on-success jobs by ledger. Default: the public RPC on testnet; pubnet has none, so set yours. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "store": {
+      "description": "Where jobs are kept: a SQLite file path, relative to this config file (default ./jobs.sqlite), or \"memory\" for tests only. May be \"env:NAME\".",
+      "type": "string"
+    },
+    "listen": {
+      "description": "Where `serve` listens. Default port 8787 on 0.0.0.0. The PORT environment variable overrides the port.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "host": { "type": "string" }, "port": { "type": "integer", "minimum": 0, "maximum": 65535 } }
+    },
+    "maxTimeoutSeconds": { "description": "How long a signed payment is valid. Default 60.", "type": "integer", "minimum": 30, "maximum": 300 },
+    "settleTimeoutSeconds": { "description": "How long a settlement may take before the job is payment_uncertain. Default maxTimeoutSeconds + 30.", "type": "integer", "minimum": 1 },
+    "retentionSeconds": { "description": "How long finished jobs stay retrievable. Default 86400.", "type": "integer", "minimum": 3600 },
+    "manifestPath": { "description": "Default /.well-known/stellar-agent-services.json.", "type": "string", "pattern": "^/" },
+    "holdSeconds": { "description": "How long create-job waits before answering 202. Default 30.", "type": "integer", "minimum": 0, "maximum": 30 },
+    "runQueuedJobs": { "description": "Whether this process runs queued upfront jobs. Default true.", "type": "boolean" },
+    "leaseSeconds": { "type": "integer", "minimum": 3 },
+    "rateLimit": {
+      "description": "Per-caller limit on create-job (429). keyHeader names the header a trusted proxy sets to the caller's address.",
+      "type": "object",
+      "required": ["requests", "windowSeconds", "keyHeader"],
+      "additionalProperties": false,
+      "properties": {
+        "requests": { "type": "integer", "minimum": 1 },
+        "windowSeconds": { "type": "integer", "minimum": 1 },
+        "keyHeader": { "type": "string", "minLength": 1 }
+      }
+    },
+    "dev": { "description": "Allows http://localhost for baseUrl and the facilitator. Never in production.", "type": "boolean" },
+    "services": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 25,
+      "items": { "$ref": "#/$defs/service" }
+    }
+  },
+  "$defs": {
+    "service": {
+      "type": "object",
+      "required": ["name", "description", "price", "inputSchema", "outputSchema", "upstream"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" },
+        "title": { "type": "string" },
+        "description": { "description": "What it does, when to use it, and its limits (§3.4).", "type": "string", "minLength": 1, "maxLength": 1000 },
+        "price": { "description": "USDC, as a decimal string such as \"0.05\".", "type": "string", "pattern": "^\\d+(\\.\\d{1,7})?$" },
+        "charge": { "enum": ["on-success", "upfront"] },
+        "expectedDurationSeconds": { "type": "integer", "minimum": 1 },
+        "timeoutSeconds": { "description": "Longest the upstream call may take. Default: twice expectedDurationSeconds, or 600.", "type": "integer", "minimum": 1 },
+        "inputSchema": { "description": "A JSON Schema object, or the path of a JSON file holding one, relative to this config file.", "type": ["object", "string"] },
+        "outputSchema": { "description": "A JSON Schema object, or the path of a JSON file holding one.", "type": ["object", "string"] },
+        "examples": {
+          "type": "array",
+          "maxItems": 5,
+          "items": {
+            "type": "object",
+            "required": ["input", "output"],
+            "additionalProperties": false,
+            "properties": { "input": { "type": "object" }, "output": { "type": "object" } }
+          }
+        },
+        "tags": { "type": "array", "maxItems": 10, "items": { "type": "string", "pattern": "^[a-z0-9-]{1,32}$" } },
+        "maxInputBytes": { "type": "integer", "minimum": 1, "maximum": 10485760 },
+        "capacity": {
+          "description": "What the upstream can take: calls at once, and how long a new job may wait (§5.8).",
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "concurrency": { "type": "integer", "minimum": 1 },
+            "maxQueued": { "type": "integer", "minimum": 0 },
+            "maxQueueWaitSeconds": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "upstream": {
+          "type": "object",
+          "required": ["url"],
+          "additionalProperties": false,
+          "properties": {
+            "url": { "description": "Where the input is POSTed as JSON. May be \"env:NAME\".", "type": "string" },
+            "headers": {
+              "description": "Sent with every call, such as the upstream's own API key. Values may be \"env:NAME\".",
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            }
+          }
+        }
+      }
+    }
+  }
+}