@agentcash/discovery 0.1.2 → 0.1.4

package/README.md

@@ -75,6 +75,7 @@ import {
   auditContextHarness,
   discover,
   discoverDetailed,
+  validatePaymentRequiredDetailed,
   type HarnessClientId,
 } from '@agentcash/discovery';
 
@@ -96,6 +97,16 @@ const harness = await auditContextHarness({
   contextWindowTokens: 200000,
   compatMode: 'on',
 });
+
+const validation = validatePaymentRequiredDetailed(payload, {
+  compatMode: 'strict',
+  metadata: {
+    title: 'Example API',
+    description: 'Sample description',
+    favicon: 'https://example.com/favicon.ico',
+    ogImages: [{ url: 'https://example.com/og.png' }],
+  },
+});
 ```
 
 ## MCP Adapter Contract
@@ -144,6 +155,11 @@ Behavior:
 - `discover(...)` stops at first valid non-empty stage.
 - `discoverDetailed(...)` runs full waterfall and merges deterministically.
 
+Validation behavior:
+
+- `validatePaymentRequiredDetailed(...)` uses Coinbase `@x402/core` schemas as the structural base gate.
+- Product policy diagnostics (network/schema/metadata) are layered on top with stable issue codes.
+
 ## Compatibility Modes
 
 - `on` (default): legacy adapters enabled.
@@ -195,3 +211,7 @@ Output:
 ## Deeper Docs
 
 Architecture and planning artifacts live in `.claude/`.
+
+Validation design doc:
+
+- `docs/VALIDATION_DIAGNOSTICS_DESIGN_2026-03-03.md`

package/dist/cli.cjs

@@ -330,7 +330,7 @@ function actionItems(run, options) {
     ];
   }
   return [
-    "Publish canonical OpenAPI discovery metadata with x-agentcash extensions",
+    "Publish canonical OpenAPI discovery metadata with x-payment-info and security schemes",
     `Validate migration path: npx @agentcash/discovery ${target} --compat strict -v --probe`,
     "Keep legacy well-known path only during sunset window"
   ];
@@ -637,7 +637,7 @@ function renderJson(run, options) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.2".includes("-mmm");
+var isMmmEnabled = () => "0.1.4".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -807,7 +807,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "Using /.well-known/x402.instructions as compatibility guidance fallback. Prefer llms.txt.",
         {
           stage: "well-known/x402",
-          hint: "Move guidance to llms.txt and reference via x-agentcash-guidance.llmsTxtUrl."
+          hint: "Move guidance to llms.txt and reference via x-discovery.llmsTxtUrl in OpenAPI."
         }
       )
     );
@@ -820,7 +820,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "Using /.well-known/x402.ownershipProofs compatibility field. Prefer OpenAPI provenance extension.",
         {
           stage: "well-known/x402",
-          hint: "Move ownership proofs to x-agentcash-provenance.ownershipProofs in OpenAPI."
+          hint: "Move ownership proofs to x-discovery.ownershipProofs in OpenAPI."
         }
       )
     );
@@ -1216,10 +1216,31 @@ function estimateTokenCount(text) {
   return Math.ceil(text.length / 4);
 }
 
-// src/core/openapi.ts
+// src/core/openapi-utils.ts
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function hasSecurity(operation, scheme) {
+  const security = operation.security;
+  return Array.isArray(security) && security.some((s) => isRecord3(s) && scheme in s);
+}
+function has402Response(operation) {
+  const responses = operation.responses;
+  if (!isRecord3(responses)) return false;
+  return Boolean(responses["402"]);
+}
+function inferAuthMode(operation) {
+  if (isRecord3(operation["x-payment-info"])) return "paid";
+  if (has402Response(operation)) {
+    if (hasSecurity(operation, "siwx")) return "siwx";
+    return "paid";
+  }
+  if (hasSecurity(operation, "apiKey")) return "apiKey";
+  if (hasSecurity(operation, "siwx")) return "siwx";
+  return void 0;
+}
+
+// src/core/openapi.ts
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -1228,11 +1249,6 @@ function parsePriceValue(value) {
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
   return void 0;
 }
-function require402Response(operation) {
-  const responses = operation.responses;
-  if (!isRecord3(responses)) return false;
-  return Boolean(responses["402"]);
-}
 function parseProtocols(paymentInfo) {
   const protocols = paymentInfo.protocols;
   if (!Array.isArray(protocols)) return [];
@@ -1240,15 +1256,6 @@ function parseProtocols(paymentInfo) {
     (entry) => typeof entry === "string" && entry.length > 0
   );
 }
-function parseAuthMode(operation) {
-  const auth = operation["x-agentcash-auth"];
-  if (!isRecord3(auth)) return void 0;
-  const mode = auth.mode;
-  if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
-    return mode;
-  }
-  return void 0;
-}
 async function runOpenApiStage(options) {
   const warnings = [];
   const resources = [];
@@ -1320,10 +1327,9 @@ async function runOpenApiStage(options) {
     };
   }
   const paths = document.paths;
-  const provenance = isRecord3(document["x-agentcash-provenance"]) ? document["x-agentcash-provenance"] : void 0;
-  const ownershipProofs = Array.isArray(provenance?.ownershipProofs) ? provenance.ownershipProofs.filter((entry) => typeof entry === "string") : [];
-  const guidance = isRecord3(document["x-agentcash-guidance"]) ? document["x-agentcash-guidance"] : void 0;
-  const llmsTxtUrl = asString(guidance?.llmsTxtUrl);
+  const discovery = isRecord3(document["x-discovery"]) ? document["x-discovery"] : void 0;
+  const ownershipProofs = Array.isArray(discovery?.ownershipProofs) ? discovery.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  const llmsTxtUrl = asString(discovery?.llmsTxtUrl);
   if (ownershipProofs.length > 0) {
     warnings.push(
       warning("OPENAPI_OWNERSHIP_PROOFS_PRESENT", "info", "OpenAPI ownership proofs detected", {
@@ -1368,13 +1374,13 @@ async function runOpenApiStage(options) {
           )
         );
       }
-      const authMode = parseAuthMode(operation);
+      const authMode = inferAuthMode(operation);
       if (!authMode) {
         warnings.push(
           warning(
             "OPENAPI_AUTH_MODE_MISSING",
             "error",
-            `${method} ${rawPath} missing x-agentcash-auth.mode`,
+            `${method} ${rawPath} missing auth mode (no x-payment-info, 402 response, or security scheme)`,
             {
               stage: "openapi"
             }
@@ -1382,7 +1388,7 @@ async function runOpenApiStage(options) {
         );
         continue;
       }
-      if ((authMode === "paid" || authMode === "siwx") && !require402Response(operation)) {
+      if ((authMode === "paid" || authMode === "siwx") && !has402Response(operation)) {
         warnings.push(
           warning(
             "OPENAPI_402_MISSING",
@@ -1961,11 +1967,6 @@ async function runDiscovery({
         }
       }
     }
-    if (!stageResult.valid) {
-      continue;
-    }
-    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
-    warnings.push(...mergeWarnings);
     if (includeRaw && stageResult.raw !== void 0) {
       if (stageResult.stage === "openapi" || stageResult.stage === "override") {
         const rawObject = stageResult.raw;
@@ -1985,6 +1986,11 @@ async function runDiscovery({
         rawSources.interopMpp = stageResult.raw;
       }
     }
+    if (!stageResult.valid) {
+      continue;
+    }
+    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
+    warnings.push(...mergeWarnings);
     if (!detailed) {
       selectedStage = selectedStage ?? stageResult.stage;
       break;
@@ -2025,6 +2031,9 @@ async function runDiscovery({
   };
 }
 
+// src/validation/payment-required.ts
+var import_schemas = require("@x402/core/schemas");
+
 // src/harness.ts
 var INTENT_TRIGGERS = ["x402", "mpp", "pay for", "micropayment", "agentic commerce"];
 var CLIENT_PROFILES = {

package/dist/cli.js

@@ -304,7 +304,7 @@ function actionItems(run, options) {
     ];
   }
   return [
-    "Publish canonical OpenAPI discovery metadata with x-agentcash extensions",
+    "Publish canonical OpenAPI discovery metadata with x-payment-info and security schemes",
     `Validate migration path: npx @agentcash/discovery ${target} --compat strict -v --probe`,
     "Keep legacy well-known path only during sunset window"
   ];
@@ -611,7 +611,7 @@ function renderJson(run, options) {
 }
 
 // src/mmm-enabled.ts
-var isMmmEnabled = () => "0.1.2".includes("-mmm");
+var isMmmEnabled = () => "0.1.4".includes("-mmm");
 
 // src/core/constants.ts
 var OPENAPI_PATH_CANDIDATES = ["/openapi.json", "/.well-known/openapi.json"];
@@ -781,7 +781,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "Using /.well-known/x402.instructions as compatibility guidance fallback. Prefer llms.txt.",
         {
           stage: "well-known/x402",
-          hint: "Move guidance to llms.txt and reference via x-agentcash-guidance.llmsTxtUrl."
+          hint: "Move guidance to llms.txt and reference via x-discovery.llmsTxtUrl in OpenAPI."
         }
       )
     );
@@ -794,7 +794,7 @@ function parseWellKnownPayload(payload, origin, sourceUrl) {
         "Using /.well-known/x402.ownershipProofs compatibility field. Prefer OpenAPI provenance extension.",
         {
           stage: "well-known/x402",
-          hint: "Move ownership proofs to x-agentcash-provenance.ownershipProofs in OpenAPI."
+          hint: "Move ownership proofs to x-discovery.ownershipProofs in OpenAPI."
         }
       )
     );
@@ -1190,10 +1190,31 @@ function estimateTokenCount(text) {
   return Math.ceil(text.length / 4);
 }
 
-// src/core/openapi.ts
+// src/core/openapi-utils.ts
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function hasSecurity(operation, scheme) {
+  const security = operation.security;
+  return Array.isArray(security) && security.some((s) => isRecord3(s) && scheme in s);
+}
+function has402Response(operation) {
+  const responses = operation.responses;
+  if (!isRecord3(responses)) return false;
+  return Boolean(responses["402"]);
+}
+function inferAuthMode(operation) {
+  if (isRecord3(operation["x-payment-info"])) return "paid";
+  if (has402Response(operation)) {
+    if (hasSecurity(operation, "siwx")) return "siwx";
+    return "paid";
+  }
+  if (hasSecurity(operation, "apiKey")) return "apiKey";
+  if (hasSecurity(operation, "siwx")) return "siwx";
+  return void 0;
+}
+
+// src/core/openapi.ts
 function asString(value) {
   return typeof value === "string" && value.length > 0 ? value : void 0;
 }
@@ -1202,11 +1223,6 @@ function parsePriceValue(value) {
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
   return void 0;
 }
-function require402Response(operation) {
-  const responses = operation.responses;
-  if (!isRecord3(responses)) return false;
-  return Boolean(responses["402"]);
-}
 function parseProtocols(paymentInfo) {
   const protocols = paymentInfo.protocols;
   if (!Array.isArray(protocols)) return [];
@@ -1214,15 +1230,6 @@ function parseProtocols(paymentInfo) {
     (entry) => typeof entry === "string" && entry.length > 0
   );
 }
-function parseAuthMode(operation) {
-  const auth = operation["x-agentcash-auth"];
-  if (!isRecord3(auth)) return void 0;
-  const mode = auth.mode;
-  if (mode === "paid" || mode === "siwx" || mode === "apiKey" || mode === "unprotected") {
-    return mode;
-  }
-  return void 0;
-}
 async function runOpenApiStage(options) {
   const warnings = [];
   const resources = [];
@@ -1294,10 +1301,9 @@ async function runOpenApiStage(options) {
     };
   }
   const paths = document.paths;
-  const provenance = isRecord3(document["x-agentcash-provenance"]) ? document["x-agentcash-provenance"] : void 0;
-  const ownershipProofs = Array.isArray(provenance?.ownershipProofs) ? provenance.ownershipProofs.filter((entry) => typeof entry === "string") : [];
-  const guidance = isRecord3(document["x-agentcash-guidance"]) ? document["x-agentcash-guidance"] : void 0;
-  const llmsTxtUrl = asString(guidance?.llmsTxtUrl);
+  const discovery = isRecord3(document["x-discovery"]) ? document["x-discovery"] : void 0;
+  const ownershipProofs = Array.isArray(discovery?.ownershipProofs) ? discovery.ownershipProofs.filter((entry) => typeof entry === "string") : [];
+  const llmsTxtUrl = asString(discovery?.llmsTxtUrl);
   if (ownershipProofs.length > 0) {
     warnings.push(
       warning("OPENAPI_OWNERSHIP_PROOFS_PRESENT", "info", "OpenAPI ownership proofs detected", {
@@ -1342,13 +1348,13 @@ async function runOpenApiStage(options) {
           )
         );
       }
-      const authMode = parseAuthMode(operation);
+      const authMode = inferAuthMode(operation);
       if (!authMode) {
         warnings.push(
           warning(
             "OPENAPI_AUTH_MODE_MISSING",
             "error",
-            `${method} ${rawPath} missing x-agentcash-auth.mode`,
+            `${method} ${rawPath} missing auth mode (no x-payment-info, 402 response, or security scheme)`,
             {
               stage: "openapi"
             }
@@ -1356,7 +1362,7 @@ async function runOpenApiStage(options) {
         );
         continue;
       }
-      if ((authMode === "paid" || authMode === "siwx") && !require402Response(operation)) {
+      if ((authMode === "paid" || authMode === "siwx") && !has402Response(operation)) {
         warnings.push(
           warning(
             "OPENAPI_402_MISSING",
@@ -1935,11 +1941,6 @@ async function runDiscovery({
         }
       }
     }
-    if (!stageResult.valid) {
-      continue;
-    }
-    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
-    warnings.push(...mergeWarnings);
     if (includeRaw && stageResult.raw !== void 0) {
       if (stageResult.stage === "openapi" || stageResult.stage === "override") {
         const rawObject = stageResult.raw;
@@ -1959,6 +1960,11 @@ async function runDiscovery({
         rawSources.interopMpp = stageResult.raw;
       }
     }
+    if (!stageResult.valid) {
+      continue;
+    }
+    const mergeWarnings = mergeResources(merged, stageResult.resources, resourceWarnings);
+    warnings.push(...mergeWarnings);
     if (!detailed) {
       selectedStage = selectedStage ?? stageResult.stage;
       break;
@@ -1999,6 +2005,9 @@ async function runDiscovery({
   };
 }
 
+// src/validation/payment-required.ts
+import { parsePaymentRequired } from "@x402/core/schemas";
+
 // src/harness.ts
 var INTENT_TRIGGERS = ["x402", "mpp", "pay for", "micropayment", "agentic commerce"];
 var CLIENT_PROFILES = {