@humanagencyp/hap-core 0.4.6 → 0.5.1

package/dist/index.d.mts

@@ -161,6 +161,32 @@ interface ProfileBoundsField {
     /** @deprecated v0.4: use boundType: { kind: 'enum', values: [...] }. */
     enum?: string[];
 }
+/**
+ * v0.5 Content Provenance — how a profile's action content is hashed into a
+ * signed receipt (`contentHash`). The ephemeral-content analog of Output
+ * Provenance: it binds the *bytes* of the action rather than a location.
+ *
+ * Profile-bound and OPTIONAL. Absent → no content hash is produced (full
+ * backward compatibility). The gateway computes the hash; the SP only ever
+ * receives the hash, never the content, so HAP's privacy-minimal design holds.
+ *
+ * The profile declares only the *policy* — whether to bind and how to
+ * canonicalize. It does NOT name the tool field: that is tool-specific and is
+ * resolved at runtime (the same content-field resolver the footer uses for
+ * `kind:"text"`; the whole record payload for `kind:"jcs"`).
+ */
+interface ContentBinding {
+    /** Canonicalization version. A verifier MUST pin the version named here. */
+    version: string;
+    /**
+     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload.
+     * - 'text' → free text: NFC + LF + trailing-whitespace strip (see
+     *   canonicalizeText), auto-detected content field.
+     */
+    kind: 'jcs' | 'text';
+    /** text only: hash the content BEFORE any appended Suveren footer. */
+    pre_footer?: boolean;
+}
 /**
  * Context field definition within a v0.4 profile.
  */
@@ -280,6 +306,13 @@ interface AgentProfile {
         max: number;
     };
     retention_minimum: number;
+    /**
+     * v0.5 Content Provenance (OPTIONAL, profile-bound). When present, the
+     * gateway computes a `contentHash` for gated writes under this profile and
+     * passes it (hash only) to the SP, which signs it into the receipt. Absent
+     * → no content hash. See {@link ContentBinding}.
+     */
+    content_binding?: ContentBinding;
     /**
      * Tool gating configuration — how MCP tools map to execution context.
      * @deprecated Tool gating now lives in integration manifests (content/integrations/*.json).
@@ -401,6 +434,90 @@ type GatekeeperResult = {
     errors: GatekeeperError[];
 };
 
+/**
+ * JCS — JSON Canonicalization (RFC 8785) for signing.
+ *
+ * Both attestation and receipt signatures are computed over a canonical byte
+ * serialization of the payload, so that two independent implementations (an AS,
+ * a gateway, an external verifier — in any language) agree on exactly which
+ * bytes were signed regardless of how they happened to construct the object.
+ *
+ * `JSON.stringify` is NOT sufficient: it preserves key *insertion* order, so the
+ * same logical payload built with keys in a different order serializes to
+ * different bytes and the signature fails to verify. Canonicalization removes
+ * that dependency by sorting keys.
+ *
+ * This is RFC 8785-compatible and matches the v0.5 spec's normative signing
+ * canonicalization (core.md "Signing Canonicalization"):
+ *   1. UTF-8.
+ *   2. Object keys sorted (RFC 8785 sorts by UTF-16 code units — exactly what
+ *      JavaScript's default String comparison does, so `Object.keys().sort()` is
+ *      correct here).
+ *   3. No insignificant whitespace.
+ *   4. Numbers in the shortest round-trippable form — the ECMAScript
+ *      Number-to-String algorithm, which `JSON.stringify(number)` produces and
+ *      RFC 8785 adopts verbatim.
+ *   5. Strings escaped per RFC 8259; non-ASCII passed through as UTF-8 (this is
+ *      `JSON.stringify`'s behaviour for strings).
+ *   6. Array order preserved.
+ *
+ * Because it relies only on `JSON.stringify` for leaves plus `Object.keys`,
+ * `Array`, and `String` sort — all of which are environment-independent in
+ * JavaScript — Node and the browser produce byte-identical output. The
+ * conformance test pins a (payload → canonical bytes) vector that any other
+ * implementation can check against.
+ */
+declare function canonicalize(value: unknown): string;
+
+/**
+ * Content binding — Level 2 content proof (HAP v0.5 Content Provenance).
+ *
+ * A receipt normally proves who/why/bounds/when but NOT the action's content.
+ * Content binding closes that gap: the gateway computes a `content_hash` over
+ * the action's content per the profile's {@link ContentBinding} and hands the
+ * SP only the hash. The SP signs it into the receipt verbatim — it never sees
+ * the content, so HAP's privacy-minimal design is preserved. Anyone holding
+ * the content can recompute the hash and check it against the signed receipt.
+ *
+ * The hash only verifies if the verifier reproduces the EXACT bytes we hashed,
+ * so canonicalization is normative and versioned (pin via `ContentBinding.version`):
+ *
+ *  - kind:"jcs"  → RFC 8785 JCS of the record payload (see {@link canonicalize}).
+ *  - kind:"text" → UTF-8 of the string after {@link canonicalizeText}
+ *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
+ *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
+ *
+ * Both Node and the browser produce byte-identical output: JCS relies only on
+ * environment-independent primitives, and the text rule uses String.normalize +
+ * plain string ops. The SHA-256 is computed with Node `crypto` here (the same
+ * pattern as frame.ts); browser callers that need to recompute use their own
+ * SubtleCrypto digest over the identical canonical bytes.
+ */
+
+/**
+ * Canonicalize free text per the v0.5 'text' rule. Idempotent.
+ *
+ *   1. Unicode NFC normalization.
+ *   2. CRLF / CR → LF.
+ *   3. Strip trailing spaces/tabs from every line.
+ *   4. Remove trailing blank lines.
+ */
+declare function canonicalizeText(input: string): string;
+/**
+ * Compute the canonical bytes that a content hash is taken over, WITHOUT
+ * hashing — exposed so verifiers can debug a mismatch by inspecting the exact
+ * serialization both sides should agree on.
+ */
+declare function contentCanonicalBytes(kind: ContentBinding['kind'], content: Record<string, unknown> | string): string;
+/**
+ * Compute a profile-bound content hash, formatted `sha256:<hex>` (matching the
+ * frame/bounds/context hash format used elsewhere in HAP).
+ *
+ * @param binding the profile's content_binding declaration
+ * @param content the record payload (jcs) or the resolved text field (text)
+ */
+declare function computeContentHash(binding: ContentBinding, content: Record<string, unknown> | string): string;
+
 /**
  * Frame Canonicalization for Agent Profiles
  *
@@ -598,4 +715,4 @@ declare function listProfiles(): string[];
 declare function getAllProfiles(): AgentProfile[];
 declare function clearProfiles(): void;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, attestationId, canonicalBounds, canonicalContext, canonicalFrame, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContextHash, computeFrameHash, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type ContentBinding, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, contentCanonicalBytes, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.d.ts

@@ -161,6 +161,32 @@ interface ProfileBoundsField {
     /** @deprecated v0.4: use boundType: { kind: 'enum', values: [...] }. */
     enum?: string[];
 }
+/**
+ * v0.5 Content Provenance — how a profile's action content is hashed into a
+ * signed receipt (`contentHash`). The ephemeral-content analog of Output
+ * Provenance: it binds the *bytes* of the action rather than a location.
+ *
+ * Profile-bound and OPTIONAL. Absent → no content hash is produced (full
+ * backward compatibility). The gateway computes the hash; the SP only ever
+ * receives the hash, never the content, so HAP's privacy-minimal design holds.
+ *
+ * The profile declares only the *policy* — whether to bind and how to
+ * canonicalize. It does NOT name the tool field: that is tool-specific and is
+ * resolved at runtime (the same content-field resolver the footer uses for
+ * `kind:"text"`; the whole record payload for `kind:"jcs"`).
+ */
+interface ContentBinding {
+    /** Canonicalization version. A verifier MUST pin the version named here. */
+    version: string;
+    /**
+     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload.
+     * - 'text' → free text: NFC + LF + trailing-whitespace strip (see
+     *   canonicalizeText), auto-detected content field.
+     */
+    kind: 'jcs' | 'text';
+    /** text only: hash the content BEFORE any appended Suveren footer. */
+    pre_footer?: boolean;
+}
 /**
  * Context field definition within a v0.4 profile.
  */
@@ -280,6 +306,13 @@ interface AgentProfile {
         max: number;
     };
     retention_minimum: number;
+    /**
+     * v0.5 Content Provenance (OPTIONAL, profile-bound). When present, the
+     * gateway computes a `contentHash` for gated writes under this profile and
+     * passes it (hash only) to the SP, which signs it into the receipt. Absent
+     * → no content hash. See {@link ContentBinding}.
+     */
+    content_binding?: ContentBinding;
     /**
      * Tool gating configuration — how MCP tools map to execution context.
      * @deprecated Tool gating now lives in integration manifests (content/integrations/*.json).
@@ -401,6 +434,90 @@ type GatekeeperResult = {
     errors: GatekeeperError[];
 };
 
+/**
+ * JCS — JSON Canonicalization (RFC 8785) for signing.
+ *
+ * Both attestation and receipt signatures are computed over a canonical byte
+ * serialization of the payload, so that two independent implementations (an AS,
+ * a gateway, an external verifier — in any language) agree on exactly which
+ * bytes were signed regardless of how they happened to construct the object.
+ *
+ * `JSON.stringify` is NOT sufficient: it preserves key *insertion* order, so the
+ * same logical payload built with keys in a different order serializes to
+ * different bytes and the signature fails to verify. Canonicalization removes
+ * that dependency by sorting keys.
+ *
+ * This is RFC 8785-compatible and matches the v0.5 spec's normative signing
+ * canonicalization (core.md "Signing Canonicalization"):
+ *   1. UTF-8.
+ *   2. Object keys sorted (RFC 8785 sorts by UTF-16 code units — exactly what
+ *      JavaScript's default String comparison does, so `Object.keys().sort()` is
+ *      correct here).
+ *   3. No insignificant whitespace.
+ *   4. Numbers in the shortest round-trippable form — the ECMAScript
+ *      Number-to-String algorithm, which `JSON.stringify(number)` produces and
+ *      RFC 8785 adopts verbatim.
+ *   5. Strings escaped per RFC 8259; non-ASCII passed through as UTF-8 (this is
+ *      `JSON.stringify`'s behaviour for strings).
+ *   6. Array order preserved.
+ *
+ * Because it relies only on `JSON.stringify` for leaves plus `Object.keys`,
+ * `Array`, and `String` sort — all of which are environment-independent in
+ * JavaScript — Node and the browser produce byte-identical output. The
+ * conformance test pins a (payload → canonical bytes) vector that any other
+ * implementation can check against.
+ */
+declare function canonicalize(value: unknown): string;
+
+/**
+ * Content binding — Level 2 content proof (HAP v0.5 Content Provenance).
+ *
+ * A receipt normally proves who/why/bounds/when but NOT the action's content.
+ * Content binding closes that gap: the gateway computes a `content_hash` over
+ * the action's content per the profile's {@link ContentBinding} and hands the
+ * SP only the hash. The SP signs it into the receipt verbatim — it never sees
+ * the content, so HAP's privacy-minimal design is preserved. Anyone holding
+ * the content can recompute the hash and check it against the signed receipt.
+ *
+ * The hash only verifies if the verifier reproduces the EXACT bytes we hashed,
+ * so canonicalization is normative and versioned (pin via `ContentBinding.version`):
+ *
+ *  - kind:"jcs"  → RFC 8785 JCS of the record payload (see {@link canonicalize}).
+ *  - kind:"text" → UTF-8 of the string after {@link canonicalizeText}
+ *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
+ *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
+ *
+ * Both Node and the browser produce byte-identical output: JCS relies only on
+ * environment-independent primitives, and the text rule uses String.normalize +
+ * plain string ops. The SHA-256 is computed with Node `crypto` here (the same
+ * pattern as frame.ts); browser callers that need to recompute use their own
+ * SubtleCrypto digest over the identical canonical bytes.
+ */
+
+/**
+ * Canonicalize free text per the v0.5 'text' rule. Idempotent.
+ *
+ *   1. Unicode NFC normalization.
+ *   2. CRLF / CR → LF.
+ *   3. Strip trailing spaces/tabs from every line.
+ *   4. Remove trailing blank lines.
+ */
+declare function canonicalizeText(input: string): string;
+/**
+ * Compute the canonical bytes that a content hash is taken over, WITHOUT
+ * hashing — exposed so verifiers can debug a mismatch by inspecting the exact
+ * serialization both sides should agree on.
+ */
+declare function contentCanonicalBytes(kind: ContentBinding['kind'], content: Record<string, unknown> | string): string;
+/**
+ * Compute a profile-bound content hash, formatted `sha256:<hex>` (matching the
+ * frame/bounds/context hash format used elsewhere in HAP).
+ *
+ * @param binding the profile's content_binding declaration
+ * @param content the record payload (jcs) or the resolved text field (text)
+ */
+declare function computeContentHash(binding: ContentBinding, content: Record<string, unknown> | string): string;
+
 /**
  * Frame Canonicalization for Agent Profiles
  *
@@ -598,4 +715,4 @@ declare function listProfiles(): string[];
 declare function getAllProfiles(): AgentProfile[];
 declare function clearProfiles(): void;
 
-export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, attestationId, canonicalBounds, canonicalContext, canonicalFrame, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContextHash, computeFrameHash, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };
+export { type AgentBoundsParams, type AgentContextParams, type AgentFrameParams, type AgentProfile, type Attestation, type AttestationHeader, type AttestationPayload, type BoundType, type ContentBinding, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type ExecutionMappingTransform, type ExecutionMappingValue, type ExecutionPath, type FieldConstraint, type FieldUnit, type GateQuestion, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, type ProfileBoundsField, type ProfileContextField, type ProfileFrameField, type ProfileToolGating, type ProfileToolGatingEntry, type ResolvedDomain, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, contentCanonicalBytes, decodeAttestationBlob, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.js

@@ -34,11 +34,15 @@ __export(index_exports, {
   canonicalBounds: () => canonicalBounds,
   canonicalContext: () => canonicalContext,
   canonicalFrame: () => canonicalFrame,
+  canonicalize: () => canonicalize,
+  canonicalizeText: () => canonicalizeText,
   checkAttestationExpiry: () => checkAttestationExpiry,
   clearProfiles: () => clearProfiles,
   computeBoundsHash: () => computeBoundsHash,
+  computeContentHash: () => computeContentHash,
   computeContextHash: () => computeContextHash,
   computeFrameHash: () => computeFrameHash,
+  contentCanonicalBytes: () => contentCanonicalBytes,
   decodeAttestationBlob: () => decodeAttestationBlob,
   encodeAttestationBlob: () => encodeAttestationBlob,
   frameHash: () => frameHash,
@@ -60,8 +64,60 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/frame.ts
+// src/canonicalize.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    throw new Error("canonicalize: undefined is not serializable");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error(`canonicalize: ${value} is not a valid JSON number`);
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((el) => el === void 0 ? "null" : canonicalize(el));
+    return "[" + items.join(",") + "]";
+  }
+  const obj = value;
+  const parts = [];
+  for (const key of Object.keys(obj).sort()) {
+    const v = obj[key];
+    if (v === void 0) continue;
+    parts.push(JSON.stringify(key) + ":" + canonicalize(v));
+  }
+  return "{" + parts.join(",") + "}";
+}
+
+// src/content-binding.ts
 var import_crypto = require("crypto");
+function canonicalizeText(input) {
+  const nfc = input.normalize("NFC");
+  const lf = nfc.replace(/\r\n?/g, "\n");
+  const lines = lf.split("\n").map((line) => line.replace(/[ \t]+$/, ""));
+  return lines.join("\n").replace(/\n+$/, "");
+}
+function sha256Hex(bytes) {
+  return (0, import_crypto.createHash)("sha256").update(bytes, "utf8").digest("hex");
+}
+function contentCanonicalBytes(kind, content) {
+  if (kind === "jcs") {
+    if (typeof content === "string") {
+      throw new Error('content_binding kind="jcs" expects a record payload (object), got a string');
+    }
+    return canonicalize(content);
+  }
+  if (typeof content !== "string") {
+    throw new Error('content_binding kind="text" expects a string, got an object');
+  }
+  return canonicalizeText(content);
+}
+function computeContentHash(binding, content) {
+  return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
+}
+
+// src/frame.ts
+var import_crypto2 = require("crypto");
 function validateFrameParams(params, profile) {
   const errors = [];
   if (!profile.frameSchema) {
@@ -98,7 +154,7 @@ function canonicalFrame(params, profile) {
   return lines.join("\n");
 }
 function frameHash(canonicalFrameString) {
-  const hash = (0, import_crypto.createHash)("sha256").update(canonicalFrameString, "utf8").digest("hex");
+  const hash = (0, import_crypto2.createHash)("sha256").update(canonicalFrameString, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 function computeFrameHash(params, profile) {
@@ -182,17 +238,17 @@ function canonicalContext(params, profile) {
 }
 function computeBoundsHash(params, profile) {
   const canonical = canonicalBounds(params, profile);
-  const hash = (0, import_crypto.createHash)("sha256").update(canonical, "utf8").digest("hex");
+  const hash = (0, import_crypto2.createHash)("sha256").update(canonical, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 function computeContextHash(params, profile) {
   const canonical = canonicalContext(params, profile);
-  const hash = (0, import_crypto.createHash)("sha256").update(canonical, "utf8").digest("hex");
+  const hash = (0, import_crypto2.createHash)("sha256").update(canonical, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 
 // src/attestation.ts
-var import_crypto2 = require("crypto");
+var import_crypto3 = require("crypto");
 var ed = __toESM(require("@noble/ed25519"));
 function decodeAttestationBlob(blob) {
   try {
@@ -210,12 +266,12 @@ function encodeAttestationBlob(attestation) {
   return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function attestationId(blob) {
-  const hash = (0, import_crypto2.createHash)("sha256").update(blob, "utf8").digest("hex");
+  const hash = (0, import_crypto3.createHash)("sha256").update(blob, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 async function verifyAttestationSignature(attestation, publicKeyHex) {
   try {
-    const payloadJson = JSON.stringify(attestation.payload);
+    const payloadJson = canonicalize(attestation.payload);
     const payloadBytes = new TextEncoder().encode(payloadJson);
     const signatureBytes = Buffer.from(attestation.signature, "base64");
     const publicKeyBytes = Buffer.from(publicKeyHex, "hex");
@@ -719,11 +775,15 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
+  canonicalize,
+  canonicalizeText,
   checkAttestationExpiry,
   clearProfiles,
   computeBoundsHash,
+  computeContentHash,
   computeContextHash,
   computeFrameHash,
+  contentCanonicalBytes,
   decodeAttestationBlob,
   encodeAttestationBlob,
   frameHash,

package/dist/index.mjs

@@ -1,5 +1,57 @@
-// src/frame.ts
+// src/canonicalize.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    throw new Error("canonicalize: undefined is not serializable");
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    throw new Error(`canonicalize: ${value} is not a valid JSON number`);
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((el) => el === void 0 ? "null" : canonicalize(el));
+    return "[" + items.join(",") + "]";
+  }
+  const obj = value;
+  const parts = [];
+  for (const key of Object.keys(obj).sort()) {
+    const v = obj[key];
+    if (v === void 0) continue;
+    parts.push(JSON.stringify(key) + ":" + canonicalize(v));
+  }
+  return "{" + parts.join(",") + "}";
+}
+
+// src/content-binding.ts
 import { createHash } from "crypto";
+function canonicalizeText(input) {
+  const nfc = input.normalize("NFC");
+  const lf = nfc.replace(/\r\n?/g, "\n");
+  const lines = lf.split("\n").map((line) => line.replace(/[ \t]+$/, ""));
+  return lines.join("\n").replace(/\n+$/, "");
+}
+function sha256Hex(bytes) {
+  return createHash("sha256").update(bytes, "utf8").digest("hex");
+}
+function contentCanonicalBytes(kind, content) {
+  if (kind === "jcs") {
+    if (typeof content === "string") {
+      throw new Error('content_binding kind="jcs" expects a record payload (object), got a string');
+    }
+    return canonicalize(content);
+  }
+  if (typeof content !== "string") {
+    throw new Error('content_binding kind="text" expects a string, got an object');
+  }
+  return canonicalizeText(content);
+}
+function computeContentHash(binding, content) {
+  return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
+}
+
+// src/frame.ts
+import { createHash as createHash2 } from "crypto";
 function validateFrameParams(params, profile) {
   const errors = [];
   if (!profile.frameSchema) {
@@ -36,7 +88,7 @@ function canonicalFrame(params, profile) {
   return lines.join("\n");
 }
 function frameHash(canonicalFrameString) {
-  const hash = createHash("sha256").update(canonicalFrameString, "utf8").digest("hex");
+  const hash = createHash2("sha256").update(canonicalFrameString, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 function computeFrameHash(params, profile) {
@@ -120,17 +172,17 @@ function canonicalContext(params, profile) {
 }
 function computeBoundsHash(params, profile) {
   const canonical = canonicalBounds(params, profile);
-  const hash = createHash("sha256").update(canonical, "utf8").digest("hex");
+  const hash = createHash2("sha256").update(canonical, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 function computeContextHash(params, profile) {
   const canonical = canonicalContext(params, profile);
-  const hash = createHash("sha256").update(canonical, "utf8").digest("hex");
+  const hash = createHash2("sha256").update(canonical, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 
 // src/attestation.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import * as ed from "@noble/ed25519";
 function decodeAttestationBlob(blob) {
   try {
@@ -148,12 +200,12 @@ function encodeAttestationBlob(attestation) {
   return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function attestationId(blob) {
-  const hash = createHash2("sha256").update(blob, "utf8").digest("hex");
+  const hash = createHash3("sha256").update(blob, "utf8").digest("hex");
   return `sha256:${hash}`;
 }
 async function verifyAttestationSignature(attestation, publicKeyHex) {
   try {
-    const payloadJson = JSON.stringify(attestation.payload);
+    const payloadJson = canonicalize(attestation.payload);
     const payloadBytes = new TextEncoder().encode(payloadJson);
     const signatureBytes = Buffer.from(attestation.signature, "base64");
     const publicKeyBytes = Buffer.from(publicKeyHex, "hex");
@@ -656,11 +708,15 @@ export {
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
+  canonicalize,
+  canonicalizeText,
   checkAttestationExpiry,
   clearProfiles,
   computeBoundsHash,
+  computeContentHash,
   computeContextHash,
   computeFrameHash,
+  contentCanonicalBytes,
   decodeAttestationBlob,
   encodeAttestationBlob,
   frameHash,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -21,22 +21,23 @@
     "dist",
     "src"
   ],
-  "dependencies": {
-    "@noble/ed25519": "^2.1.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.10.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.0.0"
-  },
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "prepublishOnly": "pnpm build",
     "release:patch": "pnpm version patch && git push --follow-tags",
     "release:minor": "pnpm version minor && git push --follow-tags",
     "release:major": "pnpm version major && git push --follow-tags"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
   }
-}
+}

package/src/attestation.ts

@@ -7,6 +7,7 @@
 import { createHash } from 'crypto';
 import * as ed from '@noble/ed25519';
 import type { Attestation, AttestationPayload } from './types';
+import { canonicalize } from './canonicalize';
 
 /**
  * Decodes a base64url-encoded attestation blob.
@@ -50,7 +51,9 @@ export async function verifyAttestationSignature(
   publicKeyHex: string
 ): Promise<void> {
   try {
-    const payloadJson = JSON.stringify(attestation.payload);
+    // JCS-canonical bytes (RFC 8785) — must match the canonicalization the
+    // signer used. The AS signs the same canonical form (see keys.ts).
+    const payloadJson = canonicalize(attestation.payload);
     const payloadBytes = new TextEncoder().encode(payloadJson);
     const signatureBytes = Buffer.from(attestation.signature, 'base64');
     const publicKeyBytes = Buffer.from(publicKeyHex, 'hex');

package/src/canonicalize.ts

@@ -0,0 +1,65 @@
+/**
+ * JCS — JSON Canonicalization (RFC 8785) for signing.
+ *
+ * Both attestation and receipt signatures are computed over a canonical byte
+ * serialization of the payload, so that two independent implementations (an AS,
+ * a gateway, an external verifier — in any language) agree on exactly which
+ * bytes were signed regardless of how they happened to construct the object.
+ *
+ * `JSON.stringify` is NOT sufficient: it preserves key *insertion* order, so the
+ * same logical payload built with keys in a different order serializes to
+ * different bytes and the signature fails to verify. Canonicalization removes
+ * that dependency by sorting keys.
+ *
+ * This is RFC 8785-compatible and matches the v0.5 spec's normative signing
+ * canonicalization (core.md "Signing Canonicalization"):
+ *   1. UTF-8.
+ *   2. Object keys sorted (RFC 8785 sorts by UTF-16 code units — exactly what
+ *      JavaScript's default String comparison does, so `Object.keys().sort()` is
+ *      correct here).
+ *   3. No insignificant whitespace.
+ *   4. Numbers in the shortest round-trippable form — the ECMAScript
+ *      Number-to-String algorithm, which `JSON.stringify(number)` produces and
+ *      RFC 8785 adopts verbatim.
+ *   5. Strings escaped per RFC 8259; non-ASCII passed through as UTF-8 (this is
+ *      `JSON.stringify`'s behaviour for strings).
+ *   6. Array order preserved.
+ *
+ * Because it relies only on `JSON.stringify` for leaves plus `Object.keys`,
+ * `Array`, and `String` sort — all of which are environment-independent in
+ * JavaScript — Node and the browser produce byte-identical output. The
+ * conformance test pins a (payload → canonical bytes) vector that any other
+ * implementation can check against.
+ */
+export function canonicalize(value: unknown): string {
+  if (value === undefined) {
+    throw new Error('canonicalize: undefined is not serializable');
+  }
+  if (typeof value === 'number' && !Number.isFinite(value)) {
+    throw new Error(`canonicalize: ${value} is not a valid JSON number`);
+  }
+
+  // Primitives: string, finite number, boolean, null — JSON.stringify is already
+  // canonical (RFC 8259 string escaping, ECMAScript number formatting).
+  if (value === null || typeof value !== 'object') {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    // Array order is preserved; undefined elements become null (matching
+    // JSON.stringify), which keeps array length stable across serializers.
+    const items = value.map((el) => (el === undefined ? 'null' : canonicalize(el)));
+    return '[' + items.join(',') + ']';
+  }
+
+  // Plain object: sort keys, omit undefined-valued properties (as JSON.stringify
+  // does), recurse on values.
+  const obj = value as Record<string, unknown>;
+  const parts: string[] = [];
+  for (const key of Object.keys(obj).sort()) {
+    const v = obj[key];
+    if (v === undefined) continue;
+    parts.push(JSON.stringify(key) + ':' + canonicalize(v));
+  }
+  return '{' + parts.join(',') + '}';
+}

package/src/content-binding.ts

@@ -0,0 +1,83 @@
+/**
+ * Content binding — Level 2 content proof (HAP v0.5 Content Provenance).
+ *
+ * A receipt normally proves who/why/bounds/when but NOT the action's content.
+ * Content binding closes that gap: the gateway computes a `content_hash` over
+ * the action's content per the profile's {@link ContentBinding} and hands the
+ * SP only the hash. The SP signs it into the receipt verbatim — it never sees
+ * the content, so HAP's privacy-minimal design is preserved. Anyone holding
+ * the content can recompute the hash and check it against the signed receipt.
+ *
+ * The hash only verifies if the verifier reproduces the EXACT bytes we hashed,
+ * so canonicalization is normative and versioned (pin via `ContentBinding.version`):
+ *
+ *  - kind:"jcs"  → RFC 8785 JCS of the record payload (see {@link canonicalize}).
+ *  - kind:"text" → UTF-8 of the string after {@link canonicalizeText}
+ *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
+ *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
+ *
+ * Both Node and the browser produce byte-identical output: JCS relies only on
+ * environment-independent primitives, and the text rule uses String.normalize +
+ * plain string ops. The SHA-256 is computed with Node `crypto` here (the same
+ * pattern as frame.ts); browser callers that need to recompute use their own
+ * SubtleCrypto digest over the identical canonical bytes.
+ */
+
+import { createHash } from 'crypto';
+import { canonicalize } from './canonicalize';
+import type { ContentBinding } from './types';
+
+/**
+ * Canonicalize free text per the v0.5 'text' rule. Idempotent.
+ *
+ *   1. Unicode NFC normalization.
+ *   2. CRLF / CR → LF.
+ *   3. Strip trailing spaces/tabs from every line.
+ *   4. Remove trailing blank lines.
+ */
+export function canonicalizeText(input: string): string {
+  const nfc = input.normalize('NFC');
+  const lf = nfc.replace(/\r\n?/g, '\n');
+  const lines = lf.split('\n').map((line) => line.replace(/[ \t]+$/, ''));
+  return lines.join('\n').replace(/\n+$/, '');
+}
+
+/** sha256 of a UTF-8 string → 64 hex chars. */
+function sha256Hex(bytes: string): string {
+  return createHash('sha256').update(bytes, 'utf8').digest('hex');
+}
+
+/**
+ * Compute the canonical bytes that a content hash is taken over, WITHOUT
+ * hashing — exposed so verifiers can debug a mismatch by inspecting the exact
+ * serialization both sides should agree on.
+ */
+export function contentCanonicalBytes(
+  kind: ContentBinding['kind'],
+  content: Record<string, unknown> | string,
+): string {
+  if (kind === 'jcs') {
+    if (typeof content === 'string') {
+      throw new Error('content_binding kind="jcs" expects a record payload (object), got a string');
+    }
+    return canonicalize(content);
+  }
+  if (typeof content !== 'string') {
+    throw new Error('content_binding kind="text" expects a string, got an object');
+  }
+  return canonicalizeText(content);
+}
+
+/**
+ * Compute a profile-bound content hash, formatted `sha256:<hex>` (matching the
+ * frame/bounds/context hash format used elsewhere in HAP).
+ *
+ * @param binding the profile's content_binding declaration
+ * @param content the record payload (jcs) or the resolved text field (text)
+ */
+export function computeContentHash(
+  binding: ContentBinding,
+  content: Record<string, unknown> | string,
+): string {
+  return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
+}

package/src/index.ts

@@ -5,6 +5,8 @@
  */
 
 export * from './types';
+export * from './canonicalize';
+export * from './content-binding';
 export * from './frame';
 export * from './attestation';
 export * from './gatekeeper';

package/src/types.ts

@@ -166,6 +166,33 @@ export interface ProfileBoundsField {
   enum?: string[];
 }
 
+/**
+ * v0.5 Content Provenance — how a profile's action content is hashed into a
+ * signed receipt (`contentHash`). The ephemeral-content analog of Output
+ * Provenance: it binds the *bytes* of the action rather than a location.
+ *
+ * Profile-bound and OPTIONAL. Absent → no content hash is produced (full
+ * backward compatibility). The gateway computes the hash; the SP only ever
+ * receives the hash, never the content, so HAP's privacy-minimal design holds.
+ *
+ * The profile declares only the *policy* — whether to bind and how to
+ * canonicalize. It does NOT name the tool field: that is tool-specific and is
+ * resolved at runtime (the same content-field resolver the footer uses for
+ * `kind:"text"`; the whole record payload for `kind:"jcs"`).
+ */
+export interface ContentBinding {
+  /** Canonicalization version. A verifier MUST pin the version named here. */
+  version: string;
+  /**
+   * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload.
+   * - 'text' → free text: NFC + LF + trailing-whitespace strip (see
+   *   canonicalizeText), auto-detected content field.
+   */
+  kind: 'jcs' | 'text';
+  /** text only: hash the content BEFORE any appended Suveren footer. */
+  pre_footer?: boolean;
+}
+
 /**
  * Context field definition within a v0.4 profile.
  */
@@ -295,6 +322,14 @@ export interface AgentProfile {
   ttl: { default: number; max: number };
   retention_minimum: number;
 
+  /**
+   * v0.5 Content Provenance (OPTIONAL, profile-bound). When present, the
+   * gateway computes a `contentHash` for gated writes under this profile and
+   * passes it (hash only) to the SP, which signs it into the receipt. Absent
+   * → no content hash. See {@link ContentBinding}.
+   */
+  content_binding?: ContentBinding;
+
   /**
    * Tool gating configuration — how MCP tools map to execution context.
    * @deprecated Tool gating now lives in integration manifests (content/integrations/*.json).