@humanagencyp/hap-core 0.12.0 → 0.12.1

package/dist/index.d.mts

@@ -384,7 +384,23 @@ interface ContentBinding {
      * Absent → the binding applies to every gated action under the profile.
      */
     appliesTo?: string[];
+    /**
+     * v2 only — what kind of value each bound field holds, so a verifier (or any
+     * view) can collect and show it without guessing from the field's name:
+     * - `text`  — one string (an email body);
+     * - `list`  — an array of strings (recipients);
+     * - `files` — the sealed fingerprints of documents sent by reference:
+     *   `[{ filename, sha256 }]` — never the bytes. A verifier asks for the
+     *   files themselves and computes each SHA-256 locally.
+     *
+     * A hint only: it never changes what is hashed. Keys MUST be a subset of
+     * {@link fields}; a field without an entry is unspecified (a verifier may
+     * offer a choice, as before).
+     */
+    field_kinds?: Record<string, ContentFieldKind>;
 }
+/** See {@link ContentBinding.field_kinds}. */
+type ContentFieldKind = 'text' | 'list' | 'files';
 /**
  * Scope field definition within a profile (renamed from `ProfileContextField`
  * in v0.7 — protocol.md → *Migration from v0.6*, `contextSchema` → `scopeSchema`).
@@ -831,6 +847,14 @@ declare function selectBoundFields(binding: ContentBinding, args: Record<string,
  * {@link selectBoundFields} + {@link computeContentHash} for the common path.
  */
 declare function computeFieldsContentHash(binding: ContentBinding, args: Record<string, unknown>): string;
+/**
+ * Why a binding's `field_kinds` is malformed, or null when it is fine (or
+ * absent). For profile validation — a malformed hint is a profile error, not
+ * a call-time refusal, because it never changes what is hashed.
+ */
+declare function invalidFieldKindsReason(binding: ContentBinding): string | null;
+/** The bound fields declared as `files` — sealed document fingerprints. */
+declare function filesFields(binding: ContentBinding): string[];
 
 /**
  * Intent hashing + intent-disclosure binding (HAP v0.5).
@@ -1477,4 +1501,4 @@ declare function decodeDidKey(did: string): Uint8Array;
 /** True iff the DID decodes as a key-bearing Ed25519 did:key. Never throws. */
 declare function isKeyBearingDid(did: string): boolean;
 
-export { type AgentBoundsParams, type AgentProfile, type AgentScopeParams, type ApprovalObject, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type FieldConstraint, type FieldUnit, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, HapError, type HapErrorCode, MANDATE_ERROR_CODES, type Mandate, type MandateHeader, type MandateOwnerEntry, type MandatePayload, type MandateProjection, type OwnerSignatureBinding, OwnerSignatureError, PROTOCOL_VERSION, type ProfileBoundsField, type ProfileOwnerSignatureFloor, type ProfileScopeField, type ProfileValidationError, SIGNABLE_COMMITMENT_MODES, SUPPORTED_VERSIONS, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, TICKET_ERROR_CODES, type TicketPayload, type VerifyOptions, allowedCommitmentModes, approvalSigningBytes, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalScope, canonicalize, canonicalizeText, checkDiscloseSubset, checkMandateExpiry, checkOwnerSignatureRequirement, clearProfiles, computeBoundsHash, computeContentHash, computeFieldsContentHash, computeIntentDisclosureHash, computeIntentHash, computeProfileHash, computeScopeHash, contentCanonicalBytes, decodeDidKey, decodeMandateBlob, deriveIdentityLine, encodeDidKey, encodeMandateBlob, fromBase64Url, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, listProfiles, mandateBlobId, negotiateVersion, projectionSigningBytes, publicTicketView, registerProfile, selectBoundFields, signApproval, signMandate, signMandateProjection, signTicket, toBase64Url, validateBoundsParams, validateMandateOwners, validateProfile, validateScopeParams, validateSubject, verify, verifyApproval, verifyMandate, verifyMandateSignature, verifyOwnerSignature, verifyOwnerSignatures, verifyTicketSignature };
+export { type AgentBoundsParams, type AgentProfile, type AgentScopeParams, type ApprovalObject, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type ContentFieldKind, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type FieldConstraint, type FieldUnit, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, HapError, type HapErrorCode, MANDATE_ERROR_CODES, type Mandate, type MandateHeader, type MandateOwnerEntry, type MandatePayload, type MandateProjection, type OwnerSignatureBinding, OwnerSignatureError, PROTOCOL_VERSION, type ProfileBoundsField, type ProfileOwnerSignatureFloor, type ProfileScopeField, type ProfileValidationError, SIGNABLE_COMMITMENT_MODES, SUPPORTED_VERSIONS, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, TICKET_ERROR_CODES, type TicketPayload, type VerifyOptions, allowedCommitmentModes, approvalSigningBytes, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalScope, canonicalize, canonicalizeText, checkDiscloseSubset, checkMandateExpiry, checkOwnerSignatureRequirement, clearProfiles, computeBoundsHash, computeContentHash, computeFieldsContentHash, computeIntentDisclosureHash, computeIntentHash, computeProfileHash, computeScopeHash, contentCanonicalBytes, decodeDidKey, decodeMandateBlob, deriveIdentityLine, encodeDidKey, encodeMandateBlob, filesFields, fromBase64Url, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, invalidFieldKindsReason, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, listProfiles, mandateBlobId, negotiateVersion, projectionSigningBytes, publicTicketView, registerProfile, selectBoundFields, signApproval, signMandate, signMandateProjection, signTicket, toBase64Url, validateBoundsParams, validateMandateOwners, validateProfile, validateScopeParams, validateSubject, verify, verifyApproval, verifyMandate, verifyMandateSignature, verifyOwnerSignature, verifyOwnerSignatures, verifyTicketSignature };

package/dist/index.d.ts

@@ -384,7 +384,23 @@ interface ContentBinding {
      * Absent → the binding applies to every gated action under the profile.
      */
     appliesTo?: string[];
+    /**
+     * v2 only — what kind of value each bound field holds, so a verifier (or any
+     * view) can collect and show it without guessing from the field's name:
+     * - `text`  — one string (an email body);
+     * - `list`  — an array of strings (recipients);
+     * - `files` — the sealed fingerprints of documents sent by reference:
+     *   `[{ filename, sha256 }]` — never the bytes. A verifier asks for the
+     *   files themselves and computes each SHA-256 locally.
+     *
+     * A hint only: it never changes what is hashed. Keys MUST be a subset of
+     * {@link fields}; a field without an entry is unspecified (a verifier may
+     * offer a choice, as before).
+     */
+    field_kinds?: Record<string, ContentFieldKind>;
 }
+/** See {@link ContentBinding.field_kinds}. */
+type ContentFieldKind = 'text' | 'list' | 'files';
 /**
  * Scope field definition within a profile (renamed from `ProfileContextField`
  * in v0.7 — protocol.md → *Migration from v0.6*, `contextSchema` → `scopeSchema`).
@@ -831,6 +847,14 @@ declare function selectBoundFields(binding: ContentBinding, args: Record<string,
  * {@link selectBoundFields} + {@link computeContentHash} for the common path.
  */
 declare function computeFieldsContentHash(binding: ContentBinding, args: Record<string, unknown>): string;
+/**
+ * Why a binding's `field_kinds` is malformed, or null when it is fine (or
+ * absent). For profile validation — a malformed hint is a profile error, not
+ * a call-time refusal, because it never changes what is hashed.
+ */
+declare function invalidFieldKindsReason(binding: ContentBinding): string | null;
+/** The bound fields declared as `files` — sealed document fingerprints. */
+declare function filesFields(binding: ContentBinding): string[];
 
 /**
  * Intent hashing + intent-disclosure binding (HAP v0.5).
@@ -1477,4 +1501,4 @@ declare function decodeDidKey(did: string): Uint8Array;
 /** True iff the DID decodes as a key-bearing Ed25519 did:key. Never throws. */
 declare function isKeyBearingDid(did: string): boolean;
 
-export { type AgentBoundsParams, type AgentProfile, type AgentScopeParams, type ApprovalObject, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type FieldConstraint, type FieldUnit, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, HapError, type HapErrorCode, MANDATE_ERROR_CODES, type Mandate, type MandateHeader, type MandateOwnerEntry, type MandatePayload, type MandateProjection, type OwnerSignatureBinding, OwnerSignatureError, PROTOCOL_VERSION, type ProfileBoundsField, type ProfileOwnerSignatureFloor, type ProfileScopeField, type ProfileValidationError, SIGNABLE_COMMITMENT_MODES, SUPPORTED_VERSIONS, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, TICKET_ERROR_CODES, type TicketPayload, type VerifyOptions, allowedCommitmentModes, approvalSigningBytes, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalScope, canonicalize, canonicalizeText, checkDiscloseSubset, checkMandateExpiry, checkOwnerSignatureRequirement, clearProfiles, computeBoundsHash, computeContentHash, computeFieldsContentHash, computeIntentDisclosureHash, computeIntentHash, computeProfileHash, computeScopeHash, contentCanonicalBytes, decodeDidKey, decodeMandateBlob, deriveIdentityLine, encodeDidKey, encodeMandateBlob, fromBase64Url, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, listProfiles, mandateBlobId, negotiateVersion, projectionSigningBytes, publicTicketView, registerProfile, selectBoundFields, signApproval, signMandate, signMandateProjection, signTicket, toBase64Url, validateBoundsParams, validateMandateOwners, validateProfile, validateScopeParams, validateSubject, verify, verifyApproval, verifyMandate, verifyMandateSignature, verifyOwnerSignature, verifyOwnerSignatures, verifyTicketSignature };
+export { type AgentBoundsParams, type AgentProfile, type AgentScopeParams, type ApprovalObject, type BoundType, CanonicalValueError, type ContentBinding, ContentBindingError, type ContentBindingErrorCode, type ContentFieldKind, type CumulativeFieldDef, type CumulativeWindow, type DeclaredFieldDef, type ExecutionContextFieldDef, type ExecutionLogEntry, type ExecutionLogQuery, type FieldConstraint, type FieldUnit, type GatekeeperError, type GatekeeperRequest, type GatekeeperResult, HapError, type HapErrorCode, MANDATE_ERROR_CODES, type Mandate, type MandateHeader, type MandateOwnerEntry, type MandatePayload, type MandateProjection, type OwnerSignatureBinding, OwnerSignatureError, PROTOCOL_VERSION, type ProfileBoundsField, type ProfileOwnerSignatureFloor, type ProfileScopeField, type ProfileValidationError, SIGNABLE_COMMITMENT_MODES, SUPPORTED_VERSIONS, type SignableCommitmentMode, type SigningSurface, type Subject, type SubjectValidation, TICKET_ERROR_CODES, type TicketPayload, type VerifyOptions, allowedCommitmentModes, approvalSigningBytes, bindingAppliesTo, boundActionTypes, buildMandateProjection, canonicalBounds, canonicalScope, canonicalize, canonicalizeText, checkDiscloseSubset, checkMandateExpiry, checkOwnerSignatureRequirement, clearProfiles, computeBoundsHash, computeContentHash, computeFieldsContentHash, computeIntentDisclosureHash, computeIntentHash, computeProfileHash, computeScopeHash, contentCanonicalBytes, decodeDidKey, decodeMandateBlob, deriveIdentityLine, encodeDidKey, encodeMandateBlob, filesFields, fromBase64Url, getAllProfiles, getProfile, intentDisclosureCanonicalBytes, invalidFieldKindsReason, isCommitmentModeAllowed, isFieldBinding, isKeyBearingDid, listProfiles, mandateBlobId, negotiateVersion, projectionSigningBytes, publicTicketView, registerProfile, selectBoundFields, signApproval, signMandate, signMandateProjection, signTicket, toBase64Url, validateBoundsParams, validateMandateOwners, validateProfile, validateScopeParams, validateSubject, verify, verifyApproval, verifyMandate, verifyMandateSignature, verifyOwnerSignature, verifyOwnerSignatures, verifyTicketSignature };

package/dist/index.js

@@ -65,10 +65,12 @@ __export(index_exports, {
   deriveIdentityLine: () => deriveIdentityLine,
   encodeDidKey: () => encodeDidKey,
   encodeMandateBlob: () => encodeMandateBlob,
+  filesFields: () => filesFields,
   fromBase64Url: () => fromBase64Url,
   getAllProfiles: () => getAllProfiles,
   getProfile: () => getProfile,
   intentDisclosureCanonicalBytes: () => intentDisclosureCanonicalBytes,
+  invalidFieldKindsReason: () => invalidFieldKindsReason,
   isCommitmentModeAllowed: () => isCommitmentModeAllowed,
   isFieldBinding: () => isFieldBinding,
   isKeyBearingDid: () => isKeyBearingDid,
@@ -315,6 +317,20 @@ function selectBoundFields(binding, args) {
 function computeFieldsContentHash(binding, args) {
   return computeContentHash(binding, selectBoundFields(binding, args));
 }
+var FIELD_KINDS = /* @__PURE__ */ new Set(["text", "list", "files"]);
+function invalidFieldKindsReason(binding) {
+  const kinds = binding.field_kinds;
+  if (kinds === void 0) return null;
+  if (!kinds || typeof kinds !== "object" || Array.isArray(kinds)) return "field_kinds must be an object";
+  for (const [field, kind] of Object.entries(kinds)) {
+    if (!(binding.fields ?? []).includes(field)) return `field_kinds names "${field}", which is not in fields`;
+    if (!FIELD_KINDS.has(kind)) return `field_kinds.${field} must be one of text, list, files`;
+  }
+  return null;
+}
+function filesFields(binding) {
+  return Object.entries(binding.field_kinds ?? {}).filter(([, k]) => k === "files").map(([f]) => f);
+}
 
 // src/intent-disclosure.ts
 var import_crypto2 = require("crypto");
@@ -1359,10 +1375,12 @@ function checkScopeConstraints(scope, execution, profile) {
   deriveIdentityLine,
   encodeDidKey,
   encodeMandateBlob,
+  filesFields,
   fromBase64Url,
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  invalidFieldKindsReason,
   isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,

package/dist/index.mjs

@@ -214,6 +214,20 @@ function selectBoundFields(binding, args) {
 function computeFieldsContentHash(binding, args) {
   return computeContentHash(binding, selectBoundFields(binding, args));
 }
+var FIELD_KINDS = /* @__PURE__ */ new Set(["text", "list", "files"]);
+function invalidFieldKindsReason(binding) {
+  const kinds = binding.field_kinds;
+  if (kinds === void 0) return null;
+  if (!kinds || typeof kinds !== "object" || Array.isArray(kinds)) return "field_kinds must be an object";
+  for (const [field, kind] of Object.entries(kinds)) {
+    if (!(binding.fields ?? []).includes(field)) return `field_kinds names "${field}", which is not in fields`;
+    if (!FIELD_KINDS.has(kind)) return `field_kinds.${field} must be one of text, list, files`;
+  }
+  return null;
+}
+function filesFields(binding) {
+  return Object.entries(binding.field_kinds ?? {}).filter(([, k]) => k === "files").map(([f]) => f);
+}
 
 // src/intent-disclosure.ts
 import { createHash as createHash2 } from "crypto";
@@ -1257,10 +1271,12 @@ export {
   deriveIdentityLine,
   encodeDidKey,
   encodeMandateBlob,
+  filesFields,
   fromBase64Url,
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
+  invalidFieldKindsReason,
   isCommitmentModeAllowed,
   isFieldBinding,
   isKeyBearingDid,

package/package.json

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

package/src/content-binding.ts

@@ -31,7 +31,7 @@
 
 import { createHash } from 'crypto';
 import { canonicalize } from './canonicalize';
-import type { ContentBinding } from './types';
+import type { ContentBinding, ContentFieldKind } from './types';
 
 /**
  * Canonicalize free text per the v0.5 'text' rule. Idempotent.
@@ -249,3 +249,28 @@ export function computeFieldsContentHash(
 ): string {
   return computeContentHash(binding, selectBoundFields(binding, args));
 }
+
+// ─── Field kinds (display / verification hint) ───────────────────────────────
+
+const FIELD_KINDS = new Set<ContentFieldKind>(['text', 'list', 'files']);
+
+/**
+ * Why a binding's `field_kinds` is malformed, or null when it is fine (or
+ * absent). For profile validation — a malformed hint is a profile error, not
+ * a call-time refusal, because it never changes what is hashed.
+ */
+export function invalidFieldKindsReason(binding: ContentBinding): string | null {
+  const kinds = binding.field_kinds;
+  if (kinds === undefined) return null;
+  if (!kinds || typeof kinds !== 'object' || Array.isArray(kinds)) return 'field_kinds must be an object';
+  for (const [field, kind] of Object.entries(kinds)) {
+    if (!(binding.fields ?? []).includes(field)) return `field_kinds names "${field}", which is not in fields`;
+    if (!FIELD_KINDS.has(kind)) return `field_kinds.${field} must be one of text, list, files`;
+  }
+  return null;
+}
+
+/** The bound fields declared as `files` — sealed document fingerprints. */
+export function filesFields(binding: ContentBinding): string[] {
+  return Object.entries(binding.field_kinds ?? {}).filter(([, k]) => k === 'files').map(([f]) => f);
+}

package/src/types.ts

@@ -359,8 +359,25 @@ export interface ContentBinding {
    * Absent → the binding applies to every gated action under the profile.
    */
   appliesTo?: string[];
+  /**
+   * v2 only — what kind of value each bound field holds, so a verifier (or any
+   * view) can collect and show it without guessing from the field's name:
+   * - `text`  — one string (an email body);
+   * - `list`  — an array of strings (recipients);
+   * - `files` — the sealed fingerprints of documents sent by reference:
+   *   `[{ filename, sha256 }]` — never the bytes. A verifier asks for the
+   *   files themselves and computes each SHA-256 locally.
+   *
+   * A hint only: it never changes what is hashed. Keys MUST be a subset of
+   * {@link fields}; a field without an entry is unspecified (a verifier may
+   * offer a choice, as before).
+   */
+  field_kinds?: Record<string, ContentFieldKind>;
 }
 
+/** See {@link ContentBinding.field_kinds}. */
+export type ContentFieldKind = 'text' | 'list' | 'files';
+
 /**
  * Scope field definition within a profile (renamed from `ProfileContextField`
  * in v0.7 — protocol.md → *Migration from v0.6*, `contextSchema` → `scopeSchema`).