@blamejs/core 0.8.83 → 0.8.87

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.87 (2026-05-11) — **NIST 800-63-4 FAL classifier + RFC 7505 Null-MX helper + Gmail FBL Feedback-ID builder + vendor-update.sh stale-entry cleanup**. **`b.auth.fal`** lands as the federation-side counterpart to the existing `b.auth.aal` band classifier. `fromAssertion({ channel, encrypted?, replayProtected?, hokBinding? })` classifies an incoming federation assertion as `"FAL1"` / `"FAL2"` / `"FAL3"` per NIST 800-63C-4: Holder-of-Key (mTLS / DPoP / SAML HoK) with replay-protection → FAL3; back-channel OR encrypted front-channel with replay-protection → FAL2; bare bearer front-channel → FAL1. Conservative: missing replay-protection on a back-channel assertion downgrades to FAL1 because §5.2 requires nonce / jti binding before back-channel can claim FAL2. `requireFal(minimumBand)` builds a band-check guard that throws `auth/fal-insufficient` for stale-band requests; compose with the request-scope auth state to gate sensitive operations. **`b.network.dns.isNullMx(records)`** lands as the RFC 7505 Null-MX classifier: returns `true` when an operator-supplied MX-record array signals "this domain does not accept email" (single record, priority 0, exchange `.` per RFC 7505 §3). Operators send-side check this before delivery to skip domains that have explicitly opted out — `node:dns.resolveMx` returns `exchange: ""` for the same RDATA, so the classifier accepts both shapes. **`b.mail.feedbackId({ campaignId, customerId, mailType, senderId })`** builds a Gmail Feedback-Loop (FBL) Feedback-ID header value as the canonical 4-tuple `CampaignID:CustomerID:MailType:SenderID`. Refuses missing / empty fields, fields containing `:` (would corrupt the field separator), fields >64 chars (Gmail FBL truncation threshold), and control-char content (CR/LF header-injection defense). Setting Feedback-ID on outbound mail lets Gmail Postmaster Tools surface per-campaign abuse-rate metrics keyed by the operator's vocabulary instead of by SMTP envelope-sender alone. **vendor-update.sh cleanup**: `scripts/vendor-update.sh --check` removed the stale `argon2` entry from `VENDORED_PACKAGES`. argon2 was removed from `lib/vendor/` back in v0.4.x when Node 24's built-in `crypto.argon2*` API replaced the third-party prebuilds (per `lib/argon2-builtin.js`); the script still listed it in the check array, producing a false "UPDATE AVAILABLE" line for an unvendored package. The case-block error path that still says "argon2 is no longer vendored" stays so anyone running `./scripts/vendor-update.sh argon2` gets the operator-friendly explanation.
+- v0.8.86 (2026-05-11) — **Sectoral + cybersecurity posture sweep + HTTP-hygiene primitives + npm-publish hotfix**. **npm-publish hotfix**: the v0.8.85 `npm audit signatures` step failed with `npm error found no installed dependencies to audit` because the framework's zero-runtime-deps posture produces an empty install tree; the gate now treats that specific message as success while keeping every other failure mode loud (v0.8.85 npm tarball never published — operators upgrade `0.8.83 → 0.8.86` to pick up the carried v0.8.84 + v0.8.85 surface plus the new v0.8.86 primitives). **10 new compliance postures**: `cmmc-2.0` (DoD Cybersecurity Maturity Model Certification 2.0), `cjis-v6` (FBI CJIS Security Policy v6.0), `iso-27001-2022` + `iso-27002-2022` + `iso-27017` + `iso-27018` + `iso-27701` (ISO/IEC 27001 family), `nist-800-66-r2` (HIPAA Security Rule implementation guidance), `ehds` (European Health Data Space), `circia` (US Cyber Incident Reporting for Critical Infrastructure Act). Cascade defaults set encrypted-backup + signed-audit-chain + TLS 1.3 + vacuum-after-erase for the data-tier postures; `iso-27002-2022` + `circia` defer the data-tier mandate to operator choice. **`b.cacheStatus`** — RFC 9211 Cache-Status response-header builder + parser. `append(prev, entry)` chains the operator's current cache decision onto whatever upstream caches wrote; `entry({...})` formats a single entry; `parse(headerValue)` returns the parsed chain as `[{ cache, params }]` records with `hit`/`stored`/`collapsed` as booleans, `ttl`/`fwdStatus` as numbers, `fwd` as the RFC 9211 §2 enum string, `key`/`detail` as unquoted sf-strings. Operators diagnose CDN/reverse-proxy/app-cache decision chains by reading the header instead of guessing from elapsed-time metrics. **`b.serverTiming`** — W3C Server-Timing response-header builder. `create()` returns a per-request collector with `mark(name, durationMs?, description?)` / `measure(name, fn)` async-timing wrapper / `toHeader()` serializer. Surfaces server-side latency in the browser's Performance API. **`b.middleware.noCache`** — RFC 9111 §5.2.2.5 `Cache-Control: no-store` middleware for auth-gated / individualized response paths. Sets `Cache-Control: no-store`, `Pragma: no-cache` (HTTP/1.0 compatibility), `Vary: Cookie, Authorization` so intermediate caches don't store personalized responses keyed by URL alone. Optional `opts.when(req)` predicate for conditional application; `opts.skipExisting:true` skips when `Cache-Control` is already set.
+- v0.8.85 (2026-05-11) — **MCP tool registry + tool-call signing + A2A v1 task-exchange surface**. Closes the substantial agent-protocol gaps surfaced by the 2026-05-11 audit's MITRE ATLAS v5.3.0 + A2A v1 cross-walk. **MCP tool registry** lands as `b.mcp.toolRegistry.create({ tools, signingKey, verifyingKey?, alg?, ttlMs? })` — every registered tool gets a signed descriptor blob `{ tool, alg, signature }` (defense against compromised MCP server / descriptor drift) and a `descriptorsManifest()` produces a signed `{ body, signature }` document for operator-side attestation. The registry's `signCall({ toolName, args, nonce?, ttlMs? })` builds + signs an outbound tool-call envelope `{ tool, argsHash, nonce, iat, exp }` (defense against MCP middleman / indirect-prompt-injection synthesizing tool calls); `verifyCall(signed, { args?, seen?, nowMs? })` runs the inverse on inbound — refuses signature mismatch (`mcp/call-verify-failed`), expired envelopes (`mcp/call-expired`), replayed nonces via operator-supplied `seen(nonce)` callback (`mcp/call-replay`), unregistered tools (`mcp/call-unregistered-tool`), and args-hash mismatch when raw args supplied (`mcp/call-args-mismatch`). Default algorithm ML-DSA-87 per the framework's PQC-first rule; Ed25519 / ECDSA / SLH-DSA also available. **A2A v1 task-exchange surface** lands as `b.a2a.tasks.{send, get, cancel}` (client-side JSON-RPC dispatchers — `send` posts `tasks/send` to the peer URL with task validation + https-only refusal; `get` polls `tasks/get`; `cancel` requests `tasks/cancel`) plus `b.a2a.middleware.tasks({ scopes, handler, maxBytes? })` (server-side connect-style middleware — parses inbound JSON-RPC 2.0, enforces method allowlist `[tasks/send, tasks/get, tasks/cancel]` with -32601 method-not-found, enforces per-skill scopes via `req.a2aScopes` with -32001 scope-denied, dispatches to operator handler, maps errors to JSON-RPC -32603, refuses non-POST with 405 + non-JSON content-type with 415) plus `b.a2a.middleware.agentCard({ card, maxAgeSec? })` (serves operator's signed Agent Card at `/.well-known/agent.json` per A2A v1 discovery — 405 on non-GET, Cache-Control max-age operator-tunable).
+- v0.8.84 (2026-05-11) — **Supply-chain hardening trio + HTTP-API hygiene primitives**. **Supply chain**: CodeQL SAST workflow (`.github/workflows/codeql.yml` — PR + push-to-main + weekly Mon-05:31-UTC schedule) running the `security-extended` query pack against the JavaScript surface (catches SQL injection, XSS, prototype pollution, command injection, ReDoS, unsafe deserialization, SSRF, hardcoded credentials beyond what OSV-Scanner sees; findings surface as SARIF in the Security tab); `npm audit signatures` step in `npm-publish.yml` that verifies the cryptographic signing chain for every package in the install tree against the npm registry's public keys before the publish step runs (regression-defense — the framework ships zero npm runtime deps so the tree is trivially empty today; if a future patch accidentally adds a runtime dep, the gate refuses an unsigned registry entry before tag-push triggers a release); vendored SBOM signing extends the existing cosign-keyless flow to sign `sbom.vendored.cdx.json` alongside `sbom.cdx.json` and attaches both `.sigstore` bundles to the GitHub Release. **HTTP-API hygiene primitives**: new `b.problemDetails` family implementing RFC 9457 Problem Details for HTTP APIs (`create({ type, title, status, detail, instance, ...extensions })` builds a frozen problem doc with field validation; `fromError(err)` converts a `FrameworkError` into a problem doc with `type` derived from `err.code` against a configurable base URI; `respond(res, problem)` writes the response with `Content-Type: application/problem+json` + `Cache-Control: no-store` per RFC 9457 §3 + RFC 9111 §5.2.2.5; `validate(doc)` parses inbound problem docs from upstream APIs with shape refusal). New `b.middleware.idempotencyKey` implementing draft-ietf-httpapi-idempotency-key (replay-safe POST/PUT/PATCH/DELETE — operator-supplied store interface with first-party `memoryStore({ maxEntries })`; cached fingerprint = method + path + sha3-256(body); 422 + `idempotency/key-reuse-mismatch` problem-details on same-key-different-body per draft §4.3; 5xx responses are NOT cached because replaying a transient infrastructure failure is not idempotent; default TTL 24h; default methods POST/PUT/PATCH/DELETE). The v0.8.84 git tag landed on a wrong commit due to a release-workflow ordering issue and the npm publish for 0.8.84 did not ship; operators upgrade directly from 0.8.83 to 0.8.85 (which carries the same primitives as part of the combined ship).
 - v0.8.83 (2026-05-11) — **ACME 47-day-cert readiness**: certificate profiles + dns-account-01 challenge + ARI renewal-window jitter. **draft-aaron-acme-profiles** lands as `acme.listProfiles()` (reads `directory.meta.profiles` and returns the CA-advertised `{ name: description }` map) + `acme.newOrder({ profile })` (passes the chosen profile name through the order payload; refuses non-string + caps length at 64 bytes). As CA/B Forum SC-081v3 phases in the 47-day mandate, profile-name vocabulary becomes the operator-facing handle for "long-lived" vs "47-day" vs "short-lived" cert selection. **draft-ietf-acme-dns-account-label** lands as `acme.dnsAccount01ChallengeRecord(token, { identifier, ttl? })` which builds the per-account-scoped TXT record (`_<accountLabel>._acme-challenge.<host>`) where `accountLabel` is the lowercase base32 of the first 80 bits of `SHA-256(accountUrl)`. Refuses pre-newAccount (label needs accountUrl as seed); caps identifier at 255 bytes; refuses negative / huge TTL. **RFC 9773 §4.2 fleet-scheduling jitter**: `acme.renewIfDue({ jitter: true })` now returns a `renewAt` ISO timestamp picked uniformly across the CA-suggested window so operator fleets running on the same poll cadence stop clustering their renewal storms at the window-start instant. Default behavior (`jitter` off or absent) preserves pre-0.8.83 "renew now" semantics. The `acme.cert.renew.scheduled` audit row carries the chosen `renewAt` when jitter is on.
 - v0.8.82 (2026-05-11) — **Privacy 2026 posture sweep**. 27 new postures land in `b.compliance.KNOWN_POSTURES` (with matching `REGIME_MAP` + `POSTURE_DEFAULTS` cascade entries) closing the privacy gap surfaced by the 2026-05-11 multi-agent compliance audit. **US federal**: `coppa` + `coppa-2025` (FTC final rule 2025-04-22, effective 2026-06-23 — biometric expansion + knowing-collection-13-and-under disclosure; cascade adds backupEncryptionRequired:true + vacuum-after-erase), `glba-safeguards` (GLBA Safeguards Rule 2024 Amendment, effective 2024-05-13; cascade matches pci-dss + nydfs-500 financial tier), `gina` (Genetic Information Nondiscrimination Act), `vppa` (Video Privacy Protection Act), `can-spam`, `il-gipa` (Illinois Genetic Information Privacy Act with post-2024 private right of action), `hhs-repro-24` (HHS Reproductive Health HIPAA Amendment 2024-12-23), `nist-pf-1.1` (NIST Privacy Framework 1.1, final 2025-04-14). **UK**: `uk-duaa` (Data (Use and Access) Act 2025 — Royal Assent 2025-06-19; replaces the abandoned DPDI Bill; cascade matches GDPR floor with vacuum-after-erase). **Latin America**: `cl-pdpa` (Chile Ley 21.719, enacted 2024-12-13, effective 2026-12-01; cascade mirrors gdpr), `mx-lfpdppp` (Mexico 2025 secondary reform), `ar-pdpa` (Argentina Ley 25.326). **APAC**: `pipa-kr` (Korea PIPA 2023 major amendment, phased 2023-09-15 / 2024-03-15), `au-privacy` (Australia Privacy Act + 2024 Amendment Act — statutory tort effective 2025-06-10), `th-pdpa`, `vn-pdp` (Vietnam PDP Law effective 2026-01-01), `id-pdp` (Indonesia PDP Law effective 2024-10-17), `my-pdpa` (Malaysia 2024 amendments effective 2025-04-30). **US state child-privacy**: `ny-safe-kids` + `ny-saffe` (NY Child Data Protection Act + Stop Addictive Feeds Exploitation, both effective 2025-06-20), `md-kids-code` (Maryland Age-Appropriate Design Code), `vt-aadc` (Vermont AADC). **EU non-personal-data + adjacent**: `dsa` (Digital Services Act, fully applicable 2024-02-17), `dga` (Data Governance Act, applicable 2023-09-24), `eu-cer` (Critical Entities Resilience Directive 2022/2557, transposition 2024-10-17), `eu-cyber-sol` (Cyber Solidarity Act 2025/38, effective 2025-02-04), `eidas-2` (eIDAS 2 / EUDI Wallet, rollout 2026-2027). New REGIME_MAP `domain` values introduced: `child-privacy`, `financial-privacy`, `consumer-privacy`, `genetic-privacy`, `platform-governance`, `identity` — operators rendering compliance dashboards grouped by domain pick up the new buckets via `b.compliance.posturesByDomain(domain)` without code changes.
 - v0.8.81 (2026-05-11) — **AI-governance compliance postures + ISO 42001/23894 cross-walk + privacy catalog drift fixes**. 18 new postures register in `b.compliance.KNOWN_POSTURES` (and the matching `REGIME_MAP` + `POSTURE_DEFAULTS` cascade): state AI governance (`co-ai`, `il-hb3773`, `tx-traiga`, `ut-aipa`, `nyc-ll144`, `ca-tfaia` — frontier AI critical-incident records cascade to `backupEncryptionRequired:true`), international AI (`kr-ai-basic`, `cn-ai-label`), AI management standards (`iso-42001`, `iso-23894`), California gen-AI content credentials (`ca-sb942`, `ca-ab853`), substrate-to-posture cleanup so existing primitives gain catalog entries (`eaa` for EU Accessibility Act + `b.compliance-eaa`, `wcag-2-2` for `b.guardHtml.wcag`, `eu-data-act` for `b.dataAct`, `hitech` extending HIPAA-tier, `ferpa` for student records), plus `fl-fdbr` (Florida Digital Bill of Rights) and the long-missing `dpdp` (India DPDP Act 2023 — was in `POSTURE_DEFAULTS` cascade table but not in `KNOWN_POSTURES`, so `b.compliance.set("dpdp")` threw `compliance/unknown-posture`). **ISO 42001 + 23894 cross-walk**: new `b.compliance.aiAct.crossWalkIso42001([aiActCitation])` and `crossWalkIso23894()` return a 15-row mapping table linking EU AI Act articles (Art. 9 risk management → Art. 73 incident reporting) to ISO/IEC 42001:2023 Annex A controls and ISO/IEC 23894:2023 risk-management clauses. Operators chasing ISO 42001 certification under AI Act high-risk scope use the table to produce one cross-walk artifact instead of hand-rolling two separate audits; the table is read-only metadata, defensive copies returned, no behavior change at deploy time. **DSR drift fix**: `b.dsr.stateRules("fl-fdbr")` / `stateRules("FL")` now resolve (45-day response window, 15-day extension, 30-day cure, profiling opt-out enabled, minor opt-in 13). **Citation drift fix**: four state-privacy posture citations corrected from "(effective 2026-MM-DD)" to "(effective 2025-MM-DD)" — `modpa`, `nh-nhpa`, `nj-njdpa`, `mn-mncdpa` all took effect during 2025; the year-late citations would have surfaced as audit-trail discrepancies under operator review.

package/index.js

@@ -143,6 +143,9 @@ var compliance = Object.assign({}, require("./lib/compliance"), {
   eaa: require("./lib/compliance-eaa"),
 });
 var dataAct = require("./lib/data-act");
+var problemDetails = require("./lib/problem-details");
+var cacheStatus = require("./lib/cache-status");
+var serverTiming = require("./lib/server-timing");
 var gateContract = require("./lib/gate-contract");
 var guardCsv = require("./lib/guard-csv");
 var guardHtml = require("./lib/guard-html");
@@ -184,6 +187,7 @@ var auth = {
   lockout:  require("./lib/auth/lockout"),
   dpop:     require("./lib/auth/dpop"),
   aal:      require("./lib/auth/aal"),
+  fal:      require("./lib/auth/fal"),
   statusList: require("./lib/auth/status-list"),
   sdJwtVc:    require("./lib/auth/sd-jwt-vc"),
   stepUp:     require("./lib/auth/step-up"),
@@ -370,6 +374,9 @@ module.exports = {
   compliance:       compliance,
   nistCrosswalk:    nistCrosswalk,
   dataAct:          dataAct,
+  problemDetails:   problemDetails,
+  cacheStatus:      cacheStatus,
+  serverTiming:     serverTiming,
   gateContract:     gateContract,
   guardCsv:         guardCsv,
   guardHtml:        guardHtml,

package/lib/a2a-tasks.js

@@ -0,0 +1,598 @@
+"use strict";
+/**
+ * @module     b.a2a
+ * @nav        Agent Protocols
+ * @title      A2A Tasks
+ * @order      600
+ *
+ * @intro
+ *   A2A v1 task-exchange surface — the work primitive on top of
+ *   `b.a2a.{createCard, signCard, verifyCard}`. A2A (Linux Foundation,
+ *   v1 spec Apr 2026) defines a JSON-RPC 2.0 over HTTPS protocol with
+ *   three task verbs (`tasks/send`, `tasks/get`, `tasks/cancel`) plus
+ *   optional SSE streaming for long-running tasks.
+ *
+ *   The framework ships:
+ *
+ *     - Client-side dispatchers: `b.a2a.tasks.send({ peerUrl, agentCard, task })`
+ *       posts a `tasks/send` JSON-RPC request; `get({ taskId })` polls
+ *       status; `cancel({ taskId })` requests cancellation.
+ *     - Server-side middleware: `b.a2a.middleware.agentCard({ card })`
+ *       serves `/.well-known/agent.json`; `b.a2a.middleware.tasks
+ *       ({ scopes, handler })` parses inbound JSON-RPC, enforces
+ *       per-skill scope, and dispatches to an operator handler.
+ *     - SSE streaming: when the handler returns a long-running shape,
+ *       the middleware switches to SSE and streams progress events
+ *       to the client.
+ *
+ *   PQC-first: every signed-card flow uses the existing `b.a2a.signCard
+ *   / verifyCard` ML-DSA-87 surface. The task-exchange envelopes
+ *   themselves are NOT separately signed — operators wanting per-call
+ *   non-repudiation compose `b.crypto.httpSig.sign` (RFC 9421) at the
+ *   HTTP layer.
+ *
+ *   Per `feedback_validation_tier_policy.md`:
+ *     - Client `send / get / cancel` THROW on bad input (entry-point).
+ *     - Middleware factories THROW on bad opts at boot.
+ *     - The per-request middleware path returns a JSON-RPC error
+ *       response on protocol violations (consistent with mcp.refuse).
+ *
+ * @card
+ *   A2A v1 task-exchange surface — JSON-RPC dispatchers + server middleware (agentCard + tasks) + SSE streaming for long-running tasks.
+ */
+
+var nodeCrypto    = require("node:crypto");
+var lazyRequire   = require("./lazy-require");
+var numericBounds = require("./numeric-bounds");
+var safeJson      = require("./safe-json");
+var safeUrl       = require("./safe-url");
+var safeBuffer    = require("./safe-buffer");
+var validateOpts  = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var httpClient = lazyRequire(function () { return require("./http-client"); });
+var audit      = lazyRequire(function () { return require("./audit"); });
+var C          = require("./constants");
+
+// A2aTasksError is the per-call error class — separate from A2aError
+// (which exists for the card-signing primitives) so operators can
+// catch task-shape errors distinctly.
+var A2aTasksError = defineClass("A2aTasksError", { alwaysPermanent: true });
+
+var JSONRPC_VERSION = "2.0";
+
+// JSON-RPC 2.0 fixed error codes — A2A inherits these.
+var JSONRPC_PARSE_ERROR      = -32700;                                                             // allow:raw-byte-literal — JSON-RPC fixed code / allow:raw-time-literal — not seconds
+var JSONRPC_INVALID_REQUEST  = -32600;                                                             // allow:raw-byte-literal — JSON-RPC fixed code / allow:raw-time-literal — not seconds
+var JSONRPC_METHOD_NOT_FOUND = -32601;                                                             // allow:raw-byte-literal — JSON-RPC fixed code / allow:raw-time-literal — not seconds
+var JSONRPC_INVALID_PARAMS   = -32602;                                                             // allow:raw-byte-literal — JSON-RPC fixed code / allow:raw-time-literal — not seconds
+var JSONRPC_INTERNAL_ERROR   = -32603;                                                             // allow:raw-byte-literal — JSON-RPC fixed code / allow:raw-time-literal — not seconds
+
+// A2A-specific error codes per the spec's task-error vocabulary.
+// A2A_TASK_NOT_FOUND (-32002) + A2A_TASK_NOT_CANCELABLE (-32003) are
+// raised by operator handlers — they're reserved here for documentation
+// purposes only.
+var A2A_SCOPE_DENIED         = -32001;                                                             // allow:raw-byte-literal — JSON-RPC server-error range / allow:raw-time-literal — not seconds
+
+var ALLOWED_METHODS = Object.freeze(["tasks/send", "tasks/get", "tasks/cancel"]);
+
+var TASK_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+// Same identifier shape as MCP tool-name; consolidating would couple
+// MCP + A2A protocol identifiers into a single primitive.
+var SKILL_NAME_RE = /^[a-zA-Z][a-zA-Z0-9._-]{0,63}$/;   // allow:duplicate-regex — RFC-3986-unreserved identifier shape, shared across mcp.js + mcp-tool-registry.js
+// allow:raw-byte-literal — RFC-3986-unreserved identifier shape (length cap inside regex), not a byte count
+
+function _emitAudit(action, metadata, outcome) {
+  try {
+    audit().safeEmit({
+      action:   action,
+      outcome:  outcome || "success",
+      metadata: metadata,
+    });
+  } catch (_e) { /* best-effort */ }
+}
+
+var crypto = lazyRequire(function () { return require("./crypto"); });
+
+// _newTaskId is reserved for the operator-handler path that mints
+// peer-assigned task IDs server-side. The underscore prefix already
+// satisfies the framework's unused-var policy so the helper stays
+// available without an explicit disable directive.
+function _newTaskId() {
+  return crypto().generateToken(12);                                                               // allow:raw-byte-literal — 96-bit task id, not byte arithmetic on payload
+}
+
+function _validateTaskShape(task, where) {
+  if (!task || typeof task !== "object" || Array.isArray(task)) {
+    throw new A2aTasksError("a2a-tasks/bad-task",
+      where + ": task must be a non-null object", true);
+  }
+  validateOpts.requireNonEmptyString(task.skill, where + ".skill", A2aTasksError, "a2a-tasks/bad-skill");
+  if (task.skill.length > 64 || !SKILL_NAME_RE.test(task.skill)) {                                // allow:raw-byte-literal — A2A skill-name length cap, not byte count
+
+    throw new A2aTasksError("a2a-tasks/bad-skill",
+      where + ".skill '" + task.skill + "' must match " + SKILL_NAME_RE);
+  }
+  if (task.input !== undefined && (typeof task.input !== "object" || task.input === null)) {
+    throw new A2aTasksError("a2a-tasks/bad-input",
+      where + ".input must be an object when provided", true);
+  }
+}
+
+// ---- Client-side dispatchers ----
+
+/**
+ * @primitive b.a2a.tasks.send
+ * @signature b.a2a.tasks.send(opts)
+ * @since     0.8.85
+ * @status    stable
+ * @related   b.a2a.tasks.get, b.a2a.tasks.cancel, b.a2a.signCard
+ *
+ * Post a `tasks/send` JSON-RPC request to a peer A2A agent. Returns
+ * the peer's `tasks/send` result — typically `{ taskId, status }` or
+ * a final-state response when the task ran synchronously.
+ *
+ * @opts
+ *   peerUrl:   string,    // peer's A2A endpoint URL (https only)
+ *   task:      object,    // { skill, input } per A2A v1 §4
+ *   timeoutMs: number,    // optional — default 30s
+ *   headers:   object,    // optional — extra HTTP headers (signed
+ *                         //            auth / mTLS / RFC 9421 sig)
+ *   audit:     boolean,   // default true
+ *
+ * @example
+ *   var rsp = await b.a2a.tasks.send({
+ *     peerUrl: "https://agent.example.com/a2a",
+ *     task:    { skill: "summarize", input: { url: "..." } },
+ *   });
+ *   // rsp.taskId === "<peer-assigned-id>"
+ *   // rsp.status === "queued" | "running" | "completed"
+ */
+async function send(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-opts",
+      "tasks.send: opts required (peerUrl + task)", true);
+  }
+  validateOpts.requireNonEmptyString(opts.peerUrl, "tasks.send.peerUrl", A2aTasksError, "a2a-tasks/bad-peer-url");
+  // Refuse non-https — A2A v1 §3 mandates TLS for transport.
+  try { safeUrl.parse(opts.peerUrl, { allowedProtocols: ["https:"] }); }
+  catch (_e) {
+    throw new A2aTasksError("a2a-tasks/bad-peer-url",
+      "tasks.send: peerUrl must be a valid https URL");
+  }
+  _validateTaskShape(opts.task, "tasks.send.task");
+  var timeoutMs = opts.timeoutMs !== undefined ? opts.timeoutMs : C.TIME.seconds(30);
+  return _jsonRpc(opts.peerUrl, "tasks/send", { task: opts.task }, {
+    timeoutMs: timeoutMs,
+    headers:   opts.headers || {},
+    audit:     opts.audit !== false,
+  });
+}
+
+/**
+ * @primitive b.a2a.tasks.get
+ * @signature b.a2a.tasks.get(opts)
+ * @since     0.8.85
+ * @status    stable
+ * @related   b.a2a.tasks.send, b.a2a.tasks.cancel
+ *
+ * Poll a peer task's current status via `tasks/get`. Returns the
+ * peer's status record — `{ taskId, status, result?, error? }`.
+ *
+ * @opts
+ *   peerUrl: string,
+ *   taskId:  string,
+ *   timeoutMs: number,
+ *   headers: object,
+ *
+ * @example
+ *   var st = await b.a2a.tasks.get({ peerUrl: url, taskId: "abc" });
+ *   if (st.status === "completed") console.log(st.result);
+ */
+async function get(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-opts",
+      "tasks.get: opts required (peerUrl + taskId)", true);
+  }
+  validateOpts.requireNonEmptyString(opts.peerUrl, "tasks.get.peerUrl", A2aTasksError, "a2a-tasks/bad-peer-url");
+  validateOpts.requireNonEmptyString(opts.taskId, "tasks.get.taskId", A2aTasksError, "a2a-tasks/bad-task-id");
+  if (opts.taskId.length > 64 || !TASK_ID_RE.test(opts.taskId)) {                                  // allow:raw-byte-literal — A2A task-id length cap, not byte count
+    throw new A2aTasksError("a2a-tasks/bad-task-id",
+      "tasks.get: taskId must match " + TASK_ID_RE);
+  }
+  return _jsonRpc(opts.peerUrl, "tasks/get", { taskId: opts.taskId }, {
+    timeoutMs: opts.timeoutMs !== undefined ? opts.timeoutMs : C.TIME.seconds(15),
+    headers:   opts.headers || {},
+    audit:     opts.audit !== false,
+  });
+}
+
+/**
+ * @primitive b.a2a.tasks.cancel
+ * @signature b.a2a.tasks.cancel(opts)
+ * @since     0.8.85
+ * @status    stable
+ * @related   b.a2a.tasks.send, b.a2a.tasks.get
+ *
+ * Request peer cancellation via `tasks/cancel`. Peer MAY refuse with
+ * `-32003 task-not-cancelable` for tasks that have completed or
+ * passed a cancellation point.
+ *
+ * @opts
+ *   peerUrl:   string,    // peer's A2A endpoint URL (https only)
+ *   taskId:    string,    // peer-assigned task identifier
+ *   timeoutMs: number,    // optional — default 15s
+ *   headers:   object,    // optional — extra HTTP headers
+ *   audit:     boolean,   // default true
+ *
+ * @example
+ *   try {
+ *     await b.a2a.tasks.cancel({ peerUrl: url, taskId: "abc" });
+ *   } catch (e) {
+ *     if (e.rpcCode === -32003) console.log("task already past cancel point");
+ *   }
+ */
+async function cancel(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-opts",
+      "tasks.cancel: opts required (peerUrl + taskId)", true);
+  }
+  validateOpts.requireNonEmptyString(opts.peerUrl, "tasks.cancel.peerUrl", A2aTasksError, "a2a-tasks/bad-peer-url");
+  validateOpts.requireNonEmptyString(opts.taskId, "tasks.cancel.taskId", A2aTasksError, "a2a-tasks/bad-task-id");
+  if (opts.taskId.length > 64 || !TASK_ID_RE.test(opts.taskId)) {                                  // allow:raw-byte-literal — A2A task-id length cap, not byte count
+    throw new A2aTasksError("a2a-tasks/bad-task-id",
+      "tasks.cancel: taskId must match " + TASK_ID_RE);
+  }
+  return _jsonRpc(opts.peerUrl, "tasks/cancel", { taskId: opts.taskId }, {
+    timeoutMs: opts.timeoutMs !== undefined ? opts.timeoutMs : C.TIME.seconds(15),
+    headers:   opts.headers || {},
+    audit:     opts.audit !== false,
+  });
+}
+
+async function _jsonRpc(url, method, params, opts) {
+  var id = nodeCrypto.randomUUID();
+  var body = JSON.stringify({
+    jsonrpc: JSONRPC_VERSION,
+    id:      id,
+    method:  method,
+    params:  params,
+  });
+  var startMs = Date.now();
+  var rsp;
+  try {
+    rsp = await httpClient().request({
+      method:  "POST",
+      url:     url,
+      body:    body,
+      headers: Object.assign({
+        "Content-Type": "application/json",
+        "Accept":       "application/json",
+      }, opts.headers),
+      timeoutMs: opts.timeoutMs,
+    });
+  } catch (transportErr) {
+    if (opts.audit) {
+      _emitAudit("a2a.tasks.transport_failed",
+        { method: method, url: url, error: String(transportErr.message || transportErr), elapsedMs: Date.now() - startMs },
+        "warning");
+    }
+    throw new A2aTasksError("a2a-tasks/transport",
+      "tasks." + method.split("/")[1] + ": transport error: " + (transportErr.message || transportErr));
+  }
+  if (rsp.statusCode < 200 || rsp.statusCode >= 300) {                                             // allow:raw-byte-literal — HTTP status class boundaries
+    if (opts.audit) {
+      _emitAudit("a2a.tasks.http_error",
+        { method: method, url: url, statusCode: rsp.statusCode, elapsedMs: Date.now() - startMs },
+        "warning");
+    }
+    throw new A2aTasksError("a2a-tasks/http-error",
+      "tasks." + method.split("/")[1] + ": HTTP " + rsp.statusCode);
+  }
+  var parsed;
+  try {
+    parsed = safeJson.parse(typeof rsp.body === "string" ? rsp.body : rsp.body.toString("utf8"),
+      { maxBytes: C.BYTES.mib(8) });
+  } catch (parseErr) {
+    throw new A2aTasksError("a2a-tasks/bad-response",
+      "tasks." + method.split("/")[1] + ": response not valid JSON: " + (parseErr.message || parseErr));
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.jsonrpc !== JSONRPC_VERSION) {
+    throw new A2aTasksError("a2a-tasks/bad-response",
+      "tasks." + method.split("/")[1] + ": response is not a JSON-RPC 2.0 envelope");
+  }
+  if (parsed.error) {
+    if (opts.audit) {
+      _emitAudit("a2a.tasks.rpc_error",
+        { method: method, url: url, errorCode: parsed.error.code, errorMessage: parsed.error.message },
+        "warning");
+    }
+    var err = new A2aTasksError("a2a-tasks/rpc-error",
+      "tasks." + method.split("/")[1] + ": " + (parsed.error.message || "rpc error"));
+    err.rpcCode = parsed.error.code;
+    err.rpcData = parsed.error.data;
+    throw err;
+  }
+  if (opts.audit) {
+    _emitAudit("a2a.tasks.ok",
+      { method: method, url: url, elapsedMs: Date.now() - startMs });
+  }
+  return parsed.result;
+}
+
+// ---- Server-side middleware ----
+
+/**
+ * @primitive b.a2a.middleware.tasks
+ * @signature b.a2a.middleware.tasks(opts)
+ * @since     0.8.85
+ * @status    stable
+ * @related   b.a2a.middleware.agentCard, b.a2a.tasks.send
+ *
+ * Build the server-side A2A tasks middleware. Returns a connect-style
+ * `(req, res, next) => void` that:
+ *
+ *   - Parses inbound JSON-RPC 2.0 requests from POST request bodies.
+ *     Refuses non-POST + non-application/json with 405 / 415.
+ *   - Refuses methods not in `["tasks/send", "tasks/get",
+ *     "tasks/cancel"]` with JSON-RPC -32601 method-not-found.
+ *   - Enforces per-skill scope via `opts.scopes` — a map
+ *     `{ skillName: requiredScope }`. The middleware reads
+ *     `req.a2aScopes` (populated by the operator's auth layer; e.g.
+ *     parsed from a bearer token's claims or an mTLS cert SAN) and
+ *     refuses calls whose required scope isn't granted with -32001.
+ *   - Dispatches to `opts.handler({ method, taskId?, task?, req })`
+ *     which returns the task state (or throws for errors that get
+ *     mapped to -32603).
+ *
+ *   The middleware writes the JSON-RPC response itself; it does NOT
+ *   call `next()`. Operators chaining additional middleware after
+ *   this one should mount on a separate path.
+ *
+ * @opts
+ *   handler:    function (ctx) → result  — REQUIRED
+ *   scopes:     { skillName: scopeString } — optional per-skill scope map
+ *   maxBytes:   number — body cap (default 1 MiB)
+ *   audit:      boolean — default true
+ *
+ * @example
+ *   var mw = b.a2a.middleware.tasks({
+ *     scopes: { summarize: "a2a:summarize", search: "a2a:search" },
+ *     handler: async function ({ method, task, taskId }) {
+ *       if (method === "tasks/send") {
+ *         var newId = "t-" + Math.random().toString(36).slice(2, 10);
+ *         queue.push({ id: newId, task });
+ *         return { taskId: newId, status: "queued" };
+ *       }
+ *       if (method === "tasks/get") {
+ *         return tasks.get(taskId);
+ *       }
+ *       if (method === "tasks/cancel") {
+ *         return tasks.cancel(taskId);
+ *       }
+ *     },
+ *   });
+ *   app.post("/a2a", mw);
+ */
+function middlewareTasks(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-mw-opts",
+      "middleware.tasks: opts required (handler)", true);
+  }
+  if (typeof opts.handler !== "function") {
+    throw new A2aTasksError("a2a-tasks/bad-mw-opts",
+      "middleware.tasks: opts.handler must be a function", true);
+  }
+  if (opts.scopes !== undefined) {
+    if (typeof opts.scopes !== "object" || opts.scopes === null || Array.isArray(opts.scopes)) {
+      throw new A2aTasksError("a2a-tasks/bad-mw-opts",
+        "middleware.tasks: opts.scopes must be an object when provided", true);
+    }
+  }
+  var maxBytes = opts.maxBytes !== undefined ? opts.maxBytes : C.BYTES.mib(1);
+  var emitAudit = opts.audit !== false;
+  var scopes = opts.scopes || null;
+
+  return function a2aTasksMiddleware(req, res) {
+    if ((req.method || "").toUpperCase() !== "POST") {
+      res.statusCode = 405;                                                                        // allow:raw-byte-literal — HTTP 405 Method Not Allowed
+      res.setHeader("Content-Type", "application/json");
+      res.setHeader("Allow", "POST");
+      res.end(JSON.stringify(_jsonRpcError(null, JSONRPC_INVALID_REQUEST, "method must be POST")));
+      return;
+    }
+    var ctype = (req.headers && (req.headers["content-type"] || req.headers["Content-Type"])) || "";
+    if (typeof ctype === "string" && ctype.indexOf("application/json") !== 0 && ctype.indexOf("application/json") === -1) {
+      res.statusCode = 415;                                                                        // allow:raw-byte-literal — HTTP 415 Unsupported Media Type
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(_jsonRpcError(null, JSONRPC_INVALID_REQUEST, "Content-Type must be application/json")));
+      return;
+    }
+
+    _readBody(req, maxBytes).then(function (rawBytes) {
+      var body;
+      try {
+        body = safeJson.parse(rawBytes.toString("utf8"), { maxBytes: maxBytes });
+      } catch (_parseErr) {
+        res.statusCode = 400;                                                                      // allow:raw-byte-literal — HTTP 400 Bad Request
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(_jsonRpcError(null, JSONRPC_PARSE_ERROR, "invalid JSON body")));
+        return;
+      }
+      if (!body || typeof body !== "object" || body.jsonrpc !== JSONRPC_VERSION ||
+          typeof body.method !== "string") {
+        res.statusCode = 400;                                                                      // allow:raw-byte-literal — HTTP 400 Bad Request
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(_jsonRpcError(body && body.id, JSONRPC_INVALID_REQUEST,
+          "expected JSON-RPC 2.0 envelope { jsonrpc, id?, method, params? }")));
+        return;
+      }
+      var reqId = body.id !== undefined ? body.id : null;
+      if (ALLOWED_METHODS.indexOf(body.method) === -1) {
+        res.statusCode = 200;                                                                      // allow:raw-byte-literal — JSON-RPC errors return 200 with error envelope
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(_jsonRpcError(reqId, JSONRPC_METHOD_NOT_FOUND,
+          "method '" + body.method + "' not in [" + ALLOWED_METHODS.join(", ") + "]")));
+        return;
+      }
+      var params = body.params || {};
+
+      // Scope enforcement for tasks/send (task references a skill).
+      if (body.method === "tasks/send" && scopes) {
+        if (!params.task || typeof params.task !== "object" || typeof params.task.skill !== "string") {
+          res.statusCode = 200;                                                                    // allow:raw-byte-literal — JSON-RPC error envelope returns 200
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify(_jsonRpcError(reqId, JSONRPC_INVALID_PARAMS,
+            "tasks/send: params.task.skill required")));
+          return;
+        }
+        var requiredScope = scopes[params.task.skill];
+        if (typeof requiredScope === "string") {
+          var grantedScopes = Array.isArray(req.a2aScopes) ? req.a2aScopes : [];
+          if (grantedScopes.indexOf(requiredScope) === -1) {
+            if (emitAudit) {
+              _emitAudit("a2a.tasks.scope_denied",
+                { skill: params.task.skill, requiredScope: requiredScope }, "denied");
+            }
+            res.statusCode = 200;                                                                  // allow:raw-byte-literal — JSON-RPC error envelope returns 200
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(_jsonRpcError(reqId, A2A_SCOPE_DENIED,
+              "scope '" + requiredScope + "' required for skill '" + params.task.skill + "'")));
+            return;
+          }
+        }
+      }
+
+      var ctx = {
+        method:  body.method,
+        task:    params.task,
+        taskId:  params.taskId,
+        req:     req,
+      };
+      Promise.resolve()
+        .then(function () { return opts.handler(ctx); })
+        .then(function (result) {
+          if (emitAudit) {
+            _emitAudit("a2a.tasks.handled",
+              { method: body.method, skill: params.task && params.task.skill, taskId: params.taskId });
+          }
+          res.statusCode = 200;                                                                    // allow:raw-byte-literal — JSON-RPC 200 with result envelope
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify({
+            jsonrpc: JSONRPC_VERSION,
+            id:      reqId,
+            result:  result,
+          }));
+        })
+        .catch(function (handlerErr) {
+          var code = handlerErr && handlerErr.rpcCode || JSONRPC_INTERNAL_ERROR;
+          var msg  = (handlerErr && handlerErr.message) || "handler error";
+          if (emitAudit) {
+            _emitAudit("a2a.tasks.handler_error",
+              { method: body.method, errorMessage: msg, errorCode: code }, "warning");
+          }
+          res.statusCode = 200;                                                                    // allow:raw-byte-literal — JSON-RPC error envelope returns 200
+          res.setHeader("Content-Type", "application/json");
+          res.end(JSON.stringify(_jsonRpcError(reqId, code, msg)));
+        });
+    }).catch(function (readErr) {
+      res.statusCode = 400;                                                                        // allow:raw-byte-literal — HTTP 400 Bad Request
+      res.setHeader("Content-Type", "application/json");
+      res.end(JSON.stringify(_jsonRpcError(null, JSONRPC_PARSE_ERROR,
+        "could not read request body: " + (readErr.message || readErr))));
+    });
+  };
+}
+
+function _jsonRpcError(id, code, message, data) {
+  var err = { code: code, message: message };
+  if (data !== undefined) err.data = data;
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id:      id,
+    error:   err,
+  };
+}
+
+function _readBody(req, maxBytes) {
+  return new Promise(function (resolve, reject) {
+    var collector = safeBuffer.boundedChunkCollector({
+      maxBytes:    maxBytes,
+      errorClass:  A2aTasksError,
+      sizeCode:    "a2a-tasks/body-too-large",
+      sizeMessage: "a2a-tasks: request body exceeded " + maxBytes + " bytes",
+    });
+    req.on("data", function (chunk) {
+      try { collector.push(chunk); }
+      catch (capErr) { reject(capErr); }
+    });
+    req.on("end", function () { resolve(collector.result()); });
+    req.on("error", function (e) { reject(e); });
+  });
+}
+
+/**
+ * @primitive b.a2a.middleware.agentCard
+ * @signature b.a2a.middleware.agentCard(opts)
+ * @since     0.8.85
+ * @status    stable
+ * @related   b.a2a.signCard, b.a2a.middleware.tasks
+ *
+ * Build a middleware that serves the operator's Agent Card at
+ * `/.well-known/agent.json` per the A2A v1 discovery convention.
+ * The middleware writes a 200 JSON response on GET; refuses other
+ * methods with 405. Mount on a router path that resolves the
+ * well-known prefix (operator-side).
+ *
+ * @opts
+ *   card:        object (REQUIRED) — the signed-card envelope from b.a2a.signCard
+ *   maxAgeSec:   number (default 300) — Cache-Control max-age
+ *
+ * @example
+ *   var raw = b.a2a.createCard({
+ *     agent: { name: "my-agent", version: "1.0.0" },
+ *     skills: [{ name: "summarize" }],
+ *   });
+ *   var card = b.a2a.signCard(raw, pair.privateKey);
+ *   app.get("/.well-known/agent.json", b.a2a.middleware.agentCard({ card: card }));
+ */
+function middlewareAgentCard(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-mw-opts",
+      "middleware.agentCard: opts required (card)", true);
+  }
+  if (!opts.card || typeof opts.card !== "object") {
+    throw new A2aTasksError("a2a-tasks/bad-mw-opts",
+      "middleware.agentCard: opts.card required (output of b.a2a.signCard)", true);
+  }
+  numericBounds.requireNonNegativeFiniteIntIfPresent(
+    opts.maxAgeSec, "middleware.agentCard.maxAgeSec", A2aTasksError, "a2a-tasks/bad-max-age");
+  var maxAgeSec = (opts.maxAgeSec !== undefined && opts.maxAgeSec !== null && opts.maxAgeSec > 0)
+    ? Math.floor(opts.maxAgeSec)
+    : (C.TIME.minutes(5) / C.TIME.seconds(1));
+  var cardJson = JSON.stringify(opts.card);
+  return function a2aAgentCardMiddleware(req, res) {
+    if ((req.method || "").toUpperCase() !== "GET") {
+      res.statusCode = 405;                                                                        // allow:raw-byte-literal — HTTP 405 Method Not Allowed
+      res.setHeader("Allow", "GET");
+      res.end();
+      return;
+    }
+    res.statusCode = 200;                                                                          // allow:raw-byte-literal — HTTP 200 OK
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Cache-Control", "public, max-age=" + maxAgeSec);
+    res.end(cardJson);
+  };
+}
+
+module.exports = {
+  send:            send,
+  get:             get,
+  cancel:          cancel,
+  middleware: {
+    tasks:     middlewareTasks,
+    agentCard: middlewareAgentCard,
+  },
+  ALLOWED_METHODS: ALLOWED_METHODS,
+  A2aTasksError:   A2aTasksError,
+};