@suveren/gateway 0.7.4 → 0.8.0

package/node_modules/@hap/core/dist/index.mjs

@@ -151,9 +151,9 @@ function computeIntentDisclosureHash(intentCiphertext, approversFrozen) {
 }
 
 // src/identity.ts
-function validateSubject(subject) {
+function validateSubject(subject, opts) {
   const errors = [];
-  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+  const { did, assurance, method, trust_root, verifier, disclose } = subject;
   if (!did) errors.push("subject.did is required");
   if (assurance === "low") {
     if (method !== "self_declared") errors.push(`low assurance requires method "self_declared", got "${method}"`);
@@ -166,7 +166,10 @@ function validateSubject(subject) {
     } else if (method === "eudi") {
       if (trust_root !== "external") errors.push('eudi requires trust_root "external"');
       if (!verifier) errors.push("eudi requires a verifier");
-      if (!owner_signature) errors.push("eudi requires an owner_signature");
+      if (opts?.ownerMandates !== void 0) {
+        const entry = opts.ownerMandates.find((m) => m.did === did && m.binding === "eudi");
+        if (!entry) errors.push('eudi requires an owner_mandates entry with binding "eudi" for this DID');
+      }
     } else {
       errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
     }
@@ -284,15 +287,51 @@ function validateContextParams(params, profile) {
   }
   return { valid: errors.length === 0, errors };
 }
+var CanonicalValueError = class extends Error {
+  code;
+  field;
+  constructor(code, field, message) {
+    super(message);
+    this.name = "CanonicalValueError";
+    this.code = code;
+    this.field = field;
+  }
+};
+function percentEncodeCanonicalValue(raw) {
+  const bytes = new TextEncoder().encode(raw);
+  let out = "";
+  for (const b of bytes) {
+    if (b === 61 || b === 37 || b < 32 || b > 126) {
+      out += "%" + b.toString(16).toUpperCase().padStart(2, "0");
+    } else {
+      out += String.fromCharCode(b);
+    }
+  }
+  return out;
+}
+function canonicalRecords(params, keyOrder, code) {
+  const lines = [];
+  for (const key of keyOrder) {
+    const value = params[key];
+    if (value === void 0 || value === null) continue;
+    const raw = String(value);
+    if (raw.includes("\n") || raw.includes("\r")) {
+      throw new CanonicalValueError(
+        code,
+        key,
+        `Value for "${key}" contains a raw newline or carriage return. Refusing: a hash over stripped or normalized input would not represent what was authorized.`
+      );
+    }
+    lines.push(`${key}=${percentEncodeCanonicalValue(raw)}`);
+  }
+  return lines.join("\n");
+}
 function canonicalBounds(params, profile) {
   const validation = validateBoundsParams(params, profile);
   if (!validation.valid) {
     throw new Error(`Invalid bounds parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.boundsSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.boundsSchema.keyOrder, "BOUNDS_INVALID_VALUE");
 }
 function canonicalContext(params, profile) {
   if (!profile.contextSchema || Object.keys(profile.contextSchema.fields).length === 0) {
@@ -302,10 +341,7 @@ function canonicalContext(params, profile) {
   if (!validation.valid) {
     throw new Error(`Invalid context parameters: ${validation.errors.join("; ")}`);
   }
-  const lines = profile.contextSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-  return lines.join("\n");
+  return canonicalRecords(params, profile.contextSchema.keyOrder, "CONTEXT_INVALID_VALUE");
 }
 function computeBoundsHash(params, profile) {
   const canonical = canonicalBounds(params, profile);
@@ -435,7 +471,17 @@ async function verify(request, publicKeyHex, now = Math.floor(Date.now() / 1e3),
     return verifyV3(request, profile, publicKeyHex, now, executionLog, errors);
   }
 }
+function noAttestationSupplied(request) {
+  return !Array.isArray(request.attestations) || request.attestations.length === 0;
+}
+function noAttestationResult() {
+  return {
+    approved: false,
+    errors: [{ code: "MALFORMED_ATTESTATION", message: "No attestation supplied \u2014 nothing to verify" }]
+  };
+}
 async function verifyV3(request, profile, publicKeyHex, now, executionLog, errors) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   let expectedFrameHash;
   try {
     expectedFrameHash = computeFrameHash(request.frame, profile);
@@ -496,6 +542,7 @@ async function verifyV3(request, profile, publicKeyHex, now, executionLog, error
   return { approved: true };
 }
 async function verifyV4(request, profile, publicKeyHex, now, executionLog) {
+  if (noAttestationSupplied(request)) return noAttestationResult();
   const errors = [];
   const bounds = request.frame;
   const context = request.context;
@@ -869,10 +916,207 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   }
   return errors;
 }
+
+// src/did-key.ts
+var B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var B58_MAP = {};
+for (let i = 0; i < B58_ALPHABET.length; i++) B58_MAP[B58_ALPHABET[i]] = i;
+var ED25519_MULTICODEC = Uint8Array.from([237, 1]);
+var ED25519_KEY_BYTES = 32;
+function base58btcEncode(bytes) {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] * 256;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) out += B58_ALPHABET[digits[i]];
+  return out;
+}
+function base58btcDecode(s) {
+  let zeros = 0;
+  while (zeros < s.length && s[zeros] === "1") zeros++;
+  const bytes = [];
+  for (let i = zeros; i < s.length; i++) {
+    const val = B58_MAP[s[i]];
+    if (val === void 0) throw new Error(`invalid base58 character "${s[i]}"`);
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + i] = bytes[bytes.length - 1 - i];
+  return out;
+}
+function encodeDidKey(publicKey) {
+  if (publicKey.length !== ED25519_KEY_BYTES) {
+    throw new Error(`INVALID_KEY: expected ${ED25519_KEY_BYTES} bytes, got ${publicKey.length}`);
+  }
+  const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKey.length);
+  prefixed.set(ED25519_MULTICODEC, 0);
+  prefixed.set(publicKey, ED25519_MULTICODEC.length);
+  return `did:key:z${base58btcEncode(prefixed)}`;
+}
+function decodeDidKey(did) {
+  if (!did.startsWith("did:key:z")) {
+    throw new Error(`NOT_KEY_BEARING: ${JSON.stringify(did)} is not a base58btc did:key`);
+  }
+  let decoded;
+  try {
+    decoded = base58btcDecode(did.slice("did:key:z".length));
+  } catch (err) {
+    throw new Error(`NOT_KEY_BEARING: ${err.message}`);
+  }
+  if (decoded.length !== ED25519_MULTICODEC.length + ED25519_KEY_BYTES || decoded[0] !== ED25519_MULTICODEC[0] || decoded[1] !== ED25519_MULTICODEC[1]) {
+    throw new Error("NOT_KEY_BEARING: not an ed25519-pub multicodec payload");
+  }
+  return decoded.slice(ED25519_MULTICODEC.length);
+}
+function isKeyBearingDid(did) {
+  try {
+    decodeDidKey(did);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/mandate.ts
+import * as ed2 from "@noble/ed25519";
+var MandateError = class extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "MandateError";
+  }
+};
+function buildMandateProjection(payload, entry) {
+  const { profile_id, bounds_hash, context_hash, execution_context_hash, gate_content_hashes, commitment_mode, expires_at } = payload;
+  if (!bounds_hash || !context_hash || !commitment_mode) {
+    throw new MandateError("MALFORMED_ATTESTATION", "mandate projection requires bounds_hash, context_hash and commitment_mode");
+  }
+  const projection = {
+    typ: "HAP-mandate",
+    version: "0.6",
+    profile_id,
+    owner_did: entry.did,
+    bounds_hash,
+    context_hash,
+    execution_context_hash,
+    gate_content_hashes,
+    commitment_mode,
+    expires_at,
+    nonce: entry.nonce
+  };
+  if (payload.intent_disclosure_hash !== void 0) {
+    projection.intent_disclosure_hash = payload.intent_disclosure_hash;
+  }
+  return projection;
+}
+function mandateSigningBytes(projection) {
+  return new TextEncoder().encode(canonicalize(projection));
+}
+function approvalSigningBytes(approval) {
+  return new TextEncoder().encode(canonicalize(approval));
+}
+function base64urlToBytes(s) {
+  const base64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = base64.length % 4 === 0 ? "" : "=".repeat(4 - base64.length % 4);
+  return new Uint8Array(Buffer.from(base64 + padding, "base64"));
+}
+function bytesToBase64url(bytes) {
+  return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function signMandateProjection(projection, privateKey) {
+  const sig = await ed2.signAsync(mandateSigningBytes(projection), privateKey);
+  return bytesToBase64url(sig);
+}
+async function signApproval(approval, privateKey) {
+  const sig = await ed2.signAsync(approvalSigningBytes(approval), privateKey);
+  return bytesToBase64url(sig);
+}
+async function verifyOwnerMandate(attestation, entry) {
+  const owners = attestation.payload.resolved_owners ?? [];
+  if (!owners.includes(entry.did)) {
+    throw new MandateError("OWNER_NOT_RESOLVED", `signing DID ${entry.did} is not in resolved_owners`);
+  }
+  if (entry.alg !== "EdDSA") {
+    throw new MandateError("MANDATE_SIGNATURE_INVALID", `alg ${entry.alg} disagrees with the DID's key type (DID is authoritative)`);
+  }
+  let publicKey;
+  try {
+    publicKey = decodeDidKey(entry.did);
+  } catch (err) {
+    throw new MandateError("NOT_KEY_BEARING", err.message);
+  }
+  const projection = buildMandateProjection(attestation.payload, entry);
+  const ok = await ed2.verifyAsync(base64urlToBytes(entry.signature), mandateSigningBytes(projection), publicKey);
+  if (!ok) {
+    throw new MandateError("MANDATE_SIGNATURE_INVALID", `owner mandate signature by ${entry.did} does not verify`);
+  }
+}
+async function verifyOwnerMandates(attestation) {
+  const entries = attestation.payload.owner_mandates ?? [];
+  for (const entry of entries) {
+    await verifyOwnerMandate(attestation, entry);
+  }
+  return entries;
+}
+async function verifyApproval(approval, signature, signerDid) {
+  let publicKey;
+  try {
+    publicKey = decodeDidKey(signerDid);
+  } catch (err) {
+    throw new MandateError("NOT_KEY_BEARING", err.message);
+  }
+  const ok = await ed2.verifyAsync(base64urlToBytes(signature), approvalSigningBytes(approval), publicKey);
+  if (!ok) {
+    throw new MandateError("APPROVAL_SIGNATURE_INVALID", `approval signature by ${signerDid} does not verify`);
+  }
+}
+
+// src/receipt.ts
+import * as ed3 from "@noble/ed25519";
+async function verifyReceiptSignature(receipt, publicKeyHex) {
+  const { signature, ...unsigned } = receipt;
+  if (!signature) {
+    throw new Error("INVALID_SIGNATURE: receipt carries no signature");
+  }
+  const bytes = new TextEncoder().encode(canonicalize(unsigned));
+  const base64 = signature.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = base64.length % 4 === 0 ? "" : "=".repeat(4 - base64.length % 4);
+  const sigBytes = new Uint8Array(Buffer.from(base64 + padding, "base64"));
+  const publicKeyBytes = new Uint8Array(Buffer.from(publicKeyHex, "hex"));
+  const ok = await ed3.verifyAsync(sigBytes, bytes, publicKeyBytes).catch(() => false);
+  if (!ok) {
+    throw new Error("INVALID_SIGNATURE: receipt signature verification failed");
+  }
+}
 export {
+  CanonicalValueError,
   ContentBindingError,
+  MandateError,
+  approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  buildMandateProjection,
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
@@ -889,26 +1133,36 @@ export {
   computeIntentHash,
   contentCanonicalBytes,
   decodeAttestationBlob,
+  decodeDidKey,
   deriveIdentityLine,
   encodeAttestationBlob,
+  encodeDidKey,
   frameHash,
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
   isFieldBinding,
+  isKeyBearingDid,
   isV4Attestation,
   listProfiles,
+  mandateSigningBytes,
   registerProfile,
   selectBoundFields,
+  signApproval,
+  signMandateProjection,
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,
   validateSubject,
   verify,
+  verifyApproval,
   verifyAttestation,
   verifyAttestationSignature,
   verifyAttestationV4,
   verifyBoundsHash,
   verifyContextHash,
-  verifyFrameHash
+  verifyFrameHash,
+  verifyOwnerMandate,
+  verifyOwnerMandates,
+  verifyReceiptSignature
 };

package/node_modules/@hap/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.8.4",
+  "version": "0.10.0",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -24,6 +24,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "pnpm build",
@@ -39,5 +40,6 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
-  }
+  },
+  "homepage": "https://humanagencyprotocol.org"
 }

package/node_modules/@hap/core/src/did-key.ts

@@ -0,0 +1,126 @@
+/**
+ * did:key — encode/decode for KEY-BEARING DIDs (HAP v0.6).
+ *
+ * A real `did:key` is self-certifying: the public key IS the identifier, so
+ * substituting the key produces a DIFFERENT DID and no key directory is ever
+ * consulted. That property is what the Owner Mandate design stands on
+ * (protocol.md → "Identity DIDs vs signing DIDs"): a signing DID MUST be
+ * key-bearing, and verification uses the key carried in the identifier —
+ * deliberately, there is no `public_key` field anywhere on the wire.
+ *
+ * Format (W3C did:key method, Ed25519):
+ *   did:key:z<base58btc( 0xed 0x01 ‖ 32-byte-public-key )>
+ * `z` is the multibase prefix for base58btc; `0xed 0x01` is the multicodec
+ * varint for ed25519-pub. The result always starts `did:key:z6Mk`.
+ *
+ * Scope: Ed25519 only — the one signing curve this protocol version uses.
+ * Anything else (including the reference implementation's legacy decorative
+ * `did:key:<uuid-fragment>` identifiers) decodes as NOT key-bearing.
+ */
+
+const B58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+const B58_MAP: Record<string, number> = {};
+for (let i = 0; i < B58_ALPHABET.length; i++) B58_MAP[B58_ALPHABET[i]] = i;
+
+/** multicodec ed25519-pub (0xed) as unsigned varint, followed by key bytes. */
+const ED25519_MULTICODEC = Uint8Array.from([0xed, 0x01]);
+const ED25519_KEY_BYTES = 32;
+
+function base58btcEncode(bytes: Uint8Array): string {
+  // Count leading zero bytes — they encode as leading '1's.
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+
+  const digits: number[] = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] * 256;
+      digits[j] = carry % 58;
+      carry = (carry / 58) | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = (carry / 58) | 0;
+    }
+  }
+
+  let out = '1'.repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) out += B58_ALPHABET[digits[i]];
+  return out;
+}
+
+function base58btcDecode(s: string): Uint8Array {
+  let zeros = 0;
+  while (zeros < s.length && s[zeros] === '1') zeros++;
+
+  const bytes: number[] = [];
+  for (let i = zeros; i < s.length; i++) {
+    const val = B58_MAP[s[i]];
+    if (val === undefined) throw new Error(`invalid base58 character "${s[i]}"`);
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 0xff;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 0xff);
+      carry >>= 8;
+    }
+  }
+
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + i] = bytes[bytes.length - 1 - i];
+  return out;
+}
+
+/** Encode a 32-byte Ed25519 public key as a key-bearing `did:key:z6Mk…`. */
+export function encodeDidKey(publicKey: Uint8Array): string {
+  if (publicKey.length !== ED25519_KEY_BYTES) {
+    throw new Error(`INVALID_KEY: expected ${ED25519_KEY_BYTES} bytes, got ${publicKey.length}`);
+  }
+  const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKey.length);
+  prefixed.set(ED25519_MULTICODEC, 0);
+  prefixed.set(publicKey, ED25519_MULTICODEC.length);
+  return `did:key:z${base58btcEncode(prefixed)}`;
+}
+
+/**
+ * Decode a key-bearing `did:key` to its Ed25519 public key bytes.
+ *
+ * @throws Error prefixed `NOT_KEY_BEARING:` for anything that is not a valid
+ * base58btc-multibase Ed25519 did:key — including the legacy decorative
+ * `did:key:<uuid-fragment>` identifiers, other multibase prefixes, and other
+ * key types. The error name is the point: under the mandate design, a
+ * non-key-bearing signing DID must fail STRUCTURALLY, never fall back.
+ */
+export function decodeDidKey(did: string): Uint8Array {
+  if (!did.startsWith('did:key:z')) {
+    throw new Error(`NOT_KEY_BEARING: ${JSON.stringify(did)} is not a base58btc did:key`);
+  }
+  let decoded: Uint8Array;
+  try {
+    decoded = base58btcDecode(did.slice('did:key:z'.length));
+  } catch (err) {
+    throw new Error(`NOT_KEY_BEARING: ${(err as Error).message}`);
+  }
+  if (
+    decoded.length !== ED25519_MULTICODEC.length + ED25519_KEY_BYTES ||
+    decoded[0] !== ED25519_MULTICODEC[0] ||
+    decoded[1] !== ED25519_MULTICODEC[1]
+  ) {
+    throw new Error('NOT_KEY_BEARING: not an ed25519-pub multicodec payload');
+  }
+  return decoded.slice(ED25519_MULTICODEC.length);
+}
+
+/** True iff the DID decodes as a key-bearing Ed25519 did:key. Never throws. */
+export function isKeyBearingDid(did: string): boolean {
+  try {
+    decodeDidKey(did);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/node_modules/@hap/core/src/frame.ts

@@ -2,8 +2,11 @@
  * Frame Canonicalization for Agent Profiles
  *
  * Agent profiles support mixed-type fields (strings and numbers).
- * Canonical form: all values are converted to strings via String(value).
- * Keys are ordered according to the profile's keyOrder.
+ * Canonical form: `key=value` records joined with LF, keys in the profile's
+ * keyOrder. Values are stringified with String(value) — the shortest
+ * round-trippable form for numbers — then percent-encoded per protocol.md
+ * (`=`, `%`, and every byte outside printable ASCII); a value carrying a raw
+ * LF/CR is refused, never normalized. See `canonicalRecords` below.
  *
  * v0.3: frameSchema
  * v0.4: boundsSchema + contextSchema (separate hashes)
@@ -176,11 +179,115 @@ export function validateContextParams(
   return { valid: errors.length === 0, errors };
 }
 
+// ─── Value Encoding (normative, v0.5+) ───────────────────────────────────────
+
+/**
+ * Thrown when a value cannot be canonicalized at all — currently only for raw
+ * LF/CR inside a value. Carries the protocol error code so callers can map it
+ * straight onto the wire without string-matching a message.
+ *
+ * protocol.md → *Bounds & Scope Canonicalization* → Value encoding:
+ *   "Values MUST NOT contain raw newline (\n) or carriage-return (\r)
+ *    characters. Implementations MUST reject input containing them; silent
+ *    stripping or normalization is a violation because it produces a hash that
+ *    does not faithfully represent the input."
+ */
+export class CanonicalValueError extends Error {
+  readonly code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE';
+  readonly field: string;
+
+  constructor(code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE', field: string, message: string) {
+    super(message);
+    this.name = 'CanonicalValueError';
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/**
+ * Percent-encode a value per protocol.md → *Value encoding*.
+ *
+ * Encoded, over the value's UTF-8 bytes, as `%` + two UPPERCASE hex digits:
+ *   - `=` (0x3D) — otherwise it would be read as the key/value separator
+ *   - `%` (0x25) — so the encoding is self-inverse
+ *   - every byte outside printable ASCII 0x20–0x7E
+ *
+ * LF and CR are deliberately NOT in this list: they are refused upstream, so
+ * encoding them is unreachable (v0.7 removed the spec's contradiction here).
+ *
+ * This runs at canonicalization time only. Stored values keep the human's
+ * original bytes.
+ */
+function percentEncodeCanonicalValue(raw: string): string {
+  const bytes = new TextEncoder().encode(raw);
+  let out = '';
+  for (const b of bytes) {
+    if (b === 0x3d || b === 0x25 || b < 0x20 || b > 0x7e) {
+      out += '%' + b.toString(16).toUpperCase().padStart(2, '0');
+    } else {
+      out += String.fromCharCode(b);
+    }
+  }
+  return out;
+}
+
+/**
+ * The one place `key=value` records are built for bounds and context.
+ *
+ * Rules applied here (all normative, protocol.md → *Bounds & Scope
+ * Canonicalization*):
+ *   - keys in the schema's keyOrder, never alphabetical
+ *   - a value carrying a raw LF/CR is REFUSED (never stripped or encoded)
+ *   - `=`, `%`, and any byte outside 0x20–0x7E are percent-encoded (UPPERCASE)
+ *   - numbers use JS `String()`, which is the shortest round-trippable form
+ *     (`String(20.0)` === "20")
+ *   - a key with no value is OMITTED entirely — it emits no record
+ *
+ * On the omission rule: required keys are guaranteed present by the caller's
+ * validation (`validateBoundsParams` / `validateContextParams` reject a missing
+ * required field), so "explicit inclusion of all required keys" still holds.
+ * What remains are *optional* keys the human never set. Rendering those as the
+ * literal string "undefined" — the pre-fix behaviour — hashed a JavaScript
+ * artifact that no other language would produce and that collides with a real
+ * value of "undefined". Omitting them (rather than emitting `key=`) also keeps
+ * "the human set no limit" distinct from "the human set an empty value", and
+ * matches this package's JSON canonicalization, which drops undefined-valued
+ * properties.
+ */
+function canonicalRecords(
+  params: Record<string, string | number | undefined>,
+  keyOrder: string[],
+  code: 'BOUNDS_INVALID_VALUE' | 'CONTEXT_INVALID_VALUE',
+): string {
+  const lines: string[] = [];
+
+  for (const key of keyOrder) {
+    const value = params[key];
+    if (value === undefined || value === null) continue;
+
+    const raw = String(value);
+    if (raw.includes('\n') || raw.includes('\r')) {
+      throw new CanonicalValueError(
+        code,
+        key,
+        `Value for "${key}" contains a raw newline or carriage return. ` +
+          'Refusing: a hash over stripped or normalized input would not represent what was authorized.',
+      );
+    }
+
+    lines.push(`${key}=${percentEncodeCanonicalValue(raw)}`);
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Builds the canonical bounds string from parameters.
- * All values are converted to strings. Keys are ordered per profile's boundsSchema.keyOrder.
+ * Keys are ordered per profile's boundsSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code BOUNDS_INVALID_VALUE) if a value carries a raw LF/CR
  */
 export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile): string {
   const validation = validateBoundsParams(params, profile);
@@ -188,19 +295,17 @@ export function canonicalBounds(params: AgentBoundsParams, profile: AgentProfile
     throw new Error(`Invalid bounds parameters: ${validation.errors.join('; ')}`);
   }
 
-  const lines = profile.boundsSchema!.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-
-  return lines.join('\n');
+  return canonicalRecords(params, profile.boundsSchema!.keyOrder, 'BOUNDS_INVALID_VALUE');
 }
 
 /**
  * Builds the canonical context string from parameters.
- * All values are converted to strings. Keys are ordered per profile's contextSchema.keyOrder.
+ * Keys are ordered per profile's contextSchema.keyOrder; values are encoded per
+ * protocol.md → *Value encoding* (see `canonicalRecords`).
  * For empty context (no contextSchema or no fields), returns "".
  *
  * @throws Error if any field fails validation
+ * @throws CanonicalValueError (code CONTEXT_INVALID_VALUE) if a value carries a raw LF/CR
  */
 export function canonicalContext(params: AgentContextParams, profile: AgentProfile): string {
   // No contextSchema or no fields → empty context
@@ -213,11 +318,7 @@ export function canonicalContext(params: AgentContextParams, profile: AgentProfi
     throw new Error(`Invalid context parameters: ${validation.errors.join('; ')}`);
   }
 
-  const lines = profile.contextSchema.keyOrder.map(
-    (key) => `${key}=${String(params[key])}`
-  );
-
-  return lines.join('\n');
+  return canonicalRecords(params, profile.contextSchema.keyOrder, 'CONTEXT_INVALID_VALUE');
 }
 
 /**