ax-audit 3.6.0 → 4.0.0

package/dist/checks/agent-card.js

@@ -0,0 +1,352 @@
+import { A2A_MEDIA_TYPE, AGENT_CARD_REQUIRED_V03, AGENT_CARD_REQUIRED_V1, A2A_PROTOCOL_BINDINGS, } from '../constants.js';
+import { guideUrl } from '../guide-urls.js';
+import { buildResult, checkContentType, isHtmlDocument, notApplicable } from './utils.js';
+import { hasAgentSurface } from './surface.js';
+import { WELL_KNOWN, standingNote } from './well-known.js';
+/**
+ * "agent-card" — the A2A (Agent2Agent) Agent Card.
+ *
+ * Two things changed since this check was written, and both matter:
+ *
+ * 1. **The path moved.** A2A v0.3.0 (2025-07-30) relocated the card from
+ *    `/.well-known/agent.json` to `/.well-known/agent-card.json`, which is now
+ *    an IANA-registered well-known URI. A site serving only the old path is
+ *    invisible to a current client.
+ *
+ * 2. **The shape changed.** A2A 1.0 (2026-03-12, breaking) folded the
+ *    top-level `url`, `protocolVersion`, `preferredTransport` and
+ *    `additionalInterfaces` fields into a single `supportedInterfaces[]` array,
+ *    and renamed `supportsAuthenticatedExtendedCard` to
+ *    `capabilities.extendedAgentCard`. Most deployed cards are still 0.3-shaped.
+ *
+ * Validating a 1.0 card against 0.3 rules (or the reverse) produces nonsense,
+ * so the check detects which generation a card belongs to from its own
+ * structure and applies the matching rules. `authentication`, dropped back in
+ * 0.2.x in favour of `securitySchemes`, is flagged wherever it appears.
+ *
+ * Spec: https://a2a-protocol.org/latest/specification/
+ * Normative field list: specification/a2a.proto in github.com/a2aproject/A2A
+ */
+export const meta = {
+    id: 'agent-card',
+    name: 'Agent Card (A2A)',
+    description: 'Checks the A2A Agent Card at /.well-known/agent-card.json',
+    category: 'protocols',
+    aliases: ['agent-json'],
+};
+const CANONICAL_PATH = '/.well-known/agent-card.json';
+const LEGACY_PATH = '/.well-known/agent.json';
+/**
+ * Detect the card generation from its own structure rather than from a version
+ * field, because 0.3 cards state `protocolVersion` at the top level and 1.0
+ * cards state it per interface.
+ */
+export function detectGeneration(data) {
+    if (Array.isArray(data.supportedInterfaces))
+        return 'v1';
+    if (typeof data.url === 'string' || typeof data.protocolVersion === 'string')
+        return 'v0.3';
+    return 'unknown';
+}
+/**
+ * Try the registered path first, then the pre-0.3 one. An HTML response counts
+ * as absent: an SPA catch-all returns its index shell for every unknown path,
+ * and reporting that as a malformed card would send an operator looking for a
+ * bug in a file they never wrote.
+ */
+async function locateCard(ctx) {
+    for (const path of [CANONICAL_PATH, LEGACY_PATH]) {
+        const res = await ctx.fetch(`${ctx.url}${path}`);
+        if (res.ok && res.body.trim().length > 0 && !isHtmlDocument(res.body))
+            return { res, path };
+    }
+    return null;
+}
+export default async function check(ctx) {
+    const start = performance.now();
+    const findings = [];
+    let score = 100;
+    const found = await locateCard(ctx);
+    if (found === null) {
+        // An Agent Card describes capabilities another agent can invoke. Most sites
+        // have none, and asking a restaurant to publish one is noise — so the check
+        // only applies where the site is already agent-facing.
+        const surface = await hasAgentSurface(ctx);
+        if (!surface.found) {
+            findings.push({
+                status: 'pass',
+                message: 'No agent-facing surface — an Agent Card does not apply to this site',
+                detail: 'No API, MCP server or existing card was found. An Agent Card advertises capabilities another agent can ' +
+                    'invoke; a site that offers none has nothing to put in it. Run with --profile agent to audit as though it did.',
+            });
+            return notApplicable(meta, findings, start);
+        }
+        findings.push({
+            status: 'fail',
+            message: `${CANONICAL_PATH} not found`,
+            detail: `Site is agent-facing (${surface.reason}). Also tried the pre-0.3 path ${LEGACY_PATH}. ${standingNote(CANONICAL_PATH) ?? ''}`.trim(),
+            hint: 'This site offers something an agent could call, but nothing tells an agent what. Publish an A2A Agent Card ' +
+                'at /.well-known/agent-card.json. A minimal 1.0 card needs name, description, version, capabilities, ' +
+                `supportedInterfaces, defaultInputModes, defaultOutputModes and skills. Spec: ${WELL_KNOWN[CANONICAL_PATH].specUrl}`,
+            learnMoreUrl: guideUrl(meta.id, 'not-found'),
+        });
+        return buildResult(meta, 0, findings, start);
+    }
+    const { res, path } = found;
+    if (path === LEGACY_PATH) {
+        findings.push({
+            status: 'warn',
+            message: `Agent Card served only from the pre-0.3 path ${LEGACY_PATH}`,
+            detail: standingNote(LEGACY_PATH),
+            hint: 'A2A moved the card to /.well-known/agent-card.json in v0.3.0 (2025-07-30), and that path is the one ' +
+                'registered with IANA. Serve the card there; keep the old path as a redirect if existing clients depend on it.',
+            learnMoreUrl: guideUrl(meta.id, 'legacy-path'),
+        });
+    }
+    else {
+        findings.push({ status: 'pass', message: `${CANONICAL_PATH} exists` });
+    }
+    const ctFinding = checkContentType(res, ['application/json', A2A_MEDIA_TYPE], {
+        checkId: meta.id,
+        resourceLabel: path,
+        anchor: 'wrong-content-type',
+    });
+    if (ctFinding) {
+        findings.push(ctFinding);
+        score -= 5;
+    }
+    let data;
+    try {
+        data = JSON.parse(res.body);
+    }
+    catch {
+        findings.push({
+            status: 'fail',
+            message: 'Invalid JSON',
+            hint: 'Fix the JSON syntax in your Agent Card. Validate it with a JSON linter.',
+            learnMoreUrl: guideUrl(meta.id, 'invalid-json'),
+        });
+        return buildResult(meta, 10, findings, start);
+    }
+    findings.push({ status: 'pass', message: 'Valid JSON' });
+    const generation = detectGeneration(data);
+    score = validateGeneration(generation, data, ctx, findings, score);
+    score = validateCommon(data, findings, score);
+    return buildResult(meta, score, findings, start);
+}
+/** Apply the field rules of whichever spec generation this card was written against. */
+function validateGeneration(generation, data, ctx, findings, score) {
+    if (generation === 'unknown') {
+        findings.push({
+            status: 'fail',
+            message: 'Card shape matches neither A2A 1.0 nor 0.3',
+            detail: 'Expected either supportedInterfaces[] (1.0) or a top-level url + protocolVersion (0.3).',
+            hint: 'Rebuild the card against the current specification. A 1.0 card declares every endpoint inside supportedInterfaces[].',
+            learnMoreUrl: guideUrl(meta.id, 'unknown-generation'),
+        });
+        return score - 30;
+    }
+    const required = generation === 'v1' ? AGENT_CARD_REQUIRED_V1 : AGENT_CARD_REQUIRED_V03;
+    findings.push({
+        status: 'pass',
+        message: generation === 'v1' ? 'Card follows A2A 1.0 (supportedInterfaces)' : 'Card follows A2A 0.3 (top-level url)',
+        ...(generation === 'v0.3'
+            ? {
+                detail: 'A2A 1.0 (2026-03-12) replaced the top-level url, protocolVersion, preferredTransport and ' +
+                    'additionalInterfaces fields with a single supportedInterfaces[] array.',
+            }
+            : {}),
+    });
+    for (const field of required) {
+        if (data[field] !== undefined && data[field] !== null) {
+            findings.push({ status: 'pass', message: `Required field "${field}" present` });
+        }
+        else {
+            findings.push({
+                status: 'fail',
+                message: `Required field "${field}" missing`,
+                hint: `Add "${field}" to your Agent Card. A2A ${generation === 'v1' ? '1.0' : '0.3'} requires it.`,
+                learnMoreUrl: guideUrl(meta.id, 'missing-field'),
+            });
+            score -= 15;
+        }
+    }
+    return generation === 'v1'
+        ? validateInterfaces(data, ctx, findings, score)
+        : validateLegacyUrl(data, ctx, findings, score);
+}
+/** A2A 1.0: every entry in `supportedInterfaces[]` needs url, binding and version. */
+function validateInterfaces(data, ctx, findings, score) {
+    const interfaces = Array.isArray(data.supportedInterfaces)
+        ? data.supportedInterfaces
+        : [];
+    if (interfaces.length === 0) {
+        findings.push({
+            status: 'fail',
+            message: 'supportedInterfaces[] is empty',
+            hint: 'Declare at least one interface: { "url": "https://…", "protocolBinding": "JSONRPC", "protocolVersion": "1.0" }.',
+            learnMoreUrl: guideUrl(meta.id, 'empty-interfaces'),
+        });
+        return score - 15;
+    }
+    const incomplete = interfaces.filter((i) => !i.url || !i.protocolBinding || !i.protocolVersion);
+    if (incomplete.length > 0) {
+        findings.push({
+            status: 'warn',
+            message: `${incomplete.length}/${interfaces.length} interface(s) missing url, protocolBinding or protocolVersion`,
+            hint: 'Each entry in supportedInterfaces[] must declare all three so a client knows where to connect and how to speak.',
+            learnMoreUrl: guideUrl(meta.id, 'incomplete-interface'),
+        });
+        score -= 10;
+    }
+    else {
+        findings.push({ status: 'pass', message: `${interfaces.length} interface(s) fully declared` });
+    }
+    const badBinding = interfaces
+        .map((i) => String(i.protocolBinding ?? ''))
+        .filter((b) => b !== '' && !A2A_PROTOCOL_BINDINGS.includes(b));
+    if (badBinding.length > 0) {
+        findings.push({
+            status: 'warn',
+            message: 'Interface with an unrecognised protocolBinding',
+            detail: badBinding.join(', '),
+            hint: `A2A 1.0 defines: ${A2A_PROTOCOL_BINDINGS.join(', ')}.`,
+            learnMoreUrl: guideUrl(meta.id, 'unknown-binding'),
+        });
+        score -= 5;
+    }
+    const offOrigin = interfaces
+        .map((i) => String(i.url ?? ''))
+        .filter((u) => u !== '' && sameHost(u, ctx.url) === false);
+    if (offOrigin.length > 0) {
+        findings.push({
+            status: 'warn',
+            message: `${offOrigin.length} interface URL(s) point to a different origin`,
+            detail: offOrigin.join(', '),
+            hint: 'Interfaces on another origin can be intentional, but agents treat the card as authoritative for this site. Confirm the endpoints are yours.',
+            learnMoreUrl: guideUrl(meta.id, 'url-mismatch'),
+        });
+        score -= 5;
+    }
+    return score;
+}
+/** A2A 0.3: the single top-level `url` should be absolute and on this origin. */
+function validateLegacyUrl(data, ctx, findings, score) {
+    if (typeof data.url !== 'string' || data.url.length === 0)
+        return score;
+    const sameOrigin = sameHost(data.url, ctx.url);
+    if (sameOrigin === false) {
+        findings.push({
+            status: 'warn',
+            message: `Agent Card "url" points to a different origin: ${data.url}`,
+            hint: 'The url field should match the audited site origin. Pointing it elsewhere can confuse agents about the canonical agent endpoint.',
+            learnMoreUrl: guideUrl(meta.id, 'url-mismatch'),
+        });
+        score -= 5;
+    }
+    else if (sameOrigin === null) {
+        findings.push({
+            status: 'warn',
+            message: `Agent Card "url" is not a valid absolute URL: ${data.url}`,
+            hint: 'Provide an absolute https:// URL for the url field.',
+            learnMoreUrl: guideUrl(meta.id, 'url-invalid'),
+        });
+        score -= 5;
+    }
+    return score;
+}
+/** Rules that hold across both generations. */
+function validateCommon(data, findings, score) {
+    if (Array.isArray(data.skills) && data.skills.length > 0) {
+        const skills = data.skills;
+        findings.push({ status: 'pass', message: `${skills.length} skill(s) defined` });
+        const incomplete = skills.filter((s) => !s.id || !s.description);
+        if (incomplete.length === 0) {
+            findings.push({ status: 'pass', message: 'All skills have id + description' });
+        }
+        else {
+            findings.push({
+                status: 'warn',
+                message: `${incomplete.length}/${skills.length} skill(s) missing id or description`,
+                hint: 'Each entry in skills[] should include both an id and a description so agents can address it and reason about its purpose.',
+                learnMoreUrl: guideUrl(meta.id, 'incomplete-skills'),
+            });
+            score -= 5;
+        }
+    }
+    else if (Array.isArray(data.skills)) {
+        findings.push({
+            status: 'warn',
+            message: 'Skills array is empty',
+            hint: 'Add at least one skill to the skills array describing what your agent can do.',
+            learnMoreUrl: guideUrl(meta.id, 'empty-skills'),
+        });
+        score -= 10;
+    }
+    // `authentication` was replaced by `securitySchemes` in A2A 0.2.x. A card
+    // still carrying it is describing its auth to nobody.
+    if (data.authentication !== undefined) {
+        findings.push({
+            status: 'warn',
+            message: 'Card uses "authentication", removed from the A2A spec',
+            hint: 'Replace it with "securitySchemes" (OpenAPI-style scheme definitions) plus the matching security requirements.',
+            learnMoreUrl: guideUrl(meta.id, 'deprecated-authentication'),
+        });
+        score -= 5;
+    }
+    if (data.securitySchemes !== undefined) {
+        findings.push({ status: 'pass', message: 'securitySchemes declared' });
+    }
+    if (Array.isArray(data.signatures) && data.signatures.length > 0) {
+        findings.push({
+            status: 'pass',
+            message: `Card carries ${data.signatures.length} JWS signature(s)`,
+            detail: 'Signed cards let a client verify the card was issued by the domain it claims.',
+        });
+    }
+    const capabilities = (data.capabilities ?? {});
+    const extensions = Array.isArray(capabilities.extensions)
+        ? capabilities.extensions
+        : [];
+    if (extensions.length > 0) {
+        findings.push({
+            status: 'pass',
+            message: `${extensions.length} capability extension(s) declared`,
+            detail: extensions.map((e) => String(e.uri ?? '(no uri)')).join(', '),
+        });
+    }
+    const optionalFields = ['provider', 'documentationUrl', 'iconUrl'];
+    const presentOptional = optionalFields.filter((f) => data[f] !== undefined);
+    if (presentOptional.length === optionalFields.length) {
+        findings.push({
+            status: 'pass',
+            message: 'All optional descriptive fields present (provider, documentationUrl, iconUrl)',
+        });
+    }
+    else if (presentOptional.length > 0) {
+        findings.push({
+            status: 'pass',
+            message: `${presentOptional.length}/${optionalFields.length} optional descriptive fields present`,
+        });
+    }
+    else {
+        findings.push({
+            status: 'warn',
+            message: 'No optional descriptive fields (provider, documentationUrl, iconUrl)',
+            hint: 'Add provider (who runs this agent), documentationUrl (where to read more) and iconUrl. Agents surface these to users when choosing between agents.',
+            learnMoreUrl: guideUrl(meta.id, 'missing-optional'),
+        });
+        score -= 5;
+    }
+    return score;
+}
+/** Returns `true` when the two URLs share host, `false` if hosts differ, `null` on parse error. */
+function sameHost(a, b) {
+    try {
+        return new URL(a).host.toLowerCase() === new URL(b).host.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=agent-card.js.map

package/dist/checks/agent-card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-card.js","sourceRoot":"","sources":["../../src/checks/agent-card.ts"],"names":[],"mappings":"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"}

package/dist/checks/agent-operability.d.ts

@@ -0,0 +1,66 @@
+import type { CheckContext, CheckResult, CheckMeta } from '../types.js';
+/**
+ * "agent-operability" — can a browser agent work this page, or only look at it?
+ *
+ * Every major browser agent reads the accessibility tree, not the pixels.
+ * Anthropic's browser tool returns the page as `link "Documentation" [ref_1]`,
+ * `button "Search" [ref_4]`; ChatGPT Atlas is documented as using ARIA roles and
+ * labels; Chrome's own guidance for agent-friendly sites asks for real
+ * `<button>` and `<a>` elements, labelled controls and stable layout.
+ *
+ * Which means the failure mode is specific and old: a `<div onclick>` styled to
+ * look like a button has no name and no role, so it does not appear in the tree
+ * at all. The agent does not see a button it cannot press. It sees nothing.
+ * An unlabelled input is a box the agent must guess the meaning of, which is how
+ * an email address ends up in a search field.
+ *
+ * This is the accessibility work that has been the right thing to do for twenty
+ * years, with a new and less patient audience. Every finding here is a genuine
+ * accessibility defect too.
+ *
+ * The check is a static approximation and says so: it reads markup, not a
+ * rendered accessibility tree, so it cannot see labels attached by script or
+ * roles computed at runtime. It reports proportions rather than absolutes for
+ * that reason.
+ */
+export declare const meta: CheckMeta;
+export interface OperabilityReport {
+    buttons: {
+        total: number;
+        named: number;
+        unnamed: string[];
+    };
+    controls: {
+        total: number;
+        labelled: number;
+        unlabelled: string[];
+    };
+    fakeInteractive: number;
+    deadLinks: {
+        noHref: number;
+        javascriptHref: number;
+    };
+    tables: {
+        total: number;
+        withHeaders: number;
+    };
+    media: {
+        total: number;
+        sized: number;
+    };
+    iframes: {
+        total: number;
+        titled: number;
+    };
+    timeElements: {
+        total: number;
+        withDatetime: number;
+    };
+    headingSkips: string[];
+    lang: string | null;
+    blockers: string[];
+}
+/** Analyse the markup for everything a browser agent needs in order to act. */
+export declare function analyseOperability(rawHtml: string): OperabilityReport;
+export default function check(ctx: CheckContext): Promise<CheckResult>;
+//# sourceMappingURL=agent-operability.d.ts.map

package/dist/checks/agent-operability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-operability.d.ts","sourceRoot":"","sources":["../../src/checks/agent-operability.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAW,MAAM,aAAa,CAAC;AAIjF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,IAAI,EAAE,SAKlB,CAAC;AAKF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC7D,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACpE,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3C,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAoCD,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAqIrE;AAED,wBAA8B,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA8B3E"}