@humanagencyp/hap-core 0.12.1 → 0.13.0

package/src/owner-signature.ts

@@ -1,11 +1,7 @@
 /**
- * Owner Signatures (v0.7) — the `HAP-mandate-projection` object, the
- * `HAP-approval` object, and their verification.
- *
- * Renamed from `mandate.ts` (protocol.md → *Migration from v0.6*: the
- * owner-signed projection's `typ` moves from `"HAP-mandate"` to
- * `"HAP-mandate-projection"`, disambiguating it from the AS-signed mandate
- * itself, which now legitimately owns the name `"HAP-mandate"`).
+ * Owner Signatures — the `HAP-mandate-projection` object, the
+ * `HAP-approval` object, and their verification (v0.8; v0.7 artifacts
+ * verified under their own field lists).
  *
  * The human signs BEFORE the AS does, so they cannot sign the finished
  * mandate (`mandate_id`/`issued_at` do not exist yet). They sign a mandate
@@ -15,6 +11,13 @@
  * with the key carried in the owner's DID. No side channel, no second
  * fetch, no key directory. See protocol.md → "Owner Signatures".
  *
+ * v0.8 adds to the projection what a compromised AS could otherwise restate:
+ * `binding` and `signing_surface` (how the owner signed), `subjects_disclosed`
+ * (whether the name is attached), and `above_cap_approvals` (how many
+ * approvers). The approval gains `approver_did` (who decided) and the
+ * operation it is for (`action`, `action_type`), and always signs the
+ * proposal's content fingerprint beside the bound subset.
+ *
  * Verification here requires NO trust in the AS. What it cannot do is tell
  * the verifier WHOSE key signed — confirming the DID belongs to the
  * expected person is the out-of-band step (protocol.md → "Verification
@@ -22,7 +25,10 @@
  */
 
 import * as ed from '@noble/ed25519';
-import type { Mandate, MandatePayload, MandateOwnerEntry, OwnerSignatureBinding, ProfileOwnerSignatureFloor } from './types';
+import type {
+  Mandate, MandatePayload, MandateOwnerEntry, OwnerSignatureBinding, ProfileOwnerSignatureFloor,
+  ProtocolVersion, SigningSurface, CommitmentMode,
+} from './types';
 import { canonicalize } from './canonicalize';
 import { decodeDidKey } from './did-key';
 import { toBase64Url, fromBase64Url } from './base64url';
@@ -35,7 +41,7 @@ import type { HapErrorCode } from './errors';
 export interface MandateProjection {
   typ: 'HAP-mandate-projection';
   /** Projection/canonicalization version. A verifier MUST pin it. */
-  version: '0.7';
+  version: ProtocolVersion;
   profile_id: string;
   /** Covered deliberately: the owner signs the profile's BYTES, not only its id. */
   profile_hash: string;
@@ -48,30 +54,47 @@ export interface MandateProjection {
   /** Included iff the mandate carries one — binds ciphertext AND the
    * frozen approver set, the swap this mechanism exists to stop. */
   intent_disclosure_hash?: string;
-  commitment_mode: string;
-  /** Included together, iff `commitment_mode === "review_above_cap"`. */
+  commitment_mode: CommitmentMode;
+  /** Included together, iff the mandate carries them (v0.8: under
+   * `review_above_cap`, or `review` in a group with approval-kind caps;
+   * v0.7: under `review_above_cap`). */
   above_cap_caps?: Record<string, number>;
   above_cap_approvers?: string[];
+  /** v0.8 only, with the other two. */
+  above_cap_approvals?: number;
   /** Included iff the mandate narrows the profile's disclose_fields. */
   disclose_fields?: string[];
   /** The replay defence: the human signs how long the authority lives. */
   expires_at: number;
   nonce: string;
+  /** v0.8, always present: MUST equal the `mandate_owners` entry's values. */
+  binding?: OwnerSignatureBinding | string;
+  signing_surface?: SigningSurface | string;
+  /** v0.8, always present: `true` exactly when the mandate carries a
+   * `subjects` entry for the owner. */
+  subjects_disclosed?: boolean;
 }
 
-/** Per-action approval, signed by the owner in `review` mode. Signing a
- * `reject` matters as much as a `commit`: a rejection the AS can discard is
- * a rejection that never happened. */
+/** Per-action approval, signed by the decider. Signing a `reject` matters as
+ * much as a `commit`: a rejection the AS can discard is a rejection that
+ * never happened. */
 export interface ApprovalObject {
   typ: 'HAP-approval';
-  version: '0.7';
+  version: ProtocolVersion;
+  /** v0.8 — who decided: the Mandate Owner in `review`, or an above-cap approver. */
+  approver_did?: string;
   proposal_id: string;
-  /** Renamed from `attestation_id` in v0.7. */
   mandate_id: string;
+  /** v0.8 — the operation the arguments are for, exactly as the ticket carries them. */
+  action?: string;
+  action_type?: string;
   decision: 'commit' | 'reject';
-  /** What was approved: the ticket's contentHash where the profile binds
-   * content; otherwise sha256 over the JCS of the proposal's argument set. */
+  /** The ticket's contentHash where a content binding applies to the action;
+   * otherwise equal to `proposal_content_hash` (v0.8) / the JCS hash of the
+   * proposal's arguments (v0.7). */
   content_hash: string;
+  /** v0.8, always present — the proposal's content fingerprint. */
+  proposal_content_hash?: string;
   decided_at: number;
   nonce: string;
 }
@@ -97,13 +120,12 @@ function decodeOrThrow(signature: string, code: HapErrorCode): Uint8Array {
 
 /**
  * Rebuild the projection a given `mandate_owners` entry signed, from the
- * mandate's own signed fields. Field absence is defined, not incidental:
- * `intent_disclosure_hash`, `above_cap_caps`/`above_cap_approvers`, and
- * `disclose_fields` are included iff the mandate carries them.
+ * mandate's own signed fields, under the mandate's own `version`. Field
+ * absence is defined, not incidental.
  */
 export function buildMandateProjection(
   payload: MandatePayload,
-  entry: Pick<MandateOwnerEntry, 'did' | 'nonce'>,
+  entry: Pick<MandateOwnerEntry, 'did' | 'nonce' | 'binding' | 'signing_surface'>,
 ): MandateProjection {
   const {
     profile_id, profile_hash, bounds_hash, scope_hash, execution_context_hash,
@@ -115,9 +137,10 @@ export function buildMandateProjection(
       'mandate projection requires profile_hash, bounds_hash, scope_hash and commitment_mode',
     );
   }
+  const version: ProtocolVersion = payload.version === '0.7' ? '0.7' : '0.8';
   const projection: MandateProjection = {
     typ: 'HAP-mandate-projection',
-    version: '0.7',
+    version,
     profile_id,
     profile_hash,
     owner_did: entry.did,
@@ -132,23 +155,44 @@ export function buildMandateProjection(
   if (payload.intent_disclosure_hash !== undefined) {
     projection.intent_disclosure_hash = payload.intent_disclosure_hash;
   }
-  if (payload.commitment_mode === 'review_above_cap') {
-    projection.above_cap_caps = payload.above_cap_caps;
-    projection.above_cap_approvers = payload.above_cap_approvers;
+  if (version === '0.7') {
+    if (payload.commitment_mode === 'review_above_cap') {
+      projection.above_cap_caps = payload.above_cap_caps;
+      projection.above_cap_approvers = payload.above_cap_approvers;
+    }
+  } else {
+    // v0.8: the three above-cap fields are projection fields exactly when the
+    // mandate carries them — review_above_cap, or review in a group with
+    // approval-kind caps (Group roles, rule 7) — always together.
+    if (payload.above_cap_approvers !== undefined) {
+      projection.above_cap_caps = payload.above_cap_caps;
+      projection.above_cap_approvers = payload.above_cap_approvers;
+      projection.above_cap_approvals = payload.above_cap_approvals;
+    }
   }
   if (payload.disclose_fields !== undefined) {
     projection.disclose_fields = payload.disclose_fields;
   }
+  if (version === '0.8') {
+    if (entry.binding === undefined || entry.signing_surface === undefined) {
+      throw new OwnerSignatureError(
+        'OWNER_SIGNATURE_INVALID',
+        'a v0.8 projection requires the entry\'s binding and signing_surface',
+      );
+    }
+    projection.binding = entry.binding;
+    projection.signing_surface = entry.signing_surface;
+    projection.subjects_disclosed = (payload.subjects ?? []).some((s) => s.did === entry.did);
+  }
   return projection;
 }
 
-/** The exact bytes an owner signs: RFC 8785 (JCS) canonical UTF-8. Renamed
- * from `mandateSigningBytes` in v0.7. */
+/** The exact bytes an owner signs: RFC 8785 (JCS) canonical UTF-8. */
 export function projectionSigningBytes(projection: MandateProjection): Uint8Array {
   return new TextEncoder().encode(canonicalize(projection));
 }
 
-/** The exact bytes an owner signs for a per-action approval. */
+/** The exact bytes a decider signs for a per-action approval. */
 export function approvalSigningBytes(approval: ApprovalObject): Uint8Array {
   return new TextEncoder().encode(canonicalize(approval));
 }
@@ -227,11 +271,14 @@ export async function verifyOwnerSignatures(mandate: Mandate): Promise<MandateOw
 
 /** Verify an approval signature against a signer's key-bearing DID. */
 export async function verifyApproval(approval: ApprovalObject, signature: string, signerDid: string): Promise<void> {
+  if (approval.version === '0.8' && approval.approver_did !== signerDid) {
+    throw new OwnerSignatureError('APPROVAL_SIGNATURE_INVALID', `approval names approver ${approval.approver_did}, verified under ${signerDid}`);
+  }
   let publicKey: Uint8Array;
   try {
     publicKey = decodeDidKey(signerDid);
   } catch (err) {
-    throw new OwnerSignatureError('OWNER_SIGNATURE_INVALID', (err as Error).message);
+    throw new OwnerSignatureError('APPROVAL_SIGNATURE_INVALID', (err as Error).message);
   }
   const ok = await ed.verifyAsync(decodeOrThrow(signature, 'APPROVAL_SIGNATURE_INVALID'), approvalSigningBytes(approval), publicKey).catch(() => false);
   if (!ok) {
@@ -240,8 +287,14 @@ export async function verifyApproval(approval: ApprovalObject, signature: string
 }
 
 /** Signature-assurance ranking for `OwnerSignatureBinding`, weakest first —
- * protocol.md → *Owner Signatures* → "binding" table ordering (raw < webauthn < eudi). */
-const BINDING_RANK: Record<OwnerSignatureBinding, number> = { raw: 0, webauthn: 1, eudi: 2 };
+ * protocol.md → *Owner Signatures* → "binding" table ordering (raw < webauthn < eudi).
+ * A binding the verifier does not know ranks as `raw` (satisfies no minimum
+ * above it). */
+export const BINDING_RANK: Record<OwnerSignatureBinding, number> = { raw: 0, webauthn: 1, eudi: 2 };
+
+export function bindingRank(binding: string | undefined): number {
+  return BINDING_RANK[binding as OwnerSignatureBinding] ?? 0;
+}
 
 /**
  * Enforce a profile's `ownerSignature` floor (protocol.md → *Owner
@@ -249,12 +302,6 @@ const BINDING_RANK: Record<OwnerSignatureBinding, number> = { raw: 0, webauthn:
  * checkable without trusting the AS: `profile_id`/`profile_hash` are in the
  * signed payload AND in the owner-signed projection).
  *
- * An unknown `binding` value is treated as rank 0 (weakest) rather than
- * rejected outright — "an AS MUST NOT reject a mandate_owners entry solely
- * because it does not recognize its binding value" extends naturally to a
- * verifier ranking it, since crediting an unrecognized binding with
- * unearned strength would be the more dangerous failure mode.
- *
  * @throws OwnerSignatureError `OWNER_SIGNATURE_REQUIRED` when the floor is
  * unmet — "MUST fail, not warn" (protocol.md, same section).
  */
@@ -272,7 +319,7 @@ export function checkOwnerSignatureRequirement(
     );
   }
   const minRank = floor.minBinding ? BINDING_RANK[floor.minBinding] : 0;
-  const haveRank = BINDING_RANK[entry!.binding as OwnerSignatureBinding] ?? 0;
+  const haveRank = bindingRank(entry!.binding);
   if (haveRank < minRank) {
     throw new OwnerSignatureError(
       'OWNER_SIGNATURE_REQUIRED',

package/src/profile.ts

@@ -182,6 +182,9 @@ export function validateProfile(profile: AgentProfile): ProfileValidationError[]
       }
       const seen = new Set<unknown>();
       for (const m of declaredModes) {
+        // Rule 8: an entry review_above_cap is ignored — the mode follows from
+        // automatic alone — so it is neither an error nor an admission.
+        if (m === 'review_above_cap') continue;
         if (!(SIGNABLE_COMMITMENT_MODES as readonly string[]).includes(m as string)) {
           errors.push({
             code: 'PROFILE_INVALID',
@@ -206,6 +209,48 @@ export function validateProfile(profile: AgentProfile): ProfileValidationError[]
     });
   }
 
+  // ── v0.8: maximum, enforcedBy, disclose_fields, content_binding ─────────
+  if (boundsSchema) {
+    const readFields = new Set<string>();
+    for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+      const bt = fieldDef.boundType;
+      if (bt && (bt.kind === 'per_transaction' || bt.kind === 'cumulative_sum')) readFields.add(bt.of);
+      const max = (fieldDef as { maximum?: unknown }).maximum;
+      if (max !== undefined && (typeof max !== 'number' || !Number.isFinite(max))) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}": maximum MUST be a number (Bounds Schema rule 9).`,
+        });
+      }
+      const enforcedBy = (fieldDef as { enforcedBy?: unknown }).enforcedBy;
+      if (enforcedBy !== undefined && enforcedBy !== 'gatekeeper') {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}": enforcedBy MUST be "gatekeeper" when present (Bounds Schema rule 11).`,
+        });
+      }
+    }
+    for (const f of profile.disclose_fields ?? []) {
+      if (!readFields.has(f)) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: 'disclose_fields',
+          message: `disclose_fields names "${f}", which no bound reads — only what a ticket carries can be disclosed.`,
+        });
+      }
+    }
+  }
+  const binding = profile.content_binding;
+  if (binding && String(binding.version) === '2' && binding.kind === 'text') {
+    errors.push({
+      code: 'PROFILE_INVALID',
+      field: 'content_binding',
+      message: 'A version-2 content_binding is defined for kind "jcs" only; kind "text" is invalid.',
+    });
+  }
+
   return errors;
 }
 

package/src/proposal-content.ts

@@ -0,0 +1,219 @@
+/**
+ * Proposal content — what the Authority Server receives of a proposal
+ * (protocol.md → *Proposals — what the Authority Server receives*, v0.8).
+ *
+ * The content is the action's argument object, serialized as RFC 8785 JCS.
+ * Its fingerprint, `proposalContentHash`, is what the AS compares, what the
+ * ticket carries and what every `HAP-approval` signs. The content itself is
+ * encrypted to its readers — the Mandate Owner and every signed decider —
+ * with exactly the construction rule 3 pins byte for byte:
+ *
+ * - a fresh 32-byte content key (CEK) per proposal;
+ * - AES-256-GCM under the CEK, random 12-byte IV, no associated data,
+ *   16-byte tag; `ciphertext` = IV ‖ GCM ciphertext ‖ tag;
+ * - per reader, HPKE (RFC 9180) base mode, DHKEM(X25519, HKDF-SHA256),
+ *   HKDF-SHA256, AES-256-GCM, empty `info`, the CEK sealed single-shot with
+ *   empty associated data; `enc` the 32-byte encapsulated key, `ct` the
+ *   48-byte sealed CEK;
+ * - every binary value base64url without padding; `encrypted_keys` keyed by
+ *   the reader's DID. The reader key is an X25519 key distinct from the
+ *   DID's signing key.
+ *
+ * The conformance vector `proposal-encryption.json` fixes the CEK, the IV
+ * and the ephemeral keys so the output is reproducible; real use draws all
+ * three at random, and the deterministic hooks exist for that test only.
+ */
+
+import { createHash, type webcrypto } from 'crypto';
+import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256, Aes256Gcm } from '@hpke/core';
+import { canonicalize } from './canonicalize';
+import { toBase64Url, fromBase64Url } from './base64url';
+import { HapError } from './errors';
+
+export interface ProposalContentEnvelope {
+  ciphertext: string;
+  encrypted_keys: Record<string, { ct: string; enc: string }>;
+  readers: string[];
+  unreadable: string[];
+}
+
+export interface ReaderKeyPair {
+  /** Raw X25519 private key, 32 bytes. */
+  privateKey: Uint8Array;
+  /** Raw X25519 public key, 32 bytes. */
+  publicKey: Uint8Array;
+}
+
+function suite(): CipherSuite {
+  return new CipherSuite({ kem: new DhkemX25519HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes256Gcm() });
+}
+
+const webCrypto = (): webcrypto.Crypto => {
+  const c = globalThis.crypto as webcrypto.Crypto | undefined;
+  if (!c?.subtle) throw new Error('WebCrypto is not available in this runtime');
+  return c;
+};
+
+/** The content's JCS bytes, as a string (rule 1). */
+export function proposalContentJcs(args: Record<string, unknown>): string {
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'proposal content is one object — the action\'s argument object');
+  }
+  return canonicalize(args);
+}
+
+/** `proposalContentHash` — `"sha256:" + hex(sha256(JCS(content)))` (rule 4). */
+export function computeProposalContentHash(args: Record<string, unknown>): string {
+  return `sha256:${createHash('sha256').update(proposalContentJcs(args), 'utf8').digest('hex')}`;
+}
+
+/** A fresh reader key pair (X25519). */
+export async function generateReaderKeyPair(): Promise<ReaderKeyPair> {
+  const kp = await suite().kem.generateKeyPair();
+  return exportKeyPair(kp);
+}
+
+/** A reader key pair derived from input keying material (RFC 9180
+ * DeriveKeyPair) — deterministic; for tests and vectors. */
+export async function deriveReaderKeyPair(ikm: Uint8Array): Promise<ReaderKeyPair> {
+  const kp = await suite().kem.deriveKeyPair(ikm);
+  return exportKeyPair(kp);
+}
+
+async function exportKeyPair(kp: webcrypto.CryptoKeyPair): Promise<ReaderKeyPair> {
+  const s = suite();
+  return {
+    privateKey: new Uint8Array(await s.kem.serializePrivateKey(kp.privateKey)),
+    publicKey: new Uint8Array(await s.kem.serializePublicKey(kp.publicKey)),
+  };
+}
+
+export interface EncryptOptions {
+  /** Signed deciders for whom no reader key exists; listed, notified, unable to decide. */
+  unreadable?: string[];
+  /** Deterministic inputs — TESTS AND VECTORS ONLY. */
+  deterministic?: {
+    contentKey: Uint8Array;
+    iv: Uint8Array;
+    /** Per reader DID: the ephemeral key material for its HPKE wrap. */
+    ephemeralIkm: Record<string, Uint8Array>;
+  };
+}
+
+/**
+ * Encrypt a proposal's content to its readers and compute its fingerprint.
+ * @param readers Each reader's DID and raw X25519 reader public key.
+ */
+export async function encryptProposalContent(
+  args: Record<string, unknown>,
+  readers: ReadonlyArray<{ did: string; publicKey: Uint8Array }>,
+  opts: EncryptOptions = {},
+): Promise<{ content: ProposalContentEnvelope; proposalContentHash: string }> {
+  if (readers.length === 0) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'a proposal has at least one reader (the Mandate Owner)');
+  }
+  const jcs = proposalContentJcs(args);
+  const proposalContentHash = computeProposalContentHash(args);
+  const crypto = webCrypto();
+  const s = suite();
+
+  const cek = opts.deterministic?.contentKey ?? crypto.getRandomValues(new Uint8Array(32));
+  const iv = opts.deterministic?.iv ?? crypto.getRandomValues(new Uint8Array(12));
+  if (cek.length !== 32 || iv.length !== 12) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'content key is 32 bytes and IV is 12 bytes');
+  }
+  const aesKey = await crypto.subtle.importKey('raw', cek, { name: 'AES-GCM', length: 256 }, false, ['encrypt']);
+  const sealed = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, aesKey, new TextEncoder().encode(jcs)));
+  const ciphertext = new Uint8Array(iv.length + sealed.length);
+  ciphertext.set(iv, 0);
+  ciphertext.set(sealed, iv.length);
+
+  const encrypted_keys: Record<string, { ct: string; enc: string }> = {};
+  for (const { did, publicKey } of readers) {
+    const recipientPublicKey = await s.kem.deserializePublicKey(publicKey);
+    const ekmIkm = opts.deterministic?.ephemeralIkm[did];
+    const sender = await s.createSenderContext({
+      recipientPublicKey,
+      ...(ekmIkm ? { ekm: await s.kem.deriveKeyPair(ekmIkm) } : {}),
+    });
+    const ct = new Uint8Array(await sender.seal(cek));
+    encrypted_keys[did] = { ct: toBase64Url(ct), enc: toBase64Url(new Uint8Array(sender.enc)) };
+  }
+
+  return {
+    content: {
+      ciphertext: toBase64Url(ciphertext),
+      encrypted_keys,
+      readers: readers.map((r) => r.did),
+      unreadable: [...(opts.unreadable ?? [])],
+    },
+    proposalContentHash,
+  };
+}
+
+/**
+ * Decrypt a proposal's content as one reader. A reader whose HPKE open or
+ * GCM decryption fails MUST treat the proposal as unreadable — never as
+ * empty or partial content (rule 3); this throws rather than returning.
+ * @returns the argument object and its JCS, so the caller recomputes the
+ * fingerprint and refuses on a mismatch (rule 8).
+ */
+export async function decryptProposalContent(
+  content: ProposalContentEnvelope,
+  readerDid: string,
+  readerPrivateKey: Uint8Array,
+): Promise<{ arguments: Record<string, unknown>; contentJcs: string; proposalContentHash: string }> {
+  const wrap = content.encrypted_keys[readerDid];
+  if (!wrap) throw new HapError('PROPOSAL_NOT_ENCRYPTED', `no key wrapped for reader ${readerDid}`);
+  const s = suite();
+  const crypto = webCrypto();
+  let cek: Uint8Array;
+  try {
+    const recipient = await s.createRecipientContext({
+      recipientKey: await s.kem.deserializePrivateKey(readerPrivateKey),
+      enc: fromBase64Url(wrap.enc),
+    });
+    cek = new Uint8Array(await recipient.open(fromBase64Url(wrap.ct)));
+  } catch (err) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', `proposal content is unreadable for ${readerDid}: ${(err as Error).message}`);
+  }
+  const bytes = fromBase64Url(content.ciphertext);
+  if (bytes.length < 12 + 16) throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'ciphertext is shorter than IV + tag');
+  let plaintext: Uint8Array;
+  try {
+    const aesKey = await crypto.subtle.importKey('raw', cek, { name: 'AES-GCM', length: 256 }, false, ['decrypt']);
+    plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: bytes.subarray(0, 12) }, aesKey, bytes.subarray(12)));
+  } catch (err) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', `proposal content is unreadable for ${readerDid}: ${(err as Error).message}`);
+  }
+  const contentJcs = new TextDecoder().decode(plaintext);
+  let args: Record<string, unknown>;
+  try {
+    args = JSON.parse(contentJcs);
+  } catch {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'decrypted content is not JSON');
+  }
+  return { arguments: args, contentJcs, proposalContentHash: computeProposalContentHash(args) };
+}
+
+/**
+ * The reader-set rules an Authority Server applies at submission (rule 2):
+ * `readers` ∪ `unreadable` equals the owner plus the signed deciders;
+ * `readers` equals the key set of `encrypted_keys`.
+ * @throws HapError `PROPOSAL_APPROVERS_INVALID` | `PROPOSAL_NOT_ENCRYPTED`
+ */
+export function checkProposalReaders(
+  content: ProposalContentEnvelope,
+  expected: { ownerDid: string; deciders: readonly string[] },
+): void {
+  const want = new Set([expected.ownerDid, ...expected.deciders]);
+  const have = new Set([...content.readers, ...content.unreadable]);
+  if (want.size !== have.size || [...want].some((d) => !have.has(d))) {
+    throw new HapError('PROPOSAL_APPROVERS_INVALID', 'readers ∪ unreadable differs from the owner plus the signed deciders');
+  }
+  const keyed = new Set(Object.keys(content.encrypted_keys));
+  const readers = new Set(content.readers);
+  if (keyed.size !== readers.size || [...readers].some((d) => !keyed.has(d))) {
+    throw new HapError('PROPOSAL_NOT_ENCRYPTED', 'readers differs from the key set of encrypted_keys');
+  }
+}