@adastracomputing/ink 0.3.0 → 0.5.0

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 { verifyInclusionReceipt, verifyConsistencyProof, 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,23 +4,23 @@
 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
 export { verifyInkAuth } from "./middleware/ink-auth.js";
 // Audit: inclusion-receipt + audit-query-response verification
-export { verifyInclusionReceipt, verifyAuditQueryResponse, } from "./audit/inclusion-receipt.js";
+export { verifyInclusionReceipt, verifyConsistencyProof, 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

package/dist/ink/checkpoint.d.ts

@@ -17,3 +17,24 @@ export interface CheckpointData {
 export declare function formatCheckpoint(data: CheckpointData): string;
 /** Parse a checkpoint body. Returns null if invalid. */
 export declare function parseCheckpoint(body: string): CheckpointData | null;
+/**
+ * Verify a signed checkpoint and return its parsed body, or `null` if the
+ * signature, origin, or format is invalid.
+ *
+ * The signed form is the C2SP-style note used by the INK witness:
+ *
+ *   <origin>\n<treeSize>\n<rootHash>\n\n-- <origin> <base64url(sig)>\n
+ *
+ * The Ed25519 signature covers the body bytes `<origin>\n<treeSize>\n<rootHash>`
+ * exactly (no trailing newline), so the `origin` first line is the domain
+ * separator binding the signed bytes to this log. Verification REQUIRES the
+ * caller's `expectedOrigin`: a checkpoint whose body origin, or whose matching
+ * signature-line origin, is not `expectedOrigin` is rejected, so a witness that
+ * operates several logs (or an attacker replaying another log's signed
+ * checkpoint) cannot substitute a different tree. This is the authenticated
+ * input that anti-rollback / freshness checks MUST consume; an unverified
+ * checkpoint body provides no security.
+ *
+ * Verification uses RFC 8032 strict mode (small-order keys rejected).
+ */
+export declare function verifyCheckpoint(signed: string, witnessPublicKey: Uint8Array, expectedOrigin: string): Promise<CheckpointData | null>;

package/dist/ink/checkpoint.js

@@ -2,6 +2,8 @@
  * INK Checkpoint formatting (C2SP tlog-checkpoint compatible).
  * Used for the public checkpoint endpoint (INK Auditability §7.7).
  */
+import * as ed from "@noble/ed25519";
+import { base64urlDecode } from "../crypto/ink.js";
 /**
  * Format a checkpoint body per C2SP tlog-checkpoint spec:
  *   line 1: origin (log identity)
@@ -67,3 +69,80 @@ export function parseCheckpoint(body) {
         return null;
     return { origin, treeSize, rootHash };
 }
+/** A signed checkpoint is the 3-line body, a blank line, then one or more
+ *  signature lines, plus a trailing newline. Bound the whole thing so an
+ *  attacker-supplied blob cannot drive large scans before rejection. */
+const MAX_SIGNED_CHECKPOINT_BODY = 4096;
+/** Cap the number of cosignature lines a verifier will scan. */
+const MAX_CHECKPOINT_SIGNATURES = 8;
+/**
+ * Verify a signed checkpoint and return its parsed body, or `null` if the
+ * signature, origin, or format is invalid.
+ *
+ * The signed form is the C2SP-style note used by the INK witness:
+ *
+ *   <origin>\n<treeSize>\n<rootHash>\n\n-- <origin> <base64url(sig)>\n
+ *
+ * The Ed25519 signature covers the body bytes `<origin>\n<treeSize>\n<rootHash>`
+ * exactly (no trailing newline), so the `origin` first line is the domain
+ * separator binding the signed bytes to this log. Verification REQUIRES the
+ * caller's `expectedOrigin`: a checkpoint whose body origin, or whose matching
+ * signature-line origin, is not `expectedOrigin` is rejected, so a witness that
+ * operates several logs (or an attacker replaying another log's signed
+ * checkpoint) cannot substitute a different tree. This is the authenticated
+ * input that anti-rollback / freshness checks MUST consume; an unverified
+ * checkpoint body provides no security.
+ *
+ * Verification uses RFC 8032 strict mode (small-order keys rejected).
+ */
+export async function verifyCheckpoint(signed, witnessPublicKey, expectedOrigin) {
+    if (typeof signed !== "string" || signed.length === 0 || signed.length > MAX_SIGNED_CHECKPOINT_BODY) {
+        return null;
+    }
+    if (!(witnessPublicKey instanceof Uint8Array) || witnessPublicKey.length !== 32) {
+        return null;
+    }
+    if (typeof expectedOrigin !== "string" || expectedOrigin.length === 0 || expectedOrigin.length > MAX_CHECKPOINT_LINE) {
+        return null;
+    }
+    const SEP = "\n\n-- ";
+    const idx = signed.indexOf(SEP);
+    if (idx === -1)
+        return null;
+    const body = signed.slice(0, idx); // <origin>\n<treeSize>\n<rootHash>
+    const data = parseCheckpoint(body + "\n");
+    if (!data)
+        return null;
+    // Bind the body's own origin to the caller's expectation before any crypto.
+    if (data.origin !== expectedOrigin)
+        return null;
+    // Signature block starts at the "-- " that began the separator.
+    const sigBlock = signed.slice(idx + 2);
+    const sigLines = sigBlock.split("\n").filter((l) => l.length > 0);
+    if (sigLines.length === 0 || sigLines.length > MAX_CHECKPOINT_SIGNATURES)
+        return null;
+    const bodyBytes = new TextEncoder().encode(body);
+    for (const line of sigLines) {
+        if (!line.startsWith("-- "))
+            return null; // any malformed signature line is fatal
+        const rest = line.slice(3);
+        const sp = rest.indexOf(" ");
+        if (sp === -1)
+            return null;
+        const lineOrigin = rest.slice(0, sp);
+        const sigB64 = rest.slice(sp + 1);
+        if (lineOrigin !== expectedOrigin)
+            continue; // a cosigner whose key we were not given
+        try {
+            const sig = base64urlDecode(sigB64);
+            if (sig.length !== 64)
+                return null;
+            const ok = await ed.verifyAsync(sig, bodyBytes, witnessPublicKey, { zip215: false });
+            return ok ? data : null; // a matching-origin signature that fails verification is fatal
+        }
+        catch {
+            return null;
+        }
+    }
+    return null; // no signature line for the expected origin
+}

package/dist/ink/discovery-gating.js

@@ -66,16 +66,16 @@ export function buildRedactedCard(card) {
 export const AgentCardQuerySchema = z.object({
     protocol: z.literal("ink/0.1"),
     type: z.literal("network.tulpa.agent_card_query"),
-    from: z.string(),
-    nonce: z.string(),
+    from: z.string().max(512),
+    nonce: z.string().max(256),
     timestamp: z.string().datetime(),
-    requestedFields: z.array(z.string()).optional(),
+    requestedFields: z.array(z.string().max(64)).max(32).optional(),
 });
 export const AgentCardResponseSchema = z.object({
     protocol: z.literal("ink/0.1"),
     type: z.literal("network.tulpa.agent_card_response"),
     card: AgentCardSchema,
-    grantedFields: z.array(z.string()),
+    grantedFields: z.array(z.string().max(64)).max(32),
     timestamp: z.string().datetime(),
 });
 export const AgentCardDeniedSchema = z.object({

package/dist/ink/receipts.d.ts

@@ -1,4 +1,4 @@
-import type { InkReceipt } from "../models/ink-audit.js";
+import { type InkReceipt } from "../models/ink-audit.js";
 export interface BuildReceiptInput {
     from: string;
     to: string;
@@ -10,6 +10,38 @@ export interface BuildReceiptInput {
 }
 /** Build a signed INK receipt envelope. */
 export declare function buildReceipt(input: BuildReceiptInput): Promise<InkReceipt>;
+export interface VerifyReceiptResult {
+    valid: boolean;
+    /** Machine-readable reason when `valid` is false. */
+    reason?: string;
+}
+/**
+ * Verify an INK receipt against the message it claims to acknowledge.
+ *
+ * Checks all the bindings a hand-rolled verifier commonly forgets: the
+ * receipt's Ed25519 signature against the issuer's (`from`) key, that `from`,
+ * `to` and `messageId` equal the expected values, and that `messageHash`
+ * equals the hash of the exact message body that was sent (recomputed here,
+ * not trusted from the receipt). A receipt that passes proves the named
+ * counterparty acknowledged that specific message; nothing weaker should be
+ * treated as proof of delivery.
+ */
+export declare function verifyReceipt(opts: {
+    receipt: unknown;
+    /** Raw 32-byte Ed25519 public key of the issuer (the receipt's `from`). */
+    senderPublicKey: Uint8Array;
+    expected: {
+        from: string;
+        to: string;
+        messageId: string;
+        messageBody: Record<string, unknown>;
+        /** When set, require the receipt to acknowledge this specific disposition
+         *  (e.g. "delivered"). The disposition is covered by the signature, but
+         *  without this a signed receipt for a different state would still pass, so
+         *  callers proving a specific delivery state MUST pin it. */
+        disposition?: InkReceipt["disposition"];
+    };
+}): Promise<VerifyReceiptResult>;
 export declare function shouldSendReceipt(intentOrType: string): boolean;
 export interface SendReceiptOptions {
     /** Allow endpoints whose hostname is loopback / private / link-local /

package/dist/ink/receipts.js

@@ -1,6 +1,7 @@
 import { computeMessageHash, signInkMessage, buildAuthHeader } from "../crypto/ink.js";
-import { signMessage } from "../crypto/sign.js";
+import { signMessage, verifyMessage } from "../crypto/sign.js";
 import { isPrivateHostname } from "../discovery/agent-card.js";
+import { InkReceiptSchema } from "../models/ink-audit.js";
 /** Build a signed INK receipt envelope. */
 export async function buildReceipt(input) {
     if (input === null || typeof input !== "object" || Array.isArray(input)) {
@@ -28,6 +29,49 @@ export async function buildReceipt(input) {
     const signature = await signMessage(unsigned, input.privateKey);
     return { ...unsigned, signature };
 }
+/**
+ * Verify an INK receipt against the message it claims to acknowledge.
+ *
+ * Checks all the bindings a hand-rolled verifier commonly forgets: the
+ * receipt's Ed25519 signature against the issuer's (`from`) key, that `from`,
+ * `to` and `messageId` equal the expected values, and that `messageHash`
+ * equals the hash of the exact message body that was sent (recomputed here,
+ * not trusted from the receipt). A receipt that passes proves the named
+ * counterparty acknowledged that specific message; nothing weaker should be
+ * treated as proof of delivery.
+ */
+export async function verifyReceipt(opts) {
+    const parsed = InkReceiptSchema.safeParse(opts.receipt);
+    if (!parsed.success)
+        return { valid: false, reason: "malformed_receipt" };
+    const receipt = parsed.data;
+    const { senderPublicKey, expected } = opts;
+    if (!(senderPublicKey instanceof Uint8Array) || senderPublicKey.length !== 32) {
+        return { valid: false, reason: "invalid_public_key" };
+    }
+    if (receipt.from !== expected.from)
+        return { valid: false, reason: "from_mismatch" };
+    if (receipt.to !== expected.to)
+        return { valid: false, reason: "to_mismatch" };
+    if (receipt.messageId !== expected.messageId)
+        return { valid: false, reason: "message_id_mismatch" };
+    if (expected.disposition !== undefined && receipt.disposition !== expected.disposition) {
+        return { valid: false, reason: "disposition_mismatch" };
+    }
+    let expectedHash;
+    try {
+        expectedHash = await computeMessageHash(expected.messageBody);
+    }
+    catch {
+        return { valid: false, reason: "message_hash_error" };
+    }
+    if (receipt.messageHash !== expectedHash)
+        return { valid: false, reason: "message_hash_mismatch" };
+    const sigOk = await verifyMessage(receipt, senderPublicKey);
+    if (!sigOk)
+        return { valid: false, reason: "invalid_signature" };
+    return { valid: true };
+}
 /** Loop prevention: don't send receipts for receipts or audit messages. */
 const NO_RECEIPT_TYPES = new Set([
     "network.tulpa.receipt",

package/dist/middleware/ink-auth.d.ts

@@ -60,6 +60,7 @@ export declare function verifyInkAuth(opts: {
 }): Promise<{
     valid: true;
     senderAgentId: string;
+    principal: string;
     keyId?: string;
     keyStatus?: KeyStatus;
 } | {

package/dist/middleware/ink-auth.js

@@ -1,5 +1,5 @@
 import { verifyInkSignature, MAX_TIMESTAMP_AGE_MS, MAX_FUTURE_TIMESTAMP_MS } from "../crypto/ink.js";
-import { extractPublicKeyFromAgentId } from "../crypto/keys.js";
+import { extractPublicKeyFromAgentId, canonicalAgentPrincipal } from "../crypto/keys.js";
 import { verifyInkSignatureWithKeys } from "../crypto/multi-key-verify.js";
 /**
  * Parse and verify an INK-Ed25519 Authorization header.
@@ -33,8 +33,10 @@ export async function verifyInkAuth(opts) {
     }
     // Ed25519 signatures are exactly 86 base64url chars — tighten the regex to
     // {86} so clearly-wrong lengths get rejected up front, rather than burning
-    // CPU on verifyInkSignature for a malformed value.
-    const match = opts.authHeader.match(/^INK-Ed25519\s+([A-Za-z0-9_-]{86})(?:\s+keyId=([A-Za-z0-9_:.-]{1,128}))?$/);
+    // CPU on verifyInkSignature for a malformed value. Single literal spaces
+    // match the spec grammar and buildAuthHeader's output; `\s` would let
+    // CR/LF/TAB into a parsed header value.
+    const match = opts.authHeader.match(/^INK-Ed25519 ([A-Za-z0-9_-]{86})(?: keyId=([A-Za-z0-9_:.-]{1,128}))?$/);
     if (!match) {
         return { valid: false, error: "invalid_auth_scheme" };
     }
@@ -172,6 +174,7 @@ export async function verifyInkAuth(opts) {
                     return {
                         valid: true,
                         senderAgentId: senderDid,
+                        principal: canonicalAgentPrincipal(senderDid),
                         keyId: result.keyId,
                         keyStatus: result.keyStatus,
                     };
@@ -206,7 +209,7 @@ export async function verifyInkAuth(opts) {
         const noncePass = await recordNonce();
         if (!noncePass.ok)
             return { valid: false, error: noncePass.error };
-        return { valid: true, senderAgentId: senderDid };
+        return { valid: true, senderAgentId: senderDid, principal: canonicalAgentPrincipal(senderDid) };
     }
     catch {
         return { valid: false, error: "signature_verification_failed" };

package/dist/models/agent-card.js

@@ -5,17 +5,17 @@ import { ProfileSnapshotSchema } from "./profile.js";
 import { KeyEntrySchema } from "./key-entry.js";
 import { InkTransportSchema, AgentCardVisibilitySchema } from "./ink-handshake.js";
 export const ThirdPartyAuditServiceSchema = z.object({
-    endpoint: z.string().url(),
-    did: z.string(),
-    publicKey: z.string(),
+    endpoint: z.string().max(2048).url(),
+    did: z.string().max(512),
+    publicKey: z.string().max(256),
 });
 export const AgentCardSchema = z.object({
     protocol: z.literal("ink/0.1"),
-    agentId: z.string(),
-    ownerDid: z.string().optional(),
-    ownerHandle: z.string().optional(),
-    atprotoRecordUri: z.string().optional(),
-    handle: z.string(),
+    agentId: z.string().max(512),
+    ownerDid: z.string().max(512).optional(),
+    ownerHandle: z.string().max(256).optional(),
+    atprotoRecordUri: z.string().max(2048).optional(),
+    handle: z.string().max(256),
     displayName: z.string().max(200),
     /**
      * Inbound message endpoint URL. Required.
@@ -27,36 +27,36 @@ export const AgentCardSchema = z.object({
      * MAY emit `inboxEndpoint` alongside it. The runtime helper
      * `resolveAgentInbox(card)` returns whichever value is present.
      */
-    endpoint: z.string().url(),
-    inboxEndpoint: z.string().url().optional(),
-    publicKeyMultibase: z.string().startsWith("z"),
+    endpoint: z.string().max(2048).url(),
+    inboxEndpoint: z.string().max(2048).url().optional(),
+    publicKeyMultibase: z.string().startsWith("z").max(128),
     // (other fields below; the `inboxEndpoint === endpoint` invariant
     // is enforced by the .superRefine() at the bottom of this schema.)
     profileSnapshot: ProfileSnapshotSchema.optional(),
     capabilities: z.object({
-        intentsAccepted: z.array(IntentTypeSchema),
-        intentsSent: z.array(IntentTypeSchema),
+        intentsAccepted: z.array(IntentTypeSchema).max(32),
+        intentsSent: z.array(IntentTypeSchema).max(32),
         receipts: z.object({
             send: z.boolean(),
-            dispositions: z.array(InkReceiptDispositionSchema),
+            dispositions: z.array(InkReceiptDispositionSchema).max(16),
         }).optional(),
         auditExchange: z.boolean().optional(),
         thirdPartyAudit: z.object({
-            services: z.array(ThirdPartyAuditServiceSchema),
+            services: z.array(ThirdPartyAuditServiceSchema).max(16),
             submitPolicy: z.enum(["all", "high_value", "none"]),
         }).optional(),
     }),
     availability: z.object({
-        timezone: z.string(),
-        meetingHours: z.string().optional(),
-        responseSla: z.string().optional(),
+        timezone: z.string().max(64),
+        meetingHours: z.string().max(200).optional(),
+        responseSla: z.string().max(200).optional(),
     }),
     keys: z.object({
-        signing: z.array(KeyEntrySchema),
-        encryption: z.array(KeyEntrySchema),
+        signing: z.array(KeyEntrySchema).max(32),
+        encryption: z.array(KeyEntrySchema).max(32),
     }).optional(),
-    currentSigningKeyId: z.string().optional(),
-    currentEncryptionKeyId: z.string().optional(),
+    currentSigningKeyId: z.string().max(128).optional(),
+    currentEncryptionKeyId: z.string().max(128).optional(),
     keySetVersion: z.number().int().positive().optional(),
     // Message protocol versions this agent's receiver can verify on the
     // body signature. When absent, assume ink/0.1 only. A sender MUST NOT