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

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,58 @@ here. Pre-1.0 releases follow `0.Y.Z` semantics, see
 
 No unreleased changes.
 
+## 0.1.0-alpha.5, ship compiled JS
+
+Fixes a publish-time regression in `0.1.0-alpha.3` (and the unreleased
+`alpha.4`) where the package shipped raw TypeScript under `main` and
+`exports`. Node 24 refuses to strip types from anything under
+`node_modules`, so any consumer following the quickstart hit
+`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` on the first `import`
+and could not use the library at all.
+
+### Changed
+
+- `npm run build` compiles `src/` to `dist/` via `tsconfig.build.json`;
+  `prepublishOnly` runs it automatically so the npm tarball always
+  contains compiled JS plus declaration maps.
+- `main`, `types` and `exports."."` now point at `./dist/index.js` and
+  `./dist/index.d.ts`. The `files` array ships `dist/` instead of
+  `src/`, so consumers no longer see raw TS in `node_modules`.
+- Dev shell and `engines.node` move from Node 22 to Node 24 (the
+  current Active LTS) to match CI.
+
+End-to-end verified against `witness-demo.tulpa.network`: the
+quickstart `submit.mjs` now returns a signed inclusion receipt on
+Node 24 without modification.
+
+## 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 +73,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 +89,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 +104,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/dist/audit/inclusion-receipt.d.ts

@@ -0,0 +1,142 @@
+export interface InclusionReceipt {
+    eventId: string;
+    leafIndex: number;
+    treeSize: number;
+    rootHash: string;
+    inclusionProof: string[];
+    /** ISO 8601 timestamp at which the witness committed the leaf. */
+    timestamp: string;
+    /** Base64url Ed25519 signature over the canonical bytes. */
+    serviceSignature: string;
+}
+export interface VerifyStep {
+    name: string;
+    pass: boolean;
+    detail?: string;
+}
+export interface InclusionReceiptVerifyResult {
+    valid: boolean;
+    steps: VerifyStep[];
+}
+/**
+ * Verify an INK inclusion receipt.
+ *
+ * Always performs:
+ *  - Structural validation of the receipt object
+ *  - Service signature verification against `witnessPublicKey`
+ *
+ * Optionally performs (when the corresponding input is provided):
+ *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
+ */
+export declare function verifyInclusionReceipt(opts: {
+    receipt: InclusionReceipt;
+    /** Raw 32-byte Ed25519 public key of the witness service. */
+    witnessPublicKey: Uint8Array;
+    /** 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
+     *  has separately validated as authentic. */
+    laterCheckpoint?: {
+        treeSize: number;
+        rootHash: string;
+    };
+}): Promise<InclusionReceiptVerifyResult>;
+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 declare 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>;