@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/a2a/http.js

@@ -0,0 +1,193 @@
+// HTTP wrapper for A2A client + v1 fallback.
+//
+// Responsibilities:
+//   - Bearer auth header injection
+//   - A2A-Extensions header injection on every mutating call (#1254)
+//   - Echo-verification warning when expected extensions are missing
+//   - Idempotent-Replayed surfacing as a typed flag on the response
+//   - RFC 7807 problem+json error parsing → typed `A2AError`
+//   - Sunset / Deprecated / Link rel=successor-version header capture
+//     for #1259 (deprecation telemetry — uses callbacks so the Prometheus
+//     counter and structured logger plug in without coupling to the
+//     telemetry module)
+//   - Optional fail-on-deprecated mode (AIWG_FAIL_ON_DEPRECATED=true)
+export class A2AError extends Error {
+    status;
+    problem;
+    path;
+    constructor(status, path, problem) {
+        super(`${status} ${problem.code ?? problem.title}: ${problem.detail ?? problem.title}`);
+        this.name = 'A2AError';
+        this.status = status;
+        this.problem = problem;
+        this.path = path;
+    }
+}
+const MUTATING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+export class A2AHttpClient {
+    baseUrl;
+    bearer;
+    defaultExtensions;
+    failOnDeprecated;
+    fetchImpl;
+    onDeprecation;
+    onExtensionEchoMissing;
+    /** Per-process dedupe set: one log per (path, sunset_date). */
+    seenDeprecations = new Set();
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this.bearer = opts.bearer;
+        this.defaultExtensions = opts.defaultExtensions ?? [];
+        this.failOnDeprecated = opts.failOnDeprecated ?? false;
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.onDeprecation = opts.onDeprecation;
+        this.onExtensionEchoMissing = opts.onExtensionEchoMissing;
+    }
+    async request(path, options = {}) {
+        const method = (options.method ?? 'GET').toUpperCase();
+        const url = path.startsWith('http') ? path : this.baseUrl + path;
+        const headers = {
+            authorization: `Bearer ${options.bearer ?? this.bearer}`,
+            accept: 'application/json',
+        };
+        if (options.body !== undefined && options.bodyRaw === undefined) {
+            headers['content-type'] = 'application/json';
+        }
+        // Inject A2A-Extensions on mutating calls. Caller can override with
+        // options.extensions (empty array clears injection).
+        if (MUTATING_METHODS.has(method)) {
+            const exts = options.extensions ?? this.defaultExtensions;
+            if (exts.length > 0) {
+                headers['a2a-extensions'] = exts.join(', ');
+            }
+        }
+        // Caller overrides last so explicit headers win.
+        if (options.headers) {
+            for (const [k, v] of Object.entries(options.headers)) {
+                headers[k.toLowerCase()] = v;
+            }
+        }
+        const init = { method, headers, signal: options.signal };
+        if (options.bodyRaw !== undefined) {
+            init.body = options.bodyRaw;
+        }
+        else if (options.body !== undefined) {
+            init.body = JSON.stringify(options.body);
+        }
+        const resp = await this.fetchImpl(url, init);
+        // Capture deprecation headers regardless of status.
+        const deprecation = captureDeprecation(path, resp.headers);
+        if (deprecation) {
+            const key = `${deprecation.path}|${deprecation.sunset ?? ''}`;
+            if (!this.seenDeprecations.has(key)) {
+                this.seenDeprecations.add(key);
+                if (this.onDeprecation)
+                    this.onDeprecation(deprecation);
+            }
+            if (this.failOnDeprecated) {
+                throw new A2AError(resp.status, path, {
+                    type: 'about:blank',
+                    title: 'Deprecated endpoint',
+                    detail: `AIWG_FAIL_ON_DEPRECATED is set; ${path} is deprecated (sunset=${deprecation.sunset ?? '?'})`,
+                    code: 'aiwg.deprecation_strict',
+                });
+            }
+        }
+        const idempotentReplayed = (resp.headers.get('idempotent-replayed') ?? '')
+            .toLowerCase()
+            .includes('true');
+        const activatedExtensions = parseExtensionList(resp.headers.get('a2a-extensions'));
+        // Warn if mutating call requested extensions that weren't echoed.
+        if (MUTATING_METHODS.has(method)) {
+            const requested = options.extensions ?? this.defaultExtensions;
+            if (requested.length > 0) {
+                const missing = requested.filter((e) => !activatedExtensions.includes(e));
+                if (missing.length > 0 && this.onExtensionEchoMissing) {
+                    this.onExtensionEchoMissing(requested, activatedExtensions, path);
+                }
+            }
+        }
+        if (options.raw) {
+            return {
+                status: resp.status,
+                body: undefined,
+                headers: resp.headers,
+                idempotentReplayed,
+                activatedExtensions,
+                rawBody: resp.body,
+                ...(deprecation ? { deprecation } : {}),
+            };
+        }
+        // Parse body (JSON, problem+json, or empty).
+        let body;
+        const ct = resp.headers.get('content-type') ?? '';
+        if (resp.status !== 204 && resp.status !== 205) {
+            const text = await resp.text();
+            if (text.length > 0) {
+                if (ct.includes('json')) {
+                    try {
+                        body = JSON.parse(text);
+                    }
+                    catch (err) {
+                        throw new A2AError(resp.status, path, {
+                            type: 'about:blank',
+                            title: 'Invalid JSON',
+                            detail: `Response was not parseable JSON: ${err.message}`,
+                            code: 'aiwg.invalid_response',
+                        });
+                    }
+                }
+                else {
+                    body = text;
+                }
+            }
+        }
+        if (resp.status >= 400) {
+            const problem = body ?? {
+                type: 'about:blank',
+                title: `HTTP ${resp.status}`,
+            };
+            throw new A2AError(resp.status, path, problem);
+        }
+        return {
+            status: resp.status,
+            body,
+            headers: resp.headers,
+            idempotentReplayed,
+            activatedExtensions,
+            ...(deprecation ? { deprecation } : {}),
+        };
+    }
+}
+// ---------- header helpers ----------
+function parseExtensionList(header) {
+    if (!header)
+        return [];
+    return header
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function captureDeprecation(path, headers) {
+    const sunset = headers.get('sunset') ?? undefined;
+    const deprecated = headers.get('deprecated') ?? undefined;
+    const link = headers.get('link') ?? undefined;
+    if (!sunset && !deprecated && !link)
+        return undefined;
+    let successor;
+    if (link) {
+        // Match the `successor-version` rel target — RFC 5988 Link entries are
+        // comma-separated; we look for `rel="successor-version"` or `rel=successor-version`.
+        const re = /<([^>]+)>\s*;\s*[^,]*rel\s*=\s*"?successor-version"?/i;
+        const m = re.exec(link);
+        if (m)
+            successor = m[1];
+    }
+    return {
+        path,
+        ...(sunset ? { sunset } : {}),
+        ...(deprecated ? { deprecated } : {}),
+        ...(successor ? { successor } : {}),
+    };
+}
+//# sourceMappingURL=http.js.map

package/dist/src/a2a/jcs.js

@@ -0,0 +1,128 @@
+// JCS (RFC 8785) canonicalization — TypeScript port of the Go reference at
+// agentic-sandbox-conformance/internal/spec/jcs.go.
+//
+// Sufficient for the AgentCard shape: objects, strings, integers, booleans,
+// null, arrays, and JSON numbers without exponential form. Numbers are emitted
+// in a form that matches serde_json output for integers and short decimals
+// (the only forms `agent_card::sign_agent_card` produces today).
+const encoder = new TextEncoder();
+export function canonicalizeJsonBytes(input) {
+    const text = typeof input === 'string' ? input : new TextDecoder('utf-8').decode(input);
+    const value = JSON.parse(text);
+    return canonicalizeJson(value);
+}
+export function canonicalizeJson(value) {
+    const chunks = [];
+    writeCanonical(chunks, value);
+    return encoder.encode(chunks.join(''));
+}
+export function canonicalizeJsonString(value) {
+    const chunks = [];
+    writeCanonical(chunks, value);
+    return chunks.join('');
+}
+function writeCanonical(out, value) {
+    if (value === null) {
+        out.push('null');
+        return;
+    }
+    if (typeof value === 'boolean') {
+        out.push(value ? 'true' : 'false');
+        return;
+    }
+    if (typeof value === 'string') {
+        writeCanonicalString(out, value);
+        return;
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error(`JCS: non-finite number ${value}`);
+        }
+        if (Number.isInteger(value)) {
+            out.push(value.toString(10));
+        }
+        else {
+            // Shortest round-trip representation; matches Go strconv -1 precision
+            // for the common cases in the AgentCard shape (it has no exotic doubles).
+            out.push(String(value));
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        out.push('[');
+        for (let i = 0; i < value.length; i++) {
+            if (i > 0)
+                out.push(',');
+            writeCanonical(out, value[i]);
+        }
+        out.push(']');
+        return;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).sort(compareUtf16);
+        out.push('{');
+        for (let i = 0; i < keys.length; i++) {
+            if (i > 0)
+                out.push(',');
+            const k = keys[i];
+            writeCanonicalString(out, k);
+            out.push(':');
+            writeCanonical(out, value[k]);
+        }
+        out.push('}');
+        return;
+    }
+    throw new Error(`JCS: unsupported type ${typeof value}`);
+}
+// Strings per RFC 8785 §3.2.2.2 / RFC 8259. Escape " \ and control chars (\u00xx).
+// Slash is NOT escaped. Non-ASCII characters are emitted as raw UTF-8.
+function writeCanonicalString(out, s) {
+    out.push('"');
+    for (let i = 0; i < s.length; i++) {
+        const ch = s.charCodeAt(i);
+        switch (ch) {
+            case 0x22: // "
+                out.push('\\"');
+                break;
+            case 0x5c: // \
+                out.push('\\\\');
+                break;
+            case 0x08:
+                out.push('\\b');
+                break;
+            case 0x0c:
+                out.push('\\f');
+                break;
+            case 0x0a:
+                out.push('\\n');
+                break;
+            case 0x0d:
+                out.push('\\r');
+                break;
+            case 0x09:
+                out.push('\\t');
+                break;
+            default:
+                if (ch < 0x20) {
+                    out.push('\\u' + ch.toString(16).padStart(4, '0'));
+                }
+                else {
+                    // Emit raw character; JS strings are already UTF-16 and TextEncoder
+                    // will produce UTF-8 bytes on encode.
+                    out.push(s[i]);
+                }
+        }
+    }
+    out.push('"');
+}
+// Compare two strings by their UTF-16 code-unit sequences (RFC 8785 §3.2.3).
+// JS string comparison is already lexicographic over UTF-16 code units, so a
+// plain compare suffices.
+function compareUtf16(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+//# sourceMappingURL=jcs.js.map

package/dist/src/a2a/jws.js

@@ -0,0 +1,187 @@
+// JWS Compact (RFC 7515) verification with EdDSA / Ed25519 support.
+// TypeScript port of agentic-sandbox-conformance/internal/spec/jws.go.
+//
+// The Rust signer (`agent_card::sign_agent_card` in agentic-sandbox) produces
+// non-detached JWS: the middle segment IS the base64url-encoded canonical
+// payload bytes. `verifyJwsCompact` cross-checks that against an
+// independently-canonicalized `expectedPayload` when provided.
+import { createHash, createPublicKey, verify as cryptoVerify } from 'node:crypto';
+import { canonicalizeJson } from './jcs.js';
+export function findJwkByKid(set, kid) {
+    if (!set)
+        return null;
+    for (const k of set.keys)
+        if (k.kid === kid)
+            return k;
+    return null;
+}
+// RFC 7638 thumbprint for OKP keys: SHA-256 over the canonical
+// { crv, kty, x } object, base64url-encoded.
+export function jwkThumbprint(jwk) {
+    if (jwk.kty !== 'OKP') {
+        throw new Error(`thumbprint: unsupported kty ${jwk.kty}`);
+    }
+    if (!jwk.crv || !jwk.x)
+        throw new Error('thumbprint: OKP key missing crv/x');
+    const canon = canonicalizeJson({ crv: jwk.crv, kty: jwk.kty, x: jwk.x });
+    const sum = createHash('sha256').update(canon).digest();
+    return base64UrlEncode(sum);
+}
+export function loadJwkSet(json) {
+    const parsed = JSON.parse(json);
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        !Array.isArray(parsed.keys)) {
+        throw new Error('JWKS: missing keys array');
+    }
+    const set = parsed;
+    if (set.keys.length === 0)
+        throw new Error('JWKS contains no keys');
+    return set;
+}
+// VerifyJwsCompact verifies a JWS Compact serialization.
+//
+// If `expectedPayload` is provided, the embedded payload bytes must match it
+// (constant-time compare). This is how the AgentCard verifier guarantees that
+// the JCS-canonicalized bytes the harness computed match what was signed.
+//
+// Throws on any verification failure with a descriptive message.
+export function verifyJwsCompact(jws, expectedPayload, jwk) {
+    if (!jwk)
+        throw new Error('verifyJwsCompact: nil JWK');
+    const parts = jws.split('.');
+    if (parts.length !== 3) {
+        throw new Error(`verifyJwsCompact: expected 3 segments, got ${parts.length}`);
+    }
+    const [headerB64, payloadB64, sigB64] = parts;
+    let header;
+    try {
+        const headerRaw = base64UrlDecode(headerB64);
+        header = JSON.parse(new TextDecoder('utf-8').decode(headerRaw));
+    }
+    catch (err) {
+        throw new Error(`verifyJwsCompact: parse header: ${err.message}`);
+    }
+    let payload;
+    let sig;
+    try {
+        payload = base64UrlDecode(payloadB64);
+        sig = base64UrlDecode(sigB64);
+    }
+    catch (err) {
+        throw new Error(`verifyJwsCompact: decode segments: ${err.message}`);
+    }
+    if (expectedPayload !== null) {
+        if (!constantTimeEqual(payload, expectedPayload)) {
+            throw new Error(`JWS payload does not match expected canonical bytes (got ${payload.length} bytes, want ${expectedPayload.length})`);
+        }
+    }
+    const signingInput = new TextEncoder().encode(headerB64 + '.' + payloadB64);
+    if (header.alg !== 'EdDSA') {
+        throw new Error(`unsupported JWS alg ${header.alg} (only EdDSA supported)`);
+    }
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+        throw new Error(`EdDSA: JWK is not OKP/Ed25519 (kty=${jwk.kty} crv=${jwk.crv ?? '?'})`);
+    }
+    if (!jwk.x)
+        throw new Error('EdDSA: JWK missing x');
+    const pubRaw = base64UrlDecode(jwk.x);
+    if (pubRaw.length !== 32) {
+        throw new Error(`EdDSA: public key wrong length ${pubRaw.length} (want 32)`);
+    }
+    // Node's crypto requires SPKI-wrapped Ed25519 keys. Build one from the raw
+    // 32-byte X coordinate.
+    const spki = wrapEd25519Spki(pubRaw);
+    const key = createPublicKey({ key: spki, format: 'der', type: 'spki' });
+    const ok = cryptoVerify(null, signingInput, key, sig);
+    if (!ok)
+        throw new Error('EdDSA signature verification failed');
+}
+// VerifyAgentCardSignature is the high-level helper: extracts signatures[0],
+// strips the `signatures` field from a deep clone, JCS-canonicalizes the rest,
+// looks up the JWK by kid, and verifies via verifyJwsCompact.
+//
+// `cardJson` is the raw JSON bytes (or string) of the AgentCard as served.
+export function verifyAgentCardSignature(cardJson, jwks) {
+    const text = typeof cardJson === 'string' ? cardJson : new TextDecoder('utf-8').decode(cardJson);
+    if (!text || text.length === 0) {
+        throw new Error('verifyAgentCardSignature: empty card body');
+    }
+    let card;
+    try {
+        card = JSON.parse(text);
+    }
+    catch (err) {
+        throw new Error(`parse card JSON: ${err.message}`);
+    }
+    const sigsRaw = card['signatures'];
+    if (sigsRaw === undefined)
+        throw new Error("agent card has no 'signatures' field");
+    if (!Array.isArray(sigsRaw) || sigsRaw.length === 0) {
+        throw new Error("agent card 'signatures' is empty or not an array");
+    }
+    const first = sigsRaw[0];
+    if (!first || typeof first !== 'object') {
+        throw new Error('signatures[0] is not an object');
+    }
+    const compact = first['signature'];
+    if (typeof compact !== 'string' || !compact) {
+        throw new Error('signatures[0].signature missing or not a string');
+    }
+    const hdr = first['header'];
+    if (!hdr || typeof hdr !== 'object' || Array.isArray(hdr)) {
+        throw new Error('signatures[0].header missing');
+    }
+    const kid = hdr['kid'];
+    if (typeof kid !== 'string' || !kid) {
+        throw new Error('signatures[0].header.kid missing');
+    }
+    const jwk = findJwkByKid(jwks, kid);
+    if (!jwk)
+        throw new Error(`no JWK matches kid=${kid}`);
+    // Build the unsigned form.
+    const unsigned = {};
+    for (const [k, v] of Object.entries(card)) {
+        if (k === 'signatures')
+            continue;
+        unsigned[k] = v;
+    }
+    const canonical = canonicalizeJson(unsigned);
+    verifyJwsCompact(compact, canonical, jwk);
+}
+// ---------- internal helpers ----------
+function base64UrlDecode(input) {
+    // Convert base64url -> base64 and pad.
+    const b64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = b64.length % 4 === 0 ? '' : '='.repeat(4 - (b64.length % 4));
+    return new Uint8Array(Buffer.from(b64 + pad, 'base64'));
+}
+function base64UrlEncode(bytes) {
+    return Buffer.from(bytes)
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+// SPKI wrapper for raw 32-byte Ed25519 public keys.
+// SubjectPublicKeyInfo ::= SEQUENCE {
+//   algorithm   AlgorithmIdentifier (id-Ed25519 = 1.3.101.112),
+//   subjectPublicKey BIT STRING (raw 32 bytes),
+// }
+// Pre-computed prefix (12 bytes): 30 2a 30 05 06 03 2b 65 70 03 21 00
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+function wrapEd25519Spki(raw) {
+    if (raw.length !== 32)
+        throw new Error('Ed25519 raw key must be 32 bytes');
+    return Buffer.concat([ED25519_SPKI_PREFIX, Buffer.from(raw)]);
+}
+//# sourceMappingURL=jws.js.map

package/dist/src/a2a/types.js

@@ -0,0 +1,24 @@
+// A2A protocol types — the subset AIWG needs to talk to an agentic-sandbox v2
+// executor. Modelled from the executor's wire surface
+// (`agentic-sandbox/management/agentic-sandbox-executor`):
+//
+//   - send_message.rs   — POST /agents/{id}/v1/messages:send
+//   - get_task.rs       — GET  /agents/{id}/v1/tasks/{tid}
+//   - cancel_task.rs    — POST /agents/{id}/v1/tasks/{tid}/cancel
+//   - subscribe_task    — GET  /agents/{id}/v1/tasks/{tid}/subscribe (SSE)
+//   - push_delivery.rs  — *   /agents/{id}/v1/tasks/{tid}/pushNotificationConfigs/*
+//   - agent_card.rs     — GET  /agents/{id}/.well-known/agent-card.json
+//                          GET  /agents/{id}/v1/extendedAgentCard
+//
+// Types are intentionally permissive (extra fields allowed). We track only
+// what the AIWG orchestrator inspects; the rest is forwarded opaquely.
+export const TERMINAL_TASK_STATES = [
+    'completed',
+    'failed',
+    'canceled',
+    'rejected',
+];
+export function isTerminalTaskState(s) {
+    return TERMINAL_TASK_STATES.includes(s);
+}
+//# sourceMappingURL=types.js.map