@agentcash/discovery 1.1.2 → 1.2.0

package/dist/index.cjs

@@ -50,6 +50,7 @@ __export(index_exports, {
   getWarningsForL2: () => getWarningsForL2,
   getWarningsForL3: () => getWarningsForL3,
   getWarningsForL4: () => getWarningsForL4,
+  getWarningsForMppHeader: () => getWarningsForMppHeader,
   getWarningsForOpenAPI: () => getWarningsForOpenAPI,
   getWarningsForWellKnown: () => getWarningsForWellKnown,
   getWellKnown: () => getWellKnown,
@@ -13887,7 +13888,6 @@ var WellKnownDocSchema = external_exports.object({
   version: external_exports.number().optional(),
   resources: external_exports.array(external_exports.string()).default([]),
   mppResources: external_exports.array(external_exports.string()).optional(),
-  // isMmmEnabled
   description: external_exports.string().optional(),
   ownershipProofs: external_exports.array(external_exports.string()).optional(),
   instructions: external_exports.string().optional()
@@ -13997,9 +13997,6 @@ function fetchSafe(url2, init) {
   return import_neverthrow.ResultAsync.fromPromise(fetch(url2, init), toFetchError);
 }
 
-// src/mmm-enabled.ts
-var isMmmEnabled = () => "1.1.2".includes("-mmm");
-
 // src/core/source/openapi/index.ts
 var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
   const routes = [];
@@ -14009,9 +14006,7 @@ var OpenApiParsedSchema = OpenApiDocSchema.transform((doc) => {
       if (!operation) continue;
       const authMode = inferAuthMode(operation, doc.security, doc.components?.securitySchemes) ?? void 0;
       const p = operation["x-payment-info"];
-      const protocols = (p?.protocols ?? []).filter(
-        (proto) => proto !== "mpp" || isMmmEnabled()
-      );
+      const protocols = (p?.protocols ?? []).filter((proto) => proto.length > 0);
       const pricing = (authMode === "paid" || authMode === "apiKey+paid") && p ? {
         pricingMode: p.pricingMode,
         ...p.price ? { price: p.price } : {},
@@ -14125,6 +14120,7 @@ function checkL2ForOpenAPI(openApi) {
   return {
     ...openApi.info.title ? { title: openApi.info.title } : {},
     ...openApi.info.description ? { description: openApi.info.description } : {},
+    ...openApi.info.version ? { version: openApi.info.version } : {},
     routes,
     source: "openapi"
   };
@@ -14195,7 +14191,13 @@ async function discoverOriginSchema(options) {
       found: true,
       origin,
       source: "openapi",
-      ...l22.title ? { info: { title: l22.title, ...l22.description ? { description: l22.description } : {} } } : {},
+      ...l22.title ? {
+        info: {
+          title: l22.title,
+          ...l22.description ? { description: l22.description } : {},
+          ...l22.version ? { version: l22.version } : {}
+        }
+      } : {},
       endpoints: l22.routes
     };
     return withGuidance(base2, l42, guidanceMode);
@@ -14649,7 +14651,7 @@ function detectProtocols(response) {
   }
   const authHeader = response.headers.get("www-authenticate")?.toLowerCase() ?? "";
   if (authHeader.includes("x402")) protocols.add("x402");
-  if (isMmmEnabled() && authHeader.includes("mpp")) protocols.add("mpp");
+  if (authHeader.includes("mpp")) protocols.add("mpp");
   return [...protocols];
 }
 function buildProbeUrl(url2, method, inputBody) {
@@ -14729,7 +14731,7 @@ function parseAuthParams(segment) {
   return params;
 }
 function extractPaymentOptions4(wwwAuthenticate) {
-  if (!isMmmEnabled() || !wwwAuthenticate) return [];
+  if (!wwwAuthenticate) return [];
   const options = [];
   for (const segment of wwwAuthenticate.split(/,\s*(?=Payment\s)/i)) {
     const stripped = segment.replace(/^Payment\s+/i, "").trim();
@@ -14758,12 +14760,10 @@ function extractPaymentOptions4(wwwAuthenticate) {
     if (!asset || !amount) continue;
     options.push({
       protocol: "mpp",
-      // isMmmEnabled
       paymentMethod,
       intent,
       realm,
       network: `tempo:${String(chainId)}`,
-      // isMmmEnabled
       asset,
       amount,
       ...decimals != null ? { decimals } : {},
@@ -14891,7 +14891,7 @@ function parseOperationProtocols(operation) {
   const paymentInfo = operation["x-payment-info"];
   if (!isRecord(paymentInfo) || !Array.isArray(paymentInfo.protocols)) return void 0;
   const protocols = paymentInfo.protocols.filter(
-    (protocol) => typeof protocol === "string" && protocol.length > 0 && (protocol !== "mpp" || isMmmEnabled())
+    (protocol) => typeof protocol === "string" && protocol.length > 0
   );
   return protocols.length > 0 ? protocols : void 0;
 }
@@ -14922,8 +14922,7 @@ function getL3ForProbe(probe, path, method) {
   const outputSchema = probeResult.paymentRequiredBody ? parseOutputSchema(probeResult.paymentRequiredBody) : void 0;
   const paymentOptions = [
     ...probeResult.paymentRequiredBody ? extractPaymentOptions3(probeResult.paymentRequiredBody) : [],
-    ...isMmmEnabled() ? extractPaymentOptions4(probeResult.wwwAuthenticate) : []
-    // isMmmEnabled
+    ...extractPaymentOptions4(probeResult.wwwAuthenticate)
   ];
   return {
     source: "probe",
@@ -14932,7 +14931,8 @@ function getL3ForProbe(probe, path, method) {
     ...inputSchema ? { inputSchema } : {},
     ...outputSchema ? { outputSchema } : {},
     ...paymentOptions.length ? { paymentOptions } : {},
-    ...probeResult.paymentRequiredBody !== void 0 ? { paymentRequiredBody: probeResult.paymentRequiredBody } : {}
+    ...probeResult.paymentRequiredBody !== void 0 ? { paymentRequiredBody: probeResult.paymentRequiredBody } : {},
+    ...probeResult.wwwAuthenticate ? { wwwAuthenticate: probeResult.wwwAuthenticate } : {}
   };
 }
 async function attachProbePayload(url2, advisories) {
@@ -14967,7 +14967,7 @@ async function checkEndpointSchema(options) {
   const endpoint = new URL(ensureProtocol(options.url));
   const origin = normalizeOrigin(endpoint.origin);
   const path = normalizePath(endpoint.pathname || "/");
-  if (options.sampleInputBody !== void 0) {
+  if (options.probe || options.sampleInputBody !== void 0) {
     const probeResult2 = await getProbe(
       endpoint.href,
       options.headers,
@@ -15113,9 +15113,23 @@ var AUDIT_CODES = {
   L3_INPUT_SCHEMA_MISSING: "L3_INPUT_SCHEMA_MISSING",
   L3_AUTH_MODE_MISSING: "L3_AUTH_MODE_MISSING",
   L3_PROTOCOLS_MISSING_ON_PAID: "L3_PROTOCOLS_MISSING_ON_PAID",
+  L3_PAYMENT_OPTIONS_MISSING_ON_PAID: "L3_PAYMENT_OPTIONS_MISSING_ON_PAID",
   // ─── L4 guidance checks ──────────────────────────────────────────────────────
   L4_GUIDANCE_MISSING: "L4_GUIDANCE_MISSING",
-  L4_GUIDANCE_TOO_LONG: "L4_GUIDANCE_TOO_LONG"
+  L4_GUIDANCE_TOO_LONG: "L4_GUIDANCE_TOO_LONG",
+  // ─── MPP WWW-Authenticate header checks ──────────────────────────────────────
+  MPP_HEADER_MISSING: "MPP_HEADER_MISSING",
+  MPP_NO_PAYMENT_CHALLENGES: "MPP_NO_PAYMENT_CHALLENGES",
+  MPP_CHALLENGE_ID_MISSING: "MPP_CHALLENGE_ID_MISSING",
+  MPP_CHALLENGE_METHOD_MISSING: "MPP_CHALLENGE_METHOD_MISSING",
+  MPP_CHALLENGE_INTENT_MISSING: "MPP_CHALLENGE_INTENT_MISSING",
+  MPP_CHALLENGE_REALM_MISSING: "MPP_CHALLENGE_REALM_MISSING",
+  MPP_CHALLENGE_EXPIRES_MISSING: "MPP_CHALLENGE_EXPIRES_MISSING",
+  MPP_CHALLENGE_REQUEST_MISSING: "MPP_CHALLENGE_REQUEST_MISSING",
+  MPP_CHALLENGE_REQUEST_INVALID: "MPP_CHALLENGE_REQUEST_INVALID",
+  MPP_CHALLENGE_ASSET_MISSING: "MPP_CHALLENGE_ASSET_MISSING",
+  MPP_CHALLENGE_AMOUNT_MISSING: "MPP_CHALLENGE_AMOUNT_MISSING",
+  MPP_CHALLENGE_RECIPIENT_MISSING: "MPP_CHALLENGE_RECIPIENT_MISSING"
 };
 
 // src/core/protocols/x402/v1/coinbase-schema.ts
@@ -15204,6 +15218,157 @@ function validateWithCoinbaseSchema2(body) {
   });
 }
 
+// src/audit/warnings/mpp.ts
+function parseAuthParams2(segment) {
+  const params = {};
+  const re = /(\w+)=(?:"([^"]*)"|'([^']*)')/g;
+  let match;
+  while ((match = re.exec(segment)) !== null) {
+    params[match[1]] = match[2] ?? match[3] ?? "";
+  }
+  return params;
+}
+function getWarningsForMppHeader(wwwAuthenticate) {
+  if (!wwwAuthenticate?.trim()) {
+    return [
+      {
+        code: AUDIT_CODES.MPP_HEADER_MISSING,
+        severity: "error",
+        message: "WWW-Authenticate header is absent.",
+        hint: "MPP endpoints must respond to unauthenticated requests with a 402 and a WWW-Authenticate: Payment ... header."
+      }
+    ];
+  }
+  const segments = wwwAuthenticate.split(/,\s*(?=Payment\s)/i).filter((s) => /^Payment\s/i.test(s.trim()));
+  if (segments.length === 0) {
+    return [
+      {
+        code: AUDIT_CODES.MPP_NO_PAYMENT_CHALLENGES,
+        severity: "error",
+        message: "WWW-Authenticate header contains no Payment challenges.",
+        hint: `Add at least one Payment challenge: WWW-Authenticate: Payment method="tempo" intent="charge" realm="..." request='...'`
+      }
+    ];
+  }
+  const warnings = [];
+  for (let i = 0; i < segments.length; i++) {
+    const stripped = segments[i].replace(/^Payment\s+/i, "").trim();
+    const params = parseAuthParams2(stripped);
+    const idx = `WWW-Authenticate[${i}]`;
+    if (!params["id"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_ID_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the id parameter.`,
+        hint: "Set id to a unique challenge identifier so clients can correlate credentials to challenges.",
+        path: `${idx}.id`
+      });
+    }
+    if (!params["method"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_METHOD_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the method parameter.`,
+        hint: 'Set method="tempo" (or your payment method identifier) on the Payment challenge.',
+        path: `${idx}.method`
+      });
+    }
+    if (!params["intent"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_INTENT_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the intent parameter.`,
+        hint: 'Set intent="charge" on the Payment challenge.',
+        path: `${idx}.intent`
+      });
+    }
+    if (!params["realm"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_REALM_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the realm parameter.`,
+        hint: "Set realm to a stable server identifier so clients can associate payment credentials.",
+        path: `${idx}.realm`
+      });
+    }
+    if (!params["expires"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_EXPIRES_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the expires parameter.`,
+        hint: "Set expires to an RFC 3339 timestamp so clients know when the challenge lapses.",
+        path: `${idx}.expires`
+      });
+    }
+    const requestStr = params["request"];
+    if (!requestStr) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_REQUEST_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing the request field.`,
+        hint: `Include a base64url-encoded JSON request field: request=base64url('{"currency":"...","amount":"...","recipient":"..."}')`,
+        path: `${idx}.request`
+      });
+      continue;
+    }
+    let request;
+    try {
+      const decoded = Buffer.from(requestStr, "base64url").toString("utf-8");
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("not an object");
+      }
+      request = parsed;
+    } catch {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_REQUEST_INVALID,
+        severity: "error",
+        message: `Payment challenge ${i} request field is not valid base64url-encoded JSON.`,
+        hint: "The request value must be a base64url-encoded JCS JSON object.",
+        path: `${idx}.request`
+      });
+      continue;
+    }
+    if (!request["currency"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_ASSET_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing currency in the request object.`,
+        hint: "Set currency to a TIP-20 token address (e.g. a USDC contract).",
+        path: `${idx}.request.currency`
+      });
+    }
+    const amount = request["amount"];
+    if (amount === void 0 || amount === null) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_AMOUNT_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing amount in the request object.`,
+        hint: 'Set amount to a raw token-unit string (e.g. "1000000" for 1 USDC with 6 decimals).',
+        path: `${idx}.request.amount`
+      });
+    } else if (typeof amount !== "string" && typeof amount !== "number") {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_AMOUNT_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} has an invalid amount type (got ${typeof amount}, expected string or number).`,
+        hint: "Set amount to a raw token-unit string.",
+        path: `${idx}.request.amount`
+      });
+    }
+    if (!request["recipient"]) {
+      warnings.push({
+        code: AUDIT_CODES.MPP_CHALLENGE_RECIPIENT_MISSING,
+        severity: "error",
+        message: `Payment challenge ${i} is missing recipient in the request object.`,
+        hint: "Set recipient to the wallet address that should receive payment.",
+        path: `${idx}.request.recipient`
+      });
+    }
+  }
+  return warnings;
+}
+
 // src/audit/warnings/l3.ts
 function getWarningsFor402Body(body) {
   if (!isRecord(body)) {
@@ -15333,17 +15498,28 @@ function getWarningsForL3(l3) {
       hint: "Add a requestBody or parameters schema so agents can construct valid payloads."
     });
   }
-  if (l3.authMode === "paid" && !l3.protocols?.length) {
+  if (l3.authMode === "paid" && l3.source === "openapi" && !l3.protocols?.length) {
     warnings.push({
       code: AUDIT_CODES.L3_PROTOCOLS_MISSING_ON_PAID,
       severity: "info",
       message: "Paid endpoint does not declare supported payment protocols.",
-      hint: "Add x-payment-info.protocols (e.g. ['x402']) to the operation."
+      hint: "Add x-payment-info.protocols (e.g. ['x402', 'mpp']) to the operation."
+    });
+  }
+  if (l3.authMode === "paid" && l3.source === "probe" && !l3.paymentOptions?.length) {
+    warnings.push({
+      code: AUDIT_CODES.L3_PAYMENT_OPTIONS_MISSING_ON_PAID,
+      severity: "warn",
+      message: "Paid endpoint did not return payment options in the 402 response.",
+      hint: "Ensure the 402 response returns a valid payment challenge so clients know how to pay."
     });
   }
   if (l3.paymentRequiredBody !== void 0) {
     warnings.push(...getWarningsFor402Body(l3.paymentRequiredBody));
   }
+  if (l3.wwwAuthenticate !== void 0) {
+    warnings.push(...getWarningsForMppHeader(l3.wwwAuthenticate));
+  }
   return warnings;
 }
 
@@ -15568,6 +15744,7 @@ function getWarningsForL4(l4) {
   getWarningsForL2,
   getWarningsForL3,
   getWarningsForL4,
+  getWarningsForMppHeader,
   getWarningsForOpenAPI,
   getWarningsForWellKnown,
   getWellKnown,

package/dist/index.d.cts

@@ -8,12 +8,14 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTION
 
 interface MppPaymentOption {
     protocol: 'mpp';
-    /** Payment method identifier, e.g. "tempo" (Tempo protocol). */ paymentMethod: string;
+    /** Payment method identifier, e.g. "tempo" (Tempo protocol). */
+    paymentMethod: string;
     /** Payment intent type, e.g. "charge". */
     intent: string;
     /** Server protection realm. */
     realm: string;
-    /** CAIP-2 style network identifier, e.g. "tempo:4217". */ network: string;
+    /** CAIP-2 style network identifier, e.g. "tempo:4217". */
+    network: string;
     /** Currency / token contract. */
     asset: string;
     /** Raw token-unit amount string. */
@@ -107,6 +109,7 @@ interface ProbeResult {
 interface L2Result {
     title?: string;
     description?: string;
+    version?: string;
     routes: L2Route[];
     source: 'openapi' | 'well-known/x402' | null;
 }
@@ -134,6 +137,11 @@ interface L3Result {
      * and returned a 402. Used by getWarningsForL3 to run full payment-required validation.
      */
     paymentRequiredBody?: unknown;
+    /**
+     * Raw WWW-Authenticate header value from the 402 response. Present when the endpoint
+     * was probed and returned a 402 with an MPP challenge. Used by getWarningsForMppHeader.
+     */
+    wwwAuthenticate?: string;
 }
 interface L4Result {
     guidance: string;
@@ -164,6 +172,7 @@ interface DiscoverOriginSchemaSuccess {
     info?: {
         title: string;
         description?: string;
+        version?: string;
     };
     /** Discovered endpoints with advisory pricing and auth metadata. */
     endpoints: L2Route[];
@@ -196,6 +205,12 @@ interface CheckEndpointOptions {
      *
      */
     sampleInputBody?: Record<string, unknown>;
+    /**
+     * When true, skips OpenAPI lookup and probes the live endpoint directly.
+     * Use this to retrieve actual PaymentOptions (realm, payTo, network, asset, amount)
+     * from the 402 response rather than static OpenAPI metadata.
+     */
+    probe?: boolean;
 }
 interface EndpointMethodAdvisory extends L3Result {
     method: HttpMethod;
@@ -351,8 +366,21 @@ declare const AUDIT_CODES: {
     readonly L3_INPUT_SCHEMA_MISSING: "L3_INPUT_SCHEMA_MISSING";
     readonly L3_AUTH_MODE_MISSING: "L3_AUTH_MODE_MISSING";
     readonly L3_PROTOCOLS_MISSING_ON_PAID: "L3_PROTOCOLS_MISSING_ON_PAID";
+    readonly L3_PAYMENT_OPTIONS_MISSING_ON_PAID: "L3_PAYMENT_OPTIONS_MISSING_ON_PAID";
     readonly L4_GUIDANCE_MISSING: "L4_GUIDANCE_MISSING";
     readonly L4_GUIDANCE_TOO_LONG: "L4_GUIDANCE_TOO_LONG";
+    readonly MPP_HEADER_MISSING: "MPP_HEADER_MISSING";
+    readonly MPP_NO_PAYMENT_CHALLENGES: "MPP_NO_PAYMENT_CHALLENGES";
+    readonly MPP_CHALLENGE_ID_MISSING: "MPP_CHALLENGE_ID_MISSING";
+    readonly MPP_CHALLENGE_METHOD_MISSING: "MPP_CHALLENGE_METHOD_MISSING";
+    readonly MPP_CHALLENGE_INTENT_MISSING: "MPP_CHALLENGE_INTENT_MISSING";
+    readonly MPP_CHALLENGE_REALM_MISSING: "MPP_CHALLENGE_REALM_MISSING";
+    readonly MPP_CHALLENGE_EXPIRES_MISSING: "MPP_CHALLENGE_EXPIRES_MISSING";
+    readonly MPP_CHALLENGE_REQUEST_MISSING: "MPP_CHALLENGE_REQUEST_MISSING";
+    readonly MPP_CHALLENGE_REQUEST_INVALID: "MPP_CHALLENGE_REQUEST_INVALID";
+    readonly MPP_CHALLENGE_ASSET_MISSING: "MPP_CHALLENGE_ASSET_MISSING";
+    readonly MPP_CHALLENGE_AMOUNT_MISSING: "MPP_CHALLENGE_AMOUNT_MISSING";
+    readonly MPP_CHALLENGE_RECIPIENT_MISSING: "MPP_CHALLENGE_RECIPIENT_MISSING";
 };
 type AuditCode = (typeof AUDIT_CODES)[keyof typeof AUDIT_CODES];
 
@@ -382,4 +410,18 @@ declare function getWarningsForL3(l3: L3Result | null): AuditWarning[];
 
 declare function getWarningsForL4(l4: L4Result | null): AuditWarning[];
 
-export { AUDIT_CODES, type AuditCode, type AuditSeverity, type AuditWarning, type AuthMode, type CheckEndpointNotFound, type CheckEndpointOptions, type CheckEndpointResult, type CheckEndpointSuccess, type DiscoverOriginSchemaNotFound, type DiscoverOriginSchemaOptions, type DiscoverOriginSchemaResult, type DiscoverOriginSchemaSuccess, type EndpointMethodAdvisory, GuidanceMode, type HttpMethod, type L2Result, type L2Route, type L3Result, type L4Result, type MetadataPreview, type MppPaymentOption, type NormalizedAccept, type NormalizedPaymentRequired, type OpenApiRoute, type OpenApiSource, type PaymentOption, type PricingMode, type ProbeResult, type TrustTier, VALIDATION_CODES, type ValidatePaymentRequiredDetailedResult, type ValidatePaymentRequiredOptions, type ValidationIssue, type ValidationSeverity, type ValidationStage, type ValidationSummary, type WellKnownRoute, type WellKnownSource, type X402PaymentOption, type X402V1PaymentOption, type X402V2PaymentOption, attachProbePayload, checkEndpointSchema, checkL2ForOpenAPI, checkL2ForWellknown, checkL4ForOpenAPI, checkL4ForWellknown, discoverOriginSchema, evaluateMetadataCompleteness, getL3, getL3ForOpenAPI, getL3ForProbe, getOpenAPI, getProbe, getWarningsFor402Body, getWarningsForL2, getWarningsForL3, getWarningsForL4, getWarningsForOpenAPI, getWarningsForWellKnown, getWellKnown, validatePaymentRequiredDetailed };
+/**
+ * Validates a raw WWW-Authenticate header value from an MPP 402 response and
+ * returns issues as AuditWarnings.
+ *
+ * Checks for:
+ * - Header presence
+ * - At least one Payment challenge
+ * - Required challenge parameters: id, method, intent, realm, expires, request
+ * - Valid base64url-encoded JSON in the request field
+ * - Required request fields: currency (asset), amount
+ * - Recommended request field: recipient (payTo)
+ */
+declare function getWarningsForMppHeader(wwwAuthenticate: string | null | undefined): AuditWarning[];
+
+export { AUDIT_CODES, type AuditCode, type AuditSeverity, type AuditWarning, type AuthMode, type CheckEndpointNotFound, type CheckEndpointOptions, type CheckEndpointResult, type CheckEndpointSuccess, type DiscoverOriginSchemaNotFound, type DiscoverOriginSchemaOptions, type DiscoverOriginSchemaResult, type DiscoverOriginSchemaSuccess, type EndpointMethodAdvisory, GuidanceMode, type HttpMethod, type L2Result, type L2Route, type L3Result, type L4Result, type MetadataPreview, type MppPaymentOption, type NormalizedAccept, type NormalizedPaymentRequired, type OpenApiRoute, type OpenApiSource, type PaymentOption, type PricingMode, type ProbeResult, type TrustTier, VALIDATION_CODES, type ValidatePaymentRequiredDetailedResult, type ValidatePaymentRequiredOptions, type ValidationIssue, type ValidationSeverity, type ValidationStage, type ValidationSummary, type WellKnownRoute, type WellKnownSource, type X402PaymentOption, type X402V1PaymentOption, type X402V2PaymentOption, attachProbePayload, checkEndpointSchema, checkL2ForOpenAPI, checkL2ForWellknown, checkL4ForOpenAPI, checkL4ForWellknown, discoverOriginSchema, evaluateMetadataCompleteness, getL3, getL3ForOpenAPI, getL3ForProbe, getOpenAPI, getProbe, getWarningsFor402Body, getWarningsForL2, getWarningsForL3, getWarningsForL4, getWarningsForMppHeader, getWarningsForOpenAPI, getWarningsForWellKnown, getWellKnown, validatePaymentRequiredDetailed };

package/dist/index.d.ts

@@ -8,12 +8,14 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTION
 
 interface MppPaymentOption {
     protocol: 'mpp';
-    /** Payment method identifier, e.g. "tempo" (Tempo protocol). */ paymentMethod: string;
+    /** Payment method identifier, e.g. "tempo" (Tempo protocol). */
+    paymentMethod: string;
     /** Payment intent type, e.g. "charge". */
     intent: string;
     /** Server protection realm. */
     realm: string;
-    /** CAIP-2 style network identifier, e.g. "tempo:4217". */ network: string;
+    /** CAIP-2 style network identifier, e.g. "tempo:4217". */
+    network: string;
     /** Currency / token contract. */
     asset: string;
     /** Raw token-unit amount string. */
@@ -107,6 +109,7 @@ interface ProbeResult {
 interface L2Result {
     title?: string;
     description?: string;
+    version?: string;
     routes: L2Route[];
     source: 'openapi' | 'well-known/x402' | null;
 }
@@ -134,6 +137,11 @@ interface L3Result {
      * and returned a 402. Used by getWarningsForL3 to run full payment-required validation.
      */
     paymentRequiredBody?: unknown;
+    /**
+     * Raw WWW-Authenticate header value from the 402 response. Present when the endpoint
+     * was probed and returned a 402 with an MPP challenge. Used by getWarningsForMppHeader.
+     */
+    wwwAuthenticate?: string;
 }
 interface L4Result {
     guidance: string;
@@ -164,6 +172,7 @@ interface DiscoverOriginSchemaSuccess {
     info?: {
         title: string;
         description?: string;
+        version?: string;
     };
     /** Discovered endpoints with advisory pricing and auth metadata. */
     endpoints: L2Route[];
@@ -196,6 +205,12 @@ interface CheckEndpointOptions {
      *
      */
     sampleInputBody?: Record<string, unknown>;
+    /**
+     * When true, skips OpenAPI lookup and probes the live endpoint directly.
+     * Use this to retrieve actual PaymentOptions (realm, payTo, network, asset, amount)
+     * from the 402 response rather than static OpenAPI metadata.
+     */
+    probe?: boolean;
 }
 interface EndpointMethodAdvisory extends L3Result {
     method: HttpMethod;
@@ -351,8 +366,21 @@ declare const AUDIT_CODES: {
     readonly L3_INPUT_SCHEMA_MISSING: "L3_INPUT_SCHEMA_MISSING";
     readonly L3_AUTH_MODE_MISSING: "L3_AUTH_MODE_MISSING";
     readonly L3_PROTOCOLS_MISSING_ON_PAID: "L3_PROTOCOLS_MISSING_ON_PAID";
+    readonly L3_PAYMENT_OPTIONS_MISSING_ON_PAID: "L3_PAYMENT_OPTIONS_MISSING_ON_PAID";
     readonly L4_GUIDANCE_MISSING: "L4_GUIDANCE_MISSING";
     readonly L4_GUIDANCE_TOO_LONG: "L4_GUIDANCE_TOO_LONG";
+    readonly MPP_HEADER_MISSING: "MPP_HEADER_MISSING";
+    readonly MPP_NO_PAYMENT_CHALLENGES: "MPP_NO_PAYMENT_CHALLENGES";
+    readonly MPP_CHALLENGE_ID_MISSING: "MPP_CHALLENGE_ID_MISSING";
+    readonly MPP_CHALLENGE_METHOD_MISSING: "MPP_CHALLENGE_METHOD_MISSING";
+    readonly MPP_CHALLENGE_INTENT_MISSING: "MPP_CHALLENGE_INTENT_MISSING";
+    readonly MPP_CHALLENGE_REALM_MISSING: "MPP_CHALLENGE_REALM_MISSING";
+    readonly MPP_CHALLENGE_EXPIRES_MISSING: "MPP_CHALLENGE_EXPIRES_MISSING";
+    readonly MPP_CHALLENGE_REQUEST_MISSING: "MPP_CHALLENGE_REQUEST_MISSING";
+    readonly MPP_CHALLENGE_REQUEST_INVALID: "MPP_CHALLENGE_REQUEST_INVALID";
+    readonly MPP_CHALLENGE_ASSET_MISSING: "MPP_CHALLENGE_ASSET_MISSING";
+    readonly MPP_CHALLENGE_AMOUNT_MISSING: "MPP_CHALLENGE_AMOUNT_MISSING";
+    readonly MPP_CHALLENGE_RECIPIENT_MISSING: "MPP_CHALLENGE_RECIPIENT_MISSING";
 };
 type AuditCode = (typeof AUDIT_CODES)[keyof typeof AUDIT_CODES];
 
@@ -382,4 +410,18 @@ declare function getWarningsForL3(l3: L3Result | null): AuditWarning[];
 
 declare function getWarningsForL4(l4: L4Result | null): AuditWarning[];
 
-export { AUDIT_CODES, type AuditCode, type AuditSeverity, type AuditWarning, type AuthMode, type CheckEndpointNotFound, type CheckEndpointOptions, type CheckEndpointResult, type CheckEndpointSuccess, type DiscoverOriginSchemaNotFound, type DiscoverOriginSchemaOptions, type DiscoverOriginSchemaResult, type DiscoverOriginSchemaSuccess, type EndpointMethodAdvisory, GuidanceMode, type HttpMethod, type L2Result, type L2Route, type L3Result, type L4Result, type MetadataPreview, type MppPaymentOption, type NormalizedAccept, type NormalizedPaymentRequired, type OpenApiRoute, type OpenApiSource, type PaymentOption, type PricingMode, type ProbeResult, type TrustTier, VALIDATION_CODES, type ValidatePaymentRequiredDetailedResult, type ValidatePaymentRequiredOptions, type ValidationIssue, type ValidationSeverity, type ValidationStage, type ValidationSummary, type WellKnownRoute, type WellKnownSource, type X402PaymentOption, type X402V1PaymentOption, type X402V2PaymentOption, attachProbePayload, checkEndpointSchema, checkL2ForOpenAPI, checkL2ForWellknown, checkL4ForOpenAPI, checkL4ForWellknown, discoverOriginSchema, evaluateMetadataCompleteness, getL3, getL3ForOpenAPI, getL3ForProbe, getOpenAPI, getProbe, getWarningsFor402Body, getWarningsForL2, getWarningsForL3, getWarningsForL4, getWarningsForOpenAPI, getWarningsForWellKnown, getWellKnown, validatePaymentRequiredDetailed };
+/**
+ * Validates a raw WWW-Authenticate header value from an MPP 402 response and
+ * returns issues as AuditWarnings.
+ *
+ * Checks for:
+ * - Header presence
+ * - At least one Payment challenge
+ * - Required challenge parameters: id, method, intent, realm, expires, request
+ * - Valid base64url-encoded JSON in the request field
+ * - Required request fields: currency (asset), amount
+ * - Recommended request field: recipient (payTo)
+ */
+declare function getWarningsForMppHeader(wwwAuthenticate: string | null | undefined): AuditWarning[];
+
+export { AUDIT_CODES, type AuditCode, type AuditSeverity, type AuditWarning, type AuthMode, type CheckEndpointNotFound, type CheckEndpointOptions, type CheckEndpointResult, type CheckEndpointSuccess, type DiscoverOriginSchemaNotFound, type DiscoverOriginSchemaOptions, type DiscoverOriginSchemaResult, type DiscoverOriginSchemaSuccess, type EndpointMethodAdvisory, GuidanceMode, type HttpMethod, type L2Result, type L2Route, type L3Result, type L4Result, type MetadataPreview, type MppPaymentOption, type NormalizedAccept, type NormalizedPaymentRequired, type OpenApiRoute, type OpenApiSource, type PaymentOption, type PricingMode, type ProbeResult, type TrustTier, VALIDATION_CODES, type ValidatePaymentRequiredDetailedResult, type ValidatePaymentRequiredOptions, type ValidationIssue, type ValidationSeverity, type ValidationStage, type ValidationSummary, type WellKnownRoute, type WellKnownSource, type X402PaymentOption, type X402V1PaymentOption, type X402V2PaymentOption, attachProbePayload, checkEndpointSchema, checkL2ForOpenAPI, checkL2ForWellknown, checkL4ForOpenAPI, checkL4ForWellknown, discoverOriginSchema, evaluateMetadataCompleteness, getL3, getL3ForOpenAPI, getL3ForProbe, getOpenAPI, getProbe, getWarningsFor402Body, getWarningsForL2, getWarningsForL3, getWarningsForL4, getWarningsForMppHeader, getWarningsForOpenAPI, getWarningsForWellKnown, getWellKnown, validatePaymentRequiredDetailed };