@agentcash/discovery 1.1.3 → 1.3.0

package/dist/index.cjs

@@ -44,15 +44,18 @@ __export(index_exports, {
   getL3: () => getL3,
   getL3ForOpenAPI: () => getL3ForOpenAPI,
   getL3ForProbe: () => getL3ForProbe,
+  getMppWellKnown: () => getMppWellKnown,
   getOpenAPI: () => getOpenAPI,
   getProbe: () => getProbe,
   getWarningsFor402Body: () => getWarningsFor402Body,
   getWarningsForL2: () => getWarningsForL2,
   getWarningsForL3: () => getWarningsForL3,
   getWarningsForL4: () => getWarningsForL4,
+  getWarningsForMppHeader: () => getWarningsForMppHeader,
   getWarningsForOpenAPI: () => getWarningsForOpenAPI,
   getWarningsForWellKnown: () => getWarningsForWellKnown,
   getWellKnown: () => getWellKnown,
+  getX402WellKnown: () => getX402WellKnown,
   validatePaymentRequiredDetailed: () => validatePaymentRequiredDetailed
 });
 module.exports = __toCommonJS(index_exports);
@@ -13895,7 +13898,8 @@ var WellKnownParsedSchema = external_exports.object({
   routes: external_exports.array(
     external_exports.object({
       path: external_exports.string(),
-      method: external_exports.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "TRACE"])
+      method: external_exports.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS", "TRACE"]),
+      price: external_exports.string().optional()
     })
   ),
   instructions: external_exports.string().optional()
@@ -13988,9 +13992,9 @@ function toAbsoluteUrl(origin, value) {
 
 // src/core/source/fetch.ts
 var import_neverthrow = require("neverthrow");
-function toFetchError(err) {
-  const cause = err instanceof DOMException && (err.name === "TimeoutError" || err.name === "AbortError") ? "timeout" : "network";
-  return { cause, message: String(err) };
+function toFetchError(err2) {
+  const cause = err2 instanceof DOMException && (err2.name === "TimeoutError" || err2.name === "AbortError") ? "timeout" : "network";
+  return { cause, message: String(err2) };
 }
 function fetchSafe(url2, init) {
   return import_neverthrow.ResultAsync.fromPromise(fetch(url2, init), toFetchError);
@@ -14056,6 +14060,9 @@ function getOpenAPI(origin, headers, signal, specificationOverrideUrl) {
 }
 
 // src/core/source/wellknown/index.ts
+var import_neverthrow5 = require("neverthrow");
+
+// src/core/source/wellknown/x402.ts
 var import_neverthrow3 = require("neverthrow");
 function toWellKnownParsed(origin, doc) {
   const routes = doc.resources.flatMap((entry) => {
@@ -14082,12 +14089,17 @@ async function parseBody2(response, origin, url2) {
     if (!doc.success) return null;
     const parsed = WellKnownParsedSchema.safeParse(toWellKnownParsed(origin, doc.data));
     if (!parsed.success) return null;
-    return { raw: payload, ...parsed.data, fetchedUrl: url2 };
+    return {
+      raw: payload,
+      ...parsed.data,
+      protocol: "x402",
+      fetchedUrl: url2
+    };
   } catch {
     return null;
   }
 }
-function getWellKnown(origin, headers, signal) {
+function getX402WellKnown(origin, headers, signal) {
   const url2 = `${origin}/.well-known/x402`;
   return fetchSafe(url2, {
     method: "GET",
@@ -14099,6 +14111,127 @@ function getWellKnown(origin, headers, signal) {
   });
 }
 
+// src/core/source/wellknown/mpp.ts
+var import_neverthrow4 = require("neverthrow");
+var MppEndpointSchema = external_exports.object({
+  method: external_exports.string(),
+  path: external_exports.string(),
+  description: external_exports.string().optional(),
+  payment: external_exports.object({
+    intent: external_exports.string().optional(),
+    method: external_exports.string().optional(),
+    amount: external_exports.string().optional(),
+    currency: external_exports.string().optional()
+  }).optional()
+});
+var MppWellKnownDocSchema = external_exports.object({
+  version: external_exports.number().optional(),
+  name: external_exports.string().optional(),
+  description: external_exports.string().optional(),
+  categories: external_exports.array(external_exports.string()).optional(),
+  methods: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
+  endpoints: external_exports.array(MppEndpointSchema).default([]),
+  docs: external_exports.object({
+    homepage: external_exports.string().optional(),
+    apiReference: external_exports.string().optional()
+  }).optional()
+});
+var MPP_DECIMALS = 6;
+function formatMppAmount(raw) {
+  if (!raw) return void 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return void 0;
+  return `$${(n / 10 ** MPP_DECIMALS).toFixed(MPP_DECIMALS)}`;
+}
+function toWellKnownParsed2(doc) {
+  const routes = doc.endpoints.flatMap((entry) => {
+    const method = parseMethod(entry.method);
+    if (!method) return [];
+    const path = normalizePath(entry.path);
+    if (!path) return [];
+    const price = formatMppAmount(entry.payment?.amount);
+    return [{ path, method, ...price ? { price } : {} }];
+  });
+  return {
+    routes,
+    ...doc.description ? { instructions: doc.description } : {}
+  };
+}
+async function parseBody3(response, url2) {
+  try {
+    const payload = await response.json();
+    const doc = MppWellKnownDocSchema.safeParse(payload);
+    if (!doc.success) return null;
+    const parsed = WellKnownParsedSchema.safeParse(toWellKnownParsed2(doc.data));
+    if (!parsed.success) return null;
+    return {
+      raw: payload,
+      ...parsed.data,
+      ...doc.data.name ? { title: doc.data.name } : {},
+      ...doc.data.description ? { description: doc.data.description } : {},
+      protocol: "mpp",
+      fetchedUrl: url2
+    };
+  } catch {
+    return null;
+  }
+}
+function getMppWellKnown(origin, headers, signal) {
+  const url2 = `${origin}/.well-known/mpp`;
+  return fetchSafe(url2, {
+    method: "GET",
+    headers: { Accept: "application/json", ...headers },
+    signal
+  }).andThen((response) => {
+    if (!response.ok) return (0, import_neverthrow4.okAsync)(null);
+    return import_neverthrow4.ResultAsync.fromSafePromise(parseBody3(response, url2));
+  });
+}
+
+// src/core/source/wellknown/index.ts
+function mergeError(a, b) {
+  return {
+    cause: a.cause === "network" || b.cause === "network" ? "network" : "timeout",
+    message: `x402: ${a.message} | mpp: ${b.message}`
+  };
+}
+function merge2(x402, mpp) {
+  const seen = /* @__PURE__ */ new Set();
+  const routes = [...x402.routes, ...mpp.routes].filter((r) => {
+    const key = `${r.method} ${r.path}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+  return {
+    raw: { ...mpp.raw, ...x402.raw },
+    routes,
+    protocol: "x402+mpp",
+    // Prefer x402 instructions; fall back to mpp
+    ...x402.instructions || mpp.instructions ? { instructions: x402.instructions ?? mpp.instructions } : {},
+    fetchedUrl: x402.fetchedUrl
+  };
+}
+function getWellKnown(origin, headers, signal) {
+  return new import_neverthrow5.ResultAsync(
+    Promise.all([
+      getX402WellKnown(origin, headers, signal),
+      getMppWellKnown(origin, headers, signal)
+    ]).then(([x402Result, mppResult]) => {
+      const x402 = x402Result.isOk() ? x402Result.value : null;
+      const mpp = mppResult.isOk() ? mppResult.value : null;
+      if (x402 && mpp) return (0, import_neverthrow5.ok)(merge2(x402, mpp));
+      if (x402) return (0, import_neverthrow5.ok)(x402);
+      if (mpp) return (0, import_neverthrow5.ok)(mpp);
+      if (x402Result.isErr() && mppResult.isErr())
+        return (0, import_neverthrow5.err)(mergeError(x402Result.error, mppResult.error));
+      if (x402Result.isErr()) return (0, import_neverthrow5.err)(x402Result.error);
+      if (mppResult.isErr()) return (0, import_neverthrow5.err)(mppResult.error);
+      return (0, import_neverthrow5.ok)(null);
+    })
+  );
+}
+
 // src/core/layers/l2.ts
 function formatPrice(pricing) {
   if (pricing.pricingMode === "fixed") return `$${pricing.price}`;
@@ -14124,15 +14257,27 @@ function checkL2ForOpenAPI(openApi) {
     source: "openapi"
   };
 }
+var WELL_KNOWN_PROTOCOLS = {
+  x402: ["x402"],
+  mpp: ["mpp"],
+  "x402+mpp": ["x402", "mpp"]
+};
 function checkL2ForWellknown(wellKnown) {
+  const protocols = WELL_KNOWN_PROTOCOLS[wellKnown.protocol];
   const routes = wellKnown.routes.map((route) => ({
     path: route.path,
     method: route.method,
     summary: `${route.method} ${route.path}`,
     authMode: "paid",
-    protocols: ["x402"]
+    protocols,
+    ...route.price ? { price: route.price } : {}
   }));
-  return { routes, source: "well-known/x402" };
+  return {
+    ...wellKnown.title ? { title: wellKnown.title } : {},
+    ...wellKnown.description ? { description: wellKnown.description } : {},
+    routes,
+    source: `well-known/${wellKnown.protocol}`
+  };
 }
 
 // src/core/layers/l4.ts
@@ -14144,7 +14289,7 @@ function checkL4ForOpenAPI(openApi) {
 }
 function checkL4ForWellknown(wellKnown) {
   if (wellKnown.instructions) {
-    return { guidance: wellKnown.instructions, source: "well-known/x402" };
+    return { guidance: wellKnown.instructions, source: `well-known/${wellKnown.protocol}` };
   }
   return null;
 }
@@ -14217,14 +14362,20 @@ async function discoverOriginSchema(options) {
   const base = {
     found: true,
     origin,
-    source: "well-known/x402",
+    source: l2.source,
+    ...l2.title ? {
+      info: {
+        title: l2.title,
+        ...l2.description ? { description: l2.description } : {}
+      }
+    } : {},
     endpoints: l2.routes
   };
   return withGuidance(base, l4, guidanceMode);
 }
 
 // src/core/source/probe/index.ts
-var import_neverthrow4 = require("neverthrow");
+var import_neverthrow6 = require("neverthrow");
 
 // src/core/protocols/x402/v1/schema.ts
 function extractSchemas(accepts) {
@@ -14674,8 +14825,8 @@ function probeMethod(url2, method, path, headers, signal, inputBody) {
     ...hasBody ? { body: JSON.stringify(inputBody) } : {},
     signal
   }).andThen((response) => {
-    if (!isUsableStatus(response.status)) return import_neverthrow4.ResultAsync.fromSafePromise(Promise.resolve(null));
-    return import_neverthrow4.ResultAsync.fromSafePromise(
+    if (!isUsableStatus(response.status)) return import_neverthrow6.ResultAsync.fromSafePromise(Promise.resolve(null));
+    return import_neverthrow6.ResultAsync.fromSafePromise(
       (async () => {
         let authHint = response.status === 402 ? "paid" : "unprotected";
         let paymentRequiredBody;
@@ -14706,7 +14857,7 @@ function probeMethod(url2, method, path, headers, signal, inputBody) {
 }
 function getProbe(url2, headers, signal, inputBody) {
   const path = normalizePath(new URL(url2).pathname || "/");
-  return import_neverthrow4.ResultAsync.fromSafePromise(
+  return import_neverthrow6.ResultAsync.fromSafePromise(
     Promise.all(
       [...HTTP_METHODS].map(
         (method) => probeMethod(url2, method, path, headers, signal, inputBody).match(
@@ -14719,6 +14870,20 @@ function getProbe(url2, headers, signal, inputBody) {
 }
 
 // src/core/protocols/mpp/index.ts
+var import_neverthrow7 = require("neverthrow");
+function parseBase64Json(encoded) {
+  return import_neverthrow7.Result.fromThrowable(
+    () => {
+      const decoded = typeof Buffer !== "undefined" ? Buffer.from(encoded, "base64").toString("utf8") : atob(encoded);
+      const parsed = JSON.parse(decoded);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("not an object");
+      }
+      return parsed;
+    },
+    (e) => e
+  )();
+}
 var TEMPO_DEFAULT_CHAIN_ID = 4217;
 function parseAuthParams(segment) {
   const params = {};
@@ -14741,14 +14906,9 @@ function extractPaymentOptions4(wwwAuthenticate) {
     const description = params["description"];
     const requestStr = params["request"];
     if (!paymentMethod || !intent || !realm || !requestStr) continue;
-    let request;
-    try {
-      const parsed = JSON.parse(requestStr);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-      request = parsed;
-    } catch {
-      continue;
-    }
+    const requestResult = parseBase64Json(requestStr);
+    if (requestResult.isErr()) continue;
+    const request = requestResult.value;
     const asset = typeof request["currency"] === "string" ? request["currency"] : void 0;
     const amountRaw = request["amount"];
     const amount = typeof amountRaw === "string" ? amountRaw : typeof amountRaw === "number" ? String(amountRaw) : void 0;
@@ -14930,7 +15090,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) {
@@ -15111,9 +15272,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
@@ -15202,6 +15377,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)) {
@@ -15331,17 +15657,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;
 }
 
@@ -15560,14 +15897,17 @@ function getWarningsForL4(l4) {
   getL3,
   getL3ForOpenAPI,
   getL3ForProbe,
+  getMppWellKnown,
   getOpenAPI,
   getProbe,
   getWarningsFor402Body,
   getWarningsForL2,
   getWarningsForL3,
   getWarningsForL4,
+  getWarningsForMppHeader,
   getWarningsForOpenAPI,
   getWarningsForWellKnown,
   getWellKnown,
+  getX402WellKnown,
   validatePaymentRequiredDetailed
 });

package/dist/index.d.cts

@@ -89,12 +89,18 @@ interface OpenApiRoute {
 interface WellKnownSource {
     raw: Record<string, unknown>;
     routes: WellKnownRoute[];
+    title?: string;
+    description?: string;
     instructions?: string;
     fetchedUrl: string;
+    /** Which well-known document(s) this source was built from. */
+    protocol: 'x402' | 'mpp' | 'x402+mpp';
 }
 interface WellKnownRoute {
     path: string;
     method: HttpMethod;
+    /** Raw price hint from the well-known document (e.g. MPP `payment.amount`). */
+    price?: string;
 }
 interface ProbeResult {
     path: string;
@@ -111,7 +117,7 @@ interface L2Result {
     description?: string;
     version?: string;
     routes: L2Route[];
-    source: 'openapi' | 'well-known/x402' | null;
+    source: 'openapi' | 'well-known/x402' | 'well-known/mpp' | 'well-known/x402+mpp' | null;
 }
 interface L2Route {
     path: string;
@@ -137,10 +143,15 @@ 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;
-    source: 'openapi' | 'well-known/x402';
+    source: 'openapi' | 'well-known/x402' | 'well-known/mpp' | 'well-known/x402+mpp';
 }
 
 declare enum GuidanceMode {
@@ -236,8 +247,21 @@ interface FetchError {
 
 declare function getOpenAPI(origin: string, headers?: Record<string, string>, signal?: AbortSignal, specificationOverrideUrl?: string): ResultAsync<OpenApiSource | null, FetchError>;
 
+/**
+ * Fetches both `/.well-known/x402` and `/.well-known/mpp` in parallel and merges results.
+ *
+ * In practice these are mutually exclusive, but if both exist their routes are combined
+ * (deduplicated by method+path). x402 wins on instruction/fetchedUrl conflicts.
+ *
+ * Individual leg failures are treated as "not found" for that leg so valid data from
+ * the other is never suppressed. Returns Err(FetchError) only when both legs hard-fail.
+ */
 declare function getWellKnown(origin: string, headers?: Record<string, string>, signal?: AbortSignal): ResultAsync<WellKnownSource | null, FetchError>;
 
+declare function getX402WellKnown(origin: string, headers?: Record<string, string>, signal?: AbortSignal): ResultAsync<WellKnownSource | null, FetchError>;
+
+declare function getMppWellKnown(origin: string, headers?: Record<string, string>, signal?: AbortSignal): ResultAsync<WellKnownSource | null, FetchError>;
+
 declare function getProbe(url: string, headers?: Record<string, string>, signal?: AbortSignal, inputBody?: Record<string, unknown>): ResultAsync<ProbeResult[], FetchError>;
 
 declare function checkL2ForOpenAPI(openApi: OpenApiSource): L2Result;
@@ -361,8 +385,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];
 
@@ -392,4 +429,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, getMppWellKnown, getOpenAPI, getProbe, getWarningsFor402Body, getWarningsForL2, getWarningsForL3, getWarningsForL4, getWarningsForMppHeader, getWarningsForOpenAPI, getWarningsForWellKnown, getWellKnown, getX402WellKnown, validatePaymentRequiredDetailed };