@humanagencyp/hap-core 0.8.0 → 0.8.1

package/dist/index.d.mts

@@ -267,22 +267,63 @@ interface ProfileBoundsField {
  * 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"`).
+ * At `version:"1"` 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"`).
+ *
+ * At `version:"2"` the profile additionally declares WHICH fields are bound (see
+ * {@link ContentBinding.fields}). Neither v1 mode is the general case: `text`
+ * binds one field and leaves everything beside it unbound, while `jcs` over the
+ * whole payload is checkable only by a party that already knows the whole
+ * payload — an email recipient holds the body, the subject and their own
+ * address, but not `bcc`. The general case is a declared subset, chosen so the
+ * intended verifier can reproduce it.
  */
 interface ContentBinding {
     /** Canonicalization version. A verifier MUST pin the version named here. */
     version: string;
     /**
-     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload.
+     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload
+     *   (v1) or over the object built from {@link fields} (v2).
      * - '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;
+    /**
+     * v2 only — the tool-argument keys this binding covers, and the complete
+     * statement of what a verifier must reproduce. The Gatekeeper builds an
+     * object from exactly these keys and canonicalizes it by `kind`.
+     *
+     * Adding or removing an entry changes every resulting hash, so it is a
+     * BREAKING profile change requiring a version bump, never a silent edit.
+     *
+     * Choose the subset by one rule: bind everything the approving human is
+     * shown, and nothing the intended verifier cannot see.
+     */
+    fields?: string[];
+    /**
+     * v2 only — the subset of {@link fields} whose absence is a fault rather than
+     * a fact. An absent OPTIONAL field is omitted from the hashed object (an
+     * email legitimately has no `cc`); an absent REQUIRED field means the call is
+     * not the call this profile thinks it is, and MUST refuse rather than hash a
+     * partial object that reads exactly like a complete one.
+     *
+     * MUST be a subset of `fields`. Absent → every field is optional, and only a
+     * wholly empty selection refuses.
+     */
+    required_fields?: string[];
+    /**
+     * v2 only — the action types this binding covers, using the same vocabulary
+     * as {@link ProfileBoundsField.appliesTo}. A profile gates more than its
+     * content-bearing calls: `email` also gates deletes, which carry an id and no
+     * content, and applying a field binding to those would refuse them.
+     *
+     * Absent → the binding applies to every gated action under the profile.
+     */
+    appliesTo?: string[];
 }
 /**
  * Context field definition within a v0.4 profile.
@@ -596,6 +637,12 @@ declare function canonicalize(value: unknown): string;
  *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
  *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
  *
+ * At `version:"2"` the profile also declares WHICH tool arguments are bound
+ * ({@link selectBoundFields}), so a receipt can commit to an email's recipients
+ * and not only its prose — while still omitting what the intended verifier
+ * cannot see. Every string entering the hashed object is canonicalized by the
+ * same `text` rule, so a delivered copy with CRLF endings still reproduces it.
+ *
  * 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
@@ -626,6 +673,56 @@ declare function contentCanonicalBytes(kind: ContentBinding['kind'], content: Re
  * @param content the record payload (jcs) or the resolved text field (text)
  */
 declare function computeContentHash(binding: ContentBinding, content: Record<string, unknown> | string): string;
+/** Why a field binding refused. Every case is fail-closed by design. */
+type ContentBindingErrorCode = 
+/** The profile declares version:"2" with no usable `fields` list. */
+'NO_FIELDS_DECLARED'
+/** `required_fields` names something absent from `fields`. */
+ | 'REQUIRED_FIELD_NOT_DECLARED'
+/** A required field was absent or empty at call time. */
+ | 'MISSING_REQUIRED_FIELD'
+/** No declared field carried a value — the hash would commit to nothing. */
+ | 'EMPTY_BINDING';
+/**
+ * A field binding could not be computed. ALWAYS a refusal, never a downgrade:
+ * the alternative is a receipt that verifies while proving less than it appears
+ * to, which is the failure content binding exists to prevent.
+ */
+declare class ContentBindingError extends Error {
+    readonly code: ContentBindingErrorCode;
+    /** The offending field, when the code names one. */
+    readonly field?: string;
+    constructor(code: ContentBindingErrorCode, message: string, field?: string);
+}
+/** True when this binding selects a declared subset (v2) rather than v1's implicit scope. */
+declare function isFieldBinding(binding: ContentBinding): boolean;
+/**
+ * Whether a field binding covers this action type, per the profile's `appliesTo`.
+ *
+ * Read STRICTLY — an undeclared action type is NOT covered. This differs from
+ * how bounds read the same key (there, an unknown action type enforces the
+ * bound, because an extra limit is safe). Here the two directions are not
+ * symmetric: applying a field binding to a call that carries no content refuses
+ * a legitimate action, so an unknown action type must fall outside rather than
+ * inside. Callers are expected to warn on the undeclared case — it is a
+ * manifest bug either way.
+ */
+declare function bindingAppliesTo(binding: ContentBinding, actionType: string | undefined): boolean;
+/**
+ * Build the object a v2 binding hashes: exactly the declared `fields` that
+ * carry a value, canonicalized. Exported so a verifier can construct the same
+ * object from what they hold and see it before hashing.
+ *
+ * Throws {@link ContentBindingError} rather than returning a partial result —
+ * see that class for why refusing is the only safe outcome.
+ */
+declare function selectBoundFields(binding: ContentBinding, args: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Compute a v2 field-binding hash from raw tool arguments: select the declared
+ * subset, then hash it by the declared `kind`. Convenience over
+ * {@link selectBoundFields} + {@link computeContentHash} for the common path.
+ */
+declare function computeFieldsContentHash(binding: ContentBinding, args: Record<string, unknown>): string;
 
 /**
  * Intent hashing + intent-disclosure binding (HAP v0.5).
@@ -917,4 +1014,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 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, type Subject, type SubjectValidation, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, 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, ContentBindingError, type ContentBindingErrorCode, 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, type Subject, type SubjectValidation, attestationId, bindingAppliesTo, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isV4Attestation, listProfiles, registerProfile, selectBoundFields, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.d.ts

@@ -267,22 +267,63 @@ interface ProfileBoundsField {
  * 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"`).
+ * At `version:"1"` 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"`).
+ *
+ * At `version:"2"` the profile additionally declares WHICH fields are bound (see
+ * {@link ContentBinding.fields}). Neither v1 mode is the general case: `text`
+ * binds one field and leaves everything beside it unbound, while `jcs` over the
+ * whole payload is checkable only by a party that already knows the whole
+ * payload — an email recipient holds the body, the subject and their own
+ * address, but not `bcc`. The general case is a declared subset, chosen so the
+ * intended verifier can reproduce it.
  */
 interface ContentBinding {
     /** Canonicalization version. A verifier MUST pin the version named here. */
     version: string;
     /**
-     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload.
+     * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload
+     *   (v1) or over the object built from {@link fields} (v2).
      * - '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;
+    /**
+     * v2 only — the tool-argument keys this binding covers, and the complete
+     * statement of what a verifier must reproduce. The Gatekeeper builds an
+     * object from exactly these keys and canonicalizes it by `kind`.
+     *
+     * Adding or removing an entry changes every resulting hash, so it is a
+     * BREAKING profile change requiring a version bump, never a silent edit.
+     *
+     * Choose the subset by one rule: bind everything the approving human is
+     * shown, and nothing the intended verifier cannot see.
+     */
+    fields?: string[];
+    /**
+     * v2 only — the subset of {@link fields} whose absence is a fault rather than
+     * a fact. An absent OPTIONAL field is omitted from the hashed object (an
+     * email legitimately has no `cc`); an absent REQUIRED field means the call is
+     * not the call this profile thinks it is, and MUST refuse rather than hash a
+     * partial object that reads exactly like a complete one.
+     *
+     * MUST be a subset of `fields`. Absent → every field is optional, and only a
+     * wholly empty selection refuses.
+     */
+    required_fields?: string[];
+    /**
+     * v2 only — the action types this binding covers, using the same vocabulary
+     * as {@link ProfileBoundsField.appliesTo}. A profile gates more than its
+     * content-bearing calls: `email` also gates deletes, which carry an id and no
+     * content, and applying a field binding to those would refuse them.
+     *
+     * Absent → the binding applies to every gated action under the profile.
+     */
+    appliesTo?: string[];
 }
 /**
  * Context field definition within a v0.4 profile.
@@ -596,6 +637,12 @@ declare function canonicalize(value: unknown): string;
  *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
  *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
  *
+ * At `version:"2"` the profile also declares WHICH tool arguments are bound
+ * ({@link selectBoundFields}), so a receipt can commit to an email's recipients
+ * and not only its prose — while still omitting what the intended verifier
+ * cannot see. Every string entering the hashed object is canonicalized by the
+ * same `text` rule, so a delivered copy with CRLF endings still reproduces it.
+ *
  * 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
@@ -626,6 +673,56 @@ declare function contentCanonicalBytes(kind: ContentBinding['kind'], content: Re
  * @param content the record payload (jcs) or the resolved text field (text)
  */
 declare function computeContentHash(binding: ContentBinding, content: Record<string, unknown> | string): string;
+/** Why a field binding refused. Every case is fail-closed by design. */
+type ContentBindingErrorCode = 
+/** The profile declares version:"2" with no usable `fields` list. */
+'NO_FIELDS_DECLARED'
+/** `required_fields` names something absent from `fields`. */
+ | 'REQUIRED_FIELD_NOT_DECLARED'
+/** A required field was absent or empty at call time. */
+ | 'MISSING_REQUIRED_FIELD'
+/** No declared field carried a value — the hash would commit to nothing. */
+ | 'EMPTY_BINDING';
+/**
+ * A field binding could not be computed. ALWAYS a refusal, never a downgrade:
+ * the alternative is a receipt that verifies while proving less than it appears
+ * to, which is the failure content binding exists to prevent.
+ */
+declare class ContentBindingError extends Error {
+    readonly code: ContentBindingErrorCode;
+    /** The offending field, when the code names one. */
+    readonly field?: string;
+    constructor(code: ContentBindingErrorCode, message: string, field?: string);
+}
+/** True when this binding selects a declared subset (v2) rather than v1's implicit scope. */
+declare function isFieldBinding(binding: ContentBinding): boolean;
+/**
+ * Whether a field binding covers this action type, per the profile's `appliesTo`.
+ *
+ * Read STRICTLY — an undeclared action type is NOT covered. This differs from
+ * how bounds read the same key (there, an unknown action type enforces the
+ * bound, because an extra limit is safe). Here the two directions are not
+ * symmetric: applying a field binding to a call that carries no content refuses
+ * a legitimate action, so an unknown action type must fall outside rather than
+ * inside. Callers are expected to warn on the undeclared case — it is a
+ * manifest bug either way.
+ */
+declare function bindingAppliesTo(binding: ContentBinding, actionType: string | undefined): boolean;
+/**
+ * Build the object a v2 binding hashes: exactly the declared `fields` that
+ * carry a value, canonicalized. Exported so a verifier can construct the same
+ * object from what they hold and see it before hashing.
+ *
+ * Throws {@link ContentBindingError} rather than returning a partial result —
+ * see that class for why refusing is the only safe outcome.
+ */
+declare function selectBoundFields(binding: ContentBinding, args: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Compute a v2 field-binding hash from raw tool arguments: select the declared
+ * subset, then hash it by the declared `kind`. Convenience over
+ * {@link selectBoundFields} + {@link computeContentHash} for the common path.
+ */
+declare function computeFieldsContentHash(binding: ContentBinding, args: Record<string, unknown>): string;
 
 /**
  * Intent hashing + intent-disclosure binding (HAP v0.5).
@@ -917,4 +1014,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 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, type Subject, type SubjectValidation, attestationId, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isV4Attestation, listProfiles, registerProfile, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, 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, ContentBindingError, type ContentBindingErrorCode, 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, type Subject, type SubjectValidation, attestationId, bindingAppliesTo, canonicalBounds, canonicalContext, canonicalFrame, canonicalize, canonicalizeText, checkAttestationExpiry, clearProfiles, computeBoundsHash, computeContentHash, computeContextHash, computeFieldsContentHash, computeFrameHash, computeIntentDisclosureHash, computeIntentHash, contentCanonicalBytes, decodeAttestationBlob, deriveIdentityLine, encodeAttestationBlob, frameHash, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isFieldBinding, isV4Attestation, listProfiles, registerProfile, selectBoundFields, validateBoundsParams, validateContextParams, validateFrameParams, validateSubject, verify, verifyAttestation, verifyAttestationSignature, verifyAttestationV4, verifyBoundsHash, verifyContextHash, verifyFrameHash };

package/dist/index.js

@@ -30,7 +30,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ContentBindingError: () => ContentBindingError,
   attestationId: () => attestationId,
+  bindingAppliesTo: () => bindingAppliesTo,
   canonicalBounds: () => canonicalBounds,
   canonicalContext: () => canonicalContext,
   canonicalFrame: () => canonicalFrame,
@@ -41,6 +43,7 @@ __export(index_exports, {
   computeBoundsHash: () => computeBoundsHash,
   computeContentHash: () => computeContentHash,
   computeContextHash: () => computeContextHash,
+  computeFieldsContentHash: () => computeFieldsContentHash,
   computeFrameHash: () => computeFrameHash,
   computeIntentDisclosureHash: () => computeIntentDisclosureHash,
   computeIntentHash: () => computeIntentHash,
@@ -52,9 +55,11 @@ __export(index_exports, {
   getAllProfiles: () => getAllProfiles,
   getProfile: () => getProfile,
   intentDisclosureCanonicalBytes: () => intentDisclosureCanonicalBytes,
+  isFieldBinding: () => isFieldBinding,
   isV4Attestation: () => isV4Attestation,
   listProfiles: () => listProfiles,
   registerProfile: () => registerProfile,
+  selectBoundFields: () => selectBoundFields,
   validateBoundsParams: () => validateBoundsParams,
   validateContextParams: () => validateContextParams,
   validateFrameParams: () => validateFrameParams,
@@ -120,6 +125,89 @@ function contentCanonicalBytes(kind, content) {
 function computeContentHash(binding, content) {
   return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
 }
+var ContentBindingError = class extends Error {
+  code;
+  /** The offending field, when the code names one. */
+  field;
+  constructor(code, message, field) {
+    super(message);
+    this.name = "ContentBindingError";
+    this.code = code;
+    this.field = field;
+  }
+};
+function isFieldBinding(binding) {
+  return binding.version === "2" && Array.isArray(binding.fields) && binding.fields.length > 0;
+}
+function bindingAppliesTo(binding, actionType) {
+  if (!binding.appliesTo) return true;
+  return actionType !== void 0 && binding.appliesTo.includes(actionType);
+}
+function canonicalizeValue(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value === "string") {
+    const text = canonicalizeText(value);
+    return text === "" ? void 0 : text;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    const items = value.map(canonicalizeValue).filter((v) => v !== void 0);
+    return items.length > 0 ? items : void 0;
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      const c = canonicalizeValue(v);
+      if (c !== void 0) out[key] = c;
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  return void 0;
+}
+function selectBoundFields(binding, args) {
+  const fields = binding.fields;
+  if (!fields || fields.length === 0) {
+    throw new ContentBindingError(
+      "NO_FIELDS_DECLARED",
+      'content_binding version "2" requires a non-empty `fields` list.'
+    );
+  }
+  const required = new Set(binding.required_fields ?? []);
+  for (const field of required) {
+    if (!fields.includes(field)) {
+      throw new ContentBindingError(
+        "REQUIRED_FIELD_NOT_DECLARED",
+        `content_binding requires "${field}" but does not bind it \u2014 required_fields must be a subset of fields.`,
+        field
+      );
+    }
+  }
+  const bound = {};
+  for (const field of fields) {
+    const value = canonicalizeValue(args[field]);
+    if (value === void 0) {
+      if (required.has(field)) {
+        throw new ContentBindingError(
+          "MISSING_REQUIRED_FIELD",
+          `content_binding requires "${field}", which is absent or empty in this call. Refusing rather than hashing a partial object.`,
+          field
+        );
+      }
+      continue;
+    }
+    bound[field] = value;
+  }
+  if (Object.keys(bound).length === 0) {
+    throw new ContentBindingError(
+      "EMPTY_BINDING",
+      `No declared field (${fields.join(", ")}) carried a value \u2014 the hash would commit to nothing.`
+    );
+  }
+  return bound;
+}
+function computeFieldsContentHash(binding, args) {
+  return computeContentHash(binding, selectBoundFields(binding, args));
+}
 
 // src/intent-disclosure.ts
 var import_crypto2 = require("crypto");
@@ -859,7 +947,9 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ContentBindingError,
   attestationId,
+  bindingAppliesTo,
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
@@ -870,6 +960,7 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   computeBoundsHash,
   computeContentHash,
   computeContextHash,
+  computeFieldsContentHash,
   computeFrameHash,
   computeIntentDisclosureHash,
   computeIntentHash,
@@ -881,9 +972,11 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isFieldBinding,
   isV4Attestation,
   listProfiles,
   registerProfile,
+  selectBoundFields,
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,

package/dist/index.mjs

@@ -49,6 +49,89 @@ function contentCanonicalBytes(kind, content) {
 function computeContentHash(binding, content) {
   return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
 }
+var ContentBindingError = class extends Error {
+  code;
+  /** The offending field, when the code names one. */
+  field;
+  constructor(code, message, field) {
+    super(message);
+    this.name = "ContentBindingError";
+    this.code = code;
+    this.field = field;
+  }
+};
+function isFieldBinding(binding) {
+  return binding.version === "2" && Array.isArray(binding.fields) && binding.fields.length > 0;
+}
+function bindingAppliesTo(binding, actionType) {
+  if (!binding.appliesTo) return true;
+  return actionType !== void 0 && binding.appliesTo.includes(actionType);
+}
+function canonicalizeValue(value) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value === "string") {
+    const text = canonicalizeText(value);
+    return text === "" ? void 0 : text;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) {
+    const items = value.map(canonicalizeValue).filter((v) => v !== void 0);
+    return items.length > 0 ? items : void 0;
+  }
+  if (typeof value === "object") {
+    const out = {};
+    for (const [key, v] of Object.entries(value)) {
+      const c = canonicalizeValue(v);
+      if (c !== void 0) out[key] = c;
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  return void 0;
+}
+function selectBoundFields(binding, args) {
+  const fields = binding.fields;
+  if (!fields || fields.length === 0) {
+    throw new ContentBindingError(
+      "NO_FIELDS_DECLARED",
+      'content_binding version "2" requires a non-empty `fields` list.'
+    );
+  }
+  const required = new Set(binding.required_fields ?? []);
+  for (const field of required) {
+    if (!fields.includes(field)) {
+      throw new ContentBindingError(
+        "REQUIRED_FIELD_NOT_DECLARED",
+        `content_binding requires "${field}" but does not bind it \u2014 required_fields must be a subset of fields.`,
+        field
+      );
+    }
+  }
+  const bound = {};
+  for (const field of fields) {
+    const value = canonicalizeValue(args[field]);
+    if (value === void 0) {
+      if (required.has(field)) {
+        throw new ContentBindingError(
+          "MISSING_REQUIRED_FIELD",
+          `content_binding requires "${field}", which is absent or empty in this call. Refusing rather than hashing a partial object.`,
+          field
+        );
+      }
+      continue;
+    }
+    bound[field] = value;
+  }
+  if (Object.keys(bound).length === 0) {
+    throw new ContentBindingError(
+      "EMPTY_BINDING",
+      `No declared field (${fields.join(", ")}) carried a value \u2014 the hash would commit to nothing.`
+    );
+  }
+  return bound;
+}
+function computeFieldsContentHash(binding, args) {
+  return computeContentHash(binding, selectBoundFields(binding, args));
+}
 
 // src/intent-disclosure.ts
 import { createHash as createHash2 } from "crypto";
@@ -787,7 +870,9 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   return errors;
 }
 export {
+  ContentBindingError,
   attestationId,
+  bindingAppliesTo,
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
@@ -798,6 +883,7 @@ export {
   computeBoundsHash,
   computeContentHash,
   computeContextHash,
+  computeFieldsContentHash,
   computeFrameHash,
   computeIntentDisclosureHash,
   computeIntentHash,
@@ -809,9 +895,11 @@ export {
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  isFieldBinding,
   isV4Attestation,
   listProfiles,
   registerProfile,
+  selectBoundFields,
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {

package/src/content-binding.ts

@@ -16,6 +16,12 @@
  *    (Unicode NFC, LF line endings, trailing per-line whitespace stripped,
  *    trailing blank lines removed), taken pre-footer when `pre_footer` is set.
  *
+ * At `version:"2"` the profile also declares WHICH tool arguments are bound
+ * ({@link selectBoundFields}), so a receipt can commit to an email's recipients
+ * and not only its prose — while still omitting what the intended verifier
+ * cannot see. Every string entering the hashed object is canonicalized by the
+ * same `text` rule, so a delivered copy with CRLF endings still reproduces it.
+ *
  * 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
@@ -81,3 +87,165 @@ export function computeContentHash(
 ): string {
   return `sha256:${sha256Hex(contentCanonicalBytes(binding.kind, content))}`;
 }
+
+// ─── v2: binding over a declared field subset ────────────────────────────────
+
+/** Why a field binding refused. Every case is fail-closed by design. */
+export type ContentBindingErrorCode =
+  /** The profile declares version:"2" with no usable `fields` list. */
+  | 'NO_FIELDS_DECLARED'
+  /** `required_fields` names something absent from `fields`. */
+  | 'REQUIRED_FIELD_NOT_DECLARED'
+  /** A required field was absent or empty at call time. */
+  | 'MISSING_REQUIRED_FIELD'
+  /** No declared field carried a value — the hash would commit to nothing. */
+  | 'EMPTY_BINDING';
+
+/**
+ * A field binding could not be computed. ALWAYS a refusal, never a downgrade:
+ * the alternative is a receipt that verifies while proving less than it appears
+ * to, which is the failure content binding exists to prevent.
+ */
+export class ContentBindingError extends Error {
+  readonly code: ContentBindingErrorCode;
+  /** The offending field, when the code names one. */
+  readonly field?: string;
+
+  constructor(code: ContentBindingErrorCode, message: string, field?: string) {
+    super(message);
+    this.name = 'ContentBindingError';
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/** True when this binding selects a declared subset (v2) rather than v1's implicit scope. */
+export function isFieldBinding(binding: ContentBinding): boolean {
+  return binding.version === '2' && Array.isArray(binding.fields) && binding.fields.length > 0;
+}
+
+/**
+ * Whether a field binding covers this action type, per the profile's `appliesTo`.
+ *
+ * Read STRICTLY — an undeclared action type is NOT covered. This differs from
+ * how bounds read the same key (there, an unknown action type enforces the
+ * bound, because an extra limit is safe). Here the two directions are not
+ * symmetric: applying a field binding to a call that carries no content refuses
+ * a legitimate action, so an unknown action type must fall outside rather than
+ * inside. Callers are expected to warn on the undeclared case — it is a
+ * manifest bug either way.
+ */
+export function bindingAppliesTo(
+  binding: ContentBinding,
+  actionType: string | undefined,
+): boolean {
+  if (!binding.appliesTo) return true;
+  return actionType !== undefined && binding.appliesTo.includes(actionType);
+}
+
+/**
+ * Canonicalize one value on its way into the bound object, or `undefined` when
+ * it carries nothing (absent / null / empty after canonicalization).
+ *
+ * Strings are run through {@link canonicalizeText} — the SAME rule `kind:"text"`
+ * uses, applied per string rather than to one field. This is not decoration:
+ * the verifier of an email holds the DELIVERED copy, whose body has CRLF line
+ * endings and transport-added trailing whitespace. JCS embeds strings verbatim,
+ * so without this the recipient could never reproduce the hash.
+ *
+ * Deliberately NOT normalized: array order (the To: header preserves what was
+ * sent, and reordering recipients is a change worth catching) and address case
+ * (the local part is case-sensitive per RFC 5321, so lowercasing would be a
+ * semantic claim this layer has no business making).
+ */
+function canonicalizeValue(value: unknown): unknown {
+  if (value === null || value === undefined) return undefined;
+  if (typeof value === 'string') {
+    const text = canonicalizeText(value);
+    return text === '' ? undefined : text;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) {
+    const items = value.map(canonicalizeValue).filter((v) => v !== undefined);
+    return items.length > 0 ? items : undefined;
+  }
+  if (typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      const c = canonicalizeValue(v);
+      if (c !== undefined) out[key] = c;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+  }
+  return undefined; // functions/symbols — not JSON, nothing to bind
+}
+
+/**
+ * Build the object a v2 binding hashes: exactly the declared `fields` that
+ * carry a value, canonicalized. Exported so a verifier can construct the same
+ * object from what they hold and see it before hashing.
+ *
+ * Throws {@link ContentBindingError} rather than returning a partial result —
+ * see that class for why refusing is the only safe outcome.
+ */
+export function selectBoundFields(
+  binding: ContentBinding,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const fields = binding.fields;
+  if (!fields || fields.length === 0) {
+    throw new ContentBindingError(
+      'NO_FIELDS_DECLARED',
+      'content_binding version "2" requires a non-empty `fields` list.',
+    );
+  }
+
+  const required = new Set(binding.required_fields ?? []);
+  for (const field of required) {
+    if (!fields.includes(field)) {
+      throw new ContentBindingError(
+        'REQUIRED_FIELD_NOT_DECLARED',
+        `content_binding requires "${field}" but does not bind it — required_fields must be a subset of fields.`,
+        field,
+      );
+    }
+  }
+
+  const bound: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = canonicalizeValue(args[field]);
+    if (value === undefined) {
+      if (required.has(field)) {
+        throw new ContentBindingError(
+          'MISSING_REQUIRED_FIELD',
+          `content_binding requires "${field}", which is absent or empty in this call. ` +
+            `Refusing rather than hashing a partial object.`,
+          field,
+        );
+      }
+      continue; // legitimately absent (an email with no cc)
+    }
+    bound[field] = value;
+  }
+
+  if (Object.keys(bound).length === 0) {
+    throw new ContentBindingError(
+      'EMPTY_BINDING',
+      `No declared field (${fields.join(', ')}) carried a value — the hash would commit to nothing.`,
+    );
+  }
+
+  return bound;
+}
+
+/**
+ * Compute a v2 field-binding hash from raw tool arguments: select the declared
+ * subset, then hash it by the declared `kind`. Convenience over
+ * {@link selectBoundFields} + {@link computeContentHash} for the common path.
+ */
+export function computeFieldsContentHash(
+  binding: ContentBinding,
+  args: Record<string, unknown>,
+): string {
+  return computeContentHash(binding, selectBoundFields(binding, args));
+}

package/src/types.ts

@@ -271,22 +271,64 @@ export interface ProfileBoundsField {
  * 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"`).
+ * At `version:"1"` 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"`).
+ *
+ * At `version:"2"` the profile additionally declares WHICH fields are bound (see
+ * {@link ContentBinding.fields}). Neither v1 mode is the general case: `text`
+ * binds one field and leaves everything beside it unbound, while `jcs` over the
+ * whole payload is checkable only by a party that already knows the whole
+ * payload — an email recipient holds the body, the subject and their own
+ * address, but not `bcc`. The general case is a declared subset, chosen so the
+ * intended verifier can reproduce it.
  */
 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.
+   * - 'jcs'  → structured writes: RFC 8785 JCS over the record payload
+   *   (v1) or over the object built from {@link fields} (v2).
    * - '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;
+
+  /**
+   * v2 only — the tool-argument keys this binding covers, and the complete
+   * statement of what a verifier must reproduce. The Gatekeeper builds an
+   * object from exactly these keys and canonicalizes it by `kind`.
+   *
+   * Adding or removing an entry changes every resulting hash, so it is a
+   * BREAKING profile change requiring a version bump, never a silent edit.
+   *
+   * Choose the subset by one rule: bind everything the approving human is
+   * shown, and nothing the intended verifier cannot see.
+   */
+  fields?: string[];
+  /**
+   * v2 only — the subset of {@link fields} whose absence is a fault rather than
+   * a fact. An absent OPTIONAL field is omitted from the hashed object (an
+   * email legitimately has no `cc`); an absent REQUIRED field means the call is
+   * not the call this profile thinks it is, and MUST refuse rather than hash a
+   * partial object that reads exactly like a complete one.
+   *
+   * MUST be a subset of `fields`. Absent → every field is optional, and only a
+   * wholly empty selection refuses.
+   */
+  required_fields?: string[];
+  /**
+   * v2 only — the action types this binding covers, using the same vocabulary
+   * as {@link ProfileBoundsField.appliesTo}. A profile gates more than its
+   * content-bearing calls: `email` also gates deletes, which carry an id and no
+   * content, and applying a field binding to those would refuse them.
+   *
+   * Absent → the binding applies to every gated action under the profile.
+   */
+  appliesTo?: string[];
 }
 
 /**