@kirkelabs/agent-readiness-scan 0.1.0 → 0.2.0

package/src/checks/04-mcp-exposure.js

@@ -1,104 +1,165 @@
-/**
- * check 04 — MCP exposure
- *
- * Model Context Protocol (MCP, Anthropic) is the agent-tooling layer
- * for the customs-house era. A brand that exposes an MCP server card
- * at /.well-known/mcp/server-card.json is declaring "agents may act on
- * me with these scoped tools, behind this auth flow."
- *
- * NSA's May-2026 guidance recommends OAuth-protected-resource metadata
- * + PKCE/S256; we check for both as positive signals.
- */
-
-export const meta = {
-  id: 'mcp-exposure',
-  title: 'MCP exposure',
-  weight: 7,
-  why: 'Model Context Protocol is how a brand publishes the tools an AI agent can call on its behalf. Without a public server card, agents have nothing to invoke — the brand is read-only to the AI economy.',
-};
-
-export function run({ wellKnown }) {
-  const findings = [];
-  const detail = { card: { found: false, valid: false }, oauth: { found: false, pkce: false } };
-
-  const card = wellKnown?.mcpServerCard;
-  if (!card || !card.found) {
-    findings.push({
-      level: 'fail',
-      msg: 'No `/.well-known/mcp/server-card.json` found. The brand exposes no agent-callable tools. AI agents can read but cannot act.',
-    });
-    return { score: 0, max: 7, findings, detail };
-  }
-
-  detail.card.found = true;
-  let parsed;
-  try {
-    parsed = JSON.parse(card.content);
-    detail.card.valid = typeof parsed === 'object' && parsed !== null;
-  } catch {
-    parsed = null;
-  }
-  if (!detail.card.valid) {
-    findings.push({
-      level: 'warn',
-      msg: 'MCP server card present but does not parse as JSON. Agents discovering this surface would skip it.',
-    });
-    return { score: 2, max: 7, findings, detail };
-  }
-
-  let score = 4;
-  findings.push({
-    level: 'pass',
-    msg: `MCP server card present and valid${parsed.name ? ` (\`${parsed.name}\`)` : ''}. Agents can discover the tool surface.`,
-  });
-  if (Array.isArray(parsed.tools) && parsed.tools.length > 0) {
-    findings.push({
-      level: 'pass',
-      msg: `${parsed.tools.length} tool(s) declared in the server card.`,
-    });
-  } else {
-    findings.push({
-      level: 'warn',
-      msg: 'Server card declares no `tools[]`. The card exists but has no callable surface for agents.',
-    });
-    score = 3;
-  }
-
-  // OAuth-protected-resource metadata (per NSA May-2026 guidance).
-  const oauth = wellKnown?.oauthProtectedResource;
-  if (oauth && oauth.found) {
-    detail.oauth.found = true;
-    score += 2;
-    findings.push({
-      level: 'pass',
-      msg: '`/.well-known/oauth-protected-resource` discoverable — meets NSA May-2026 trust-boundary recommendation.',
-    });
-    try {
-      const meta = JSON.parse(oauth.content);
-      const auth = wellKnown?.oauthAuthorizationServer;
-      if (auth && auth.found) {
-        const authMeta = JSON.parse(auth.content);
-        const methods = authMeta.code_challenge_methods_supported || [];
-        if (Array.isArray(methods) && methods.includes('S256')) {
-          detail.oauth.pkce = true;
-          score += 1;
-          findings.push({
-            level: 'pass',
-            msg: 'OAuth authorization server declares PKCE (S256) — scoped auth posture as recommended.',
-          });
-        }
-      }
-      // Suppress unused-var lint for `meta` if minimal.
-      void meta;
-    } catch {
-      // ignore parse errors; partial credit already awarded.
-    }
-  } else {
-    findings.push({
-      level: 'warn',
-      msg: 'No `/.well-known/oauth-protected-resource` metadata. NSA guidance recommends scoped OAuth gating before tool-call forwarding.',
-    });
-  }
-
-  return { score: Math.min(score, 7), max: 7, findings, detail };
-}
+/**
+ * check 04 — MCP exposure
+ *
+ * Model Context Protocol (MCP, Anthropic) is the agent-tooling layer
+ * for the customs-house era. A brand that exposes an MCP server card
+ * at /.well-known/mcp/server-card.json is declaring "agents may act on
+ * me with these scoped tools, behind this auth flow."
+ *
+ * NSA's May-2026 guidance recommends OAuth-protected-resource metadata
+ * + PKCE/S256; we check for both as positive signals.
+ *
+ * Scoped auth is scored standards-neutrally: a card can declare its
+ * trust boundary via EITHER OAuth-protected-resource (+PKCE) OR an Open
+ * Agent Access policy guard (+enforced policy). The two paths are
+ * mutually-reinforcing but capped — neither is privileged and the OAA
+ * path cannot push the dimension above the same ceiling OAuth reaches.
+ *
+ * Disclosure: Open Agent Access (OAA) is implemented by Kirke Labs, the
+ * author of this scanner. It is recognized here as one of several live
+ * scoped-auth postures, held to the same evidentiary bar as OAuth: a
+ * real, parseable artifact (an `authorization.model` declaration, plus a
+ * policy that genuinely requires an agent passport and gates calls).
+ */
+
+export const meta = {
+  id: 'mcp-exposure',
+  title: 'MCP exposure',
+  weight: 7,
+  why: 'Model Context Protocol is how a brand publishes the tools an AI agent can call on its behalf. Without a public server card, agents have nothing to invoke — the brand is read-only to the AI economy.',
+};
+
+export function run({ wellKnown }) {
+  const findings = [];
+  const detail = {
+    card: { found: false, valid: false },
+    oauth: { found: false, pkce: false },
+    oaaGuard: { model: false, enforced: false },
+  };
+
+  const card = wellKnown?.mcpServerCard;
+  if (!card || !card.found) {
+    findings.push({
+      level: 'fail',
+      msg: 'No `/.well-known/mcp/server-card.json` found. The brand exposes no agent-callable tools. AI agents can read but cannot act.',
+    });
+    return { score: 0, max: 7, findings, detail };
+  }
+
+  detail.card.found = true;
+  let parsed;
+  try {
+    parsed = JSON.parse(card.content);
+    detail.card.valid = typeof parsed === 'object' && parsed !== null;
+  } catch {
+    parsed = null;
+  }
+  if (!detail.card.valid) {
+    findings.push({
+      level: 'warn',
+      msg: 'MCP server card present but does not parse as JSON. Agents discovering this surface would skip it.',
+    });
+    return { score: 2, max: 7, findings, detail };
+  }
+
+  let score = 4;
+  findings.push({
+    level: 'pass',
+    msg: `MCP server card present and valid${parsed.name ? ` (\`${parsed.name}\`)` : ''}. Agents can discover the tool surface.`,
+  });
+  if (Array.isArray(parsed.tools) && parsed.tools.length > 0) {
+    findings.push({
+      level: 'pass',
+      msg: `${parsed.tools.length} tool(s) declared in the server card.`,
+    });
+  } else {
+    findings.push({
+      level: 'warn',
+      msg: 'Server card declares no `tools[]`. The card exists but has no callable surface for agents.',
+    });
+    score = 3;
+  }
+
+  // --- Scoped-auth posture: OAuth path OR Open Agent Access path. ---
+
+  // OAuth-protected-resource metadata (per NSA May-2026 guidance).
+  const oauth = wellKnown?.oauthProtectedResource;
+  if (oauth && oauth.found) {
+    detail.oauth.found = true;
+    score += 2;
+    findings.push({
+      level: 'pass',
+      msg: '`/.well-known/oauth-protected-resource` discoverable — meets NSA May-2026 trust-boundary recommendation.',
+    });
+    try {
+      const meta = JSON.parse(oauth.content);
+      const auth = wellKnown?.oauthAuthorizationServer;
+      if (auth && auth.found) {
+        const authMeta = JSON.parse(auth.content);
+        const methods = authMeta.code_challenge_methods_supported || [];
+        if (Array.isArray(methods) && methods.includes('S256')) {
+          detail.oauth.pkce = true;
+          score += 1;
+          findings.push({
+            level: 'pass',
+            msg: 'OAuth authorization server declares PKCE (S256) — scoped auth posture as recommended.',
+          });
+        }
+      }
+      // Suppress unused-var lint for `meta` if minimal.
+      void meta;
+    } catch {
+      // ignore parse errors; partial credit already awarded.
+    }
+  }
+
+  // Open Agent Access guard: per-tool authorization via a published policy.
+  // Functionally parallel to OAuth-protected-resource as a trust boundary.
+  const authz = parsed.authorization;
+  const hasOaaModel =
+    authz?.model === 'open-agent-access' || typeof authz?.policy === 'string';
+  if (hasOaaModel) {
+    detail.oaaGuard.model = true;
+    score += 2;
+    findings.push({
+      level: 'pass',
+      msg: 'Server card declares an Open Agent Access authorization model (scoped per-tool policy) — a trust-boundary posture parallel to OAuth-protected-resource.',
+    });
+    // Confirm the referenced policy genuinely enforces per-call gating:
+    // an agent passport is required AND at least one deny/charge decision.
+    const oaa = wellKnown?.agentAccess;
+    if (oaa && oaa.found) {
+      try {
+        const policy = JSON.parse(oaa.content);
+        const rules = Array.isArray(policy?.rules) ? policy.rules : [];
+        const gated = rules.some(
+          (r) => r?.decision === 'deny' || r?.decision === 'charge',
+        );
+        if (policy?.defaults?.requireAgentIdentity === true && gated) {
+          detail.oaaGuard.enforced = true;
+          score += 1;
+          findings.push({
+            level: 'pass',
+            msg: 'Referenced Open Agent Access policy enforces per-call gating (agent passport required + deny/charge decisioning).',
+          });
+        } else {
+          findings.push({
+            level: 'warn',
+            msg: 'Open Agent Access policy present but does not enforce per-call gating (needs `defaults.requireAgentIdentity: true` and a deny/charge rule).',
+          });
+        }
+      } catch {
+        // ignore parse errors; partial credit already awarded for the declared model.
+      }
+    }
+  }
+
+  if (!detail.oauth.found && !detail.oaaGuard.model) {
+    findings.push({
+      level: 'warn',
+      msg: 'No scoped-auth posture declared. Add `/.well-known/oauth-protected-resource` (OAuth, per NSA guidance) or an `authorization.model: "open-agent-access"` policy before tool-call forwarding.',
+    });
+  }
+
+  return { score: Math.min(score, 7), max: 7, findings, detail };
+}

package/src/checks/05-agentic-commerce.js

@@ -1,85 +1,152 @@
-/**
- * check 05 — Agentic-commerce manifests
- *
- * The customs declaration for commerce. The two live specs as of mid-2026:
- *   - Agentic Commerce Protocol (OpenAI/Stripe): /.well-known/acp/manifest.json
- *   - Google Universal Cart Protocol (UCP):       /.well-known/ucp
- *
- * Either one is a credible declaration that an agent can transact on
- * the brand's behalf. Both is full coverage.
- */
-
-export const meta = {
-  id: 'agentic-commerce',
-  title: 'Agentic-commerce manifests',
-  weight: 7,
-  why: 'ACP (OpenAI/Stripe) and UCP (Google) are the two live 2026 protocols for agent-initiated checkout. Without a manifest at the canonical .well-known path, conversational-commerce surfaces have no place to bind to.',
-};
-
-export function run({ wellKnown }) {
-  const findings = [];
-  const detail = { acp: { found: false, valid: false }, ucp: { found: false, valid: false } };
-
-  // ACP
-  const acp = wellKnown?.acpManifest;
-  if (acp && acp.found) {
-    detail.acp.found = true;
-    try {
-      const parsed = JSON.parse(acp.content);
-      detail.acp.valid = typeof parsed === 'object' && parsed !== null;
-      if (detail.acp.valid) {
-        findings.push({
-          level: 'pass',
-          msg: `Agentic Commerce Protocol manifest present at \`/.well-known/acp/manifest.json\`${parsed.version ? ` (version \`${parsed.version}\`)` : ''}.`,
-        });
-      } else {
-        findings.push({ level: 'warn', msg: 'ACP manifest present but invalid JSON shape.' });
-      }
-    } catch {
-      findings.push({ level: 'warn', msg: 'ACP manifest present but does not parse as JSON.' });
-    }
-  }
-
-  // UCP
-  const ucp = wellKnown?.ucp;
-  if (ucp && ucp.found) {
-    detail.ucp.found = true;
-    try {
-      const parsed = JSON.parse(ucp.content);
-      detail.ucp.valid = typeof parsed === 'object' && parsed !== null;
-      if (detail.ucp.valid) {
-        findings.push({
-          level: 'pass',
-          msg: `Google Universal Cart manifest present at \`/.well-known/ucp\`${parsed.version ? ` (version \`${parsed.version}\`)` : ''}.`,
-        });
-      } else {
-        findings.push({ level: 'warn', msg: 'UCP manifest present but invalid JSON shape.' });
-      }
-    } catch {
-      findings.push({ level: 'warn', msg: 'UCP manifest present but does not parse as JSON.' });
-    }
-  }
-
-  let score;
-  if (detail.acp.valid && detail.ucp.valid) {
-    score = 7;
-    findings.push({
-      level: 'pass',
-      msg: 'Both ACP and UCP manifests declared. Cross-platform agent commerce is wired.',
-    });
-  } else if (detail.acp.valid || detail.ucp.valid) {
-    score = 5;
-    findings.push({
-      level: 'warn',
-      msg: 'One of the two live agentic-commerce protocols declared. Consider adding the other to widen agent-marketplace coverage.',
-    });
-  } else {
-    score = 0;
-    findings.push({
-      level: 'fail',
-      msg: 'Neither `/.well-known/acp/manifest.json` (OpenAI/Stripe) nor `/.well-known/ucp` (Google) present. The site cannot be transacted on by an AI agent.',
-    });
-  }
-
-  return { score, max: 7, findings, detail };
-}
+/**
+ * check 05 — Agentic-commerce manifests
+ *
+ * The customs declaration for commerce. The live, interoperable specs as
+ * of mid-2026, scored as equal-weight alternatives:
+ *   - Agentic Commerce Protocol (OpenAI/Stripe): /.well-known/acp/manifest.json
+ *   - Google Universal Cart Protocol (UCP):       /.well-known/ucp
+ *   - Open Agent Access + x402 (on Algorand):     /.well-known/agent-access.json
+ *
+ * Any one is a credible declaration that an agent can transact on the
+ * brand's behalf; more than one is wider coverage. The three are treated
+ * as standards-neutral alternatives — no protocol is privileged and the
+ * scoring ladder is unchanged.
+ *
+ * Disclosure: Open Agent Access (OAA) is implemented by Kirke Labs, the
+ * author of this scanner. It is recognized here as ONE of several live
+ * standards, held to the same evidentiary bar as ACP and UCP: a real,
+ * parseable artifact at a canonical path that actually advertises a
+ * transactable capability (an x402 `charge` rule). Detection is additive;
+ * it does not raise the weight or reduce credit for ACP/UCP.
+ */
+
+export const meta = {
+  id: 'agentic-commerce',
+  title: 'Agentic-commerce manifests',
+  weight: 7,
+  why: 'ACP (OpenAI/Stripe), UCP (Google), and Open Agent Access + x402 (Algorand) are live 2026 protocols for agent-initiated checkout. Without a manifest at a canonical .well-known path, conversational-commerce surfaces have no place to bind to.',
+};
+
+export function run({ wellKnown }) {
+  const findings = [];
+  const detail = {
+    acp: { found: false, valid: false },
+    ucp: { found: false, valid: false },
+    oaaX402: { found: false, valid: false },
+  };
+
+  // ACP (OpenAI/Stripe)
+  const acp = wellKnown?.acpManifest;
+  if (acp && acp.found) {
+    detail.acp.found = true;
+    try {
+      const parsed = JSON.parse(acp.content);
+      detail.acp.valid = typeof parsed === 'object' && parsed !== null;
+      if (detail.acp.valid) {
+        findings.push({
+          level: 'pass',
+          msg: `Agentic Commerce Protocol manifest present at \`/.well-known/acp/manifest.json\`${parsed.version ? ` (version \`${parsed.version}\`)` : ''}.`,
+        });
+      } else {
+        findings.push({
+          level: 'warn',
+          msg: 'ACP manifest present but invalid JSON shape.',
+        });
+      }
+    } catch {
+      findings.push({
+        level: 'warn',
+        msg: 'ACP manifest present but does not parse as JSON.',
+      });
+    }
+  }
+
+  // UCP (Google)
+  const ucp = wellKnown?.ucp;
+  if (ucp && ucp.found) {
+    detail.ucp.found = true;
+    try {
+      const parsed = JSON.parse(ucp.content);
+      detail.ucp.valid = typeof parsed === 'object' && parsed !== null;
+      if (detail.ucp.valid) {
+        findings.push({
+          level: 'pass',
+          msg: `Google Universal Cart manifest present at \`/.well-known/ucp\`${parsed.version ? ` (version \`${parsed.version}\`)` : ''}.`,
+        });
+      } else {
+        findings.push({
+          level: 'warn',
+          msg: 'UCP manifest present but invalid JSON shape.',
+        });
+      }
+    } catch {
+      findings.push({
+        level: 'warn',
+        msg: 'UCP manifest present but does not parse as JSON.',
+      });
+    }
+  }
+
+  // Open Agent Access + x402 (Algorand). Counts only when the policy
+  // advertises a transactable capability: a `charge` rule carrying an
+  // x402 payment object. payment.network / payment.settlement corroborate.
+  const oaa = wellKnown?.agentAccess;
+  if (oaa && oaa.found) {
+    detail.oaaX402.found = true;
+    try {
+      const parsed = JSON.parse(oaa.content);
+      const rules = Array.isArray(parsed?.rules) ? parsed.rules : [];
+      const chargeRule = rules.find(
+        (r) => r?.decision === 'charge' && r?.payment?.type === 'x402',
+      );
+      detail.oaaX402.valid = Boolean(chargeRule);
+      if (detail.oaaX402.valid) {
+        const network =
+          chargeRule?.payment?.network || chargeRule?.payment?.settlement || 'Algorand';
+        findings.push({
+          level: 'pass',
+          msg: `Open Agent Access policy with x402 payment terms present at \`/.well-known/agent-access.json\` — agent-initiated settlement on ${network}.`,
+        });
+      } else {
+        findings.push({
+          level: 'warn',
+          msg: 'Open Agent Access policy present but declares no x402 `charge` rule — not yet a transactable commerce signal.',
+        });
+      }
+    } catch {
+      findings.push({
+        level: 'warn',
+        msg: 'Open Agent Access policy present but does not parse as JSON.',
+      });
+    }
+  }
+
+  // Score on the count of DISTINCT valid declarations among {acp, ucp, oaaX402}.
+  // Ladder unchanged: >=2 -> 7 ; exactly 1 -> 5 ; 0 -> 0.
+  const validCount = [detail.acp.valid, detail.ucp.valid, detail.oaaX402.valid].filter(
+    Boolean,
+  ).length;
+
+  let score;
+  if (validCount >= 2) {
+    score = 7;
+    findings.push({
+      level: 'pass',
+      msg: 'Multiple agentic-commerce declarations present — cross-platform agent commerce is wired.',
+    });
+  } else if (validCount === 1) {
+    score = 5;
+    findings.push({
+      level: 'warn',
+      msg: 'One of the live agentic-commerce protocols declared (ACP, UCP, or Open Agent Access + x402). Consider adding another to widen agent-marketplace coverage.',
+    });
+  } else {
+    score = 0;
+    findings.push({
+      level: 'fail',
+      msg: 'None of `/.well-known/acp/manifest.json` (OpenAI/Stripe), `/.well-known/ucp` (Google), or `/.well-known/agent-access.json` (Open Agent Access + x402) present. The site cannot be transacted on by an AI agent.',
+    });
+  }
+
+  return { score, max: 7, findings, detail };
+}