@adastracomputing/ink 0.1.0-alpha.2 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to INK and the reference implementation are recorded
+All notable changes to INK are recorded
 here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 [`docs/maturity.md`](docs/maturity.md) for the versioning policy.
 
@@ -8,6 +8,34 @@ here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 
 No unreleased changes.
 
+## 0.1.0-alpha.3, signed audit-query response
+
+Closes the last HIGH conformance-audit finding (witness audit-query
+response missing signature, proofs and protocol envelope).
+
+### Added
+
+- `signAuditQueryResponse(payload, privateKey)` and `verifyAuditQueryResponseSignature(payload, signature, publicKey)` primitives. Canonical signed bytes are `ink/audit-query-response/v1\n` + JCS(payload without serviceSignature). The payload binds `serviceDid`, `messageId`, `requester`, `events`, `proofs`, `treeSize`, `rootHash`, `timestamp`, so a valid signature cannot be rebound to a different witness, message, requester, or root.
+- `verifyAuditQueryResponse({response, witnessPublicKey, expectedRequester, expectedMessageId, verifyEventSignature, expectedServiceDid?, laterCheckpoint?})` is the recommended high-level verifier. `verifyEventSignature` is a REQUIRED callback that resolves the submitting agent's keys and validates each event's `agentSignature`. Without it, the verifier refuses to return valid, because Merkle inclusion alone does not prove agent provenance (§7.5). The function enforces envelope shape, requester binding, events/proofs strict one-to-one alignment, the §7.4 per-event scope rule, walks every Merkle proof via `computeAuditMerkleLeafHash` up to the response's `rootHash`, runs `verifyEventSignature` on every event and supports optional later-checkpoint cross-check. `verifyAuditQueryResponseSignature` alone is signature-only and is documented as a low-level primitive.
+- `computeAuditMerkleLeafHash(event)` primitive: the RFC 6962 leaf-hash rule for inclusion proofs, `SHA-256(0x00 || JCS(event-without-agentSignature))`. Distinct from `computeEventHash` (unprefixed, used only for `previousEventHash` chain linkage). Verifiers walking an inclusion proof MUST use this function, not `computeEventHash`.
+- Nix flake now exposes `apps.default`, so `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file r.json --witness URL` works without `npm install`.
+
+### Security
+
+- The §7.3 envelope now binds `requester`. Without this binding, a signed witness response generated for Alice could be replayed to Bob as Bob's authoritative view of the same `messageId`. Verifiers MUST check the response's `requester` equals their locally authenticated requester before accepting events as a complete view.
+- Witnesses MUST fail closed when the requester's visible event set for a `messageId` exceeds the response cap, returning an unsigned HTTP 413 rather than silently signing a partial response. The reference and OSS witnesses query `LIMIT MAX_QUERY_EVENTS + 1`, detect overflow and refuse to sign.
+- Witnesses MUST emit a deterministic, stable result-set order so signed bytes are reproducible. The reference and OSS witnesses use `ORDER BY event_id ASC`.
+- Storage-integrity failures during proof construction (missing event_hash, hash mismatch, missing Merkle node, unprovable leaf, malformed event_json) now return HTTP 500 instead of silently omitting events from a signed response.
+- All canonicalize-and-sign / canonicalize-and-verify paths now cap by UTF-8 byte length, not JS string length. With non-ASCII event data the prior cap could be undercounted and let oversized payloads through. Affects `buildSignatureBase`, `computeMessageHash`, `signAuditEvent` / `verifyAuditEventSignature`, `computeEventHash`, `signAuditResponse` / `verifyAuditResponseSignature`, `signAuditQueryResponse` / `verifyAuditQueryResponseSignature` and the witness `handleQuery` response-size guard.
+- `verifyAuditEventSignature`, `verifyAuditResponseSignature`, `verifyAuditQueryResponseSignature` now wrap canonicalization inside the try/catch, so payloads that pass the complexity precheck but throw inside `jcsCanonicalize` (e.g. objects with `undefined` values) return `false` instead of propagating.
+
+### Spec
+
+- `specs/ink-auditability.md` §7.3 (audit-query response) now defines the full signed-envelope shape: `{protocol, type: "network.tulpa.audit_query_response", serviceDid, messageId, requester, events, proofs[{eventId, leafIndex, inclusionProof}], treeSize, rootHash, timestamp, serviceSignature}`. Previous text described a bare `{events}` shape with no signature, no protocol envelope and no per-event proofs.
+- §7.3 leaf-hash text now references `computeAuditMerkleLeafHash` directly and warns implementers that `computeEventHash` (chain linkage) is NOT the leaf input.
+- §7.3 now explicitly forbids witnesses from signing partial results: truncation MUST be an unsigned error. A signed response is a complete enumeration of the requester's visible events at `(treeSize, rootHash)`.
+- §7.3 requires witnesses to emit `events` and `proofs` in a stable, deterministic order.
+
 ## 0.1.0-alpha.2, inclusion-receipt verifier
 
 Adds a public verification path for INK Auditability Section 7
@@ -21,7 +49,7 @@ trusting any specific operator's UI.
 
 ## 0.1.0-alpha.1, spec clarification
 
-Spec-only release. Reference-implementation code in `src/` is
+Spec-only release. Library code in `src/` is
 unchanged from `0.1.0-alpha.0`; the bundled spec text is updated.
 
 ### Spec changes
@@ -37,8 +65,7 @@ unchanged from `0.1.0-alpha.0`; the bundled spec text is updated.
 
 ## 0.1.0-alpha.0, first public alpha
 
-Initial open-source release of the INK protocol reference implementation
-and accompanying specification.
+Initial open-source release of the INK protocol library and specification.
 
 ### Protocol surface
 
@@ -53,7 +80,7 @@ and accompanying specification.
 - Optional containment extension: capability-gated visibility, handshake
   budgets, sender silent-drop after first rate-limit violation.
 
-### Reference implementation
+### Library
 
 - Public API exported from the package root, see README for the export
   surface.

package/CODE_OF_CONDUCT.md

@@ -11,7 +11,7 @@ Participate in this project as a professional. That means:
 - Assume good faith from contributors and maintainers. If you believe
   someone has acted in bad faith, raise it privately first.
 - Keep public discussions focused on the protocol, the spec, the
-  reference implementation, or related interoperability work.
+  library, or related interoperability work.
 
 ## Scope
 

package/README.md

@@ -65,7 +65,9 @@ const ok = await verifyInkSignature(input, signature, keypair.publicKey);
 
 For inbound request verification, `verifyInkAuth` parses the `Authorization: INK-Ed25519 <sig>` header, checks freshness, and applies the key-rotation authority rule. It requires a `nonceStore` option so the 5-minute freshness window does not silently accept replays; pass a `NonceStore` to have the middleware enforce single-use, or `"deferred"` to acknowledge that the caller will run `checkReplay` (or equivalent) elsewhere in the request pipeline.
 
-For consumers of audit-exchange responses, call both `verifyAuditResponseSignature` (signed response wrapper) and `verifyAuditEventChain` (sequence-by-one and `previousEventHash` continuity, fork detection). The signature gate alone does not prevent a witness from returning a gapped or forked slice.
+For consumers of bilateral audit-exchange responses (`network.tulpa.audit_response`), call both `verifyAuditResponseSignature` (signed response wrapper) and `verifyAuditEventChain` (sequence-by-one and `previousEventHash` continuity, fork detection). The signature gate alone does not prevent a peer from returning a gapped or forked slice.
+
+For consumers of witness audit-query responses (`network.tulpa.audit_query_response`, Auditability §7.3, added in `0.1.0-alpha.3`), call `verifyAuditQueryResponse({response, witnessPublicKey, expectedRequester, expectedMessageId, verifyEventSignature, expectedServiceDid?, laterCheckpoint?})`. The `verifyEventSignature` callback is REQUIRED: it resolves the submitting agent's Ed25519 keys (typically via Agent Card §2) and validates each event's `agentSignature`. Without it, the verifier refuses to return valid, because Merkle inclusion alone does not prove a real agent produced the event (§7.5). The verifier enforces envelope shape, the `requester` binding (prevents cross-requester replay), events/proofs strict one-to-one alignment, the §7.4 per-event scope rule, walks every Merkle proof via `computeAuditMerkleLeafHash` up to the response's `rootHash`, runs `verifyEventSignature` on every event and supports an optional later-checkpoint cross-check. The lower-level `verifyAuditQueryResponseSignature` is signature-only and is not sufficient to accept a witness response on its own.
 
 ## Tests
 
@@ -76,12 +78,12 @@ npm run lint        # eslint
 npm run check:surface   # public-surface drift check
 ```
 
-For Nix users: `nix develop` gives a pinned Node 22 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`.
+For Nix users: `nix develop` gives a pinned Node 22 + git + gitleaks shell. `nix build` produces the publishable npm tarball under `result/`. `nix run github:Ad-Astra-Computing/ink -- verify-inclusion --file receipt.json --witness https://witness.example.com` runs the CLI without installing anything globally.
 
 ## Layout
 
 ```
-src/           reference implementation
+src/           library implementation
   crypto/      signing, multi-key verification, key encoding
   models/      Zod schemas for Agent Card, handshake, key entries
   middleware/  transport-level INK auth (verifyInkAuth)
@@ -93,7 +95,7 @@ test-vectors/  JSON interop vectors
 test/          vitest unit + integration tests
 ```
 
-The reference implementation runs on any runtime providing standard Web Crypto and `fetch`: Node 22+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
+The library runs on any runtime providing standard Web Crypto and `fetch`: Node 22+, Deno, Bun, Cloudflare Workers, browsers. The timestamp freshness window is enforced inside `verifyInkAuth`; nonce single-use is enforced when a `NonceStore` is passed (otherwise `checkReplay` must be called separately). Nonce backing storage and its TTL policy are the integrator's choice.
 
 ## What's stable in v0.1
 
@@ -117,7 +119,7 @@ You will see `network.tulpa.*` on the wire (e.g. `network.tulpa.intent`) and `in
 
 ## Relationship to Tulpa
 
-INK is developed by [Ad Astra Computing](https://adastracomputing.com) as the underlying protocol for [Tulpa](https://tulpa.network). The spec and the reference implementation in this repo are deliberately free of Tulpa product code so other agent platforms can adopt INK without inheriting Tulpa's surface area. Tulpa's product integration (message orchestration, marketplace, user-facing APIs) lives in a separate, closed-source codebase.
+INK is developed by [Ad Astra Computing](https://adastracomputing.com) as the underlying protocol for [Tulpa](https://tulpa.network). The spec and the library in this repo are deliberately free of Tulpa product code so other agent platforms can adopt INK without inheriting Tulpa's surface area. Tulpa's product integration (message orchestration, marketplace, user-facing APIs) lives in a separate, closed-source codebase.
 
 ## Security
 

package/SECURITY.md

@@ -39,7 +39,7 @@ In scope:
 
 Out of scope:
 
-- DoS via high-entropy inputs against the reference implementation
+- DoS via high-entropy inputs against the library
 - Attacks that require a compromised identity system (e.g., a malicious PDS returning a fabricated DID document)
 - Timing side-channels in the reference `@noble/ed25519` verification
 - Attacks on Tulpa's product infrastructure (separate codebase, separate disclosure process)

package/bin/verify-inclusion-impl.mjs

@@ -76,7 +76,10 @@ Usage:
 Options:
   -w, --witness <url>      Witness base URL (e.g. https://witness.tulpa.network)
   -f, --file <path>        Receipt JSON file. Omit to read from stdin.
-  -e, --event-hash <hex>   Optional. Re-walk the inclusion proof using this leaf.
+  -e, --event-hash <hex>   Optional. RFC 6962 leaf hash for the audit event:
+                            SHA-256(0x00 || JCS(event-without-agentSignature)),
+                            hex-encoded. When set, the inclusion proof is
+                            re-walked from this leaf up to the claimed root.
   -h, --help               Show this help.
 
 Exit codes:

package/docs/maturity.md

@@ -17,7 +17,7 @@
   implementations should report discrepancies as issues.
 - The protocol is in use by one production integrator (Tulpa). That is
   one data point, not a guarantee of robustness at scale.
-- The reference implementation in `src/` runs on any runtime providing
+- The library in `src/` runs on any runtime providing
   standard Web Crypto (`crypto.subtle`) and `fetch`, modern Node, Deno,
   Bun, and edge runtimes. Browser use is feasible but not exercised by
   the maintainers.
@@ -55,7 +55,7 @@ Pre-1.0 releases follow `0.Y.Z` semantics:
 
 - `0.Y.0`, Minor version bump indicates a wire-format change. Receivers
   must support at least one prior minor during a transition window.
-- `0.Y.Z` (Z > 0), Patch bumps fix bugs in the reference implementation
+- `0.Y.Z` (Z > 0), Patch bumps fix bugs in the library
   and update test vectors where needed. They do not change wire format.
 
 Breaking changes before v1.0 will be announced in the repository
@@ -71,7 +71,7 @@ be a real incident:
    falls inside the in-scope protections and you accept the out-of-scope
    limits.
 2. Run `../test-vectors/*` against your implementation.
-3. Fuzz your envelope parser. The reference implementation's tests are
+3. Fuzz your envelope parser. The library's tests are
    not a substitute.
 4. Pen-test the rotation and revocation flows specifically. The
    authority rule is the single most security-sensitive piece and the

package/docs/threat-model.md

@@ -80,7 +80,7 @@ bounds the damage window but does not eliminate it. Key custody is out of
 scope.
 
 ### Malicious marketplace extensions (if you integrate one)
-The reference implementation does not include an extension/marketplace
+The library does not include an extension/marketplace
 layer. A product that integrates INK and adds a delegation-token layer
 (for third-party agents to act on behalf of users) must design its own
 trust model for the marketplace, manifest review, and capability

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adastracomputing/ink",
-  "version": "0.1.0-alpha.2",
-  "description": "Reference implementation and specification of the INK (Inter-agent Networking Kernel) protocol",
+  "version": "0.1.0-alpha.3",
+  "description": "Library and specification for the INK (Inter-agent Networking Kernel) protocol",
   "license": "MIT OR Apache-2.0",
   "author": "Ad Astra Computing Inc.",
   "repository": {
@@ -71,6 +71,6 @@
     "ed25519",
     "atproto",
     "agent-to-agent",
-    "reference-implementation"
+    "transparency-log"
   ]
 }

package/specs/ink-auditability.md

@@ -461,9 +461,9 @@ The audit service:
 1. Accepts signed `InkAuditEvent` submissions from agents
 2. Appends them to a **Merkle tree** (not just a hash chain, enables efficient inclusion proofs)
 3. Returns a **signed inclusion receipt** proving the event was recorded at a specific tree position and timestamp
-4. Serves **inclusion proofs** and **consistency proofs** on demand
+4. Serves **inclusion proofs** on demand (per-submission via the inclusion receipt and per-query via the signed `audit_query_response` envelope). **Consistency proofs** between two arbitrary checkpoints are not in scope for alpha.3; consistency-proof verification against external `tlog-witness` cosigners (§7.0) is the alpha.3 mitigation against split-view attacks.
 
-The service CANNOT forge events (they carry the submitting agent's Ed25519 signature). It CAN prove:
+The service CANNOT forge events that verifiers will accept, because every returned event carries the submitting agent's Ed25519 `agentSignature` and §7.3 verifiers re-check it against the agent's published keys. A witness that commits a fabricated event_json into its Merkle tree can produce a valid inclusion proof, but verifiers will reject the response when the agent signature fails to validate. (Verifiers that walk Merkle proofs without checking `agentSignature` lose this guarantee; see §7.5.) The service CAN prove:
 - That a specific event was submitted at a specific time (inclusion)
 - That the log is append-only and no events have been removed (consistency)
 - That two parties submitted conflicting events for the same message (conflict detection)
@@ -531,41 +531,66 @@ Authorization: INK-Ed25519 <signature>
 }
 ```
 
-**Response includes Merkle inclusion proofs:**
+**Response includes Merkle inclusion proofs and is signed by the witness:**
 
 ```json
 {
   "protocol": "ink/0.1",
-  "type": "network.tulpa.audit_response",
+  "type": "network.tulpa.audit_query_response",
+  "serviceDid": "did:web:witness.example.com",
   "messageId": "msg-123",
-  "events": [ /* InkAuditEvent[] from all agents */ ],
+  "requester": "did:plc:requester",
+  "events": [ /* InkAuditEvent[] visible to the requester */ ],
   "proofs": [
     {
       "eventId": "01JBTEST0001",
       "leafIndex": 48290,
-      "inclusionPath": ["<hash>", "<hash>", "..."],
-      "treeSize": 48291,
-      "rootHash": "<SHA-256 hex>"
+      "inclusionProof": ["<hash>", "<hash>", "..."]
     }
   ],
-  "serviceSignature": "<Ed25519 over JCS(response)>"
+  "treeSize": 48291,
+  "rootHash": "<SHA-256 hex of Merkle tree root at response time>",
+  "timestamp": "2026-03-19T13:00:01Z",
+  "serviceSignature": "<Ed25519, see canonical format below>"
 }
 ```
 
+**Canonical signature format.** `serviceSignature` is an Ed25519 signature over the bytes:
+
+```
+"ink/audit-query-response/v1\n" || JCS(response-fields-without-serviceSignature)
+```
+
+The signed payload binds the witness's `serviceDid`, the `messageId` requested, the authenticated `requester` whose access-control scope produced the result, every returned event, every inclusion proof, the witness's `treeSize` and `rootHash` at response time and the `timestamp`. The `proofs` array has one entry per event, keyed by `eventId`; verifiers MUST reject if proofs do not match events one-to-one. `treeSize` and `rootHash` apply uniformly to every proof. The `requester` binding prevents cross-requester replay: a witness response generated for Alice cannot be presented to Bob as Bob's authoritative view of the same `messageId`. Verifiers MUST check `requester` equals the locally authenticated requester before treating the response as their own scoped view.
+
+Per-event scope: a signed envelope binds `messageId` and `requester` but says nothing about the event objects until verifiers look inside them. To prevent a witness or a tampering intermediary from smuggling out-of-scope events into a signed response, verifiers MUST reject any response where, for any returned event, `event.messageId` differs from the envelope `messageId`, OR the envelope `requester` is neither `event.agentId` nor `event.counterpartyId`. Witnesses SHOULD reject the same conditions at signing time as defense in depth against storage corruption.
+
+Empty-log responses: a witness that has not yet committed any leaves reports `treeSize: 0` and `rootHash` equal to SHA-256 of the empty string (`e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855`). A signed response with `treeSize: 0` is legitimate but MUST also have empty `events`, empty `proofs` and the empty-tree `rootHash`. Verifiers MUST reject any `treeSize: 0` response that deviates from this shape.
+
+Per-event agent signatures: Merkle validity alone does NOT prove a returned event was produced by the agent named in `event.agentId`. A witness could in principle commit a fabricated event_json that is not a real `InkAuditEvent`. Every returned event MUST therefore include its `agentSignature` field. Verifiers MUST resolve the submitting agent's published Ed25519 keys (via Agent Card §2) and verify `agentSignature` on every event in addition to walking the Merkle proof. A response that omits `agentSignature` on any event MUST be rejected as structurally invalid.
+
+Truncation: witnesses MUST NOT silently sign a partial result. If the requester's visible event set for a `messageId` exceeds the witness's response cap, the witness MUST return an unsigned error response (HTTP 413). A signed response is, by definition, a complete enumeration of the requester's visible events for that `messageId` at `(treeSize, rootHash)`.
+
+Determinism: witnesses MUST emit `events` and matching `proofs` in a stable, deterministic order so verifiers can reproduce the signed bytes from the underlying records.
+
+Leaf hash: each event's Merkle leaf hash is `SHA-256(0x00 || JCS(event-without-agentSignature))`. The leading `0x00` byte is the RFC 6962 leaf-domain-separation tag; internal Merkle nodes use `0x01 || left || right`. Verifiers MUST rehash the returned `event` object themselves (stripping `agentSignature`, then JCS, then SHA-256 with the `0x00` prefix) and use that hash as the leaf input to `inclusionProof`. They MUST NOT trust any leaf-hash value supplied by the witness alongside the event. Walking the proof from this computed leaf hash up through `inclusionProof` MUST reach the top-level `rootHash` per the proof construction in §7.2. The INK library exposes this exact computation as `computeAuditMerkleLeafHash`; it is distinct from `computeEventHash`, which is the unprefixed SHA-256 used for `previousEventHash` chain linkage and MUST NOT be used as the Merkle leaf input.
+
 #### 7.4 Access Control
 
 The audit service operates under **access-controlled transparency** (per SCITT):
 - Events are tagged with the `messageId` and the DIDs of sender/recipient
-- Only the sender, recipient or a party with a valid delegation chain (§ INK Authorization Chain) can query events for a given `messageId`
+- Only the sender or recipient (i.e. an event's own `agentId` or `counterpartyId`) can query events for a given `messageId`. The witness MUST refuse to serve a row to any other requester
 - The service verifies the requester's identity via INK auth (§3.3) before serving events
-- The Merkle tree structure is public (anyone can verify consistency proofs) but event contents are access-controlled
+- The Merkle tree structure is public: anyone can verify inclusion proofs against signed checkpoints and, where consistency-proof endpoints are deployed, cross-check that checkpoints are append-only. Event contents remain access-controlled
+
+Delegated queries (where a third-party agent queries events on behalf of a principal via an INK Authorization Chain) are not in scope for alpha.3. A future revision will define the additional envelope fields the witness signs to bind the effective principal alongside the immediate requester, and verifiers will be updated accordingly. Until then, conformant witnesses MUST treat the per-event scope rule in §7.3 as authoritative: a returned event's `agentId` or `counterpartyId` MUST equal the response `requester`.
 
 This follows SCITT's model: the transparency guarantee (append-only, no suppression) is public, but the data itself is private.
 
 #### 7.5 Trust Model
 
 The audit service is a **semi-trusted witness**, not an arbiter:
-- It CANNOT forge events (Ed25519 signatures from agents)
+- It CANNOT forge events that verifiers will accept, because verifiers re-check `event.agentSignature` against the agent's published Ed25519 keys (§7.3). A witness that commits a fabricated event_json into its Merkle tree can produce a valid inclusion proof, but the per-event agent-signature check fails and the response is rejected. Verifiers that walk the proof without checking `agentSignature` lose this guarantee.
 - It CANNOT modify events without breaking Merkle proofs
 - It CAN suppress events by refusing to include them (detectable via consistency proofs between submissions)
 - It CAN be unavailable (agents fall back to bilateral exchange)

package/specs/ink-compliance-checklist.md

@@ -16,7 +16,7 @@ This checklist lets an independent implementer verify INK conformance without re
 - **SHOULD**, recommended; deviations require justification
 - **MAY**, truly optional; advertised via capability
 
-**Status column** applies to the Tulpa reference implementation:
+**Status column** applies to the Tulpa implementation:
 - **Required**, part of the v1 wire contract
 - **Optional**, capability-gated, not assumed
 - **Extension**, defined but not required for base interop
@@ -145,6 +145,14 @@ This checklist lets an independent implementer verify INK conformance without re
 | W6 | Checkpoint: C2SP tlog-checkpoint format at `GET /ink/v1/checkpoint` | SHOULD | Optional | Auditability §7 |, | `witness/witness/test/endpoints.test.ts (witness repo)` |
 | W7 | Transport auth on submit: dual signature (transport + event) | MUST | Optional | Auditability §7 | `witness.json` | `witness/witness/test/endpoints.test.ts (witness repo)` |
 | W8 | Submit includes `signingKeyId` in transport auth | SHOULD | Required | Key Rotation Phase 3 |, | `test/ink-key-rotation.test.ts` |
+| W9 | Query response is the signed `network.tulpa.audit_query_response` envelope binding `serviceDid`, `messageId`, `requester`, `events`, `proofs`, `treeSize`, `rootHash`, `timestamp` | MUST | Optional | Auditability §7.3 | `witness.json` | `test/audit-query-response.test.ts`, `test/verify-audit-query-response.test.ts` |
+| W10 | Per-event Merkle proof rule: leaf = `SHA-256(0x00 \|\| JCS(event-without-agentSignature))` (RFC 6962) | MUST | Optional | Auditability §7.3 | `witness.json` | `test/merkle-leaf-hash.test.ts` |
+| W11 | Per-event scope: `event.messageId == envelope.messageId` AND `envelope.requester ∈ {event.agentId, event.counterpartyId}` | MUST | Optional | Auditability §7.3, §7.4 |, | `test/verify-audit-query-response.test.ts` |
+| W12 | Deterministic result-set ordering so signed bytes are reproducible | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W13 | Fail-closed on truncation: refuse to sign a partial result; return unsigned 413 | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W14 | Fail-closed on storage integrity (event_hash mismatch, missing Merkle node, column-vs-event_json drift): HTTP 500, no signed response | MUST | Optional | Auditability §7.3 |, | `witness/witness/test/security-round12.test.ts (witness repo)` |
+| W15 | Empty-log response: `treeSize == 0` MUST have empty `events`, empty `proofs` and canonical empty-tree `rootHash` | MUST | Optional | Auditability §7.3 |, | `test/verify-audit-query-response.test.ts` |
+| W16 | Every returned event MUST include `agentSignature`; verifiers MUST verify it against the agent's published keys (witness Merkle validity does not prove agent provenance) | MUST | Optional | Auditability §7.3, §7.5 |, | `test/verify-audit-query-response.test.ts` |
 
 ---
 

package/src/audit/inclusion-receipt.ts

@@ -21,7 +21,14 @@
  * current checkpoint and calls verifyInclusionReceipt.
  */
 import * as ed from "@noble/ed25519";
-import { base64urlDecode, jcsCanonicalize, hexToBytes, bytesToHex } from "../crypto/ink.js";
+import {
+  base64urlDecode,
+  jcsCanonicalize,
+  hexToBytes,
+  bytesToHex,
+  computeAuditMerkleLeafHash,
+  verifyAuditQueryResponseSignature,
+} from "../crypto/ink.js";
 
 export interface InclusionReceipt {
   eventId: string;
@@ -61,9 +68,10 @@ export async function verifyInclusionReceipt(opts: {
   receipt: InclusionReceipt;
   /** Raw 32-byte Ed25519 public key of the witness service. */
   witnessPublicKey: Uint8Array;
-  /** Optional leaf hash (SHA-256 of JCS(audit event without agentSignature),
-   *  hex-encoded). When provided, the inclusion proof is walked from
-   *  the leaf up to the claimed rootHash. */
+  /** Optional RFC 6962 leaf hash for the underlying audit event:
+   *  SHA-256(0x00 || JCS(event-without-agentSignature)), hex-encoded.
+   *  Use `computeAuditMerkleLeafHash` to derive it. When provided, the
+   *  inclusion proof is walked from this leaf up to the claimed rootHash. */
   eventHash?: string;
   /** Optional later checkpoint to cross-check the receipt against.
    *  Must come from a `/ink/v1/checkpoint` response that the verifier
@@ -157,6 +165,281 @@ export async function verifyInclusionReceipt(opts: {
   return { valid: true, steps };
 }
 
+// ── Audit-query response verification (INK Auditability §7.3) ──
+//
+// The low-level `verifyAuditQueryResponseSignature` only checks the
+// Ed25519 signature over caller-supplied canonical bytes. This wrapper
+// is the recommended verifier for consumers of a witness response: it
+// re-derives the canonical bytes, then performs every additional
+// envelope and proof check §7.3 mandates.
+
+export interface AuditQueryResponse {
+  protocol: "ink/0.1";
+  type: "network.tulpa.audit_query_response";
+  serviceDid: string;
+  messageId: string;
+  requester: string;
+  events: Array<Record<string, unknown> & { id: string }>;
+  proofs: Array<{ eventId: string; leafIndex: number; inclusionProof: string[] }>;
+  treeSize: number;
+  rootHash: string;
+  timestamp: string;
+  serviceSignature: string;
+}
+
+export interface AuditQueryResponseVerifyResult {
+  valid: boolean;
+  steps: VerifyStep[];
+}
+
+/**
+ * Full §7.3 verification of a witness audit-query response. Use this in
+ * preference to `verifyAuditQueryResponseSignature`, which is the
+ * underlying primitive and verifies only the Ed25519 signature. This
+ * function additionally enforces:
+ *
+ *  - Envelope shape (protocol, type, serviceDid, requester, messageId,
+ *    timestamp, treeSize, rootHash, events[], proofs[])
+ *  - Service signature with the right canonical bytes
+ *  - Optional caller-supplied bindings: expected `messageId`,
+ *    `requester`, `serviceDid` (each rejected on mismatch)
+ *  - `events` and `proofs` align one-to-one by `eventId`
+ *  - Every event includes a non-empty `agentSignature` field
+ *  - Every proof walks from `computeAuditMerkleLeafHash(event)` up to
+ *    the response's `rootHash` at `treeSize`
+ *  - Optional `laterCheckpoint`: tree only grew, no fork at same size
+ *
+ * **Per-event agent-signature verification (§7.5 trust model).** A
+ * Merkle-valid response is necessary but not sufficient: the witness
+ * could in principle commit a fabricated "event" not signed by any
+ * agent, sign the resulting `(treeSize, rootHash)`, and the Merkle
+ * proof walks just fine. To detect this, callers MUST pass a
+ * `verifyEventSignature` callback that resolves the agent's published
+ * Ed25519 keys (typically via Agent Card §2) and validates
+ * `event.agentSignature`. The callback is REQUIRED, not optional: the
+ * verifier refuses to return `valid: true` without it, so a caller
+ * cannot accidentally accept witness-fabricated events.
+ *
+ * **Freshness.** A `valid: true` result attests that the response was a
+ * complete enumeration of the requester's visible events at the
+ * `(treeSize, rootHash)` snapshot the witness signed, NOT that it is
+ * the witness's current authoritative view. The signed envelope binds
+ * `timestamp`, but verifiers wanting "is this still current?"
+ * semantics MUST additionally fetch a fresh witness checkpoint and
+ * compare it (e.g. require `laterCheckpoint.treeSize === response.treeSize
+ * && laterCheckpoint.rootHash === response.rootHash` for "current", or
+ * use `laterCheckpoint` here only to prove the tree never rewound or
+ * forked).
+ *
+ * Returns `{valid, steps}` where each step explains pass/fail with detail.
+ * Pure function. Does not perform network I/O.
+ */
+export async function verifyAuditQueryResponse(opts: {
+  response: AuditQueryResponse;
+  /** Raw 32-byte Ed25519 public key of the witness service. */
+  witnessPublicKey: Uint8Array;
+  /** Locally authenticated requester DID. Verifier MUST supply this so
+   *  a response signed for Alice cannot be replayed to Bob. */
+  expectedRequester: string;
+  /** The `messageId` the verifier asked about. Bound for paranoia: the
+   *  signed envelope already commits to messageId, so this catches
+   *  client-side routing bugs before they become trust bugs. */
+  expectedMessageId: string;
+  /** Optional: witness DID the verifier expects (pinned out of band). */
+  expectedServiceDid?: string;
+  /** Optional later checkpoint to cross-check against. Same semantics
+   *  as `verifyInclusionReceipt`. */
+  laterCheckpoint?: { treeSize: number; rootHash: string };
+  /** Per-event agent-signature verifier (REQUIRED by Auditability §7.5).
+   *  The caller resolves the event's submitting agent's public key set
+   *  (typically from the Agent Card) and returns true if
+   *  `event.agentSignature` verifies. The verifier refuses to return
+   *  `valid: true` without this: Merkle inclusion alone does not prove
+   *  the agent produced the event. If a caller genuinely wants to
+   *  bypass per-event signature checks (e.g. during a pure Merkle
+   *  audit), they MUST explicitly pass a callback that does so. */
+  verifyEventSignature: (event: Record<string, unknown>) => Promise<boolean>;
+}): Promise<AuditQueryResponseVerifyResult> {
+  const steps: VerifyStep[] = [];
+  const { response, witnessPublicKey, expectedRequester, expectedMessageId, expectedServiceDid, laterCheckpoint, verifyEventSignature } = opts;
+
+  // ── Step 1: structural validation ──
+  const structuralProblem = checkAuditQueryResponseShape(response);
+  if (structuralProblem) {
+    steps.push({ name: "structure", pass: false, detail: structuralProblem });
+    return { valid: false, steps };
+  }
+  steps.push({ name: "structure", pass: true });
+
+  // ── Step 2: caller-supplied binding checks ──
+  if (response.messageId !== expectedMessageId) {
+    steps.push({ name: "binding", pass: false, detail: `messageId mismatch: response=${response.messageId} expected=${expectedMessageId}` });
+    return { valid: false, steps };
+  }
+  if (response.requester !== expectedRequester) {
+    steps.push({ name: "binding", pass: false, detail: "requester mismatch (response signed for a different requester)" });
+    return { valid: false, steps };
+  }
+  if (expectedServiceDid !== undefined && response.serviceDid !== expectedServiceDid) {
+    steps.push({ name: "binding", pass: false, detail: `serviceDid mismatch: response=${response.serviceDid} expected=${expectedServiceDid}` });
+    return { valid: false, steps };
+  }
+  steps.push({ name: "binding", pass: true });
+
+  // ── Step 3: signature over canonical bytes ──
+  const { serviceSignature, ...payload } = response;
+  const sigValid = await verifyAuditQueryResponseSignature(
+    payload as unknown as Record<string, unknown>,
+    serviceSignature,
+    witnessPublicKey,
+  );
+  if (!sigValid) {
+    steps.push({ name: "signature", pass: false, detail: "Ed25519 verification failed" });
+    return { valid: false, steps };
+  }
+  steps.push({ name: "signature", pass: true });
+
+  // ── Step 4: per-event scope check ──
+  //
+  // The envelope binds messageId and requester, but until we look INTO
+  // each event we don't know the witness isn't returning a Merkle-valid
+  // event from a different messageId or one the requester is not a
+  // party to. Reject any event whose own fields contradict the envelope.
+  for (const event of response.events) {
+    const eMessageId = (event as { messageId?: unknown }).messageId;
+    if (typeof eMessageId !== "string" || eMessageId !== response.messageId) {
+      steps.push({ name: "scope", pass: false, detail: `event ${event.id}: messageId does not match envelope` });
+      return { valid: false, steps };
+    }
+    const eAgentId = (event as { agentId?: unknown }).agentId;
+    const eCounterpartyId = (event as { counterpartyId?: unknown }).counterpartyId;
+    const requesterIsParty =
+      (typeof eAgentId === "string" && eAgentId === expectedRequester) ||
+      (typeof eCounterpartyId === "string" && eCounterpartyId === expectedRequester);
+    if (!requesterIsParty) {
+      steps.push({ name: "scope", pass: false, detail: `event ${event.id}: requester ${expectedRequester} is not a party (agentId/counterpartyId)` });
+      return { valid: false, steps };
+    }
+  }
+  steps.push({ name: "scope", pass: true });
+
+  // ── Step 5: events ↔ proofs strict one-to-one by eventId ──
+  //
+  // §7.3 mandates a one-to-one mapping. Enforce both directions:
+  //   - No duplicate event.id (otherwise `events: [A, A]` paired with
+  //     `proofs: [proof(A), proof(extra)]` could pass length + has-proof
+  //     checks while including a proof for an unverified event).
+  //   - No duplicate proof.eventId.
+  //   - Every proof.eventId corresponds to some event.id (no "extra"
+  //     proofs for events not in the response).
+  if (response.events.length !== response.proofs.length) {
+    steps.push({ name: "proofs", pass: false, detail: `events and proofs length differ: ${response.events.length} vs ${response.proofs.length}` });
+    return { valid: false, steps };
+  }
+  const eventIds = new Set<string>();
+  for (const event of response.events) {
+    if (eventIds.has(event.id)) {
+      steps.push({ name: "proofs", pass: false, detail: `duplicate event id ${event.id}` });
+      return { valid: false, steps };
+    }
+    eventIds.add(event.id);
+  }
+  const proofById = new Map<string, { leafIndex: number; inclusionProof: string[] }>();
+  for (const p of response.proofs) {
+    if (proofById.has(p.eventId)) {
+      steps.push({ name: "proofs", pass: false, detail: `duplicate proof for eventId ${p.eventId}` });
+      return { valid: false, steps };
+    }
+    if (!eventIds.has(p.eventId)) {
+      steps.push({ name: "proofs", pass: false, detail: `proof references unknown eventId ${p.eventId}` });
+      return { valid: false, steps };
+    }
+    proofById.set(p.eventId, { leafIndex: p.leafIndex, inclusionProof: p.inclusionProof });
+  }
+  for (const event of response.events) {
+    if (!proofById.has(event.id)) {
+      steps.push({ name: "proofs", pass: false, detail: `event ${event.id} has no matching proof` });
+      return { valid: false, steps };
+    }
+  }
+  steps.push({ name: "proofs", pass: true });
+
+  // ── Step 6: walk each inclusion proof ──
+  for (const event of response.events) {
+    const p = proofById.get(event.id)!;
+    let leafHash: string;
+    try {
+      leafHash = await computeAuditMerkleLeafHash(event as unknown as Record<string, unknown>);
+    } catch (e) {
+      steps.push({ name: "proof-walk", pass: false, detail: `event ${event.id}: leaf-hash computation failed: ${e instanceof Error ? e.message : String(e)}` });
+      return { valid: false, steps };
+    }
+    const ok = await verifyInclusionProof(leafHash, p.inclusionProof, p.leafIndex, response.treeSize, response.rootHash);
+    if (!ok) {
+      steps.push({ name: "proof-walk", pass: false, detail: `event ${event.id}: leaf-to-root walk did not reach claimed rootHash` });
+      return { valid: false, steps };
+    }
+  }
+  steps.push({ name: "proof-walk", pass: true });
+
+  // ── Step 6: per-event agent signature ──
+  //
+  // Merkle validity proves the witness committed to these exact event
+  // bytes; it does NOT prove an agent ever signed them. The caller
+  // MUST supply `verifyEventSignature`; we refuse to return valid
+  // otherwise.
+  if (typeof verifyEventSignature !== "function") {
+    steps.push({
+      name: "agent-signature",
+      pass: false,
+      detail: "verifyEventSignature callback is required (Auditability §7.5); refusing to accept witness Merkle inclusion as proof of agent provenance",
+    });
+    return { valid: false, steps };
+  }
+  for (const event of response.events) {
+    let ok = false;
+    try {
+      ok = await verifyEventSignature(event as unknown as Record<string, unknown>);
+    } catch (e) {
+      steps.push({ name: "agent-signature", pass: false, detail: `event ${event.id}: verifier threw: ${e instanceof Error ? e.message : String(e)}` });
+      return { valid: false, steps };
+    }
+    if (!ok) {
+      steps.push({ name: "agent-signature", pass: false, detail: `event ${event.id}: agentSignature did not verify` });
+      return { valid: false, steps };
+    }
+  }
+  steps.push({ name: "agent-signature", pass: true });
+
+  // ── Step 7: optional later-checkpoint cross-check ──
+  if (laterCheckpoint !== undefined) {
+    const cpShape = checkCheckpointShape(laterCheckpoint);
+    if (cpShape) {
+      steps.push({ name: "checkpoint", pass: false, detail: cpShape });
+      return { valid: false, steps };
+    }
+    if (laterCheckpoint.treeSize < response.treeSize) {
+      steps.push({
+        name: "checkpoint",
+        pass: false,
+        detail: `checkpoint treeSize ${laterCheckpoint.treeSize} < response treeSize ${response.treeSize} (witness rewound the tree)`,
+      });
+      return { valid: false, steps };
+    }
+    if (laterCheckpoint.treeSize === response.treeSize && laterCheckpoint.rootHash !== response.rootHash) {
+      steps.push({
+        name: "checkpoint",
+        pass: false,
+        detail: "checkpoint rootHash differs from response rootHash at same treeSize (fork)",
+      });
+      return { valid: false, steps };
+    }
+    steps.push({ name: "checkpoint", pass: true });
+  }
+
+  return { valid: true, steps };
+}
+
 // ── Internal helpers ──
 
 /** Generous upper bound on inclusion-proof length. Real proofs are
@@ -192,6 +475,59 @@ function checkReceiptShape(receipt: InclusionReceipt): string | null {
   return null;
 }
 
+// SHA-256("") in hex, used as the empty-log Merkle root per RFC 6962 §2.1.
+// A fresh witness with no submissions reports treeSize=0 and rootHash=EMPTY_TREE_ROOT.
+const EMPTY_TREE_ROOT = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+
+function checkAuditQueryResponseShape(r: AuditQueryResponse): string | null {
+  if (r === null || typeof r !== "object") return "response is not an object";
+  if (r.protocol !== "ink/0.1") return `protocol must be "ink/0.1"`;
+  if (r.type !== "network.tulpa.audit_query_response") return `type must be "network.tulpa.audit_query_response"`;
+  if (typeof r.serviceDid !== "string" || r.serviceDid.length === 0) return "serviceDid missing";
+  if (typeof r.messageId !== "string" || r.messageId.length === 0) return "messageId missing";
+  if (typeof r.requester !== "string" || r.requester.length === 0) return "requester missing";
+  if (typeof r.timestamp !== "string" || r.timestamp.length === 0) return "timestamp missing";
+  if (typeof r.serviceSignature !== "string" || r.serviceSignature.length === 0) return "serviceSignature missing";
+  if (!Number.isInteger(r.treeSize) || r.treeSize < 0) return "treeSize must be a non-negative integer";
+  if (typeof r.rootHash !== "string" || !/^[0-9a-f]{64}$/.test(r.rootHash)) {
+    return "rootHash must be 64 lowercase hex chars";
+  }
+  if (!Array.isArray(r.events)) return "events must be an array";
+  if (!Array.isArray(r.proofs)) return "proofs must be an array";
+  // Empty-log case: a fresh witness can sign treeSize=0 with the
+  // canonical empty-tree root and zero events/proofs. Any other shape
+  // at treeSize=0 is the witness fabricating a state.
+  if (r.treeSize === 0) {
+    if (r.events.length !== 0) return "treeSize=0 response must have empty events";
+    if (r.proofs.length !== 0) return "treeSize=0 response must have empty proofs";
+    if (r.rootHash !== EMPTY_TREE_ROOT) return "treeSize=0 response must have the empty-tree rootHash";
+  }
+  for (const e of r.events) {
+    if (e === null || typeof e !== "object") return "every event must be an object";
+    if (typeof (e as { id?: unknown }).id !== "string") return "every event must have a string id";
+    const agentSig = (e as { agentSignature?: unknown }).agentSignature;
+    if (typeof agentSig !== "string" || agentSig.length === 0) {
+      return "every event must include a non-empty agentSignature";
+    }
+  }
+  for (const p of r.proofs) {
+    if (p === null || typeof p !== "object") return "every proof must be an object";
+    if (typeof p.eventId !== "string" || p.eventId.length === 0) return "every proof must have an eventId";
+    if (!Number.isInteger(p.leafIndex) || p.leafIndex < 0) return "every proof.leafIndex must be a non-negative integer";
+    if (p.leafIndex >= r.treeSize) return "every proof.leafIndex must be < treeSize";
+    if (!Array.isArray(p.inclusionProof)) return "every proof.inclusionProof must be an array";
+    if (p.inclusionProof.length > MAX_PROOF_LENGTH) {
+      return `proof.inclusionProof exceeds max length of ${MAX_PROOF_LENGTH} entries`;
+    }
+    for (const h of p.inclusionProof) {
+      if (typeof h !== "string" || !/^[0-9a-f]{64}$/.test(h)) {
+        return "every inclusionProof entry must be 64 lowercase hex chars";
+      }
+    }
+  }
+  return null;
+}
+
 function checkCheckpointShape(cp: { treeSize: number; rootHash: string }): string | null {
   if (cp === null || typeof cp !== "object") return "laterCheckpoint must be an object";
   if (!Number.isInteger(cp.treeSize) || cp.treeSize < 0) {

package/src/crypto/ink.ts

@@ -211,7 +211,7 @@ export function buildSignatureBase(input: InkSignInput): string {
     throw new Error("Signature base body exceeds maximum allowed complexity");
   }
   const canonical = jcsCanonicalize(input.body);
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) {
+  if (new TextEncoder().encode(canonical).length > MAX_SIGBASE_BODY_BYTES) {
     throw new Error("Signature base body exceeds maximum allowed size");
   }
   return `ink/0.1\n${input.method}\n${input.path}\n${input.recipientDid}\n${canonical}\n${input.timestamp}`;
@@ -685,10 +685,10 @@ export async function computeMessageHash(body: Record<string, unknown>): Promise
     throw new Error("Message body exceeds maximum allowed complexity");
   }
   const canonical = jcsCanonicalize(body);
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) {
+  const bytes = new TextEncoder().encode(canonical);
+  if (bytes.length > MAX_SIGBASE_BODY_BYTES) {
     throw new Error("Message body exceeds maximum allowed size");
   }
-  const bytes = new TextEncoder().encode(canonical);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return bytesToHex(new Uint8Array(digest));
 }
@@ -713,12 +713,11 @@ export async function signAuditEvent(
     throw new Error("Audit event exceeds maximum allowed complexity");
   }
   const canonical = jcsCanonicalize(eventWithoutSig);
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) {
-    throw new Error("Audit event exceeds maximum allowed size");
-  }
-  // Domain separation: prefix prevents cross-protocol signature replay
   const prefixed = `ink/audit-event\n${canonical}`;
   const bytes = new TextEncoder().encode(prefixed);
+  if (bytes.length > MAX_SIGBASE_BODY_BYTES) {
+    throw new Error("Audit event exceeds maximum allowed size");
+  }
   const sig = await ed.signAsync(bytes, privateKey);
   return base64urlEncode(sig);
 }
@@ -741,24 +740,58 @@ export async function verifyAuditEventSignature(
   // attacker-supplied object that would only get rejected by the size cap
   // below. Cheap enough that it adds no cost for real events.
   if (!isWithinCanonicalizeBounds(eventWithoutSig)) return false;
-  const canonical = jcsCanonicalize(eventWithoutSig);
-  // Defense-in-depth: cap canonicalized body size to bound pre-verify work.
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) return false;
-  // Domain separation: must match signAuditEvent prefix
-  const prefixed = `ink/audit-event\n${canonical}`;
-  const bytes = new TextEncoder().encode(prefixed);
   try {
+    const canonical = jcsCanonicalize(eventWithoutSig);
+    const prefixed = `ink/audit-event\n${canonical}`;
+    const bytes = new TextEncoder().encode(prefixed);
+    // Defense-in-depth: cap signed-body byte count to bound pre-verify work.
+    // UTF-8 byte length, not JS string length, so multi-byte event data
+    // cannot smuggle past the cap.
+    if (bytes.length > MAX_SIGBASE_BODY_BYTES) return false;
     const sig = base64urlDecode(signature);
     return await ed.verifyAsync(sig, bytes, publicKey);
   } catch {
-    // Malformed signature (wrong length, invalid chars, bad key) — treat as invalid
     return false;
   }
 }
 
+/**
+ * Compute the RFC 6962 Merkle leaf hash for an INK audit event:
+ *
+ *   SHA-256(0x00 || JCS(event-without-agentSignature))
+ *
+ * This is the leaf-hashing rule a witness MUST use when building its
+ * transparency log (Auditability §7.3). It is distinct from
+ * `computeEventHash`, which omits the 0x00 prefix and is used only for
+ * `previousEventHash` chain linkage inside the agent's local audit log.
+ *
+ * Returns the lowercase-hex digest.
+ */
+export async function computeAuditMerkleLeafHash(event: Record<string, unknown>): Promise<string> {
+  if (event === null || typeof event !== "object" || Array.isArray(event)) {
+    throw new Error("event must be a non-null object");
+  }
+  const { agentSignature: _, ...eventWithoutSig } = event;
+  if (!isWithinCanonicalizeBounds(eventWithoutSig)) {
+    throw new Error("Audit event exceeds maximum allowed complexity");
+  }
+  const canonical = jcsCanonicalize(eventWithoutSig);
+  const canonicalBytes = new TextEncoder().encode(canonical);
+  if (canonicalBytes.length > MAX_SIGBASE_BODY_BYTES) {
+    throw new Error("Audit event exceeds maximum allowed size");
+  }
+  const prefixed = new Uint8Array(canonicalBytes.length + 1);
+  prefixed[0] = 0x00;
+  prefixed.set(canonicalBytes, 1);
+  const digest = await crypto.subtle.digest("SHA-256", prefixed);
+  return bytesToHex(new Uint8Array(digest));
+}
+
 /**
  * Compute SHA-256 hash of JCS-canonicalized audit event (excluding agentSignature).
- * Used for previousEventHash chain linkage.
+ * Used for previousEventHash chain linkage. NOT the Merkle leaf hash:
+ * see `computeAuditMerkleLeafHash` for the RFC 6962 leaf-hash rule used
+ * by witness transparency logs.
  */
 export async function computeEventHash(event: Record<string, unknown>): Promise<string> {
   if (event === null || typeof event !== "object" || Array.isArray(event)) {
@@ -773,10 +806,10 @@ export async function computeEventHash(event: Record<string, unknown>): Promise<
     throw new Error("Audit event exceeds maximum allowed complexity");
   }
   const canonical = jcsCanonicalize(eventWithoutSig);
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) {
+  const bytes = new TextEncoder().encode(canonical);
+  if (bytes.length > MAX_SIGBASE_BODY_BYTES) {
     throw new Error("Audit event exceeds maximum allowed size");
   }
-  const bytes = new TextEncoder().encode(canonical);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return bytesToHex(new Uint8Array(digest));
 }
@@ -797,14 +830,14 @@ export async function signAuditResponse(
     throw new Error("Audit response events exceed maximum allowed complexity");
   }
   const canonical = jcsCanonicalize(events);
-  // Cap canonicalized body size — mirrors the verify path's guard so the
-  // sign side can't be used to mint signatures over payloads larger than
-  // any conformant verifier would accept.
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) {
-    throw new Error("Audit response events exceed maximum allowed size");
-  }
   const prefixed = `ink/audit-response\n${canonical}`;
   const bytes = new TextEncoder().encode(prefixed);
+  // Cap signed-body byte count. Mirrors the verify path's guard so the
+  // sign side can't mint signatures over payloads larger than any
+  // conformant verifier would accept.
+  if (bytes.length > MAX_SIGBASE_BODY_BYTES) {
+    throw new Error("Audit response events exceed maximum allowed size");
+  }
   const sig = await ed.signAsync(bytes, privateKey);
   return base64urlEncode(sig);
 }
@@ -825,16 +858,14 @@ export async function verifyAuditResponseSignature(
   if (!/^[A-Za-z0-9_-]{86}$/.test(signature)) return false;
   // Pre-canonicalize complexity cap (see verifyAuditEventSignature).
   if (!isWithinCanonicalizeBounds(events)) return false;
-  const canonical = jcsCanonicalize(events);
-  // Defense-in-depth: cap canonicalized body size to bound pre-verify work.
-  if (canonical.length > MAX_SIGBASE_BODY_BYTES) return false;
-  const prefixed = `ink/audit-response\n${canonical}`;
-  const bytes = new TextEncoder().encode(prefixed);
   try {
+    const canonical = jcsCanonicalize(events);
+    const prefixed = `ink/audit-response\n${canonical}`;
+    const bytes = new TextEncoder().encode(prefixed);
+    if (bytes.length > MAX_SIGBASE_BODY_BYTES) return false;
     const sig = base64urlDecode(signature);
     return await ed.verifyAsync(sig, bytes, publicKey);
   } catch {
-    // Malformed signature (wrong length, invalid chars, bad key) — treat as invalid
     return false;
   }
 }
@@ -898,5 +929,118 @@ export async function verifyAuditEventChain(
   return { valid: true };
 }
 
+// ── Audit-query response (witness side, Auditability Section 7.3) ──
+//
+// Distinct from signAuditResponse, which is the bilateral peer-to-peer
+// audit-exchange response between two agents. The witness query response
+// commits the WITNESS to (a) the events, (b) per-event Merkle proofs,
+// (c) the witness's treeSize / rootHash at response time, (d) the
+// messageId queried, signed under the witness's identity key.
+
+/**
+ * Sign an INK audit-query response from a witness. The signed bytes are:
+ *
+ *   "ink/audit-query-response/v1\n" + JCS(response object minus serviceSignature)
+ *
+ * Callers pass the response object EXCLUDING `serviceSignature`. The
+ * canonical bytes bind every other field, including `protocol`, `type`,
+ * `messageId`, `events`, `proofs`, `treeSize`, `rootHash`, `serviceDid`,
+ * and `timestamp`, so verifiers cannot rebind a valid signature to a
+ * different witness/message/root.
+ */
+export async function signAuditQueryResponse(
+  responseWithoutSignature: Record<string, unknown>,
+  privateKey: Uint8Array,
+): Promise<string> {
+  if (responseWithoutSignature === null || typeof responseWithoutSignature !== "object" || Array.isArray(responseWithoutSignature)) {
+    throw new Error("response must be a non-null object");
+  }
+  // §7.3 / §7.4 sign-side scope enforcement. A conformant witness must
+  // not mint a signature over a response where any event falls outside
+  // the envelope's (messageId, requester) scope: those rules apply at
+  // sign time as well as at verify time. Without this, a witness that
+  // composed payloads incorrectly could ship alpha.3-invalid signed
+  // bytes that the high-level verifier would then reject. Catching it
+  // here ensures the primitive is self-defending.
+  const envMessageId = (responseWithoutSignature as { messageId?: unknown }).messageId;
+  const envRequester = (responseWithoutSignature as { requester?: unknown }).requester;
+  const events = (responseWithoutSignature as { events?: unknown }).events;
+  if (Array.isArray(events) && events.length > 0) {
+    if (typeof envMessageId !== "string" || envMessageId.length === 0) {
+      throw new Error("Audit-query response must include a non-empty messageId");
+    }
+    if (typeof envRequester !== "string" || envRequester.length === 0) {
+      throw new Error("Audit-query response must include a non-empty requester");
+    }
+    for (const event of events) {
+      if (event === null || typeof event !== "object" || Array.isArray(event)) {
+        throw new Error("Every event must be a non-null object");
+      }
+      const e = event as { messageId?: unknown; agentId?: unknown; counterpartyId?: unknown; agentSignature?: unknown };
+      if (e.messageId !== envMessageId) {
+        throw new Error("Per-event scope violation: event.messageId does not match envelope.messageId");
+      }
+      const requesterIsParty =
+        (typeof e.agentId === "string" && e.agentId === envRequester) ||
+        (typeof e.counterpartyId === "string" && e.counterpartyId === envRequester);
+      if (!requesterIsParty) {
+        throw new Error("Per-event scope violation: requester is not a party (agentId/counterpartyId)");
+      }
+      // §7.3 verifier MUST check agentSignature; sign-side mirror so a
+      // witness using this primitive cannot ship signed responses that
+      // strip per-event provenance.
+      if (typeof e.agentSignature !== "string" || e.agentSignature.length === 0) {
+        throw new Error("Per-event scope violation: event.agentSignature is missing or empty");
+      }
+    }
+  }
+  if (!isWithinCanonicalizeBounds(responseWithoutSignature)) {
+    throw new Error("Audit-query response exceeds maximum allowed complexity");
+  }
+  const canonical = jcsCanonicalize(responseWithoutSignature);
+  const prefixed = `ink/audit-query-response/v1\n${canonical}`;
+  const bytes = new TextEncoder().encode(prefixed);
+  if (bytes.length > MAX_SIGBASE_BODY_BYTES) {
+    throw new Error("Audit-query response exceeds maximum allowed size");
+  }
+  const sig = await ed.signAsync(bytes, privateKey);
+  return base64urlEncode(sig);
+}
+
+/**
+ * Verify the Ed25519 signature on an audit-query response. This is the
+ * LOW-LEVEL primitive. Most consumers should call
+ * `verifyAuditQueryResponse` (from `src/audit/inclusion-receipt.ts`)
+ * instead: it enforces envelope shape, requester binding, the
+ * events-to-proofs one-to-one mapping, and walks every Merkle proof.
+ *
+ * Calling this function alone does NOT prove the response is acceptable.
+ * A signed but malformed envelope (wrong type, wrong protocol, no
+ * proofs, wrong requester) can still pass here. Caller is responsible
+ * for pinning / resolving the witness public key out of band (e.g.
+ * via /.well-known/did.json). Returns false (never throws) for any
+ * malformed input.
+ */
+export async function verifyAuditQueryResponseSignature(
+  responseWithoutSignature: Record<string, unknown>,
+  signature: string,
+  publicKey: Uint8Array,
+): Promise<boolean> {
+  if (responseWithoutSignature === null || typeof responseWithoutSignature !== "object" || Array.isArray(responseWithoutSignature)) return false;
+  if (typeof signature !== "string") return false;
+  if (!/^[A-Za-z0-9_-]{86}$/.test(signature)) return false;
+  if (!isWithinCanonicalizeBounds(responseWithoutSignature)) return false;
+  try {
+    const canonical = jcsCanonicalize(responseWithoutSignature);
+    const prefixed = `ink/audit-query-response/v1\n${canonical}`;
+    const bytes = new TextEncoder().encode(prefixed);
+    if (bytes.length > MAX_SIGBASE_BODY_BYTES) return false;
+    const sig = base64urlDecode(signature);
+    return await ed.verifyAsync(sig, bytes, publicKey);
+  } catch {
+    return false;
+  }
+}
+
 // Re-export encoding helpers for test use
 export { base64urlEncode, base64urlDecode, hexToBytes, bytesToHex, jcsCanonicalize };

package/src/index.ts

@@ -9,11 +9,14 @@ export {
   buildAuthHeader,
   computeMessageHash,
   computeEventHash,
+  computeAuditMerkleLeafHash,
   signAuditEvent,
   verifyAuditEventSignature,
   signAuditResponse,
   verifyAuditResponseSignature,
   verifyAuditEventChain,
+  signAuditQueryResponse,
+  verifyAuditQueryResponseSignature,
   encryptInkPayload,
   decryptInkPayload,
   checkReplay,
@@ -46,11 +49,14 @@ export {
 // Middleware: transport-level INK auth
 export { verifyInkAuth, type NonceStore } from "./middleware/ink-auth.js";
 
-// Audit: inclusion-receipt verification
+// Audit: inclusion-receipt + audit-query-response verification
 export {
   verifyInclusionReceipt,
+  verifyAuditQueryResponse,
   type InclusionReceipt,
   type InclusionReceiptVerifyResult,
+  type AuditQueryResponse,
+  type AuditQueryResponseVerifyResult,
   type VerifyStep,
 } from "./audit/inclusion-receipt.js";
 

package/src/models/ink-audit.ts

@@ -66,18 +66,18 @@ export type InkAuditEventType = z.infer<typeof InkAuditEventTypeSchema>;
 // ── INK Audit Event (hash-chained, signed) ──
 
 export const InkAuditEventSchema = z.object({
-  id: z.string(),
+  id: z.string().min(1),
   version: z.literal("ink-audit/1"),
-  agentId: z.string(),
-  agentSignature: z.string(),
+  agentId: z.string().min(1),
+  agentSignature: z.string().min(1),
   sequence: z.number().int().positive(),
-  previousEventHash: z.string().nullable(),
+  previousEventHash: z.string().regex(/^[0-9a-f]{64}$/).nullable(),
   eventType: InkAuditEventTypeSchema,
   timestamp: z.string().datetime(),
-  messageId: z.string().optional(),
-  correlationId: z.string().optional(),
-  counterpartyId: z.string().optional(),
-  signingKeyId: z.string().optional(),
+  messageId: z.string().min(1).optional(),
+  correlationId: z.string().min(1).optional(),
+  counterpartyId: z.string().min(1).optional(),
+  signingKeyId: z.string().min(1).optional(),
   data: z.record(z.unknown()).optional(),
 });