@agentcash/discovery 1.6.5 → 1.7.0

package/docs/SPECIFICATION.md

@@ -0,0 +1,270 @@
+# Agentcash Discovery Specification
+
+Version: v1.0
+
+Status: Public draft for implementation and feedback.
+
+## 1. Introduction
+
+Agentcash Discovery is a discovery profile for agent-facing HTTP APIs that charge for or
+authenticate access to individual resources.
+
+The protocol defines how an origin advertises:
+
+- which resources exist
+- how each resource is addressed
+- which auth or payment mode an agent should expect
+- which payment protocols are supported
+- where larger schemas and guidance can be fetched on demand
+
+Discovery metadata is advisory. Runtime execution MUST verify auth and payment truth from the
+live endpoint response, including HTTP 402 challenges.
+
+## 2. Conformance
+
+The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL are
+to be interpreted as described in BCP 14 when they appear in uppercase.
+
+An implementation conforms to v1 when it implements the OpenAPI profile in this document and
+preserves the resource identity rules below.
+
+## 3. Terminology
+
+- Origin: scheme plus host plus optional port, with no path, query, fragment, or trailing slash.
+- Resource: one callable HTTP operation identified by origin, method, and path.
+- Resource key: the stable identity string for a resource.
+- Auth hint: advisory discovery-time classification of the auth/payment behavior.
+- Payment info: advisory pricing and protocol metadata declared in OpenAPI.
+
+## 4. Resource Identity
+
+Resource identity is always:
+
+```text
+${origin} ${method} ${path}
+```
+
+Rules:
+
+- `origin` MUST be normalized to `scheme://host[:port]`.
+- `method` MUST be an uppercase HTTP method.
+- `path` MUST start with `/`.
+- `path` MUST exclude query strings and fragments.
+- `path` MUST NOT have a trailing slash except for `/`.
+
+Clients SHOULD use `resourceKey` for dedupe, caching, display, and audit joins.
+
+## 5. Discovery Order
+
+Origin discovery proceeds in this fixed order:
+
+1. Caller-supplied OpenAPI override URL, when provided.
+2. `GET /openapi.json`.
+
+If no OpenAPI spec is found, discovery returns not found. Legacy `/.well-known/x402`,
+`/.well-known/mpp`, and DNS `_x402` records are no longer parsed; implementations MAY probe their
+presence to emit a single `LEGACY_WELL_KNOWN_FOUND` migration warning.
+
+## 6. Canonical OpenAPI Profile
+
+OpenAPI is the canonical machine-readable discovery source.
+
+Required top-level fields:
+
+- `openapi`
+- `info.title`
+- `info.version`
+- `paths`
+
+Required per-operation fields:
+
+- `summary` or `description`
+- an effective OpenAPI `security` declaration
+- `responses`
+
+Authentication MUST use OpenAPI `security`. Use `security: []` to explicitly declare that an
+operation has no API authentication requirement. Payment is declared independently with
+`x-payment-info`.
+
+SIWX is represented as a security scheme with an agentcash marker because OpenAPI has no native
+SIWX scheme type:
+
+```json
+"components": {
+  "securitySchemes": {
+    "WalletAuth": {
+      "type": "apiKey",
+      "in": "header",
+      "name": "SIGN-IN-WITH-X",
+      "x-agentcash-auth-kind": "siwx"
+    }
+  }
+}
+```
+
+Discovery auth hints are derived from OpenAPI `security` plus `x-payment-info`:
+
+| Effective security | `x-payment-info` | Derived auth hint |
+| ------------------ | ---------------- | ----------------- |
+| `[]`               | absent           | `unprotected`     |
+| `[]`               | present          | `paid`            |
+| API key            | absent           | `apiKey`          |
+| API key            | present          | `apiKey+paid`     |
+| SIWX scheme        | absent           | `siwx`            |
+| SIWX scheme        | present          | `paid`            |
+
+Implementations MAY recognize a security scheme literally named `siwx` for compatibility, but new
+providers SHOULD use `x-agentcash-auth-kind: "siwx"` on the security scheme.
+
+## 7. Payment Metadata
+
+Paid operations SHOULD declare `x-payment-info`.
+
+Canonical structured shape:
+
+```json
+{
+  "x-payment-info": {
+    "price": {
+      "mode": "fixed",
+      "currency": "USD",
+      "amount": "0.02"
+    },
+    "protocols": [{ "x402": {} }]
+  }
+}
+```
+
+Dynamic pricing MAY include bounded or unbounded hints:
+
+```json
+{
+  "x-payment-info": {
+    "price": {
+      "mode": "dynamic",
+      "currency": "USD",
+      "min": "0.01",
+      "max": "2.50"
+    },
+    "protocols": [
+      { "x402": {} },
+      { "mpp": { "method": "tempo", "intent": "charge", "currency": "USD" } }
+    ]
+  }
+}
+```
+
+Rules:
+
+- `price.mode` MUST be `fixed` or `dynamic`.
+- `fixed` prices MUST include `amount`.
+- `dynamic` prices SHOULD include `min` and `max` when an agent can safely pre-authorize a bound.
+- `currency`, when present, SHOULD be an ISO 4217 uppercase code.
+- `protocols` SHOULD list protocol objects; unknown protocol keys MUST be ignored by clients.
+
+Legacy flat `x-payment-info` MAY be parsed for compatibility. v1-conformant providers
+SHOULD emit the structured shape.
+
+## 8. Guidance And Provenance
+
+OpenAPI carries machine metadata. Freeform agent guidance is fetched separately, typically
+from `llms.txt`.
+
+Canonical optional OpenAPI extensions:
+
+```json
+{
+  "x-agentcash-provenance": {
+    "ownershipProofs": ["..."]
+  },
+  "x-agentcash-guidance": {
+    "llmsTxtUrl": "https://api.example.com/llms.txt"
+  }
+}
+```
+
+Rules:
+
+- `ownershipProofs` SHOULD be short strings or URLs to proof artifacts.
+- `llmsTxtUrl` SHOULD point to concise domain-level guidance.
+- Short inline OpenAPI guidance SHOULD use `info.x-guidance`.
+- `info.guidance` is a deprecated compatibility fallback.
+- Clients SHOULD keep first-pass discovery token-light and fetch large guidance only on demand.
+
+## 9. Warning Codes
+
+Warning codes are public API. Implementations MUST NOT rename or reuse codes in a minor or
+patch release.
+
+Severity values are:
+
+- `error`
+- `warn`
+- `info`
+
+A single legacy detection warning is emitted when `/.well-known/x402` or `/.well-known/mpp` is
+present at an origin: `LEGACY_WELL_KNOWN_FOUND`. agentcash-discovery does not parse these
+documents; the warning exists to tell publishers to migrate to OpenAPI.
+
+## 10. Extensibility And Adjacent Standards
+
+This profile is narrow in scope. It discovers resources, auth/payment hints, and schema
+pointers. It does not define agent identity, capability grants, or approval flows.
+
+Future extensions SHOULD use namespaced OpenAPI extension fields or objects such as:
+
+- `x-agentcash-auth-kind`
+- `x-agentcash-provenance`
+- `x-agentcash-guidance`
+- `x-agentcash-capabilities`
+- `x-agentcash-agent-auth`
+
+Clients MUST ignore unknown extension fields and unknown protocol objects.
+
+Agent identity standards such as Agent Auth can compose with this profile by advertising their
+authorization server, capability mapping, or registration metadata in a namespaced OpenAPI
+extension while keeping resource identity unchanged.
+
+## 11. Minimal Example
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Example Commerce API",
+    "version": "1.0.0"
+  },
+  "x-agentcash-guidance": {
+    "llmsTxtUrl": "https://api.example.com/llms.txt"
+  },
+  "paths": {
+    "/search": {
+      "post": {
+        "summary": "Search purchasable records",
+        "security": [],
+        "x-payment-info": {
+          "price": { "mode": "fixed", "currency": "USD", "amount": "0.02" },
+          "protocols": [{ "x402": {} }]
+        },
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["query"],
+                "properties": {
+                  "query": { "type": "string" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": { "description": "Result" },
+          "402": { "description": "Payment Required" }
+        }
+      }
+    }
+  }
+}
+```

package/docs/VALIDATION_DIAGNOSTICS_DESIGN_2026-03-03.md

@@ -0,0 +1,117 @@
+# Validation Diagnostics Design (2026-03-03)
+
+## Goal
+Eliminate recurring discovery/x402 validation bugs by moving protocol validation and policy diagnostics into `@agentcash/discovery` and making all consumers render one canonical issue contract.
+
+## Constraints
+- Unify discovery/validation across all surfaces.
+- Surface actionable errors for wrong chain/network, missing `accepts`, missing schema, and missing metadata.
+- Keep compatibility support while making strict mode deterministic.
+- Keep package lean and avoid UI/runtime scraping concerns in core validation.
+
+## Ownership Boundary
+
+### Lives in `@agentcash/discovery`
+- x402 payload parsing/normalization.
+- Network policy (including Solana CAIP + alias handling).
+- Schema policy checks.
+- Metadata completeness diagnostics (validation only; no scraping).
+- Stable issue taxonomy and strictness matrix.
+- Regression fixtures and snapshot tests.
+
+### Lives in Consumer App (`x402scan`)
+- Probing strategy and retries.
+- Data persistence.
+- UI rendering/grouping of issue codes.
+- Metadata scraping before calling validator.
+
+## Canonical API
+
+```ts
+validatePaymentRequiredDetailed(payload, options) => {
+  valid: boolean,
+  version?: 1 | 2,
+  parsed?: Record<string, unknown>,
+  normalized?: {
+    version: 1 | 2,
+    accepts: NormalizedAccept[],
+    hasInputSchema: boolean,
+    hasOutputSchema: boolean,
+  },
+  issues: ValidationIssue[],
+  summary: {
+    errorCount: number,
+    warnCount: number,
+    infoCount: number,
+    byCode: Record<string, number>,
+  },
+}
+```
+
+## Validation Pipeline
+1. Coinbase structural gate via `@x402/core/schemas` (`parsePaymentRequired`).
+2. Map Coinbase Zod issues into canonical `ValidationIssue` entries (`COINBASE_SCHEMA_INVALID`).
+3. Apply product policy overlay checks (network policy, schema quality checks, metadata completeness).
+4. Compute summary + validity from merged issues.
+
+## Issue Taxonomy
+- `X402_*`: shape/version/accept-entry errors.
+- `NETWORK_*`: CAIP/network policy errors.
+- `SCHEMA_*`: input/output schema checks.
+- `METADATA_*`: title/description/favicon/og checks.
+
+## Strictness Matrix
+
+| Code family | compat=`on` | compat=`strict` |
+|---|---|---|
+| `COINBASE_SCHEMA_INVALID` | error | error |
+| `X402_*` | error | error |
+| `NETWORK_CAIP2_INVALID` | error | error |
+| `NETWORK_SOLANA_ALIAS_INVALID` | error | error |
+| `NETWORK_REFERENCE_UNKNOWN` | error | error |
+| `NETWORK_SOLANA_ALIAS_COMPAT` | warn | warn |
+| `SCHEMA_INPUT_MISSING` | error | error |
+| `SCHEMA_OUTPUT_MISSING` | warn | error |
+| `METADATA_*` | warn | warn |
+
+## Solana Policy
+
+### Accepted canonical refs (v2)
+- `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` (mainnet)
+- `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` (devnet)
+- `solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z` (testnet)
+
+### Compatibility aliases (warn)
+- `solana:mainnet`
+- `solana:devnet`
+- `solana:testnet`
+
+### Invalid aliases (error)
+- `solana-mainnet-beta`
+- Unknown `solana:<ref>`
+
+## Confidence Plan
+- Unit tests for each bug class and strictness behavior.
+- Regression fixtures for known incidents.
+- Consumer contract tests asserting `issues[]` is present on all relevant APIs.
+- UI tests mapping issue codes to checklist rows with unknown-code fallback.
+
+## UI Rendering Contract
+- UI must use `issues[]` as source of truth.
+- No string parsing of free-form errors.
+- Unknown codes render as generic warning/error rows so display never breaks.
+
+## Package Bloat Controls
+- Validation module is isolated (`src/validation/*`) and tree-shakable via root exports.
+- No scraping or heavy runtime dependencies in validator.
+- Test fixtures remain test-only (not shipped in package output).
+
+## Deprecation Timeline
+- `2026-03-03`: Introduce canonical `issues[]` contract in package.
+- `2026-03-10`: Consumer apps return `issues[]` + legacy string errors in parallel.
+- `2026-03-24`: Remove legacy string-only validation transport from consumers.
+
+## Immediate Follow-ups
+1. Expand fixture matrix with additional malformed network/schema combinations.
+2. Add OpenAPI operation-level schema policy checks to pair static + runtime diagnostics.
+3. Publish migration note for consumers adopting canonical `issues[]`.

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@agentcash/discovery",
-  "version": "1.6.5",
+  "version": "1.7.0",
   "description": "Canonical OpenAPI-first discovery runtime for the agentcash ecosystem",
+  "homepage": "https://github.com/merit-systems/agentcash-discovery#readme",
+  "bugs": {
+    "url": "https://github.com/merit-systems/agentcash-discovery/issues"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": "./bin/discovery.js",
   "exports": {
     ".": {
       "import": {
@@ -27,21 +30,12 @@
         "types": "./dist/schemas.d.cts",
         "default": "./dist/schemas.cjs"
       }
-    },
-    "./flags": {
-      "import": {
-        "types": "./dist/flags.d.ts",
-        "default": "./dist/flags.js"
-      },
-      "require": {
-        "types": "./dist/flags.d.cts",
-        "default": "./dist/flags.cjs"
-      }
     }
   },
   "files": [
     "dist",
     "bin",
+    "docs",
     "README.md",
     "LICENSE",
     "AGENTS.md"
@@ -51,10 +45,15 @@
   },
   "keywords": [
     "agentcash",
+    "agentic-commerce",
     "discovery",
     "x402",
-    "openapi"
+    "mpp",
+    "openapi",
+    "payments",
+    "agents"
   ],
+  "sideEffects": false,
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -66,19 +65,19 @@
   "dependencies": {
     "dereference-json-schema": "^0.2.2",
     "neverthrow": "^8.2.0",
-    "zod": "^4.0.0"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.8",
+    "@changesets/cli": "^2.31.0",
     "@eslint/js": "^10.0.1",
-    "@types/node": "^22.18.0",
+    "@types/node": "^22.19.19",
     "@vitest/coverage-v8": "^3.2.4",
-    "eslint": "^10.0.0",
-    "knip": "^5.85.0",
-    "prettier": "^3.8.1",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.2",
-    "typescript-eslint": "^8.43.0",
+    "eslint": "^10.4.0",
+    "knip": "^5.88.1",
+    "prettier": "^3.8.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.4",
     "vitest": "^3.2.4"
   },
   "scripts": {
@@ -94,5 +93,8 @@
     "audit:registry:quick": "pnpm build && node scripts/audit-registry.mjs --origin-limit 50 --resource-limit 500",
     "knip": "knip",
     "check": "pnpm format:check && pnpm lint && pnpm knip && pnpm typecheck && pnpm build && pnpm test"
+  },
+  "bin": {
+    "discovery": "./bin/discovery.js"
   }
 }

package/dist/flags.cjs

@@ -1,44 +0,0 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/flags.ts
-var flags_exports = {};
-__export(flags_exports, {
-  DEFAULT_COMPAT_MODE: () => DEFAULT_COMPAT_MODE,
-  LEGACY_SUNSET_DATE: () => LEGACY_SUNSET_DATE,
-  STRICT_ESCALATION_CODES: () => STRICT_ESCALATION_CODES
-});
-module.exports = __toCommonJS(flags_exports);
-var LEGACY_SUNSET_DATE = "2026-03-24";
-var DEFAULT_COMPAT_MODE = "on";
-var STRICT_ESCALATION_CODES = [
-  "LEGACY_WELL_KNOWN_USED",
-  "LEGACY_DNS_USED",
-  "LEGACY_DNS_PLAIN_URL",
-  "LEGACY_MISSING_METHOD",
-  "LEGACY_INSTRUCTIONS_USED",
-  "LEGACY_OWNERSHIP_PROOFS_USED",
-  "INTEROP_MPP_USED"
-];
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  DEFAULT_COMPAT_MODE,
-  LEGACY_SUNSET_DATE,
-  STRICT_ESCALATION_CODES
-});

package/dist/flags.d.cts

@@ -1,6 +0,0 @@
-declare const LEGACY_SUNSET_DATE = "2026-03-24";
-type CompatibilityMode = 'on' | 'off' | 'strict';
-declare const DEFAULT_COMPAT_MODE: CompatibilityMode;
-declare const STRICT_ESCALATION_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_MISSING_METHOD", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "INTEROP_MPP_USED"];
-
-export { type CompatibilityMode, DEFAULT_COMPAT_MODE, LEGACY_SUNSET_DATE, STRICT_ESCALATION_CODES };

package/dist/flags.d.ts

@@ -1,6 +0,0 @@
-declare const LEGACY_SUNSET_DATE = "2026-03-24";
-type CompatibilityMode = 'on' | 'off' | 'strict';
-declare const DEFAULT_COMPAT_MODE: CompatibilityMode;
-declare const STRICT_ESCALATION_CODES: readonly ["LEGACY_WELL_KNOWN_USED", "LEGACY_DNS_USED", "LEGACY_DNS_PLAIN_URL", "LEGACY_MISSING_METHOD", "LEGACY_INSTRUCTIONS_USED", "LEGACY_OWNERSHIP_PROOFS_USED", "INTEROP_MPP_USED"];
-
-export { type CompatibilityMode, DEFAULT_COMPAT_MODE, LEGACY_SUNSET_DATE, STRICT_ESCALATION_CODES };

package/dist/flags.js

@@ -1,17 +0,0 @@
-// src/flags.ts
-var LEGACY_SUNSET_DATE = "2026-03-24";
-var DEFAULT_COMPAT_MODE = "on";
-var STRICT_ESCALATION_CODES = [
-  "LEGACY_WELL_KNOWN_USED",
-  "LEGACY_DNS_USED",
-  "LEGACY_DNS_PLAIN_URL",
-  "LEGACY_MISSING_METHOD",
-  "LEGACY_INSTRUCTIONS_USED",
-  "LEGACY_OWNERSHIP_PROOFS_USED",
-  "INTEROP_MPP_USED"
-];
-export {
-  DEFAULT_COMPAT_MODE,
-  LEGACY_SUNSET_DATE,
-  STRICT_ESCALATION_CODES
-};