@adastracomputing/ink 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,58 @@ 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.
 
+## 0.4.0, stricter verification, message-size bounds, checkpoint and receipt verification
+
+This release tightens signature verification and input validation and adds
+several verification helpers. It is published on the `next` dist-tag.
+
+### Potentially breaking validation tightenings
+
+These reject inputs that `0.3.0` accepted. Legitimate signer and receiver
+traffic is unaffected; the rejected inputs are malformed, malicious, or outside
+the documented profile.
+
+- Ed25519 signatures are now verified in strict RFC 8032 mode at every
+  verification site. Small-order public keys and non-canonical point encodings
+  are rejected.
+- Signed JSON numbers are constrained to the forms every canonicalizer
+  serializes identically: non-finite values, negative zero, and values whose
+  shortest form uses exponential notation are rejected at signing and
+  verification.
+- The agent card, audit, handshake, and discovery schemas now enforce maximum
+  field lengths and array sizes.
+- The `Authorization: INK-Ed25519` header is matched against single literal
+  spaces; a tab, carriage return, or line feed in the separator is rejected.
+
+### Additions
+
+- `verifyCheckpoint(signed, witnessPublicKey, expectedOrigin)` verifies a signed
+  C2SP checkpoint: the witness Ed25519 signature over the checkpoint body and the
+  log origin. A checkpoint used for the inclusion-receipt cross-check must be
+  verified this way first.
+- `verifyReceipt({ receipt, senderPublicKey, expected })` binds a delivery
+  receipt to the exact message it acknowledges: issuer key, `from`/`to`/
+  `messageId`, the recomputed message hash, and an optional `disposition`.
+- `verifyInclusionReceipt` accepts an `event` option that recomputes the leaf
+  hash and binds it to `receipt.eventId`. The legacy `eventHash` is retained but
+  does not provide that binding.
+- `verifyInkAuth` returns a prefix-independent `principal` alongside the raw
+  sender id; per-sender security state (blocks, rate limits) should key on
+  `principal`. `canonicalAgentPrincipal(agentId)` is exported for the same use.
+
+Per the pre-1.0 policy this release publishes under the `next` dist-tag; `latest`
+is unchanged.
+
+## 0.3.0, accept the ink: agentId alias for key extraction
+
+`extractPublicKeyFromAgentId` now accepts either the canonical `tulpa:` prefix or the `ink:` alias introduced in ink/0.4. Both carry the identical multibase Ed25519 key, so the bootstrap verification key is byte-identical and a signature made with that key verifies regardless of which accepted prefix carried it. The prefix is identity syntax, not signing authority.
+
+Emission is unchanged: `deriveAgentId` still returns `tulpa:` (accept both, emit one). The new `AGENT_ID_KEY_PREFIXES` export is frozen so a consumer cannot widen the accepted set at runtime. The change is additive and backward compatible. Existing `tulpa:` inputs behave exactly as before, and every previously rejected prefix other than `ink:` is still rejected. The wire protocol version is unchanged.
+
+A receiver that keys per-sender security state (blocks, rate limits, duplicate-payload checks, cached verification keys, connection identity) MUST collapse the two spellings to one prefix-independent principal so a sender cannot switch prefix to dodge a block or split a rate-limit window. See [Identity](https://ink.tulpa.network/spec/identity/).
+
+Per the pre-1.0 policy this release publishes under the `next` dist-tag.
+
 ## 0.2.0, version-keyed body-signature domain
 
 Version-keyed body-signature domain. The body message signature is now domain-separated by protocol version. ink/0.1 messages, and any object with no explicit ink/0.2 protocol, keep the legacy `tulpa/sign` domain so every signature produced to date still verifies. ink/0.2 messages are signed and verified under the neutral `ink/sign` domain. The verifier selects exactly one domain from the signed `protocol` field and never tries an alternate, so a signature made under one version's domain cannot be replayed under another.

package/README.md

@@ -98,6 +98,13 @@ For consumers of bilateral audit-exchange responses (`network.tulpa.audit_respon
 
 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.
 
+Verification helpers added in `0.4.0`:
+
+- `verifyCheckpoint(signed, witnessPublicKey, expectedOrigin)` verifies a signed C2SP checkpoint's witness Ed25519 signature and binds its log origin, returning the parsed `{origin, treeSize, rootHash}` or `null`. Any checkpoint passed to `verifyInclusionReceipt`'s `laterCheckpoint` cross-check must be verified this way first; an unverified checkpoint body is attacker-controllable and provides no anti-rollback value.
+- `verifyReceipt({receipt, senderPublicKey, expected})` verifies a delivery receipt against the message it acknowledges: the issuer's signature plus `from`/`to`/`messageId`, the recomputed message hash, and an optional `disposition`. It returns `{valid, reason?}`.
+- `verifyInclusionReceipt` accepts an `event` option that recomputes the leaf hash and binds `event.id` to `receipt.eventId`, so the proof attests the named event's inclusion. Prefer it over the legacy unbound `eventHash`.
+- `verifyInkAuth` returns a prefix-independent `principal` alongside the raw `senderAgentId`. Per-sender security state (block lists, rate limits) MUST key on `principal`, because the `tulpa:` and `ink:` spellings of one key are the same actor; `canonicalAgentPrincipal(agentId)` exposes the same mapping.
+
 ## Agent-assisted implementation
 
 If you are asking an AI coding agent to add INK support to an existing service, the canonical packet for that workflow is the [Agent-assisted implementation](https://ink.tulpa.network/guides/agent-assisted-implementation/) guide. It contains the curated implementer prompt, a mandatory traceability matrix, the conformance checklist, and a human-review checklist. The guide is updated as the protocol evolves; treat it as the live source rather than copying its contents into your repo.
@@ -152,9 +159,11 @@ Subject to change before v1.0:
 
 You will see `network.tulpa.*` on the wire (e.g. `network.tulpa.intent`) and `ink.tulpa.network` for the docs site. Both are historical artifacts of the protocol's origin and do not imply a runtime dependency on Tulpa. A vendor-neutral namespace may be introduced in a future revision.
 
+As a first, non-breaking step in that direction, agentIds may use either the canonical `tulpa:` method prefix or the `ink:` alias; both encode the same Ed25519 key and denote the same actor. `deriveAgentId` still emits `tulpa:`, and `extractPublicKeyFromAgentId` accepts both (accept-both, emit-one). A receiver MUST collapse the two spellings to one prefix-independent principal for all per-sender security state (blocks, rate limits, duplicate-payload checks, cached keys, connection identity).
+
 ## 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 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.
+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 codebase.
 
 ## Interoperability
 

package/bin/verify-inclusion-impl.mjs

@@ -38,6 +38,7 @@ function parseArgs(argv) {
     const a = argv[i];
     if (a === "--file" || a === "-f") out.file = argv[++i];
     else if (a === "--witness" || a === "-w") out.witness = argv[++i];
+    else if (a === "--origin") out.origin = argv[++i];
     else if (a === "--event-hash" || a === "-e") out.eventHash = argv[++i];
     else if (a === "--allow-http") out.allowHttp = true;
     else if (a === "--help" || a === "-h") out.help = true;
@@ -75,6 +76,10 @@ Usage:
 
 Options:
   -w, --witness <url>      Witness base URL (e.g. https://witness.tulpa.network)
+      --origin <name>      Optional. Expected checkpoint origin (log identity)
+                            to bind the signed checkpoint to. When omitted, the
+                            checkpoint signature is still verified against the
+                            witness key and the body/signature origins must agree.
   -f, --file <path>        Receipt JSON file. Omit to read from stdin.
   -e, --event-hash <hex>   Optional. RFC 6962 leaf hash for the audit event:
                             SHA-256(0x00 || JCS(event-without-agentSignature)),
@@ -226,7 +231,8 @@ async function verifyReceipt(receipt, witnessPublicKey, eventHash, laterCheckpoi
   let sigValid = false;
   try {
     const sig = base64urlDecode(receipt.serviceSignature);
-    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
+    // RFC 8032 strict verification, matching the library (reject small-order keys).
+    sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey, { zip215: false });
   } catch (e) {
     steps.push({ name: "signature", pass: false, detail: e instanceof Error ? e.message : "signature decode failed" });
     return { valid: false, steps };
@@ -343,28 +349,59 @@ async function fetchWitnessPublicKey(witnessUrl) {
 }
 
 /**
- * Parse a C2SP tlog-checkpoint response. The body has three header
- * lines (origin, treeSize, rootHash), each terminated by \n, then a
- * blank line, then a signature line. We don't verify the signature
- * here (it'd require pre-fetching the witness key, which the caller
- * already does for the receipt). Just extract the header fields with
- * strict regexes so a malformed checkpoint can't fake-pass.
+ * Verify a signed C2SP tlog-checkpoint and return { treeSize, rootHash,
+ * origin }, or null if the signature, origin, or format is invalid. The
+ * Ed25519 signature covers the body bytes `<origin>\n<treeSize>\n<rootHash>`
+ * (no trailing newline). The anti-rollback cross-check below only means
+ * anything against a checkpoint whose signature we have verified against the
+ * witness key, so this MUST verify, not just parse.
+ *
+ * Mirrors verifyCheckpoint() in src/ink/checkpoint.ts — keep them in sync.
  */
-function parseCheckpointBody(body) {
-  const sepIdx = body.indexOf("\n\n");
-  if (sepIdx < 0) return null;
-  const header = body.slice(0, sepIdx);
-  const lines = header.split("\n");
+async function verifyCheckpointBody(signed, witnessPublicKey, expectedOrigin) {
+  if (typeof signed !== "string" || signed.length === 0 || signed.length > 4096) return null;
+  const SEP = "\n\n-- ";
+  const idx = signed.indexOf(SEP);
+  if (idx < 0) return null;
+  const body = signed.slice(0, idx);
+  const lines = body.split("\n");
   if (lines.length !== 3) return null;
-  if (!lines[0]) return null;
-  if (!/^\d+$/.test(lines[1])) return null;
-  const treeSize = parseInt(lines[1], 10);
+  const [origin, sizeLine, rootHash] = lines;
+  if (!origin || origin.length > 256) return null;
+  if (!/^\d+$/.test(sizeLine)) return null;
+  const treeSize = parseInt(sizeLine, 10);
   if (!Number.isInteger(treeSize) || treeSize < 0 || treeSize > Number.MAX_SAFE_INTEGER) return null;
-  if (!/^[0-9a-f]{64}$/.test(lines[2])) return null;
-  return { treeSize, rootHash: lines[2] };
+  if (!/^[0-9a-f]{64}$/.test(rootHash)) return null;
+  // The expected origin must be supplied by the caller (a trusted value), not
+  // taken from the checkpoint body, so a witness key that signs several origins
+  // cannot substitute a checkpoint for a different log than the receipt's.
+  if (typeof expectedOrigin !== "string" || expectedOrigin.length === 0) return null;
+  if (origin !== expectedOrigin) return null;
+  const sigLines = signed.slice(idx + 2).split("\n").filter((l) => l.length > 0);
+  if (sigLines.length === 0 || sigLines.length > 8) return null;
+  const bodyBytes = new TextEncoder().encode(body);
+  for (const line of sigLines) {
+    if (!line.startsWith("-- ")) return null;
+    const rest = line.slice(3);
+    const sp = rest.indexOf(" ");
+    if (sp < 0) return null;
+    if (rest.slice(0, sp) !== expectedOrigin) continue;
+    try {
+      const sig = base64urlDecode(rest.slice(sp + 1));
+      if (sig.length !== 64) return null;
+      const ok = await ed.verifyAsync(sig, bodyBytes, witnessPublicKey, { zip215: false });
+      return ok ? { treeSize, rootHash, origin } : null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
 }
 
-async function fetchCurrentCheckpoint(witnessUrl) {
+async function fetchCurrentCheckpoint(witnessUrl, witnessPublicKey, expectedOrigin) {
+  // No trusted origin, no cross-check: refuse to trust the checkpoint body's
+  // self-asserted origin. Pass --origin <witness-origin> to enable it.
+  if (typeof expectedOrigin !== "string" || expectedOrigin.length === 0) return null;
   const url = `${witnessUrl.replace(/\/$/, "")}/ink/v1/checkpoint`;
   let body;
   try {
@@ -374,7 +411,7 @@ async function fetchCurrentCheckpoint(witnessUrl) {
     // 'not available' rather than crashing the verifier.
     return null;
   }
-  return parseCheckpointBody(body);
+  return verifyCheckpointBody(body, witnessPublicKey, expectedOrigin);
 }
 
 async function readStdin() {
@@ -451,16 +488,22 @@ async function main() {
     process.exit(2);
   }
 
-  const laterCheckpoint = await fetchCurrentCheckpoint(witnessBase);
+  // The checkpoint cross-check only carries weight against a checkpoint whose
+  // Ed25519 signature we have verified against the witness key. An unverified
+  // checkpoint (bad/absent signature, or origin mismatch) is dropped so the
+  // cross-check is skipped rather than trusting attacker-controlled values.
+  const laterCheckpoint = await fetchCurrentCheckpoint(witnessBase, witnessPublicKey, args.origin);
 
   const result = await verifyReceipt(receipt, witnessPublicKey, args.eventHash, laterCheckpoint ?? undefined);
 
   console.log(`Receipt: eventId=${receipt?.eventId} leafIndex=${receipt?.leafIndex} treeSize=${receipt?.treeSize}`);
   console.log(`Witness: ${witnessBase}`);
   if (laterCheckpoint) {
-    console.log(`Current checkpoint: treeSize=${laterCheckpoint.treeSize} rootHash=${laterCheckpoint.rootHash}`);
+    console.log(`Current checkpoint (signature verified): treeSize=${laterCheckpoint.treeSize} rootHash=${laterCheckpoint.rootHash}`);
+  } else if (!args.origin) {
+    console.log("Current checkpoint: cross-check skipped (pass --origin <witness-origin> to enable the anti-rollback check)");
   } else {
-    console.log("Current checkpoint: not available (skipping checkpoint cross-check)");
+    console.log("Current checkpoint: not available or signature unverified (skipping checkpoint cross-check)");
   }
   console.log("");
   for (const step of result.steps) {

package/dist/audit/inclusion-receipt.d.ts

@@ -26,21 +26,31 @@ export interface InclusionReceiptVerifyResult {
  *  - Service signature verification against `witnessPublicKey`
  *
  * Optionally performs (when the corresponding input is provided):
- *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Leaf-to-root proof walk: pass `event` (recommended — recomputes the leaf
+ *    hash and binds it to `receipt.eventId`) or `eventHash` (legacy, unbound)
  *  - 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. */
+    /** Optional audit event the receipt claims inclusion for. This is the
+     *  RECOMMENDED way to verify the proof: the leaf hash is recomputed from the
+     *  event with `computeAuditMerkleLeafHash`, and `event.id` is bound to
+     *  `receipt.eventId`, so the proof attests that the event named by the
+     *  receipt is in the tree — not merely that some caller-chosen hash is. */
+    event?: Record<string, unknown>;
+    /** Optional pre-computed RFC 6962 leaf hash (hex). LEGACY / lower-assurance:
+     *  unlike `event`, a bare hash is NOT bound to `receipt.eventId`, so the proof
+     *  only attests "this hash is in the tree", not "the event the receipt names
+     *  is in the tree". Prefer `event`. Ignored when `event` is provided. */
     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. */
+    /** Optional later checkpoint to cross-check the receipt against. This MUST be
+     *  the parsed body of a checkpoint whose Ed25519 signature and origin the
+     *  caller has already verified with `verifyCheckpoint` against the witness
+     *  key. Passing an unverified (merely parsed) checkpoint gives the
+     *  anti-rollback / fork cross-check no security, because the treeSize and
+     *  rootHash would then be attacker-controllable. */
     laterCheckpoint?: {
         treeSize: number;
         rootHash: string;

package/dist/audit/inclusion-receipt.js

@@ -30,12 +30,13 @@ import { base64urlDecode, jcsCanonicalize, hexToBytes, bytesToHex, computeAuditM
  *  - Service signature verification against `witnessPublicKey`
  *
  * Optionally performs (when the corresponding input is provided):
- *  - Leaf-to-root proof walk (`eventHash`)
+ *  - Leaf-to-root proof walk: pass `event` (recommended — recomputes the leaf
+ *    hash and binds it to `receipt.eventId`) or `eventHash` (legacy, unbound)
  *  - Cross-check against a later signed checkpoint (`laterCheckpoint`)
  */
 export async function verifyInclusionReceipt(opts) {
     const steps = [];
-    const { receipt, witnessPublicKey, eventHash, laterCheckpoint } = opts;
+    const { receipt, witnessPublicKey, event, eventHash, laterCheckpoint } = opts;
     // ── Step 1: structural validation ──
     const structuralProblem = checkReceiptShape(receipt);
     if (structuralProblem) {
@@ -55,7 +56,7 @@ export async function verifyInclusionReceipt(opts) {
     let sigValid = false;
     try {
         const sig = base64urlDecode(receipt.serviceSignature);
-        sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey);
+        sigValid = await ed.verifyAsync(sig, new TextEncoder().encode(sigBase), witnessPublicKey, { zip215: false });
     }
     catch (e) {
         steps.push({
@@ -71,12 +72,35 @@ export async function verifyInclusionReceipt(opts) {
     }
     steps.push({ name: "signature", pass: true });
     // ── Step 3: inclusion-proof walk (optional) ──
-    if (eventHash !== undefined) {
+    // Prefer the `event` path: recompute the leaf hash from the event and bind it
+    // to receipt.eventId, so the proof attests the named event's inclusion.
+    let leafHash;
+    if (event !== undefined) {
+        if (typeof event.id !== "string") {
+            steps.push({ name: "proof", pass: false, detail: "event.id is missing or not a string" });
+            return { valid: false, steps };
+        }
+        if (event.id !== receipt.eventId) {
+            steps.push({ name: "proof", pass: false, detail: "event.id does not match receipt.eventId" });
+            return { valid: false, steps };
+        }
+        try {
+            leafHash = await computeAuditMerkleLeafHash(event);
+        }
+        catch {
+            steps.push({ name: "proof", pass: false, detail: "could not compute leaf hash from event" });
+            return { valid: false, steps };
+        }
+    }
+    else if (eventHash !== undefined) {
         if (!/^[0-9a-f]{64}$/.test(eventHash)) {
             steps.push({ name: "proof", pass: false, detail: "eventHash must be 64 lowercase hex chars" });
             return { valid: false, steps };
         }
-        const verified = await verifyInclusionProof(eventHash, receipt.inclusionProof, receipt.leafIndex, receipt.treeSize, receipt.rootHash);
+        leafHash = eventHash;
+    }
+    if (leafHash !== undefined) {
+        const verified = await verifyInclusionProof(leafHash, receipt.inclusionProof, receipt.leafIndex, receipt.treeSize, receipt.rootHash);
         if (!verified) {
             steps.push({ name: "proof", pass: false, detail: "leaf-to-root walk did not reach claimed rootHash" });
             return { valid: false, steps };

package/dist/crypto/ink.js

@@ -1,6 +1,7 @@
 import * as ed from "@noble/ed25519";
 import { x25519 } from "@noble/curves/ed25519.js";
 import canonicalize from "canonicalize";
+import { isJcsSafeNumber } from "./sign.js";
 // ── Encoding helpers ──
 const MAX_ENCODE_INPUT_BYTES = 2_000_000;
 function base64urlEncode(bytes) {
@@ -137,6 +138,11 @@ function isWithinCanonicalizeBounds(value) {
                 if (chars > MAX_PRECHECK_CHARS)
                     return false;
             }
+            else if (typeof v === "number" && !isJcsSafeNumber(v)) {
+                // Reject numbers that don't canonicalize identically across JSON
+                // serializers (non-finite, -0, exponential notation). See sign.ts.
+                return false;
+            }
             return true;
         }
         if (Array.isArray(v)) {
@@ -236,7 +242,9 @@ export async function verifyInkSignature(input, signatureBase64url, publicKey) {
     const bytes = new TextEncoder().encode(sigBase);
     try {
         const sig = base64urlDecode(signatureBase64url);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        // RFC 8032 strict verification (not the default ZIP-215): reject
+        // small-order keys and non-canonical encodings. See verifyMessage.
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -629,7 +637,7 @@ export async function verifyAuditEventSignature(event, publicKey) {
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -739,7 +747,7 @@ export async function verifyAuditResponseSignature(events, signature, publicKey)
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;
@@ -905,7 +913,7 @@ export async function verifyAuditQueryResponseSignature(responseWithoutSignature
         if (bytes.length > MAX_SIGBASE_BODY_BYTES)
             return false;
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, bytes, publicKey);
+        return await ed.verifyAsync(sig, bytes, publicKey, { zip215: false });
     }
     catch {
         return false;

package/dist/crypto/keys.d.ts

@@ -53,3 +53,22 @@ export declare function deriveAgentId(publicKey: Uint8Array): string;
  * same way for both, so a malformed tail is rejected identically.
  */
 export declare function extractPublicKeyFromAgentId(agentId: string): Uint8Array;
+/**
+ * Collapse an agent ID to a single, prefix-independent principal string that
+ * per-sender security state (block lists, rate limits, duplicate-payload
+ * checks, cached verification keys, connection identity) MUST key on.
+ *
+ * The accepted spellings `tulpa:zKEY` and `ink:zKEY` encode the same Ed25519
+ * key and are therefore the same actor; this maps both — and any non-canonical
+ * multibase encoding of that key — to `key:<canonical-multibase>`, so a sender
+ * cannot switch prefix or re-encode to dodge a block or split a rate-limit
+ * window. DIDs (and any other identifier) are returned unchanged. A raw `key:`
+ * input — never a legitimate agent ID — is escaped to `raw:key:…` so a sender
+ * cannot forge a collision with a canonicalized key principal.
+ *
+ * Not idempotent: call exactly once, at the storage boundary, on the raw
+ * agent ID. Total over well-formed string input (it never throws on a
+ * malformed key body — that is escaped to `raw:…` so a principal is always
+ * derivable); throws only on a non-string, empty, or over-length argument.
+ */
+export declare function canonicalAgentPrincipal(agentId: string): string;

package/dist/crypto/keys.js

@@ -190,3 +190,42 @@ export function extractPublicKeyFromAgentId(agentId) {
     }
     return decodePublicKeyMultibase(agentId.slice(prefix.length));
 }
+/**
+ * Collapse an agent ID to a single, prefix-independent principal string that
+ * per-sender security state (block lists, rate limits, duplicate-payload
+ * checks, cached verification keys, connection identity) MUST key on.
+ *
+ * The accepted spellings `tulpa:zKEY` and `ink:zKEY` encode the same Ed25519
+ * key and are therefore the same actor; this maps both — and any non-canonical
+ * multibase encoding of that key — to `key:<canonical-multibase>`, so a sender
+ * cannot switch prefix or re-encode to dodge a block or split a rate-limit
+ * window. DIDs (and any other identifier) are returned unchanged. A raw `key:`
+ * input — never a legitimate agent ID — is escaped to `raw:key:…` so a sender
+ * cannot forge a collision with a canonicalized key principal.
+ *
+ * Not idempotent: call exactly once, at the storage boundary, on the raw
+ * agent ID. Total over well-formed string input (it never throws on a
+ * malformed key body — that is escaped to `raw:…` so a principal is always
+ * derivable); throws only on a non-string, empty, or over-length argument.
+ */
+export function canonicalAgentPrincipal(agentId) {
+    if (typeof agentId !== "string" || agentId.length === 0 || agentId.length > 512) {
+        throw new Error("Invalid agent ID");
+    }
+    const prefix = AGENT_ID_KEY_PREFIXES.find((p) => agentId.startsWith(p));
+    if (prefix) {
+        try {
+            return "key:" + encodePublicKeyMultibase(decodePublicKeyMultibase(agentId.slice(prefix.length)));
+        }
+        catch {
+            // Malformed multibase body: keep the function total by treating it as an
+            // opaque identifier. Such an ID cannot authenticate via the bootstrap
+            // path anyway, so it never collides with a real key principal.
+            return "raw:" + agentId;
+        }
+    }
+    if (agentId.startsWith("key:")) {
+        return "raw:" + agentId;
+    }
+    return agentId;
+}

package/dist/crypto/sign.d.ts

@@ -1,3 +1,24 @@
+/**
+ * A number is safe for canonical JSON only if every conforming canonicalizer
+ * serializes it identically. We reject non-finite values (not valid JSON),
+ * negative zero (serializes as `0`, losing the sign), and any value whose
+ * shortest decimal uses exponential notation (`1e21`, `1e-7`) — exponential
+ * forms are exactly where JSON serializers and strict RFC 8785 disagree.
+ * Rejecting them keeps the signed-byte representation unambiguous across
+ * implementations (the reference and a future second implementation), without
+ * affecting the small integers and plain decimals INK payloads actually carry.
+ */
+export declare function isJcsSafeNumber(n: number): boolean;
+/**
+ * Cheap depth/node/byte walk over a value before it is handed to
+ * `canonicalize`. Bails before the recursive sort+serialize runs, so an
+ * attacker who supplies a syntactically valid-shape signature with a
+ * pathological message body cannot burn CPU/memory inside the verify
+ * path. Mirrors src/crypto/ink.ts:isWithinCanonicalizeBounds, including
+ * the byte counter that stops a single huge string from sneaking past
+ * the node check.
+ */
+export declare function isWithinBounds(value: unknown): boolean;
 /**
  * Sign a message object using Ed25519.
  *

package/dist/crypto/sign.js

@@ -10,6 +10,23 @@ const MAX_MESSAGE_CHARS = 1_200_000;
  * walk: a message can be small in node count but still expand to huge
  * canonical bytes via long string values. */
 const MAX_MESSAGE_CANONICAL_BYTES = 1_048_576;
+/**
+ * A number is safe for canonical JSON only if every conforming canonicalizer
+ * serializes it identically. We reject non-finite values (not valid JSON),
+ * negative zero (serializes as `0`, losing the sign), and any value whose
+ * shortest decimal uses exponential notation (`1e21`, `1e-7`) — exponential
+ * forms are exactly where JSON serializers and strict RFC 8785 disagree.
+ * Rejecting them keeps the signed-byte representation unambiguous across
+ * implementations (the reference and a future second implementation), without
+ * affecting the small integers and plain decimals INK payloads actually carry.
+ */
+export function isJcsSafeNumber(n) {
+    if (!Number.isFinite(n))
+        return false;
+    if (Object.is(n, -0))
+        return false;
+    return !/[eE]/.test(String(n));
+}
 /**
  * Cheap depth/node/byte walk over a value before it is handed to
  * `canonicalize`. Bails before the recursive sort+serialize runs, so an
@@ -19,7 +36,7 @@ const MAX_MESSAGE_CANONICAL_BYTES = 1_048_576;
  * the byte counter that stops a single huge string from sneaking past
  * the node check.
  */
-function isWithinBounds(value) {
+export function isWithinBounds(value) {
     let nodes = 0;
     let chars = 0;
     function walk(v, depth) {
@@ -33,6 +50,9 @@ function isWithinBounds(value) {
                 if (chars > MAX_MESSAGE_CHARS)
                     return false;
             }
+            else if (typeof v === "number" && !isJcsSafeNumber(v)) {
+                return false;
+            }
             return true;
         }
         if (Array.isArray(v)) {
@@ -162,7 +182,11 @@ export async function verifyMessage(message, publicKey) {
     const prefixedBytes = new TextEncoder().encode(prefixed);
     try {
         const sig = base64urlDecode(signature);
-        return await ed.verifyAsync(sig, prefixedBytes, publicKey);
+        // RFC 8032 strict verification, not the library default ZIP-215 mode:
+        // reject small-order public keys and non-canonical point encodings so a
+        // signature binds to exactly one (key, message). Identity is the embedded
+        // public key and signatures feed the audit log, so strictness is required.
+        return await ed.verifyAsync(sig, prefixedBytes, publicKey, { zip215: false });
     }
     catch {
         // Malformed signature (invalid base64url, wrong byte length, bad key) — treat as invalid

package/dist/discovery/agent-card.d.ts

@@ -24,13 +24,15 @@ export interface FetchAgentCardOptions {
      * connect targets (e.g. undici with a custom dispatcher on Node, or
      * `cf: { resolveOverride: validatedIp }` on Cloudflare Workers). */
     fetch?: typeof fetch;
-    /** Strict mode: require that the caller supply `options.fetch`. When
-     * true, the default global `fetch` is refused for non-literal hostnames
-     * because the default cannot perform connect-time IP filtering and is
-     * therefore vulnerable to DNS rebinding. Off by default for backwards
-     * compatibility; on by default for any production integration where
-     * `baseUrl` is taken from untrusted input. Returns null without
-     * fetching when the condition fails. */
+    /** Strict mode: require that the caller supply `options.fetch`, returning
+     * null (without fetching) if it is absent. This only guarantees that *some*
+     * fetch override was provided; it does NOT and cannot verify that the
+     * override pins connect-time IPs, so passing `requireSafeFetch: true` with
+     * the plain global `fetch` does not close the DNS-rebinding window. The
+     * literal-private-IP allowlist this module applies to `baseUrl` does not stop
+     * a public hostname that resolves to a private address at fetch time; only a
+     * connect-time-IP-pinning `options.fetch` (for example a custom undici
+     * dispatcher) does. Off by default for backwards compatibility. */
     requireSafeFetch?: boolean;
 }
 /**

package/dist/index.d.ts

@@ -1,15 +1,15 @@
 export { signInkMessage, verifyInkSignature, buildSignatureBase, buildAuthHeader, computeMessageHash, computeEventHash, computeAuditMerkleLeafHash, signAuditEvent, verifyAuditEventSignature, signAuditResponse, verifyAuditResponseSignature, verifyAuditEventChain, signAuditQueryResponse, verifyAuditQueryResponseSignature, encryptInkPayload, decryptInkPayload, checkReplay, base64urlEncode, base64urlDecode, hexToBytes, bytesToHex, jcsCanonicalize, MAX_TIMESTAMP_AGE_MS, MAX_FUTURE_TIMESTAMP_MS, } from "./crypto/ink.js";
 export { signMessage, verifyMessage } from "./crypto/sign.js";
 export { verifyInkSignatureWithKeys } from "./crypto/multi-key-verify.js";
-export { generateKeypair, generateEncryptionKeypair, deriveAgentId, encodePublicKeyMultibase, encodeEncryptionKeyMultibase, decodePublicKeyMultibase, decodeEncryptionKeyMultibase, extractPublicKeyFromAgentId, AGENT_ID_KEY_PREFIXES, } from "./crypto/keys.js";
+export { generateKeypair, generateEncryptionKeypair, deriveAgentId, encodePublicKeyMultibase, encodeEncryptionKeyMultibase, decodePublicKeyMultibase, decodeEncryptionKeyMultibase, extractPublicKeyFromAgentId, canonicalAgentPrincipal, AGENT_ID_KEY_PREFIXES, } from "./crypto/keys.js";
 export { fetchAgentCard, extractCandidateKeys, resolveBaseUrl, } from "./discovery/agent-card.js";
 export { verifyInkAuth, type NonceStore } from "./middleware/ink-auth.js";
 export { verifyInclusionReceipt, verifyAuditQueryResponse, type InclusionReceipt, type InclusionReceiptVerifyResult, type AuditQueryResponse, type AuditQueryResponseVerifyResult, type VerifyStep, } from "./audit/inclusion-receipt.js";
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
-export { buildReceipt, shouldSendReceipt, sendReceiptFireAndForget, } from "./ink/receipts.js";
+export { buildReceipt, verifyReceipt, shouldSendReceipt, sendReceiptFireAndForget, } from "./ink/receipts.js";
 export { resolveEffectiveTransports, checkTransportAllowed, } from "./ink/transport-auth.js";
 export { buildRedactedCard, shouldRedactOnGet, AgentCardQuerySchema, } from "./ink/discovery-gating.js";
-export { parseCheckpoint, formatCheckpoint, } from "./ink/checkpoint.js";
+export { parseCheckpoint, formatCheckpoint, verifyCheckpoint, } from "./ink/checkpoint.js";
 export type { CheckpointData } from "./ink/checkpoint.js";
 export { InkAuditEventTypeSchema, InkAuditEventSchema, InkAuditInclusionSchema, InkReceiptSchema, InkAuditQuerySchema, InkIntroductionReceiptSchema, } from "./models/ink-audit.js";
 export type { InkAuditEventType, InkAuditEvent, InkAuditInclusion, InkReceipt, InkAuditQuery, InkAuditResponse, InkIntroductionReceiptStatus, } from "./models/ink-audit.js";

package/dist/index.js

@@ -4,7 +4,7 @@
 export { signInkMessage, verifyInkSignature, buildSignatureBase, buildAuthHeader, computeMessageHash, computeEventHash, computeAuditMerkleLeafHash, signAuditEvent, verifyAuditEventSignature, signAuditResponse, verifyAuditResponseSignature, verifyAuditEventChain, signAuditQueryResponse, verifyAuditQueryResponseSignature, encryptInkPayload, decryptInkPayload, checkReplay, base64urlEncode, base64urlDecode, hexToBytes, bytesToHex, jcsCanonicalize, MAX_TIMESTAMP_AGE_MS, MAX_FUTURE_TIMESTAMP_MS, } from "./crypto/ink.js";
 export { signMessage, verifyMessage } from "./crypto/sign.js";
 export { verifyInkSignatureWithKeys } from "./crypto/multi-key-verify.js";
-export { generateKeypair, generateEncryptionKeypair, deriveAgentId, encodePublicKeyMultibase, encodeEncryptionKeyMultibase, decodePublicKeyMultibase, decodeEncryptionKeyMultibase, extractPublicKeyFromAgentId, AGENT_ID_KEY_PREFIXES, } from "./crypto/keys.js";
+export { generateKeypair, generateEncryptionKeypair, deriveAgentId, encodePublicKeyMultibase, encodeEncryptionKeyMultibase, decodePublicKeyMultibase, decodeEncryptionKeyMultibase, extractPublicKeyFromAgentId, canonicalAgentPrincipal, AGENT_ID_KEY_PREFIXES, } from "./crypto/keys.js";
 // Discovery: Agent Card fetch + candidate-key extraction
 export { fetchAgentCard, extractCandidateKeys, resolveBaseUrl, } from "./discovery/agent-card.js";
 // Middleware: transport-level INK auth
@@ -13,14 +13,14 @@ export { verifyInkAuth } from "./middleware/ink-auth.js";
 export { verifyInclusionReceipt, verifyAuditQueryResponse, } from "./audit/inclusion-receipt.js";
 // Optional containment / governance primitives
 export { HandshakeBudgetTracker } from "./ink/handshake-budget.js";
-// Receipts: build and send INK delivery receipts
-export { buildReceipt, shouldSendReceipt, sendReceiptFireAndForget, } from "./ink/receipts.js";
+// Receipts: build, verify, and send INK delivery receipts
+export { buildReceipt, verifyReceipt, shouldSendReceipt, sendReceiptFireAndForget, } from "./ink/receipts.js";
 // Transport-auth: token-level transport allowlist for extension tokens
 export { resolveEffectiveTransports, checkTransportAllowed, } from "./ink/transport-auth.js";
 // Discovery-gating: visibility-aware Agent Card redaction
 export { buildRedactedCard, shouldRedactOnGet, AgentCardQuerySchema, } from "./ink/discovery-gating.js";
-// Checkpoint parsing for transparency-log signed checkpoints
-export { parseCheckpoint, formatCheckpoint, } from "./ink/checkpoint.js";
+// Checkpoint parsing and signature verification for transparency-log checkpoints
+export { parseCheckpoint, formatCheckpoint, verifyCheckpoint, } from "./ink/checkpoint.js";
 // Audit event schemas + types for receipts, query, inclusion proofs
 export { InkAuditEventTypeSchema, InkAuditEventSchema, InkAuditInclusionSchema, InkReceiptSchema, InkAuditQuerySchema, InkIntroductionReceiptSchema, } from "./models/ink-audit.js";
 // Handshake message schemas