A2A Agent Card Auditor
Pricing
Pay per usage
Fetch and validate a public domain .well-known/agent-card.json against the A2A protocol v1.0 spec.
Pricing
Pay per usage
Rating
0.0
(0)
Developer
Sanskar Jaiswal
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
a day ago
Last modified
Categories
Share
FROM apify/actor-node:20
COPY package*.json ./RUN npm --quiet set progress=false \ && npm install --omit=dev --omit=optional
COPY . ./
CMD ["npm", "start"]{ "name": "a2a-agent-card-auditor", "version": "0.1.0", "description": "Apify Actor that fetches a public domain's /.well-known/agent-card.json and validates the A2A (Agent2Agent) protocol Agent Card against the v1.0 spec. Returns field-level validation, interface/skill/security analysis, a readiness score, letter grade, and recommendations.", "type": "module", "private": true, "main": "src/main.js", "scripts": { "start": "node src/main.js", "test": "node --test test/*.test.js", "lint": "node --check src/main.js" }, "dependencies": { "apify": "^3.4.5" }, "devDependencies": {}}{ "actorSpecification": 1, "name": "a2a-agent-card-auditor", "title": "A2A Agent Card Auditor", "description": "Fetch and validate a public domain's /.well-known/agent-card.json against the Agent2Agent (A2A) protocol v1.0 spec. Returns presence, HTTP status, content type, JSON validity, field checks, interface/skill/security validation, readiness score, grade, and recommendations.", "version": "0.1", "buildTag": "latest", "meta": { "templateId": "js-start" }, "input": "./input_schema.json", "output": "./output_schema.json", "storages": { "dataset": "./dataset_schema.json" }, "dockerfile": "./Dockerfile", "defaultRunOptions": { "build": "latest", "timeoutSecs": 60, "memoryMbytes": 512 }}{ "actorSpecification": 1, "fields": { "type": "object", "properties": { "inputUrl": { "type": "string", "description": "The domain URL provided as input" }, "wellKnownUrl": { "type": "string", "description": "The resolved /.well-known/agent-card.json URL that was fetched" }, "finalUrl": { "type": "string", "description": "Final URL after redirects" }, "https": { "type": "boolean", "description": "Whether the final response was served over HTTPS" }, "httpStatus": { "type": "integer", "description": "HTTP status code of the well-known endpoint response, or null if the request failed" }, "contentType": { "type": "string", "description": "Content-Type response header from the well-known endpoint" }, "cardFound": { "type": "boolean", "description": "Whether an Agent Card was found and parseable as JSON" }, "jsonValid": { "type": "boolean", "description": "Whether the response body parsed as valid JSON" }, "parseError": { "type": "string", "description": "JSON parse error message when the body is not valid JSON, or null" }, "name": { "type": "string", "description": "Agent name from the Agent Card" }, "description": { "type": "string", "description": "Agent description from the Agent Card" }, "version": { "type": "string", "description": "Agent version string from the Agent Card" }, "interfaces": { "type": "array", "description": "Per-interface analysis (url, protocolBinding, protocolVersion, tenant, issues)" }, "interfaceCount": { "type": "integer", "description": "Number of supported interfaces declared" }, "capabilities": { "type": "object", "description": "Agent capabilities summary (streaming, pushNotifications, extendedAgentCard, extensionCount)" }, "provider": { "type": "object", "description": "Agent provider details (url, organization) when present, or null" }, "skills": { "type": "array", "description": "Per-skill analysis (id, name, description, tagsCount, examplesCount, inputModes, outputModes, issues)" }, "skillCount": { "type": "integer", "description": "Number of skills declared" }, "securitySchemes": { "type": "object", "description": "Security schemes summary (count of declared security schemes)" }, "securitySchemeCount": { "type": "integer", "description": "Number of declared security schemes" }, "signatures": { "type": "array", "description": "Per-signature analysis (protected, signature present, issues)" }, "signatureCount": { "type": "integer", "description": "Number of JWS signatures declared" }, "iconUrl": { "type": "string", "description": "Agent icon URL when present, or null" }, "documentationUrl": { "type": "string", "description": "Agent documentation URL when present, or null" }, "defaultInputModes": { "type": "array", "description": "Default input media types declared on the Agent Card" }, "defaultOutputModes": { "type": "array", "description": "Default output media types declared on the Agent Card" }, "issues": { "type": "array", "description": "Aggregated issue descriptions across all validation checks" }, "score": { "type": "integer", "description": "A2A Agent Card readiness score (0-100)" }, "grade": { "type": "string", "description": "Letter grade (A+, A, B, C, D, E, F)" }, "checkedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp" }, "recommendations": { "type": "array", "description": "Actionable recommendations for improving A2A Agent Card readiness" } } }, "views": { "overview": { "title": "Overview", "transformation": { "fields": ["wellKnownUrl", "https", "httpStatus", "contentType", "cardFound", "jsonValid", "name", "version", "interfaceCount", "skillCount", "capabilities", "grade", "score", "issues", "recommendations", "checkedAt"] }, "display": { "component": "table", "properties": { "wellKnownUrl": { "label": "Well-known URL", "format": "link" }, "https": { "label": "HTTPS", "format": "boolean" }, "httpStatus": { "label": "HTTP status", "format": "number" }, "contentType": { "label": "Content-Type", "format": "text" }, "cardFound": { "label": "Card found", "format": "boolean" }, "jsonValid": { "label": "Valid JSON", "format": "boolean" }, "name": { "label": "Agent name", "format": "text" }, "version": { "label": "Version", "format": "text" }, "interfaceCount": { "label": "Interfaces", "format": "number" }, "skillCount": { "label": "Skills", "format": "number" }, "capabilities": { "label": "Capabilities", "format": "object" }, "grade": { "label": "Grade", "format": "text" }, "score": { "label": "Score", "format": "number" }, "issues": { "label": "Issues", "format": "array" }, "recommendations": { "label": "Recommendations", "format": "array" }, "checkedAt": { "label": "Checked", "format": "date" } } } } }}{ "title": "A2A Agent Card Auditor", "type": "object", "schemaVersion": 1, "description": "Fetch and validate a public domain's /.well-known/agent-card.json against the Agent2Agent (A2A) protocol v1.0 spec. Returns presence, HTTP status, content type, JSON validity, required-field checks, interface/skill/security validation, readiness score, grade, and recommendations.", "properties": { "startUrl": { "title": "Domain URL", "type": "string", "description": "Public domain or base URL to audit. The actor appends /.well-known/agent-card.json and fetches the A2A Agent Card. HTTP and HTTPS only. Private IP ranges are blocked.", "editor": "textfield", "prefill": "https://example.com", "pattern": "^https?://.+" }, "timeoutSeconds": { "title": "Request timeout (seconds)", "type": "integer", "description": "Timeout for the HTTP request to the well-known endpoint.", "minimum": 3, "maximum": 30, "default": 10, "unit": "seconds", "editor": "number" }, "maxBytes": { "title": "Max response bytes", "type": "integer", "description": "Maximum response body size to download and parse. The A2A Agent Card is JSON and should be small.", "minimum": 1024, "maximum": 524288, "default": 65536, "editor": "number" } }, "required": ["startUrl"]}{ "actorOutputSchemaVersion": 1, "title": "Output schema of A2A Agent Card Auditor", "description": "Audit results are stored in the default dataset.", "properties": { "results": { "type": "string", "title": "Audit results", "template": "{{links.apiDefaultDatasetUrl}}/items" } }}1import { Actor } from 'apify';2import dns from 'node:dns/promises';3import net from 'node:net';4import { fileURLToPath } from 'node:url';5
6const USER_AGENT = 'A2AAgentCardAuditor/0.1 (+https://apify.com)';7const DEFAULT_TIMEOUT_SECONDS = 10;8const DEFAULT_MAX_BYTES = 65536;9const MAX_BYTES = 524288;10const WELL_KNOWN_PATH = '/.well-known/agent-card.json';11
12// ponytail: the core protocol bindings officially supported by the A2A v1.0 spec.13const KNOWN_PROTOCOL_BINDINGS = new Set(['JSONRPC', 'GRPC', 'HTTP+JSON']);14// Known major.minor versions as of A2A v1.0.0 spec.15const KNOWN_PROTOCOL_VERSIONS = new Set(['0.2', '0.3', '1.0']);16
17/* ------------------------------------------------------------------18 * SSRF protection — shared pattern used across URL-fetching actors.19 * ---------------------------------------------------------------- */20
21function isPrivateIPv4(ip) {22 const parts = ip.split('.').map(Number);23 if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;24 const [a, b] = parts;25 return a === 1026 || (a === 172 && b >= 16 && b <= 31)27 || (a === 192 && b === 168)28 || a === 12729 || a === 030 || (a === 169 && b === 254);31}32
33function isPrivateIPv6(ip) {34 const normalized = ip.toLowerCase();35 return normalized === '::1'36 || normalized.startsWith('fc')37 || normalized.startsWith('fd')38 || normalized.startsWith('fe80:');39}40
41export async function normalizeAndValidateUrl(rawUrl) {42 if (!rawUrl || typeof rawUrl !== 'string') throw new Error('startUrl is required');43 if (/^[a-z][a-z0-9+.-]*:/i.test(rawUrl) && !/^https?:\/\//i.test(rawUrl)) {44 throw new Error('Only HTTP and HTTPS URLs are supported');45 }46
47 const withScheme = /^https?:\/\//i.test(rawUrl) ? rawUrl : `https://${rawUrl}`;48 const url = new URL(withScheme);49 if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Only HTTP and HTTPS URLs are supported');50 // Strip any path — we only care about the origin for well-known discovery.51 if (!url.hostname || url.username || url.password) throw new Error('URL must be public and must not include credentials');52
53 const literalType = net.isIP(url.hostname);54 if (literalType === 4 && isPrivateIPv4(url.hostname)) throw new Error('Private IPv4 targets are blocked');55 if (literalType === 6 && isPrivateIPv6(url.hostname)) throw new Error('Private IPv6 targets are blocked');56
57 const records = literalType ? [{ address: url.hostname, family: literalType }] : await dns.lookup(url.hostname, { all: true });58 for (const record of records) {59 if (record.family === 4 && isPrivateIPv4(record.address)) throw new Error('DNS resolves to a private IPv4 address; blocked for SSRF safety');60 if (record.family === 6 && isPrivateIPv6(record.address)) throw new Error('DNS resolves to a private IPv6 address; blocked for SSRF safety');61 }62 return url;63}64
65/* ------------------------------------------------------------------66 * HTTP fetch of the well-known endpoint with manual redirect67 * revalidation (SSRF-safe) and body cap.68 * ---------------------------------------------------------------- */69
70async function fetchAgentCard(originUrl, timeoutSeconds, maxBytes, redirectsRemaining = 3) {71 const wellKnownUrl = new URL(WELL_KNOWN_PATH, originUrl.href);72 await normalizeAndValidateUrl(wellKnownUrl.href);73 const controller = new AbortController();74 const timeout = setTimeout(() => controller.abort(), timeoutSeconds * 1000);75 try {76 const response = await fetch(wellKnownUrl, {77 redirect: 'manual',78 signal: controller.signal,79 headers: {80 'user-agent': USER_AGENT,81 accept: 'application/a2a+json, application/json, */*;q=0.1',82 },83 });84
85 if ([301, 302, 303, 307, 308].includes(response.status)) {86 if (redirectsRemaining <= 0) throw new Error('Too many redirects');87 const location = response.headers.get('location');88 if (!location) throw new Error('Redirect without Location header');89 const nextUrl = new URL(location, wellKnownUrl.href);90 await normalizeAndValidateUrl(nextUrl.href);91 return fetchAgentCard(nextUrl, timeoutSeconds, maxBytes, redirectsRemaining - 1);92 }93
94 const reader = response.body.getReader();95 const chunks = [];96 let total = 0;97 let truncated = false;98 while (true) {99 const { done, value } = await reader.read();100 if (done) break;101 if (total + value.length > maxBytes) {102 chunks.push(value.slice(0, Math.max(0, maxBytes - total)));103 truncated = true;104 break;105 }106 chunks.push(value);107 total += value.length;108 }109 try { await reader.cancel(); } catch { /* ignore */ }110
111 const body = new TextDecoder('utf-8', { fatal: false }).decode(Buffer.concat(chunks));112 const headerMap = {};113 response.headers.forEach((value, key) => { headerMap[key.toLowerCase()] = value; });114
115 return {116 ok: response.ok,117 status: response.status,118 finalUrl: response.url || wellKnownUrl.href,119 https: (response.url || wellKnownUrl.href).startsWith('https://'),120 body,121 headers: headerMap,122 truncated,123 error: null,124 };125 } catch (error) {126 return {127 ok: false,128 status: null,129 finalUrl: wellKnownUrl.href,130 https: wellKnownUrl.protocol === 'https:',131 body: '',132 headers: {},133 truncated: false,134 error: error.message,135 };136 } finally {137 clearTimeout(timeout);138 }139}140
141/* ------------------------------------------------------------------142 * JSON parse with structured error reporting.143 * ---------------------------------------------------------------- */144
145export function parseCardJson(body) {146 if (!body || !body.trim()) return { card: null, error: 'empty response body' };147 try {148 const parsed = JSON.parse(body);149 if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {150 return { card: null, error: 'AgentCard JSON must be an object' };151 }152 return { card: parsed, error: null };153 } catch (err) {154 return { card: null, error: `invalid JSON: ${err.message}` };155 }156}157
158function isPlainObject(v) {159 return v !== null && typeof v === 'object' && !Array.isArray(v);160}161
162function isNonEmptyString(v) {163 return typeof v === 'string' && v.trim() !== '';164}165
166function isNonEmptyArray(v) {167 return Array.isArray(v) && v.length > 0;168}169
170/* ------------------------------------------------------------------171 * Content-Type validation.172 * Expected: application/a2a+json (registered for Agent Cards) or173 * application/json (widely accepted in practice).174 * HTML content type is a reliable sign the path returns an error page.175 * ---------------------------------------------------------------- */176
177export function analyzeContentType(contentTypeHeader) {178 const ct = (contentTypeHeader || '').toLowerCase();179 const isA2aJson = ct.includes('application/a2a+json');180 const isJson = ct.includes('application/json');181 const isHtml = ct.includes('text/html') || ct.includes('application/xhtml');182 // Empty content type is not ideal but not necessarily an error.183 const issues = [];184 if (isHtml) {185 issues.push('Content-Type is HTML — the well-known path likely returns an error page, not an Agent Card');186 } else if (!isA2aJson && !isJson && ct !== '') {187 issues.push(`Content-Type ${ct} is not application/a2a+json or application/json`);188 }189 return { contentType: contentTypeHeader || '', isA2aJson, isJson, isHtml, issues };190}191
192/* ------------------------------------------------------------------193 * Interface (AgentInterface) validation.194 * Required: url (HTTPS in prod for HTTP transports), protocolBinding,195 * protocolVersion.196 * ---------------------------------------------------------------- */197
198export function analyzeInterface(iface, index) {199 const issues = [];200 const block = {201 index,202 url: null,203 protocolBinding: null,204 protocolVersion: null,205 tenant: null,206 issues,207 };208
209 if (!isPlainObject(iface)) {210 issues.push(`interface[${index}] is not an object`);211 return block;212 }213
214 // url — required, HTTPS in production for HTTP-based transports.215 const url = iface.url;216 if (!isNonEmptyString(url)) {217 issues.push(`interface[${index}].url is missing or empty (required, must be HTTPS in production for HTTP-based transports)`);218 } else {219 block.url = url;220 try {221 const parsed = new URL(url);222 if (parsed.protocol !== 'https:') {223 issues.push(`interface[${index}].url is not HTTPS (production agents must use HTTPS for HTTP-based transports)`);224 }225 if (parsed.username || parsed.password) {226 issues.push(`interface[${index}].url must not include credentials`);227 }228 } catch {229 issues.push(`interface[${index}].url is not a valid URL: ${url}`);230 }231 }232
233 // protocolBinding — required.234 const binding = iface.protocolBinding;235 if (!isNonEmptyString(binding)) {236 issues.push(`interface[${index}].protocolBinding is missing or empty (required)`);237 } else {238 block.protocolBinding = binding;239 // ponytail: check known bindings case-insensitively but report the original.240 if (!KNOWN_PROTOCOL_BINDINGS.has(binding.toUpperCase())) {241 issues.push(`interface[${index}].protocolBinding "${binding}" is not a core A2A binding (JSONRPC, GRPC, HTTP+JSON)`);242 }243 }244
245 // protocolVersion — required.246 const version = iface.protocolVersion;247 if (!isNonEmptyString(version)) {248 issues.push(`interface[${index}].protocolVersion is missing or empty (required, e.g. "1.0")`);249 } else {250 block.protocolVersion = version;251 if (!KNOWN_PROTOCOL_VERSIONS.has(version)) {252 issues.push(`interface[${index}].protocolVersion "${version}" is not a known A2A version (0.2, 0.3, 1.0)`);253 }254 }255
256 // tenant — optional opaque routing string.257 if (iface.tenant !== undefined && iface.tenant !== null) {258 if (typeof iface.tenant !== 'string') {259 issues.push(`interface[${index}].tenant must be a string when present`);260 } else {261 block.tenant = iface.tenant;262 }263 }264
265 return block;266}267
268/* ------------------------------------------------------------------269 * Skill (AgentSkill) validation.270 * Required: id, name, description, tags (non-empty array of strings).271 * Optional: examples, inputModes, outputModes, securityRequirements.272 * ---------------------------------------------------------------- */273
274export function analyzeSkill(skill, index) {275 const issues = [];276 const block = {277 index,278 id: null,279 name: null,280 description: null,281 tagsCount: 0,282 examplesCount: 0,283 inputModes: [],284 outputModes: [],285 issues,286 };287
288 if (!isPlainObject(skill)) {289 issues.push(`skill[${index}] is not an object`);290 return block;291 }292
293 // id — required, non-empty string.294 const id = skill.id;295 if (!isNonEmptyString(id)) {296 issues.push(`skill[${index}].id is missing or empty (required)`);297 } else {298 block.id = id;299 }300
301 // name — required.302 const name = skill.name;303 if (!isNonEmptyString(name)) {304 issues.push(`skill[${index}].name is missing or empty (required)`);305 } else {306 block.name = name;307 }308
309 // description — required.310 const desc = skill.description;311 if (!isNonEmptyString(desc)) {312 issues.push(`skill[${index}].description is missing or empty (required)`);313 } else {314 block.description = desc;315 }316
317 // tags — required, non-empty array of strings.318 const tags = skill.tags;319 if (!isNonEmptyArray(tags)) {320 issues.push(`skill[${index}].tags is missing or empty (required, must be a non-empty array of strings)`);321 } else {322 const allStrings = tags.every((t) => typeof t === 'string');323 if (!allStrings) {324 issues.push(`skill[${index}].tags must all be strings`);325 } else {326 block.tagsCount = tags.length;327 }328 }329
330 // examples — optional array of strings.331 if (skill.examples !== undefined && skill.examples !== null) {332 if (!Array.isArray(skill.examples) || !skill.examples.every((e) => typeof e === 'string')) {333 issues.push(`skill[${index}].examples must be an array of strings`);334 } else {335 block.examplesCount = skill.examples.length;336 }337 }338
339 // inputModes — optional array of strings (media types).340 if (skill.inputModes !== undefined && skill.inputModes !== null) {341 if (!Array.isArray(skill.inputModes) || !skill.inputModes.every((m) => typeof m === 'string')) {342 issues.push(`skill[${index}].inputModes must be an array of strings`);343 } else {344 block.inputModes = skill.inputModes;345 }346 }347
348 // outputModes — optional array of strings.349 if (skill.outputModes !== undefined && skill.outputModes !== null) {350 if (!Array.isArray(skill.outputModes) || !skill.outputModes.every((m) => typeof m === 'string')) {351 issues.push(`skill[${index}].outputModes must be an array of strings`);352 } else {353 block.outputModes = skill.outputModes;354 }355 }356
357 return block;358}359
360/* ------------------------------------------------------------------361 * Capabilities (AgentCapabilities) validation.362 * Optional fields: streaming, pushNotifications, extendedAgentCard363 * (bools), extensions (array of AgentExtension).364 * ---------------------------------------------------------------- */365
366export function analyzeCapabilities(caps) {367 const issues = [];368 const block = {369 streaming: null,370 pushNotifications: null,371 extendedAgentCard: null,372 extensionCount: 0,373 issues,374 };375
376 if (!isPlainObject(caps)) {377 issues.push('capabilities is not an object');378 return block;379 }380
381 for (const boolField of ['streaming', 'pushNotifications', 'extendedAgentCard']) {382 if (caps[boolField] !== undefined && caps[boolField] !== null) {383 if (typeof caps[boolField] !== 'boolean') {384 issues.push(`capabilities.${boolField} must be a boolean`);385 } else {386 block[boolField] = caps[boolField];387 }388 }389 }390
391 // extensions — optional array of AgentExtension.392 if (caps.extensions !== undefined && caps.extensions !== null) {393 if (!Array.isArray(caps.extensions)) {394 issues.push('capabilities.extensions must be an array');395 } else {396 block.extensionCount = caps.extensions.length;397 caps.extensions.forEach((ext, i) => {398 if (!isPlainObject(ext)) {399 issues.push(`capabilities.extensions[${i}] is not an object`);400 return;401 }402 if (!isNonEmptyString(ext.uri)) {403 issues.push(`capabilities.extensions[${i}].uri is missing or empty`);404 }405 if (ext.required !== undefined && ext.required !== null && typeof ext.required !== 'boolean') {406 issues.push(`capabilities.extensions[${i}].required must be a boolean`);407 }408 });409 }410 }411
412 return block;413}414
415/* ------------------------------------------------------------------416 * Provider (AgentProvider) validation.417 * Optional. When present: url (required, HTTPS), organization (required).418 * ---------------------------------------------------------------- */419
420export function analyzeProvider(provider) {421 const issues = [];422 const block = { url: null, organization: null, issues };423
424 if (provider === undefined || provider === null) return block;425 if (!isPlainObject(provider)) {426 issues.push('provider is not an object');427 return block;428 }429
430 const url = provider.url;431 if (!isNonEmptyString(url)) {432 issues.push('provider.url is missing or empty');433 } else {434 block.url = url;435 try {436 const parsed = new URL(url);437 if (parsed.protocol !== 'https:') {438 issues.push('provider.url should be HTTPS');439 }440 } catch {441 issues.push(`provider.url is not a valid URL`);442 }443 }444
445 const org = provider.organization;446 if (!isNonEmptyString(org)) {447 issues.push('provider.organization is missing or empty');448 } else {449 block.organization = org;450 }451
452 return block;453}454
455/* ------------------------------------------------------------------456 * Signatures (AgentCardSignature) validation.457 * Optional array. Each signature: protected (required, base64url),458 * signature (required, base64url), header (optional Struct).459 * ---------------------------------------------------------------- */460
461export function analyzeSignature(sig, index) {462 const issues = [];463 const block = { index, protected: null, signature: null, issues };464
465 if (!isPlainObject(sig)) {466 issues.push(`signatures[${index}] is not an object`);467 return block;468 }469
470 if (!isNonEmptyString(sig.protected)) {471 issues.push(`signatures[${index}].protected is missing or empty (required, base64url JWS header)`);472 } else {473 block.protected = sig.protected;474 }475
476 if (!isNonEmptyString(sig.signature)) {477 issues.push(`signatures[${index}].signature is missing or empty (required, base64url JWS signature)`);478 } else {479 block.signature = sig.signature;480 }481
482 return block;483}484
485/* ------------------------------------------------------------------486 * Security schemes summary — count declared schemes.487 * Does NOT deeply validate scheme shapes (OAuth2, HTTP, APIKey, etc.)488 * — that would pull in the full OpenAPI-style security schema.489 * ponytail: just report presence and count; deep security scheme490 * validation is out of scope for a discovery/structure auditor.491 * ---------------------------------------------------------------- */492
493export function analyzeSecuritySchemes(schemes) {494 const issues = [];495 let count = 0;496
497 if (schemes === undefined || schemes === null) return { count, issues };498
499 if (!isPlainObject(schemes)) {500 issues.push('securitySchemes is not an object (should be a map of name -> scheme)');501 return { count: 0, issues };502 }503
504 const keys = Object.keys(schemes);505 count = keys.length;506 for (const key of keys) {507 if (!isPlainObject(schemes[key])) {508 issues.push(`securitySchemes["${key}"] is not an object`);509 }510 }511
512 return { count, issues };513}514
515/* ------------------------------------------------------------------516 * Top-level AgentCard validation.517 * Validates all required and optional fields per A2A v1.0 spec.518 * ---------------------------------------------------------------- */519
520export function analyzeAgentCard(card) {521 const issues = [];522 const result = {523 name: null,524 description: null,525 version: null,526 documentationUrl: null,527 iconUrl: null,528 interfaces: [],529 interfaceCount: 0,530 capabilities: null,531 provider: null,532 skills: [],533 skillCount: 0,534 securitySchemes: { count: 0, issues: [] },535 securitySchemeCount: 0,536 signatures: [],537 signatureCount: 0,538 defaultInputModes: [],539 defaultOutputModes: [],540 issues,541 };542
543 if (!isPlainObject(card)) {544 issues.push('AgentCard is not an object');545 return result;546 }547
548 // name — required.549 if (!isNonEmptyString(card.name)) {550 issues.push('name is missing or empty (required)');551 } else {552 result.name = card.name;553 }554
555 // description — required.556 if (!isNonEmptyString(card.description)) {557 issues.push('description is missing or empty (required)');558 } else {559 result.description = card.description;560 }561
562 // version — required.563 if (!isNonEmptyString(card.version)) {564 issues.push('version is missing or empty (required)');565 } else {566 result.version = card.version;567 }568
569 // supportedInterfaces — required, non-empty array.570 const interfaces = card.supportedInterfaces;571 if (!isNonEmptyArray(interfaces)) {572 issues.push('supportedInterfaces is missing or empty (required, must be a non-empty array)');573 } else {574 result.interfaceCount = interfaces.length;575 for (let i = 0; i < interfaces.length; i++) {576 const block = analyzeInterface(interfaces[i], i);577 result.interfaces.push(block);578 for (const iss of block.issues) issues.push(iss);579 }580 }581
582 // capabilities — required.583 result.capabilities = analyzeCapabilities(card.capabilities);584 for (const iss of result.capabilities.issues) issues.push(iss);585
586 // defaultInputModes — required, non-empty array of strings.587 const inputModes = card.defaultInputModes;588 if (!isNonEmptyArray(inputModes)) {589 issues.push('defaultInputModes is missing or empty (required, must be a non-empty array of media types)');590 } else {591 if (!inputModes.every((m) => typeof m === 'string')) {592 issues.push('defaultInputModes must all be strings');593 } else {594 result.defaultInputModes = inputModes;595 }596 }597
598 // defaultOutputModes — required, non-empty array of strings.599 const outputModes = card.defaultOutputModes;600 if (!isNonEmptyArray(outputModes)) {601 issues.push('defaultOutputModes is missing or empty (required, must be a non-empty array of media types)');602 } else {603 if (!outputModes.every((m) => typeof m === 'string')) {604 issues.push('defaultOutputModes must all be strings');605 } else {606 result.defaultOutputModes = outputModes;607 }608 }609
610 // skills — required, non-empty array.611 const skills = card.skills;612 if (!isNonEmptyArray(skills)) {613 issues.push('skills is missing or empty (required, must be a non-empty array)');614 } else {615 result.skillCount = skills.length;616 for (let i = 0; i < skills.length; i++) {617 const block = analyzeSkill(skills[i], i);618 result.skills.push(block);619 for (const iss of block.issues) issues.push(iss);620 }621 }622
623 // provider — optional.624 result.provider = analyzeProvider(card.provider);625 for (const iss of result.provider.issues) issues.push(iss);626
627 // documentationUrl — optional string.628 if (card.documentationUrl !== undefined && card.documentationUrl !== null) {629 if (!isNonEmptyString(card.documentationUrl)) {630 issues.push('documentationUrl must be a non-empty string when present');631 } else {632 result.documentationUrl = card.documentationUrl;633 }634 }635
636 // iconUrl — optional string.637 if (card.iconUrl !== undefined && card.iconUrl !== null) {638 if (!isNonEmptyString(card.iconUrl)) {639 issues.push('iconUrl must be a non-empty string when present');640 } else {641 result.iconUrl = card.iconUrl;642 }643 }644
645 // securitySchemes — optional map.646 result.securitySchemes = analyzeSecuritySchemes(card.securitySchemes);647 result.securitySchemeCount = result.securitySchemes.count;648 for (const iss of result.securitySchemes.issues) issues.push(iss);649
650 // signatures — optional array.651 if (card.signatures !== undefined && card.signatures !== null) {652 if (!Array.isArray(card.signatures)) {653 issues.push('signatures must be an array');654 } else {655 result.signatureCount = card.signatures.length;656 for (let i = 0; i < card.signatures.length; i++) {657 const block = analyzeSignature(card.signatures[i], i);658 result.signatures.push(block);659 for (const iss of block.issues) issues.push(iss);660 }661 }662 }663
664 return result;665}666
667/* ------------------------------------------------------------------668 * Scoring.669 * ponytail: rewards presence of required fields, HTTPS interfaces,670 * multiple interfaces, streaming/pushNotifications, skills with671 * examples, security schemes, and signatures. Penalizes each issue.672 * ---------------------------------------------------------------- */673
674export function scoreAgentCard(summary, https) {675 const { issues } = summary;676 if (!summary.name && issues.some((i) => i.includes('not an object'))) return 0;677
678 let earned = 0;679 const possible = 100;680
681 // Required field presence (40 points total, ~5.7 each for 7 required fields/arrays).682 if (summary.name) earned += 5;683 if (summary.description) earned += 5;684 if (summary.version) earned += 5;685 if (summary.interfaceCount > 0) earned += 8;686 if (summary.capabilities && summary.capabilities.issues.length === 0) earned += 5;687 if (summary.defaultInputModes.length > 0) earned += 5;688 if (summary.defaultOutputModes.length > 0) earned += 5;689 if (summary.skillCount > 0) earned += 7;690
691 // HTTPS endpoint (10 points) — production agents must use HTTPS.692 if (https) earned += 10;693
694 // Quality depth (30 points):695 // +capabilities with streaming or pushNotifications (+8)696 if (summary.capabilities && (summary.capabilities.streaming || summary.capabilities.pushNotifications)) earned += 8;697 // +skills with examples (+6)698 if (summary.skills.some((s) => s.examplesCount > 0)) earned += 6;699 // +security schemes declared (+6)700 if (summary.securitySchemeCount > 0) earned += 6;701 // +provider organization declared (+5)702 if (summary.provider && summary.provider.organization) earned += 5;703 // +documentationUrl (+5)704 if (summary.documentationUrl) earned += 5;705
706 // Issue penalty (up to 40 points off).707 const issuePenalty = Math.min(issues.length * 8, 40);708 earned = Math.max(0, earned - issuePenalty);709
710 return Math.round((earned / possible) * 100);711}712
713export function gradeFromScore(score) {714 if (score >= 95) return 'A+';715 if (score >= 85) return 'A';716 if (score >= 75) return 'B';717 if (score >= 65) return 'C';718 if (score >= 50) return 'D';719 if (score >= 30) return 'E';720 return 'F';721}722
723/* ------------------------------------------------------------------724 * Recommendations.725 * ---------------------------------------------------------------- */726
727export function buildRecommendations(summary, score, https, httpStatus, contentTypeInfo) {728 const recs = new Set();729 const { issues } = summary;730
731 // JSON / structure issues.732 if (issues.some((i) => i.includes('invalid JSON') || i.includes('must be an object'))) {733 recs.add('Fix the Agent Card JSON — the response body must be a valid JSON object, not an HTML error page or malformed text.');734 }735
736 // HTTPS.737 if (!https) {738 recs.add('Serve the /.well-known/agent-card.json endpoint over HTTPS. Production A2A agents must use HTTPS for HTTP-based transports.');739 }740
741 // Content type.742 if (contentTypeInfo && contentTypeInfo.isHtml) {743 recs.add('The well-known endpoint returned HTML, not JSON. Ensure your server routes /.well-known/agent-card.json to the Agent Card, not a fallback error page.');744 } else if (contentTypeInfo && !contentTypeInfo.isA2aJson && !contentTypeInfo.isJson && contentTypeInfo.contentType !== '' && !contentTypeInfo.isHtml) {745 recs.add(`Set the Content-Type to application/a2a+json (preferred) or application/json for the well-known endpoint.`);746 }747
748 // Required fields.749 if (issues.some((i) => i.includes('name is missing'))) recs.add('Add a human-readable `name` field to the Agent Card.');750 if (issues.some((i) => i.includes('description is missing'))) recs.add('Add a `description` field explaining what the agent does.');751 if (issues.some((i) => i.includes('version is missing'))) recs.add('Add a semantic `version` string (e.g. "1.0.0") to the Agent Card.');752 if (issues.some((i) => i.includes('supportedInterfaces'))) recs.add('Add at least one entry to `supportedInterfaces` with url, protocolBinding, and protocolVersion.');753 if (issues.some((i) => i.includes('defaultInputModes'))) recs.add('Add `defaultInputModes` as a non-empty array of supported input media types (e.g. ["text/plain"]).');754 if (issues.some((i) => i.includes('defaultOutputModes'))) recs.add('Add `defaultOutputModes` as a non-empty array of supported output media types (e.g. ["text/plain"]).');755 if (issues.some((i) => i.includes('skills is missing'))) recs.add('Add at least one `skill` with id, name, description, and tags to declare what the agent can do.');756
757 // Interface HTTPS.758 if (issues.some((i) => i.includes('not HTTPS'))) {759 recs.add('Use HTTPS URLs for all HTTP-based interface endpoints in `supportedInterfaces`.');760 }761
762 // Interface binding.763 if (issues.some((i) => i.includes('protocolBinding') && i.includes('core A2A'))) {764 recs.add('Use a supported `protocolBinding` (JSONRPC, GRPC, or HTTP+JSON) for each interface.');765 }766
767 // Protocol version.768 if (issues.some((i) => i.includes('protocolVersion') && i.includes('known A2A'))) {769 recs.add('Set `protocolVersion` to a known A2A version (0.2, 0.3, or 1.0) for each interface.');770 }771
772 // Capabilities.773 if (summary.capabilities && !summary.capabilities.streaming && !summary.capabilities.pushNotifications) {774 recs.add('If your agent supports streaming or push notifications, declare them in `capabilities` to enable richer client interactions.');775 }776
777 // Security.778 if (summary.securitySchemeCount === 0) {779 recs.add('Declare `securitySchemes` if the agent requires authentication (OAuth2, API key, HTTP bearer, etc.).');780 }781
782 // Provider.783 if (!summary.provider || !summary.provider.organization) {784 recs.add('Declare a `provider` with the organization name and a documentation URL for discoverability and trust.');785 }786
787 // Signatures.788 if (summary.signatureCount === 0) {789 recs.add('Consider adding JWS `signatures` to allow clients to verify Agent Card authenticity and detect tampering.');790 }791
792 // HTTP status.793 if (httpStatus !== null && httpStatus === 404) {794 recs.add('The /.well-known/agent-card.json path returned 404. Create the endpoint so A2A clients can discover your agent via the standard well-known URI (RFC 8615).');795 } else if (httpStatus !== null && httpStatus >= 500) {796 recs.add('The well-known endpoint returned a server error. Check your server configuration and ensure /.well-known/agent-card.json is routed correctly.');797 }798
799 // Positive close when clean.800 if (issues.length === 0 && summary.name) {801 recs.add('The A2A Agent Card is well-structured and conformant. Schedule this audit periodically to catch deployment regressions.');802 }803
804 return [...recs];805}806
807/* ------------------------------------------------------------------808 * Main audit pipeline.809 * ---------------------------------------------------------------- */810
811export async function auditAgentCard(input) {812 const baseUrl = await normalizeAndValidateUrl(input.startUrl);813 const timeoutSeconds = Math.min(Math.max(Number(input.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS), 3), 30);814 const maxBytes = Math.min(Math.max(Number(input.maxBytes || DEFAULT_MAX_BYTES), 1024), MAX_BYTES);815
816 const wellKnownUrl = new URL(WELL_KNOWN_PATH, baseUrl.href).href;817 const fetchResult = await fetchAgentCard(baseUrl, timeoutSeconds, maxBytes);818
819 if (fetchResult.error) {820 return {821 inputUrl: input.startUrl,822 wellKnownUrl,823 finalUrl: fetchResult.finalUrl,824 https: fetchResult.https,825 httpStatus: fetchResult.status,826 contentType: '',827 cardFound: false,828 jsonValid: false,829 parseError: null,830 name: null,831 description: null,832 version: null,833 interfaces: [],834 interfaceCount: 0,835 capabilities: null,836 provider: null,837 skills: [],838 skillCount: 0,839 securitySchemes: { count: 0, issues: [] },840 securitySchemeCount: 0,841 signatures: [],842 signatureCount: 0,843 iconUrl: null,844 documentationUrl: null,845 defaultInputModes: [],846 defaultOutputModes: [],847 issues: [],848 score: 0,849 grade: 'F',850 checkedAt: new Date().toISOString(),851 recommendations: ['The request to /.well-known/agent-card.json failed. Verify the domain is reachable and the well-known path exists.'],852 error: fetchResult.error,853 };854 }855
856 const contentTypeRaw = fetchResult.headers['content-type'] || '';857 const contentTypeInfo = analyzeContentType(contentTypeRaw);858
859 // HTTP error status.860 if (!fetchResult.ok) {861 const score = 0;862 const grade = 'F';863 const recommendations = buildRecommendations(864 { name: null, issues: [], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null },865 score,866 fetchResult.https,867 fetchResult.status,868 contentTypeInfo,869 );870 return {871 inputUrl: input.startUrl,872 wellKnownUrl,873 finalUrl: fetchResult.finalUrl,874 https: fetchResult.https,875 httpStatus: fetchResult.status,876 contentType: contentTypeRaw,877 cardFound: false,878 jsonValid: false,879 parseError: null,880 name: null,881 description: null,882 version: null,883 interfaces: [],884 interfaceCount: 0,885 capabilities: null,886 provider: null,887 skills: [],888 skillCount: 0,889 securitySchemes: { count: 0, issues: [] },890 securitySchemeCount: 0,891 signatures: [],892 signatureCount: 0,893 iconUrl: null,894 documentationUrl: null,895 defaultInputModes: [],896 defaultOutputModes: [],897 issues: [`/.well-known/agent-card.json returned HTTP ${fetchResult.status}`],898 score,899 grade,900 checkedAt: new Date().toISOString(),901 recommendations,902 error: null,903 };904 }905
906 // Parse JSON.907 const { card, error: parseError } = parseCardJson(fetchResult.body);908 const cardFound = card !== null;909
910 if (!cardFound) {911 const issues = [parseError, ...contentTypeInfo.issues];912 const score = 0;913 const grade = 'F';914 const recommendations = buildRecommendations(915 { name: null, issues, skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null },916 score,917 fetchResult.https,918 fetchResult.status,919 contentTypeInfo,920 );921 return {922 inputUrl: input.startUrl,923 wellKnownUrl,924 finalUrl: fetchResult.finalUrl,925 https: fetchResult.https,926 httpStatus: fetchResult.status,927 contentType: contentTypeRaw,928 cardFound: false,929 jsonValid: false,930 parseError,931 name: null,932 description: null,933 version: null,934 interfaces: [],935 interfaceCount: 0,936 capabilities: null,937 provider: null,938 skills: [],939 skillCount: 0,940 securitySchemes: { count: 0, issues: [] },941 securitySchemeCount: 0,942 signatures: [],943 signatureCount: 0,944 iconUrl: null,945 documentationUrl: null,946 defaultInputModes: [],947 defaultOutputModes: [],948 issues,949 score,950 grade,951 checkedAt: new Date().toISOString(),952 recommendations,953 error: null,954 };955 }956
957 // Analyze the Agent Card.958 const summary = analyzeAgentCard(card);959 // Merge content-type issues into the main issue list.960 for (const iss of contentTypeInfo.issues) {961 if (!summary.issues.includes(iss)) summary.issues.push(iss);962 }963
964 const score = scoreAgentCard(summary, fetchResult.https);965 const grade = gradeFromScore(score);966 const recommendations = buildRecommendations(summary, score, fetchResult.https, fetchResult.status, contentTypeInfo);967
968 return {969 inputUrl: input.startUrl,970 wellKnownUrl,971 finalUrl: fetchResult.finalUrl,972 https: fetchResult.https,973 httpStatus: fetchResult.status,974 contentType: contentTypeRaw,975 cardFound: true,976 jsonValid: true,977 parseError: null,978 name: summary.name,979 description: summary.description,980 version: summary.version,981 interfaces: summary.interfaces,982 interfaceCount: summary.interfaceCount,983 capabilities: summary.capabilities,984 provider: summary.provider,985 skills: summary.skills,986 skillCount: summary.skillCount,987 securitySchemes: summary.securitySchemes,988 securitySchemeCount: summary.securitySchemeCount,989 signatures: summary.signatures,990 signatureCount: summary.signatureCount,991 iconUrl: summary.iconUrl,992 documentationUrl: summary.documentationUrl,993 defaultInputModes: summary.defaultInputModes,994 defaultOutputModes: summary.defaultOutputModes,995 issues: summary.issues,996 score,997 grade,998 checkedAt: new Date().toISOString(),999 recommendations,1000 error: null,1001 };1002}1003
1004/* ------------------------------------------------------------------1005 * Apify runtime entry point.1006 * ---------------------------------------------------------------- */1007
1008const isExecutedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];1009
1010if (process.env.NODE_ENV !== 'test' && isExecutedDirectly) {1011 await Actor.init();1012 try {1013 const input = await Actor.getInput();1014 const result = await auditAgentCard(input || {});1015 await Actor.pushData(result);1016 await Actor.setValue('OUTPUT', result);1017 Actor.log.info('A2A Agent Card audit complete', { finalUrl: result.finalUrl, cardFound: result.cardFound, score: result.score, grade: result.grade });1018 } finally {1019 await Actor.exit();1020 }1021}1import test from 'node:test';2import assert from 'node:assert/strict';3import {4 analyzeAgentCard,5 analyzeCapabilities,6 analyzeContentType,7 analyzeInterface,8 analyzeProvider,9 analyzeSecuritySchemes,10 analyzeSignature,11 analyzeSkill,12 buildRecommendations,13 gradeFromScore,14 normalizeAndValidateUrl,15 parseCardJson,16 scoreAgentCard,17} from '../src/main.js';18
19/* ------------------------------------------------------------------20 * SSRF / URL validation security tests21 * ---------------------------------------------------------------- */22
23test('normalizeAndValidateUrl blocks private IPv4 literal', async () => {24 await assert.rejects(() => normalizeAndValidateUrl('http://127.0.0.1/'), /Private IPv4/);25});26
27test('normalizeAndValidateUrl blocks 169.254 link-local', async () => {28 await assert.rejects(() => normalizeAndValidateUrl('http://169.254.169.254/'), /Private IPv4/);29});30
31test('normalizeAndValidateUrl rejects URL credentials', async () => {32 await assert.rejects(() => normalizeAndValidateUrl('https://user:pass@example.com'), /credentials/);33});34
35test('normalizeAndValidateUrl rejects non-HTTP schemes', async () => {36 await assert.rejects(() => normalizeAndValidateUrl('file:///etc/hosts'), /HTTP and HTTPS/);37});38
39test('normalizeAndValidateUrl rejects ftp scheme', async () => {40 await assert.rejects(() => normalizeAndValidateUrl('ftp://example.com/file'), /HTTP and HTTPS/);41});42
43test('normalizeAndValidateUrl accepts public hostname and defaults to https', async () => {44 const url = await normalizeAndValidateUrl('example.com');45 assert.equal(url.hostname, 'example.com');46 assert.equal(url.protocol, 'https:');47});48
49/* ------------------------------------------------------------------50 * JSON parser tests51 * ---------------------------------------------------------------- */52
53test('parseCardJson parses valid object', () => {54 const { card, error } = parseCardJson('{"name":"test"}');55 assert.equal(error, null);56 assert.deepEqual(card, { name: 'test' });57});58
59test('parseCardJson rejects empty body', () => {60 const { card, error } = parseCardJson(' ');61 assert.equal(card, null);62 assert.match(error, /empty response body/);63});64
65test('parseCardJson rejects non-object JSON (array)', () => {66 const { card, error } = parseCardJson('[]');67 assert.equal(card, null);68 assert.match(error, /must be an object/);69});70
71test('parseCardJson rejects non-object JSON (string)', () => {72 const { card, error } = parseCardJson('"hello"');73 assert.equal(card, null);74 assert.match(error, /must be an object/);75});76
77test('parseCardJson rejects malformed JSON', () => {78 const { card, error } = parseCardJson('{not json');79 assert.equal(card, null);80 assert.match(error, /invalid JSON/);81});82
83test('parseCardJson rejects null', () => {84 const { card, error } = parseCardJson('null');85 assert.equal(card, null);86 assert.match(error, /must be an object/);87});88
89/* ------------------------------------------------------------------90 * Content-Type validation tests91 * ---------------------------------------------------------------- */92
93test('analyzeContentType recognizes application/a2a+json', () => {94 const info = analyzeContentType('application/a2a+json');95 assert.equal(info.isA2aJson, true);96 assert.equal(info.isJson, false);97 assert.equal(info.isHtml, false);98 assert.equal(info.issues.length, 0);99});100
101test('analyzeContentType recognizes application/json', () => {102 const info = analyzeContentType('application/json; charset=utf-8');103 assert.equal(info.isJson, true);104 assert.equal(info.isA2aJson, false);105 assert.equal(info.issues.length, 0);106});107
108test('analyzeContentType flags HTML as likely error page', () => {109 const info = analyzeContentType('text/html; charset=utf-8');110 assert.equal(info.isHtml, true);111 assert.ok(info.issues.some((i) => i.includes('error page')));112});113
114test('analyzeContentType flags non-JSON content type', () => {115 const info = analyzeContentType('text/plain');116 assert.ok(info.issues.some((i) => i.includes('not application/a2a+json')));117});118
119test('analyzeContentType accepts empty content type without issue', () => {120 const info = analyzeContentType('');121 assert.equal(info.issues.length, 0);122});123
124/* ------------------------------------------------------------------125 * Interface validation tests126 * ---------------------------------------------------------------- */127
128test('analyzeInterface validates a well-formed JSONRPC interface', () => {129 const block = analyzeInterface({130 url: 'https://agent.example.com/a2a',131 protocolBinding: 'JSONRPC',132 protocolVersion: '1.0',133 }, 0);134 assert.equal(block.url, 'https://agent.example.com/a2a');135 assert.equal(block.protocolBinding, 'JSONRPC');136 assert.equal(block.protocolVersion, '1.0');137 assert.equal(block.issues.length, 0);138});139
140test('analyzeInterface flags missing url', () => {141 const block = analyzeInterface({ protocolBinding: 'JSONRPC', protocolVersion: '1.0' }, 0);142 assert.ok(block.issues.some((i) => i.includes('url is missing')));143});144
145test('analyzeInterface flags non-HTTPS url', () => {146 const block = analyzeInterface({147 url: 'http://agent.example.com/a2a',148 protocolBinding: 'JSONRPC',149 protocolVersion: '1.0',150 }, 0);151 assert.ok(block.issues.some((i) => i.includes('not HTTPS')));152});153
154test('analyzeInterface flags url with credentials', () => {155 const block = analyzeInterface({156 url: 'https://user:pass@agent.example.com/a2a',157 protocolBinding: 'JSONRPC',158 protocolVersion: '1.0',159 }, 0);160 assert.ok(block.issues.some((i) => i.includes('credentials')));161});162
163test('analyzeInterface flags missing protocolBinding', () => {164 const block = analyzeInterface({ url: 'https://agent.example.com', protocolVersion: '1.0' }, 0);165 assert.ok(block.issues.some((i) => i.includes('protocolBinding is missing')));166});167
168test('analyzeInterface flags unknown protocol binding', () => {169 const block = analyzeInterface({170 url: 'https://agent.example.com',171 protocolBinding: 'WEBSOCKET',172 protocolVersion: '1.0',173 }, 0);174 assert.ok(block.issues.some((i) => i.includes('not a core A2A binding')));175});176
177test('analyzeInterface flags missing protocolVersion', () => {178 const block = analyzeInterface({ url: 'https://agent.example.com', protocolBinding: 'JSONRPC' }, 0);179 assert.ok(block.issues.some((i) => i.includes('protocolVersion is missing')));180});181
182test('analyzeInterface flags unknown protocol version', () => {183 const block = analyzeInterface({184 url: 'https://agent.example.com',185 protocolBinding: 'JSONRPC',186 protocolVersion: '2.5',187 }, 0);188 assert.ok(block.issues.some((i) => i.includes('not a known A2A version')));189});190
191test('analyzeInterface flags non-object input', () => {192 const block = analyzeInterface('not-an-object', 0);193 assert.ok(block.issues.some((i) => i.includes('not an object')));194});195
196test('analyzeInterface captures tenant string', () => {197 const block = analyzeInterface({198 url: 'https://agent.example.com',199 protocolBinding: 'GRPC',200 protocolVersion: '1.0',201 tenant: 'org-123',202 }, 0);203 assert.equal(block.tenant, 'org-123');204 assert.equal(block.issues.length, 0);205});206
207/* ------------------------------------------------------------------208 * Skill validation tests209 * ---------------------------------------------------------------- */210
211test('analyzeSkill validates a well-formed skill', () => {212 const block = analyzeSkill({213 id: 'summarize',214 name: 'Summarize Document',215 description: 'Summarizes a document into key points.',216 tags: ['summarization', 'nlp'],217 examples: ['Summarize this article'],218 }, 0);219 assert.equal(block.id, 'summarize');220 assert.equal(block.name, 'Summarize Document');221 assert.equal(block.tagsCount, 2);222 assert.equal(block.examplesCount, 1);223 assert.equal(block.issues.length, 0);224});225
226test('analyzeSkill flags missing id', () => {227 const block = analyzeSkill({ name: 'x', description: 'y', tags: ['t'] }, 0);228 assert.ok(block.issues.some((i) => i.includes('id is missing')));229});230
231test('analyzeSkill flags missing tags', () => {232 const block = analyzeSkill({ id: 'x', name: 'y', description: 'z' }, 0);233 assert.ok(block.issues.some((i) => i.includes('tags is missing')));234});235
236test('analyzeSkill flags empty tags array', () => {237 const block = analyzeSkill({ id: 'x', name: 'y', description: 'z', tags: [] }, 0);238 assert.ok(block.issues.some((i) => i.includes('tags is missing')));239});240
241test('analyzeSkill flags non-string tags', () => {242 const block = analyzeSkill({ id: 'x', name: 'y', description: 'z', tags: [1, 2] }, 0);243 assert.ok(block.issues.some((i) => i.includes('must all be strings')));244});245
246test('analyzeSkill captures inputModes and outputModes', () => {247 const block = analyzeSkill({248 id: 'x',249 name: 'y',250 description: 'z',251 tags: ['t'],252 inputModes: ['text/plain'],253 outputModes: ['text/plain', 'application/json'],254 }, 0);255 assert.deepEqual(block.inputModes, ['text/plain']);256 assert.deepEqual(block.outputModes, ['text/plain', 'application/json']);257});258
259/* ------------------------------------------------------------------260 * Capabilities validation tests261 * ---------------------------------------------------------------- */262
263test('analyzeCapabilities validates all boolean fields', () => {264 const block = analyzeCapabilities({265 streaming: true,266 pushNotifications: false,267 extendedAgentCard: true,268 });269 assert.equal(block.streaming, true);270 assert.equal(block.pushNotifications, false);271 assert.equal(block.extendedAgentCard, true);272 assert.equal(block.issues.length, 0);273});274
275test('analyzeCapabilities flags non-boolean streaming', () => {276 const block = analyzeCapabilities({ streaming: 'yes' });277 assert.ok(block.issues.some((i) => i.includes('streaming must be a boolean')));278});279
280test('analyzeCapabilities flags non-object input', () => {281 const block = analyzeCapabilities(null);282 assert.ok(block.issues.some((i) => i.includes('not an object')));283});284
285test('analyzeCapabilities validates extensions array', () => {286 const block = analyzeCapabilities({287 extensions: [288 { uri: 'https://example.com/ext/v1', description: 'test', required: false },289 ],290 });291 assert.equal(block.extensionCount, 1);292 assert.equal(block.issues.length, 0);293});294
295test('analyzeCapabilities flags extension with missing uri', () => {296 const block = analyzeCapabilities({297 extensions: [{ description: 'no uri' }],298 });299 assert.ok(block.issues.some((i) => i.includes('uri is missing')));300});301
302/* ------------------------------------------------------------------303 * Provider validation tests304 * ---------------------------------------------------------------- */305
306test('analyzeProvider validates well-formed provider', () => {307 const block = analyzeProvider({308 url: 'https://ai.google.dev',309 organization: 'Google',310 });311 assert.equal(block.url, 'https://ai.google.dev');312 assert.equal(block.organization, 'Google');313 assert.equal(block.issues.length, 0);314});315
316test('analyzeProvider returns empty block for undefined', () => {317 const block = analyzeProvider(undefined);318 assert.equal(block.url, null);319 assert.equal(block.organization, null);320 assert.equal(block.issues.length, 0);321});322
323test('analyzeProvider flags missing organization', () => {324 const block = analyzeProvider({ url: 'https://example.com' });325 assert.ok(block.issues.some((i) => i.includes('organization is missing')));326});327
328test('analyzeProvider flags non-HTTPS url', () => {329 const block = analyzeProvider({ url: 'http://example.com', organization: 'X' });330 assert.ok(block.issues.some((i) => i.includes('should be HTTPS')));331});332
333/* ------------------------------------------------------------------334 * Signature validation tests335 * ---------------------------------------------------------------- */336
337test('analyzeSignature validates well-formed signature', () => {338 const block = analyzeSignature({339 protected: 'eyJhbGciOiJSUzI1NiJ9',340 signature: 'c2lnbmF0dXJl',341 }, 0);342 assert.equal(block.protected, 'eyJhbGciOiJSUzI1NiJ9');343 assert.equal(block.signature, 'c2lnbmF0dXJl');344 assert.equal(block.issues.length, 0);345});346
347test('analyzeSignature flags missing protected', () => {348 const block = analyzeSignature({ signature: 'sig' }, 0);349 assert.ok(block.issues.some((i) => i.includes('protected is missing')));350});351
352test('analyzeSignature flags missing signature field', () => {353 const block = analyzeSignature({ protected: 'hdr' }, 0);354 assert.ok(block.issues.some((i) => i.includes('signature is missing')));355});356
357/* ------------------------------------------------------------------358 * Security schemes tests359 * ---------------------------------------------------------------- */360
361test('analyzeSecuritySchemes returns count 0 for undefined', () => {362 const { count, issues } = analyzeSecuritySchemes(undefined);363 assert.equal(count, 0);364 assert.equal(issues.length, 0);365});366
367test('analyzeSecuritySchemes counts declared schemes', () => {368 const { count, issues } = analyzeSecuritySchemes({369 oauth2: { type: 'oauth2' },370 apiKey: { type: 'apiKey' },371 });372 assert.equal(count, 2);373 assert.equal(issues.length, 0);374});375
376test('analyzeSecuritySchemes flags non-object scheme', () => {377 const { count, issues } = analyzeSecuritySchemes({ bad: 'not-an-object' });378 assert.equal(count, 1);379 assert.ok(issues.some((i) => i.includes('not an object')));380});381
382/* ------------------------------------------------------------------383 * Top-level analyzeAgentCard tests384 * ---------------------------------------------------------------- */385
386const VALID_CARD = {387 name: 'Recipe Agent',388 description: 'Agent that helps users with recipes and cooking.',389 version: '1.0.0',390 supportedInterfaces: [391 { url: 'https://agent.example.com/a2a', protocolBinding: 'JSONRPC', protocolVersion: '1.0' },392 ],393 capabilities: { streaming: true, pushNotifications: false },394 defaultInputModes: ['text/plain'],395 defaultOutputModes: ['text/plain'],396 skills: [397 { id: 'recipes', name: 'Recipes', description: 'Suggest recipes', tags: ['food'], examples: ['What can I cook?'] },398 ],399 provider: { url: 'https://example.com', organization: 'Example Corp' },400 securitySchemes: { oauth2: { type: 'oauth2' } },401};402
403test('analyzeAgentCard accepts a well-formed card with no issues', () => {404 const summary = analyzeAgentCard(VALID_CARD);405 assert.equal(summary.name, 'Recipe Agent');406 assert.equal(summary.interfaceCount, 1);407 assert.equal(summary.skillCount, 1);408 assert.equal(summary.securitySchemeCount, 1);409 assert.equal(summary.issues.length, 0);410});411
412test('analyzeAgentCard flags all missing required fields on empty object', () => {413 const summary = analyzeAgentCard({});414 assert.ok(summary.issues.some((i) => i.includes('name is missing')));415 assert.ok(summary.issues.some((i) => i.includes('description is missing')));416 assert.ok(summary.issues.some((i) => i.includes('version is missing')));417 assert.ok(summary.issues.some((i) => i.includes('supportedInterfaces')));418 assert.ok(summary.issues.some((i) => i.includes('defaultInputModes')));419 assert.ok(summary.issues.some((i) => i.includes('defaultOutputModes')));420 assert.ok(summary.issues.some((i) => i.includes('skills is missing')));421});422
423test('analyzeAgentCard flags non-object input', () => {424 const summary = analyzeAgentCard('not an object');425 assert.ok(summary.issues.some((i) => i.includes('not an object')));426});427
428test('analyzeAgentCard captures documentationUrl and iconUrl', () => {429 const summary = analyzeAgentCard({430 ...VALID_CARD,431 documentationUrl: 'https://docs.example.com',432 iconUrl: 'https://example.com/icon.png',433 });434 assert.equal(summary.documentationUrl, 'https://docs.example.com');435 assert.equal(summary.iconUrl, 'https://example.com/icon.png');436});437
438test('analyzeAgentCard captures signatures', () => {439 const summary = analyzeAgentCard({440 ...VALID_CARD,441 signatures: [{ protected: 'hdr', signature: 'sig' }],442 });443 assert.equal(summary.signatureCount, 1);444 assert.equal(summary.signatures[0].protected, 'hdr');445});446
447/* ------------------------------------------------------------------448 * Scoring tests449 * ---------------------------------------------------------------- */450
451test('scoreAgentCard returns 0 for non-object card', () => {452 const summary = { name: null, issues: ['AgentCard is not an object'], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null, interfaceCount: 0, defaultInputModes: [], defaultOutputModes: [] };453 assert.equal(scoreAgentCard(summary, true), 0);454});455
456test('scoreAgentCard rewards a complete valid card', () => {457 const summary = analyzeAgentCard(VALID_CARD);458 const score = scoreAgentCard(summary, true);459 assert.ok(score > 0 && score <= 100, `expected 0-100, got ${score}`);460});461
462test('scoreAgentCard penalizes issues but not below 0', () => {463 const summary = analyzeAgentCard({ name: 'x', version: '1.0', description: 'd', issues: [] });464 // Empty card has many missing required fields -> issues465 const score = scoreAgentCard(summary, true);466 assert.ok(score >= 0 && score < 100);467});468
469test('scoreAgentCard gives higher score to HTTPS vs HTTP', () => {470 const summary = analyzeAgentCard(VALID_CARD);471 const httpsScore = scoreAgentCard(summary, true);472 const httpScore = scoreAgentCard(summary, false);473 assert.ok(httpsScore > httpScore, 'HTTPS should score higher');474});475
476test('gradeFromScore returns expected letter grades', () => {477 assert.equal(gradeFromScore(100), 'A+');478 assert.equal(gradeFromScore(90), 'A');479 assert.equal(gradeFromScore(80), 'B');480 assert.equal(gradeFromScore(70), 'C');481 assert.equal(gradeFromScore(55), 'D');482 assert.equal(gradeFromScore(40), 'E');483 assert.equal(gradeFromScore(10), 'F');484});485
486/* ------------------------------------------------------------------487 * Recommendations tests488 * ---------------------------------------------------------------- */489
490test('buildRecommendations suggests HTTPS when not HTTPS', () => {491 const summary = { name: 'x', issues: [], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null };492 const recs = buildRecommendations(summary, 50, false, 200, null);493 assert.ok(recs.some((r) => r.includes('HTTPS')));494});495
496test('buildRecommendations suggests fixing JSON for invalid JSON issue', () => {497 const summary = { name: null, issues: ['invalid JSON: unexpected token'], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null };498 const recs = buildRecommendations(summary, 0, true, 200, null);499 assert.ok(recs.some((r) => r.includes('valid JSON object')));500});501
502test('buildRecommendations suggests creating endpoint for 404', () => {503 const summary = { name: null, issues: [], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null };504 const recs = buildRecommendations(summary, 0, true, 404, null);505 assert.ok(recs.some((r) => r.includes('404')));506});507
508test('buildRecommendations positive close when clean', () => {509 const summary = analyzeAgentCard(VALID_CARD);510 const recs = buildRecommendations(summary, 95, true, 200, { isA2aJson: true, isJson: false, isHtml: false, issues: [], contentType: 'application/a2a+json' });511 assert.ok(recs.some((r) => r.includes('well-structured')));512});513
514test('buildRecommendations suggests declaring securitySchemes when absent', () => {515 const summary = { name: 'x', issues: [], skills: [], capabilities: null, provider: null, securitySchemeCount: 0, signatureCount: 0, documentationUrl: null };516 const recs = buildRecommendations(summary, 50, true, 200, null);517 assert.ok(recs.some((r) => r.includes('securitySchemes')));518});