@agenticprimitives/agent-profile 1.0.0-alpha.21 → 1.0.0-alpha.23

package/dist/a2a/jws.js

@@ -0,0 +1,186 @@
+/**
+ * Standard A2A card signatures: detached JWS over the canonical card bytes (spec 347 §4.2).
+ *
+ *   signing input = base64url(protected) "." base64url(canonicalCardBytes)
+ *   protected     = { alg: 'ES256' | 'EdDSA', kid: <RFC 7638 JWK thumbprint> }
+ *
+ * WebCrypto only (`globalThis.crypto.subtle`, Node ≥ 20 and workerd) — no `jose`. ES256 (P-256) is the
+ * Ring-0 default; EdDSA is used only when the runtime can do it (`supportsEdDSA()`), never required.
+ *
+ * Verification is FAIL-CLOSED (ADR-0013): no signatures, an unknown `kid`, an unsupported `alg`, a header
+ * that cannot be parsed, or any bad signature ⇒ `ok: false`. A non-AP A2A client verifies these signatures
+ * and never needs the Smart Agent binding (`binding.ts`).
+ */
+import { jcsCanonicalize } from '@agenticprimitives/types';
+import { canonicalCardBytes } from './canonical.js';
+// ─── base64url ───────────────────────────────────────────────────────────────────────────────────────
+export function base64UrlEncode(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+export function base64UrlDecode(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        throw new Error('invalid base64url');
+    const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (s.length % 4)) % 4);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+const utf8 = new TextEncoder();
+const utf8dec = new TextDecoder();
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle)
+        throw new Error('WebCrypto (crypto.subtle) is not available in this runtime');
+    return c.subtle;
+}
+// ─── JWK thumbprint (RFC 7638) ───────────────────────────────────────────────────────────────────────
+/** RFC 7638 thumbprint: sha256 over the JCS of the REQUIRED public members only, base64url. */
+export async function jwkThumbprint(jwk) {
+    let required;
+    switch (jwk.kty) {
+        case 'EC':
+            required = { crv: must(jwk.crv, 'crv'), kty: 'EC', x: must(jwk.x, 'x'), y: must(jwk.y, 'y') };
+            break;
+        case 'OKP':
+            required = { crv: must(jwk.crv, 'crv'), kty: 'OKP', x: must(jwk.x, 'x') };
+            break;
+        case 'RSA':
+            required = { e: must(jwk.e, 'e'), kty: 'RSA', n: must(jwk.n, 'n') };
+            break;
+        default:
+            throw new Error(`jwkThumbprint: unsupported kty "${String(jwk.kty)}"`);
+    }
+    const digest = await subtle().digest('SHA-256', utf8.encode(jcsCanonicalize(required)));
+    return base64UrlEncode(new Uint8Array(digest));
+}
+function must(v, name) {
+    if (typeof v !== 'string' || v.length === 0)
+        throw new Error(`jwkThumbprint: missing JWK member "${name}"`);
+    return v;
+}
+// ─── Keys ────────────────────────────────────────────────────────────────────────────────────────────
+/** Is EdDSA (Ed25519) usable here? Feature-detected, never assumed (workerd has no Ed25519). */
+export async function supportsEdDSA() {
+    try {
+        await subtle().generateKey({ name: 'Ed25519' }, false, ['sign', 'verify']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a card-signing key pair. ES256 by default; `EdDSA` throws where the runtime lacks it. */
+export async function generateA2ACardSigningKey(alg = 'ES256') {
+    const s = subtle();
+    const params = alg === 'ES256' ? { name: 'ECDSA', namedCurve: 'P-256' } : { name: 'Ed25519' };
+    const pair = (await s.generateKey(params, true, ['sign', 'verify']));
+    const publicJwk = await s.exportKey('jwk', pair.publicKey);
+    delete publicJwk.key_ops;
+    delete publicJwk.ext;
+    return { alg, privateKey: pair.privateKey, publicKey: pair.publicKey, publicJwk, kid: await jwkThumbprint(publicJwk) };
+}
+/** Import a public JWK as a verification key for `alg`. */
+export async function importVerificationKey(jwk, alg) {
+    const params = alg === 'ES256' ? { name: 'ECDSA', namedCurve: 'P-256' } : { name: 'Ed25519' };
+    return subtle().importKey('jwk', jwk, params, true, ['verify']);
+}
+function signParams(alg) {
+    return alg === 'ES256' ? { name: 'ECDSA', hash: 'SHA-256' } : { name: 'Ed25519' };
+}
+/** Sign the canonical card bytes; returns the card with the signature appended. Pure apart from the key op. */
+export async function signA2ACard(card, opts) {
+    const alg = opts.alg ?? 'ES256';
+    if (!opts.kid)
+        throw new Error('signA2ACard: kid is required');
+    const protectedHeader = base64UrlEncode(utf8.encode(jcsCanonicalize({ alg, kid: opts.kid })));
+    const payload = base64UrlEncode(canonicalCardBytes(card));
+    const signingInput = utf8.encode(`${protectedHeader}.${payload}`);
+    const sig = new Uint8Array(await subtle().sign(signParams(alg), opts.privateKey, signingInput));
+    const signature = { protected: protectedHeader, signature: base64UrlEncode(sig) };
+    const existing = Array.isArray(card.signatures) ? card.signatures : [];
+    return {
+        card: { ...card, signatures: [...existing, signature] },
+        signature,
+        compact: `${protectedHeader}..${signature.signature}`,
+        payload,
+    };
+}
+/** Re-derive the canonical bytes and verify every signature entry. Fail-closed. */
+export async function verifyA2ACardSignatures(card, opts) {
+    const verified = [];
+    const failures = [];
+    const sigs = card.signatures;
+    if (!Array.isArray(sigs) || sigs.length === 0) {
+        return { ok: false, verified, failures: [{ kid: '', reason: 'no_signatures' }] };
+    }
+    let payload;
+    try {
+        payload = base64UrlEncode(canonicalCardBytes(card));
+    }
+    catch {
+        return { ok: false, verified, failures: [{ kid: '', reason: 'bad_entry' }] };
+    }
+    for (const entry of sigs) {
+        const e = entry;
+        if (!e || typeof e.protected !== 'string' || typeof e.signature !== 'string') {
+            failures.push({ kid: '', reason: 'bad_entry' });
+            continue;
+        }
+        let header;
+        try {
+            header = JSON.parse(utf8dec.decode(base64UrlDecode(e.protected)));
+        }
+        catch {
+            failures.push({ kid: '', reason: 'bad_protected_header' });
+            continue;
+        }
+        const kid = typeof header.kid === 'string' ? header.kid : '';
+        if (!kid) {
+            failures.push({ kid: '', reason: 'bad_protected_header' });
+            continue;
+        }
+        const alg = header.alg;
+        if (alg !== 'ES256' && alg !== 'EdDSA') {
+            failures.push({ kid, reason: 'unsupported_alg' });
+            continue;
+        }
+        const resolved = await opts.keys(kid);
+        if (!resolved) {
+            failures.push({ kid, reason: 'unknown_kid' });
+            continue;
+        }
+        let key;
+        try {
+            key = isCryptoKey(resolved) ? resolved : await importVerificationKey(resolved, alg);
+        }
+        catch {
+            failures.push({ kid, reason: 'key_import_failed' });
+            continue;
+        }
+        let valid = false;
+        try {
+            valid = await subtle().verify(signParams(alg), key, base64UrlDecode(e.signature), utf8.encode(`${e.protected}.${payload}`));
+        }
+        catch {
+            valid = false;
+        }
+        if (valid)
+            verified.push(kid);
+        else
+            failures.push({ kid, reason: 'signature_invalid' });
+    }
+    return { ok: failures.length === 0 && verified.length > 0, verified, failures };
+}
+function isCryptoKey(k) {
+    return typeof k.type === 'string' && typeof k.algorithm === 'object' && !('kty' in k);
+}
+/** Decode a signature entry's protected header (`alg`, `kid`) without verifying anything. */
+export function decodeProtectedHeader(entry) {
+    return JSON.parse(utf8dec.decode(base64UrlDecode(entry.protected)));
+}
+//# sourceMappingURL=jws.js.map

package/dist/a2a/jws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jws.js","sourceRoot":"","sources":["../../src/a2a/jws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAiB,MAAM,gBAAgB,CAAC;AAKnE,wGAAwG;AAExG,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,IAAI,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,CAAC;IAC7E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;IACtE,MAAM,GAAG,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;IACtB,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAChE,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC;AAC/B,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,SAAS,MAAM;IACb,MAAM,CAAC,GAAI,UAAkC,CAAC,MAAM,CAAC;IACrD,IAAI,CAAC,CAAC,EAAE,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAC9F,OAAO,CAAC,CAAC,MAAM,CAAC;AAClB,CAAC;AAED,wGAAwG;AAExG,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAe;IACjD,IAAI,QAAgC,CAAC;IACrC,QAAQ,GAAG,CAAC,GAAG,EAAE,CAAC;QAChB,KAAK,IAAI;YACP,QAAQ,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YAC9F,MAAM;QACR,KAAK,KAAK;YACR,QAAQ,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YAC1E,MAAM;QACR,KAAK,KAAK;YACR,QAAQ,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;YACpE,MAAM;QACR;YACE,MAAM,IAAI,KAAK,CAAC,mCAAmC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;IACxF,OAAO,eAAe,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,IAAI,CAAC,CAAqB,EAAE,IAAY;IAC/C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,IAAI,GAAG,CAAC,CAAC;IAC5G,OAAO,CAAC,CAAC;AACX,CAAC;AAED,wGAAwG;AAExG,gGAAgG;AAChG,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,IAAI,CAAC;QACH,MAAM,MAAM,EAAE,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,SAAS,EAAe,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;QACxF,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAWD,qGAAqG;AACrG,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,MAAqB,OAAO;IAC1E,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;IACnB,MAAM,MAAM,GACV,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,SAAS,EAAgB,CAAC;IAChG,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAkB,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3D,OAAQ,SAAmC,CAAC,OAAO,CAAC;IACpD,OAAQ,SAA+B,CAAC,GAAG,CAAC;IAC5C,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;AACzH,CAAC;AAED,2DAA2D;AAC3D,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAe,EAAE,GAAkB;IAC7E,MAAM,MAAM,GACV,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,SAAS,EAAgB,CAAC;IAChG,OAAO,MAAM,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,SAAS,UAAU,CAAC,GAAkB;IACpC,OAAO,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,SAAS,EAAgB,CAAC;AACnG,CAAC;AAqBD,+GAA+G;AAC/G,MAAM,CAAC,KAAK,UAAU,WAAW,CAAqB,IAAO,EAAE,IAAwB;IACrF,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;IAC/D,MAAM,eAAe,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9F,MAAM,OAAO,GAAG,eAAe,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,eAAe,IAAI,OAAO,EAAE,CAAC,CAAC;IAClE,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,MAAM,MAAM,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC;IAChG,MAAM,SAAS,GAA4B,EAAE,SAAS,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3G,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAE,IAAI,CAAC,UAAwC,CAAC,CAAC,CAAC,EAAE,CAAC;IACtG,OAAO;QACL,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,CAAC,GAAG,QAAQ,EAAE,SAAS,CAAC,EAAE;QACvD,SAAS;QACT,OAAO,EAAE,GAAG,eAAe,KAAK,SAAS,CAAC,SAAS,EAAE;QACrD,OAAO;KACR,CAAC;AACJ,CAAC;AA2BD,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAA+B,EAC/B,IAAoC;IAEpC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAA8C,EAAE,CAAC;IAC/D,MAAM,IAAI,GAAI,IAAiB,CAAC,UAAU,CAAC;IAC3C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,EAAE,CAAC;IACnF,CAAC;IACD,IAAI,OAAe,CAAC;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,eAAe,CAAC,kBAAkB,CAAC,IAAgB,CAAC,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAC/E,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,IAAiB,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,KAAgD,CAAC;QAC3D,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YAChD,SAAS;QACX,CAAC;QACD,IAAI,MAAwC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAqC,CAAC;QACxG,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACvB,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;YAClD,SAAS;QACX,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;YAC9C,SAAS;QACX,CAAC;QACD,IAAI,GAAc,CAAC;QACnB,IAAI,CAAC;YACH,GAAG,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,qBAAqB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACtF,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;YACpD,SAAS;QACX,CAAC;QACD,IAAI,KAAK,GAAG,KAAK,CAAC;QAClB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,MAAM,EAAE,CAAC,MAAM,CAC3B,UAAU,CAAC,GAAG,CAAC,EACf,GAAG,EACH,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC,EAC5B,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,IAAI,OAAO,EAAE,CAAC,CACzC,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,KAAK,GAAG,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,KAAK;YAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;;YACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAClF,CAAC;AAED,SAAS,WAAW,CAAC,CAAyB;IAC5C,OAAO,OAAQ,CAAe,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAQ,CAAe,CAAC,SAAS,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;AACtH,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,qBAAqB,CAAC,KAA8B;IAClE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAmC,CAAC;AACxG,CAAC"}

package/dist/a2a/playbook-binding.d.ts

@@ -0,0 +1,29 @@
+import type { A2AAgentCardV1, A2AAgentExtensionV1 } from './types.js';
+/** The A2A extension URI a released card carries when its playbook is public. */
+/** The extension's URI, under the substrate's own namespace like every other AP extension (`agenticprimitives.org/a2a/<name>/v1`) —
+ *  a package names no deployment domain (ADR-0021). */
+export declare const PLAYBOOK_BINDING_EXT_URI = "https://agenticprimitives.org/a2a/playbook-binding/v1";
+export interface PlaybookBindingV1 {
+    /** Canonical skill id of the archetype (`skill:<ns>/<name>`). */
+    archetypeId: string;
+    /** Exact version — NEVER 'latest' (spec 340 pinning; a historical record naming 'latest' drifts). */
+    archetypeVersion: string;
+    /** The compiled AgentHarnessDefinitionV1 digest — the content commitment verified against the corpus. */
+    definitionDigest: string;
+}
+/** Build the `capabilities.extensions[]` entry that binds a playbook to a card release. */
+export declare function playbookBindingExtension(binding: PlaybookBindingV1): A2AAgentExtensionV1;
+/** Read the playbook binding off a card, or null when it carries none / carries a malformed one. */
+export declare function readPlaybookBinding(card: Pick<A2AAgentCardV1, 'capabilities'>): PlaybookBindingV1 | null;
+/** Add (or replace) the playbook binding on a card's capabilities, returning a NEW card (cards are
+ *  immutable once released; this builds the content a release will sign). */
+export declare function withPlaybookBinding(card: A2AAgentCardV1, binding: PlaybookBindingV1): A2AAgentCardV1;
+/** Among an agent's card releases, the one whose card binds this exact definition digest — the release a
+ *  Home cites as "Bound to release r-N". Newest matching release wins (highest releaseNumber). Reads the
+ *  signed card when present (that is what the world sees), else the unsigned one. */
+export declare function playbookBoundRelease<R extends {
+    releaseNumber: number;
+    signedCard?: Pick<A2AAgentCardV1, 'capabilities'>;
+    unsignedCard: Pick<A2AAgentCardV1, 'capabilities'>;
+}>(releases: readonly R[], definitionDigest: string): R | null;
+//# sourceMappingURL=playbook-binding.d.ts.map

package/dist/a2a/playbook-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-binding.d.ts","sourceRoot":"","sources":["../../src/a2a/playbook-binding.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtE,iFAAiF;AACjF;uDACuD;AACvD,eAAO,MAAM,wBAAwB,0DAA0D,CAAC;AAEhG,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,gBAAgB,EAAE,MAAM,CAAC;IACzB,yGAAyG;IACzG,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,GAAG,mBAAmB,CASxF;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAWxG;AAED;6EAC6E;AAC7E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,iBAAiB,GAAG,cAAc,CAMpG;AAED;;qFAEqF;AACrF,wBAAgB,oBAAoB,CAClC,CAAC,SAAS;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAAC,YAAY,EAAE,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,CAAA;CAAE,EAC1I,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,gBAAgB,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAO5D"}

package/dist/a2a/playbook-binding.js

@@ -0,0 +1,65 @@
+// spec 354 K6 — the PLAYBOOK BINDING on a released A2A card.
+//
+// An agent's archetype assignment is a PRIVATE vault record (behavior is private posture; an org may not
+// want its playbook public — spec 354 §2). When the steward chooses to make it public, a card release
+// carries the compiled definition's digest as an A2A capability EXTENSION. The A2A 1.0 card model is
+// closed at the top level, so the binding rides `capabilities.extensions[]` — the same mechanism the
+// payment-gate and skill-provenance extensions use — never an off-spec top-level field.
+//
+// The binding is DISCLOSURE + VERIFIABILITY, never authority: it names WHICH playbook version a released
+// card promises (canonical skill id + version + definition digest), so the world can verify that version
+// against the corpus's Merkle root. It grants nothing; a playbook is never authority (spec 354 §1). The
+// digest IS the content commitment — a verifier re-derives the definition digest and checks THAT against
+// the corpus, exactly as `skill-provenance/v1` does at run time.
+/** The A2A extension URI a released card carries when its playbook is public. */
+/** The extension's URI, under the substrate's own namespace like every other AP extension (`agenticprimitives.org/a2a/<name>/v1`) —
+ *  a package names no deployment domain (ADR-0021). */
+export const PLAYBOOK_BINDING_EXT_URI = 'https://agenticprimitives.org/a2a/playbook-binding/v1';
+/** Build the `capabilities.extensions[]` entry that binds a playbook to a card release. */
+export function playbookBindingExtension(binding) {
+    return {
+        uri: PLAYBOOK_BINDING_EXT_URI,
+        // Not required for interop: a client that does not understand the binding still uses the card. The
+        // binding is evidence for those who verify, never a gate on reaching the agent.
+        required: false,
+        description: 'the compiled archetype playbook this card promises (verifiable against the skills corpus by digest)',
+        params: { archetypeId: binding.archetypeId, archetypeVersion: binding.archetypeVersion, definitionDigest: binding.definitionDigest },
+    };
+}
+/** Read the playbook binding off a card, or null when it carries none / carries a malformed one. */
+export function readPlaybookBinding(card) {
+    const ext = (card.capabilities?.extensions ?? []).find((e) => e.uri === PLAYBOOK_BINDING_EXT_URI);
+    if (!ext?.params)
+        return null;
+    const p = ext.params;
+    const archetypeId = typeof p.archetypeId === 'string' ? p.archetypeId : '';
+    const archetypeVersion = typeof p.archetypeVersion === 'string' ? p.archetypeVersion : '';
+    const definitionDigest = typeof p.definitionDigest === 'string' ? p.definitionDigest : '';
+    // A binding is only meaningful if it names all three, and 'latest' is refused here too (a released card
+    // that promises "latest" promises nothing checkable).
+    if (!archetypeId || !archetypeVersion || archetypeVersion === 'latest' || !definitionDigest)
+        return null;
+    return { archetypeId, archetypeVersion, definitionDigest };
+}
+/** Add (or replace) the playbook binding on a card's capabilities, returning a NEW card (cards are
+ *  immutable once released; this builds the content a release will sign). */
+export function withPlaybookBinding(card, binding) {
+    const others = (card.capabilities?.extensions ?? []).filter((e) => e.uri !== PLAYBOOK_BINDING_EXT_URI);
+    return {
+        ...card,
+        capabilities: { ...card.capabilities, extensions: [...others, playbookBindingExtension(binding)] },
+    };
+}
+/** Among an agent's card releases, the one whose card binds this exact definition digest — the release a
+ *  Home cites as "Bound to release r-N". Newest matching release wins (highest releaseNumber). Reads the
+ *  signed card when present (that is what the world sees), else the unsigned one. */
+export function playbookBoundRelease(releases, definitionDigest) {
+    let best = null;
+    for (const r of releases) {
+        const binding = readPlaybookBinding(r.signedCard ?? r.unsignedCard);
+        if (binding?.definitionDigest === definitionDigest && (!best || r.releaseNumber > best.releaseNumber))
+            best = r;
+    }
+    return best;
+}
+//# sourceMappingURL=playbook-binding.js.map

package/dist/a2a/playbook-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"playbook-binding.js","sourceRoot":"","sources":["../../src/a2a/playbook-binding.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,EAAE;AACF,yGAAyG;AACzG,sGAAsG;AACtG,qGAAqG;AACrG,qGAAqG;AACrG,wFAAwF;AACxF,EAAE;AACF,yGAAyG;AACzG,yGAAyG;AACzG,wGAAwG;AACxG,yGAAyG;AACzG,iEAAiE;AAIjE,iFAAiF;AACjF;uDACuD;AACvD,MAAM,CAAC,MAAM,wBAAwB,GAAG,uDAAuD,CAAC;AAWhG,2FAA2F;AAC3F,MAAM,UAAU,wBAAwB,CAAC,OAA0B;IACjE,OAAO;QACL,GAAG,EAAE,wBAAwB;QAC7B,mGAAmG;QACnG,gFAAgF;QAChF,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,qGAAqG;QAClH,MAAM,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE;KACrI,CAAC;AACJ,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CAAC,IAA0C;IAC5E,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,wBAAwB,CAAC,CAAC;IAClG,IAAI,CAAC,GAAG,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,CAAC,GAAG,GAAG,CAAC,MAAiC,CAAC;IAChD,MAAM,WAAW,GAAG,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,MAAM,gBAAgB,GAAG,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,MAAM,gBAAgB,GAAG,OAAO,CAAC,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,wGAAwG;IACxG,sDAAsD;IACtD,IAAI,CAAC,WAAW,IAAI,CAAC,gBAAgB,IAAI,gBAAgB,KAAK,QAAQ,IAAI,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAC;IACzG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC;AAC7D,CAAC;AAED;6EAC6E;AAC7E,MAAM,UAAU,mBAAmB,CAAC,IAAoB,EAAE,OAA0B;IAClF,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,wBAAwB,CAAC,CAAC;IACvG,OAAO;QACL,GAAG,IAAI;QACP,YAAY,EAAE,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,UAAU,EAAE,CAAC,GAAG,MAAM,EAAE,wBAAwB,CAAC,OAAO,CAAC,CAAC,EAAE;KACnG,CAAC;AACJ,CAAC;AAED;;qFAEqF;AACrF,MAAM,UAAU,oBAAoB,CAElC,QAAsB,EAAE,gBAAwB;IAChD,IAAI,IAAI,GAAa,IAAI,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,OAAO,GAAG,mBAAmB,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC;QACpE,IAAI,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC;YAAE,IAAI,GAAG,CAAC,CAAC;IAClH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/a2a/pointer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * RFC 6901 JSON Pointer helpers — pure, immutable (`setAtPointer` returns a structural copy).
+ * Shared by field bindings (provenance is keyed by pointer), validation (`sourcePointer`) and import
+ * (`unknownFields`).
+ */
+export declare function parsePointer(pointer: string): string[];
+export declare function escapePointerToken(token: string): string;
+export declare function joinPointer(...tokens: (string | number)[]): string;
+/** Value at `pointer`, or `undefined` when any step is missing. Never throws on a missing path. */
+export declare function getAtPointer(root: unknown, pointer: string): unknown;
+/** Copy of `root` with `value` placed at `pointer` (intermediate objects created; `undefined` deletes). */
+export declare function setAtPointer<T>(root: T, pointer: string, value: unknown): T;
+//# sourceMappingURL=pointer.d.ts.map

package/dist/a2a/pointer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer.d.ts","sourceRoot":"","sources":["../../src/a2a/pointer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAOtD;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,WAAW,CAAC,GAAG,MAAM,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM,CAElE;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAapE;AAED,2GAA2G;AAC3G,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAI3E"}

package/dist/a2a/pointer.js

@@ -0,0 +1,78 @@
+/**
+ * RFC 6901 JSON Pointer helpers — pure, immutable (`setAtPointer` returns a structural copy).
+ * Shared by field bindings (provenance is keyed by pointer), validation (`sourcePointer`) and import
+ * (`unknownFields`).
+ */
+export function parsePointer(pointer) {
+    if (pointer === '')
+        return [];
+    if (!pointer.startsWith('/'))
+        throw new Error(`invalid JSON pointer "${pointer}" (must start with "/")`);
+    return pointer
+        .slice(1)
+        .split('/')
+        .map((t) => t.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+export function escapePointerToken(token) {
+    return token.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+export function joinPointer(...tokens) {
+    return tokens.map((t) => `/${escapePointerToken(String(t))}`).join('');
+}
+/** Value at `pointer`, or `undefined` when any step is missing. Never throws on a missing path. */
+export function getAtPointer(root, pointer) {
+    let cur = root;
+    for (const token of parsePointer(pointer)) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        if (Array.isArray(cur)) {
+            const idx = Number(token);
+            if (!Number.isInteger(idx) || idx < 0)
+                return undefined;
+            cur = cur[idx];
+        }
+        else {
+            cur = cur[token];
+        }
+    }
+    return cur;
+}
+/** Copy of `root` with `value` placed at `pointer` (intermediate objects created; `undefined` deletes). */
+export function setAtPointer(root, pointer, value) {
+    const tokens = parsePointer(pointer);
+    if (tokens.length === 0)
+        return value;
+    return setRec(root, tokens, 0, value);
+}
+function setRec(node, tokens, i, value) {
+    const token = tokens[i];
+    const last = i === tokens.length - 1;
+    if (Array.isArray(node)) {
+        const idx = token === '-' ? node.length : Number(token);
+        if (!Number.isInteger(idx) || idx < 0)
+            throw new Error(`invalid array index "${token}" in pointer`);
+        const copy = node.slice();
+        if (last) {
+            if (value === undefined)
+                copy.splice(idx, 1);
+            else
+                copy[idx] = value;
+        }
+        else {
+            copy[idx] = setRec(copy[idx], tokens, i + 1, value);
+        }
+        return copy;
+    }
+    const obj = node !== null && typeof node === 'object' ? { ...node } : {};
+    if (last) {
+        if (value === undefined)
+            delete obj[token];
+        else
+            obj[token] = value;
+    }
+    else {
+        obj[token] = setRec(obj[token], tokens, i + 1, value);
+    }
+    return obj;
+}
+//# sourceMappingURL=pointer.js.map

package/dist/a2a/pointer.js.map

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

package/dist/a2a/release.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Card release lifecycle (spec 347 §3):
+ *
+ *   draft → validated → approvalPending → approved → signed → published → { superseded | deprecated | revoked }
+ *
+ * A release is immutable and identified by release id AND content digest. Editing at `approved` or later
+ * forks a NEW draft (`forkDraft`). Superseding never erases; revocation records reason, authority, date and
+ * successor, and a revoked release is not projection-ready. Every function here is pure and returns a new
+ * object; illegal moves throw `A2ACardLifecycleError` instead of being ignored.
+ */
+import type { ApprovalRefV1 } from '@agenticprimitives/types';
+import type { A2AAgentCardDraftV1, A2AAgentCardReleaseV1, A2AAgentCardSignatureV1, A2AAgentCardV1, CardReleaseState, SignedSmartAgentCardBindingV1 } from './types.js';
+import { validateA2ACard, type ValidateA2ACardOptions } from './validation.js';
+export declare class A2ACardLifecycleError extends Error {
+    readonly from: CardReleaseState | 'draft';
+    readonly to: CardReleaseState;
+    constructor(message: string, from: CardReleaseState | 'draft', to: CardReleaseState);
+}
+/** Legal transitions. `revoked` is reachable from every non-terminal state via `revoke()`. */
+export declare const CARD_RELEASE_TRANSITIONS: Readonly<Record<CardReleaseState, readonly CardReleaseState[]>>;
+export declare const TERMINAL_RELEASE_STATES: ReadonlySet<CardReleaseState>;
+/** Can a projection consume this release? Only approved-and-signed (or published) releases, never revoked. */
+export declare function isProjectionReady(r: A2AAgentCardReleaseV1): boolean;
+export interface CreateReleaseOptions {
+    releaseId?: string;
+    releaseNumber: number;
+    agentVersion: string;
+    /** ISO timestamp (pure — caller's clock). */
+    now: string;
+    /** Validation context; the release is refused when validation has ERRORS. */
+    validation: ValidateA2ACardOptions;
+    supersedes?: string;
+}
+export declare class A2ACardValidationError extends Error {
+    readonly diagnostics: ReturnType<typeof validateA2ACard>;
+    constructor(diagnostics: ReturnType<typeof validateA2ACard>);
+}
+/** Freeze a draft into a `validated` release. Throws `A2ACardValidationError` when validation has errors. */
+export declare function createRelease(draft: A2AAgentCardDraftV1, opts: CreateReleaseOptions): A2AAgentCardReleaseV1;
+export interface TransitionContext {
+    now: string;
+    /** Required for `approvalPending → approved`; MUST name this release's `unsignedContentDigest`. */
+    approval?: ApprovalRefV1;
+    /** Required for `signed → published`. */
+    publication?: {
+        uri: string;
+    };
+    /** Required for `published → superseded`. */
+    successor?: string;
+    reason?: string;
+}
+/** Move a release along a legal transition. Throws `A2ACardLifecycleError` otherwise. */
+export declare function transition(release: A2AAgentCardReleaseV1, to: CardReleaseState, ctx: TransitionContext): A2AAgentCardReleaseV1;
+export interface AttachSignatureInput {
+    /** The signed card as returned by `signA2ACard` — MUST be this release's unsigned card plus signatures. */
+    signedCard: A2AAgentCardV1;
+    signature: A2AAgentCardSignatureV1;
+    signedAt?: string;
+}
+/** Attach a JWS signature (state `approved` or `signed` → `signed`). Refuses a signature over other bytes. */
+export declare function attachSignature(release: A2AAgentCardReleaseV1, input: AttachSignatureInput): A2AAgentCardReleaseV1;
+/** Attach the SA's EIP-712 binding (state `signed` or `published`). Digests MUST match this release. */
+export declare function attachSmartAgentBinding(release: A2AAgentCardReleaseV1, signed: SignedSmartAgentCardBindingV1): A2AAgentCardReleaseV1;
+export interface RevokeOptions {
+    reason: string;
+    authority: string;
+    now: string;
+    successor?: string;
+}
+/** Revoke from any non-terminal state. Records reason / authority / date / successor; never erases. */
+export declare function revoke(release: A2AAgentCardReleaseV1, opts: RevokeOptions): A2AAgentCardReleaseV1;
+/** Editing after `approved` = a new draft. Starts from the release's unsigned card + bindings. */
+export declare function forkDraft(release: A2AAgentCardReleaseV1, opts: {
+    now: string;
+    revision?: number;
+}): A2AAgentCardDraftV1;
+//# sourceMappingURL=release.d.ts.map

package/dist/a2a/release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.d.ts","sourceRoot":"","sources":["../../src/a2a/release.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAI9D,OAAO,KAAK,EACV,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,cAAc,EAEd,gBAAgB,EAChB,6BAA6B,EAC9B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAa,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE1F,qBAAa,qBAAsB,SAAQ,KAAK;IACjB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;IAAE,QAAQ,CAAC,EAAE,EAAE,gBAAgB;gBAAzF,OAAO,EAAE,MAAM,EAAW,IAAI,EAAE,gBAAgB,GAAG,OAAO,EAAW,EAAE,EAAE,gBAAgB;CAItG;AAED,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,SAAS,gBAAgB,EAAE,CAAC,CASpG,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,gBAAgB,CAAoD,CAAC;AAEvH,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAEnE;AAED,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,6EAA6E;IAC7E,UAAU,EAAE,sBAAsB,CAAC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC;gBAA/C,WAAW,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC;CAIrE;AAED,6GAA6G;AAC7G,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,oBAAoB,GAAG,qBAAqB,CA8B3G;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,mGAAmG;IACnG,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,yCAAyC;IACzC,WAAW,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,yFAAyF;AACzF,wBAAgB,UAAU,CAAC,OAAO,EAAE,qBAAqB,EAAE,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,iBAAiB,GAAG,qBAAqB,CA8B9H;AAED,MAAM,WAAW,oBAAoB;IACnC,2GAA2G;IAC3G,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,uBAAuB,CAAC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8GAA8G;AAC9G,wBAAgB,eAAe,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CA6BlH;AAED,wGAAwG;AACxG,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,qBAAqB,EAAE,MAAM,EAAE,6BAA6B,GAAG,qBAAqB,CAYpI;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,uGAAuG;AACvG,wBAAgB,MAAM,CAAC,OAAO,EAAE,qBAAqB,EAAE,IAAI,EAAE,aAAa,GAAG,qBAAqB,CAYjG;AAED,kGAAkG;AAClG,wBAAgB,SAAS,CAAC,OAAO,EAAE,qBAAqB,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,mBAAmB,CAcvH"}