@humanagencyp/hap-core 0.8.3 → 0.9.0

package/dist/index.mjs

@@ -151,9 +151,9 @@ function computeIntentDisclosureHash(intentCiphertext, approversFrozen) {
 }
 
 // src/identity.ts
-function validateSubject(subject) {
+function validateSubject(subject, opts) {
   const errors = [];
-  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+  const { did, assurance, method, trust_root, verifier, disclose } = subject;
   if (!did) errors.push("subject.did is required");
   if (assurance === "low") {
     if (method !== "self_declared") errors.push(`low assurance requires method "self_declared", got "${method}"`);
@@ -166,7 +166,10 @@ function validateSubject(subject) {
     } else if (method === "eudi") {
       if (trust_root !== "external") errors.push('eudi requires trust_root "external"');
       if (!verifier) errors.push("eudi requires a verifier");
-      if (!owner_signature) errors.push("eudi requires an owner_signature");
+      if (opts?.ownerMandates !== void 0) {
+        const entry = opts.ownerMandates.find((m) => m.did === did && m.binding === "eudi");
+        if (!entry) errors.push('eudi requires an owner_mandates entry with binding "eudi" for this DID');
+      }
     } else {
       errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
     }
@@ -869,10 +872,206 @@ function resolveCumulativeFields(request, profile, executionLog, now) {
   }
   return errors;
 }
+
+// src/did-key.ts
+var B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+var B58_MAP = {};
+for (let i = 0; i < B58_ALPHABET.length; i++) B58_MAP[B58_ALPHABET[i]] = i;
+var ED25519_MULTICODEC = Uint8Array.from([237, 1]);
+var ED25519_KEY_BYTES = 32;
+function base58btcEncode(bytes) {
+  let zeros = 0;
+  while (zeros < bytes.length && bytes[zeros] === 0) zeros++;
+  const digits = [];
+  for (let i = zeros; i < bytes.length; i++) {
+    let carry = bytes[i];
+    for (let j = 0; j < digits.length; j++) {
+      carry += digits[j] * 256;
+      digits[j] = carry % 58;
+      carry = carry / 58 | 0;
+    }
+    while (carry > 0) {
+      digits.push(carry % 58);
+      carry = carry / 58 | 0;
+    }
+  }
+  let out = "1".repeat(zeros);
+  for (let i = digits.length - 1; i >= 0; i--) out += B58_ALPHABET[digits[i]];
+  return out;
+}
+function base58btcDecode(s) {
+  let zeros = 0;
+  while (zeros < s.length && s[zeros] === "1") zeros++;
+  const bytes = [];
+  for (let i = zeros; i < s.length; i++) {
+    const val = B58_MAP[s[i]];
+    if (val === void 0) throw new Error(`invalid base58 character "${s[i]}"`);
+    let carry = val;
+    for (let j = 0; j < bytes.length; j++) {
+      carry += bytes[j] * 58;
+      bytes[j] = carry & 255;
+      carry >>= 8;
+    }
+    while (carry > 0) {
+      bytes.push(carry & 255);
+      carry >>= 8;
+    }
+  }
+  const out = new Uint8Array(zeros + bytes.length);
+  for (let i = 0; i < bytes.length; i++) out[zeros + i] = bytes[bytes.length - 1 - i];
+  return out;
+}
+function encodeDidKey(publicKey) {
+  if (publicKey.length !== ED25519_KEY_BYTES) {
+    throw new Error(`INVALID_KEY: expected ${ED25519_KEY_BYTES} bytes, got ${publicKey.length}`);
+  }
+  const prefixed = new Uint8Array(ED25519_MULTICODEC.length + publicKey.length);
+  prefixed.set(ED25519_MULTICODEC, 0);
+  prefixed.set(publicKey, ED25519_MULTICODEC.length);
+  return `did:key:z${base58btcEncode(prefixed)}`;
+}
+function decodeDidKey(did) {
+  if (!did.startsWith("did:key:z")) {
+    throw new Error(`NOT_KEY_BEARING: ${JSON.stringify(did)} is not a base58btc did:key`);
+  }
+  let decoded;
+  try {
+    decoded = base58btcDecode(did.slice("did:key:z".length));
+  } catch (err) {
+    throw new Error(`NOT_KEY_BEARING: ${err.message}`);
+  }
+  if (decoded.length !== ED25519_MULTICODEC.length + ED25519_KEY_BYTES || decoded[0] !== ED25519_MULTICODEC[0] || decoded[1] !== ED25519_MULTICODEC[1]) {
+    throw new Error("NOT_KEY_BEARING: not an ed25519-pub multicodec payload");
+  }
+  return decoded.slice(ED25519_MULTICODEC.length);
+}
+function isKeyBearingDid(did) {
+  try {
+    decodeDidKey(did);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/mandate.ts
+import * as ed2 from "@noble/ed25519";
+var MandateError = class extends Error {
+  constructor(code, message) {
+    super(`${code}: ${message}`);
+    this.code = code;
+    this.name = "MandateError";
+  }
+};
+function buildMandateProjection(payload, entry) {
+  const { profile_id, bounds_hash, context_hash, execution_context_hash, gate_content_hashes, commitment_mode, expires_at } = payload;
+  if (!bounds_hash || !context_hash || !commitment_mode) {
+    throw new MandateError("MALFORMED_ATTESTATION", "mandate projection requires bounds_hash, context_hash and commitment_mode");
+  }
+  const projection = {
+    typ: "HAP-mandate",
+    version: "0.6",
+    profile_id,
+    owner_did: entry.did,
+    bounds_hash,
+    context_hash,
+    execution_context_hash,
+    gate_content_hashes,
+    commitment_mode,
+    expires_at,
+    nonce: entry.nonce
+  };
+  if (payload.intent_disclosure_hash !== void 0) {
+    projection.intent_disclosure_hash = payload.intent_disclosure_hash;
+  }
+  return projection;
+}
+function mandateSigningBytes(projection) {
+  return new TextEncoder().encode(canonicalize(projection));
+}
+function approvalSigningBytes(approval) {
+  return new TextEncoder().encode(canonicalize(approval));
+}
+function base64urlToBytes(s) {
+  const base64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = base64.length % 4 === 0 ? "" : "=".repeat(4 - base64.length % 4);
+  return new Uint8Array(Buffer.from(base64 + padding, "base64"));
+}
+function bytesToBase64url(bytes) {
+  return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+async function signMandateProjection(projection, privateKey) {
+  const sig = await ed2.signAsync(mandateSigningBytes(projection), privateKey);
+  return bytesToBase64url(sig);
+}
+async function signApproval(approval, privateKey) {
+  const sig = await ed2.signAsync(approvalSigningBytes(approval), privateKey);
+  return bytesToBase64url(sig);
+}
+async function verifyOwnerMandate(attestation, entry) {
+  const owners = attestation.payload.resolved_owners ?? [];
+  if (!owners.includes(entry.did)) {
+    throw new MandateError("OWNER_NOT_RESOLVED", `signing DID ${entry.did} is not in resolved_owners`);
+  }
+  if (entry.alg !== "EdDSA") {
+    throw new MandateError("MANDATE_SIGNATURE_INVALID", `alg ${entry.alg} disagrees with the DID's key type (DID is authoritative)`);
+  }
+  let publicKey;
+  try {
+    publicKey = decodeDidKey(entry.did);
+  } catch (err) {
+    throw new MandateError("NOT_KEY_BEARING", err.message);
+  }
+  const projection = buildMandateProjection(attestation.payload, entry);
+  const ok = await ed2.verifyAsync(base64urlToBytes(entry.signature), mandateSigningBytes(projection), publicKey);
+  if (!ok) {
+    throw new MandateError("MANDATE_SIGNATURE_INVALID", `owner mandate signature by ${entry.did} does not verify`);
+  }
+}
+async function verifyOwnerMandates(attestation) {
+  const entries = attestation.payload.owner_mandates ?? [];
+  for (const entry of entries) {
+    await verifyOwnerMandate(attestation, entry);
+  }
+  return entries;
+}
+async function verifyApproval(approval, signature, signerDid) {
+  let publicKey;
+  try {
+    publicKey = decodeDidKey(signerDid);
+  } catch (err) {
+    throw new MandateError("NOT_KEY_BEARING", err.message);
+  }
+  const ok = await ed2.verifyAsync(base64urlToBytes(signature), approvalSigningBytes(approval), publicKey);
+  if (!ok) {
+    throw new MandateError("APPROVAL_SIGNATURE_INVALID", `approval signature by ${signerDid} does not verify`);
+  }
+}
+
+// src/receipt.ts
+import * as ed3 from "@noble/ed25519";
+async function verifyReceiptSignature(receipt, publicKeyHex) {
+  const { signature, ...unsigned } = receipt;
+  if (!signature) {
+    throw new Error("INVALID_SIGNATURE: receipt carries no signature");
+  }
+  const bytes = new TextEncoder().encode(canonicalize(unsigned));
+  const base64 = signature.replace(/-/g, "+").replace(/_/g, "/");
+  const padding = base64.length % 4 === 0 ? "" : "=".repeat(4 - base64.length % 4);
+  const sigBytes = new Uint8Array(Buffer.from(base64 + padding, "base64"));
+  const publicKeyBytes = new Uint8Array(Buffer.from(publicKeyHex, "hex"));
+  const ok = await ed3.verifyAsync(sigBytes, bytes, publicKeyBytes).catch(() => false);
+  if (!ok) {
+    throw new Error("INVALID_SIGNATURE: receipt signature verification failed");
+  }
+}
 export {
   ContentBindingError,
+  MandateError,
+  approvalSigningBytes,
   attestationId,
   bindingAppliesTo,
+  buildMandateProjection,
   canonicalBounds,
   canonicalContext,
   canonicalFrame,
@@ -889,26 +1088,36 @@ export {
   computeIntentHash,
   contentCanonicalBytes,
   decodeAttestationBlob,
+  decodeDidKey,
   deriveIdentityLine,
   encodeAttestationBlob,
+  encodeDidKey,
   frameHash,
   getAllProfiles,
   getProfile,
   intentDisclosureCanonicalBytes,
   isFieldBinding,
+  isKeyBearingDid,
   isV4Attestation,
   listProfiles,
+  mandateSigningBytes,
   registerProfile,
   selectBoundFields,
+  signApproval,
+  signMandateProjection,
   validateBoundsParams,
   validateContextParams,
   validateFrameParams,
   validateSubject,
   verify,
+  verifyApproval,
   verifyAttestation,
   verifyAttestationSignature,
   verifyAttestationV4,
   verifyBoundsHash,
   verifyContextHash,
-  verifyFrameHash
+  verifyFrameHash,
+  verifyOwnerMandate,
+  verifyOwnerMandates,
+  verifyReceiptSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -39,5 +39,6 @@
     "tsup": "^8.0.0",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
-  }
+  },
+  "homepage": "https://humanagencyprotocol.org"
 }

package/src/did-key.ts

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

package/src/identity.ts

@@ -8,7 +8,7 @@
  *  - {@link deriveIdentityLine} — the human-readable footer line for a subject.
  */
 
-import type { Subject } from './types';
+import type { OwnerMandate, Subject } from './types';
 
 export interface SubjectValidation {
   valid: boolean;
@@ -19,12 +19,25 @@ export interface SubjectValidation {
  * Enforce the Identity-Assurance invariants on a single subject:
  *  - `self_declared` ⇒ `low` / `self`, no disclosed name.
  *  - `as_vouched`    ⇒ `high` / `as`,  `verifier` required.
- *  - `eudi`          ⇒ `high` / `external`, `verifier` + `owner_signature` required.
+ *  - `eudi`          ⇒ `high` / `external`, `verifier` required — and, when the
+ *    carrying attestation's `owner_mandates` are supplied, a corresponding
+ *    entry with `binding:"eudi"` for this subject's DID.
  *  - `disclose.name` only at `assurance:"high"`.
+ *
+ * v0.6: `Subject.owner_signature` is deprecated and IGNORED here — it signed
+ * the identity claim, not the mandate (see the field's deprecation note). The
+ * signature-bearing object is the attestation's `owner_mandates` entry, which
+ * is payload-level context this per-subject check cannot see on its own; pass
+ * `opts.ownerMandates` to enforce the eudi ⇒ mandate-entry rule, omit it to
+ * validate subject shape alone (pre-0.6 callers keep their behaviour minus
+ * the retired owner_signature requirement).
  */
-export function validateSubject(subject: Subject): SubjectValidation {
+export function validateSubject(
+  subject: Subject,
+  opts?: { ownerMandates?: OwnerMandate[] },
+): SubjectValidation {
   const errors: string[] = [];
-  const { did, assurance, method, trust_root, verifier, disclose, owner_signature } = subject;
+  const { did, assurance, method, trust_root, verifier, disclose } = subject;
 
   if (!did) errors.push('subject.did is required');
 
@@ -39,7 +52,10 @@ export function validateSubject(subject: Subject): SubjectValidation {
     } else if (method === 'eudi') {
       if (trust_root !== 'external') errors.push('eudi requires trust_root "external"');
       if (!verifier) errors.push('eudi requires a verifier');
-      if (!owner_signature) errors.push('eudi requires an owner_signature');
+      if (opts?.ownerMandates !== undefined) {
+        const entry = opts.ownerMandates.find(m => m.did === did && m.binding === 'eudi');
+        if (!entry) errors.push('eudi requires an owner_mandates entry with binding "eudi" for this DID');
+      }
     } else {
       errors.push(`high assurance requires method "as_vouched" or "eudi", got "${method}"`);
     }

package/src/index.ts

@@ -13,3 +13,6 @@ export * from './frame';
 export * from './attestation';
 export * from './gatekeeper';
 export * from './profiles';
+export * from './did-key';
+export * from './mandate';
+export * from './receipt';

package/src/mandate.ts

@@ -0,0 +1,207 @@
+/**
+ * Owner Mandate Signatures (HAP v0.6) — the `HAP-mandate` projection, the
+ * `HAP-approval` object, and their verification.
+ *
+ * The human signs BEFORE the AS does, so they cannot sign the finished
+ * attestation (`attestation_id`/`issued_at` do not exist yet). They sign a
+ * mandate PROJECTION: a canonical object every field of which is known at
+ * approval time and reconstructible from the finished attestation — so a
+ * verifier rebuilds it from the attestation it already holds and checks the
+ * signature with the key carried in the owner's DID. No side channel, no
+ * second fetch, no key directory. See protocol.md → "Owner Mandate Signatures".
+ *
+ * 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 → "Identity DIDs vs signing
+ * DIDs"), and it is the honest cost of cold verification.
+ */
+
+import * as ed from '@noble/ed25519';
+import type { Attestation, AttestationPayload, OwnerMandate } from './types';
+import { canonicalize } from './canonicalize';
+import { decodeDidKey } from './did-key';
+
+/** The object the owner signs — a canonical projection of the mandate. */
+export interface MandateProjection {
+  typ: 'HAP-mandate';
+  /** Projection/canonicalization version. A verifier MUST pin it. */
+  version: '0.6';
+  profile_id: string;
+  /** The signing owner's own DID. MUST be a member of `resolved_owners`. */
+  owner_did: string;
+  bounds_hash: string;
+  context_hash: string;
+  execution_context_hash: string;
+  gate_content_hashes: Record<string, string>;
+  /** Included iff the attestation carries one — binds ciphertext AND the
+   * frozen approver set, the swap this mechanism exists to stop. */
+  intent_disclosure_hash?: string;
+  commitment_mode: string;
+  /** The replay defence: the human signs how long the authority lives. */
+  expires_at: number;
+  nonce: string;
+}
+
+/** 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. */
+export interface ApprovalObject {
+  typ: 'HAP-approval';
+  version: '0.6';
+  proposal_id: string;
+  attestation_id: string;
+  decision: 'commit' | 'reject';
+  /** What was approved: the receipt's contentHash where the profile binds
+   * content; otherwise sha256 over the JCS of the proposal's argument set. */
+  content_hash: string;
+  decided_at: number;
+  nonce: string;
+}
+
+export class MandateError extends Error {
+  constructor(
+    public code:
+      | 'MANDATE_SIGNATURE_INVALID'
+      | 'APPROVAL_SIGNATURE_INVALID'
+      | 'NOT_KEY_BEARING'
+      | 'OWNER_NOT_RESOLVED'
+      | 'MALFORMED_ATTESTATION',
+    message: string,
+  ) {
+    super(`${code}: ${message}`);
+    this.name = 'MandateError';
+  }
+}
+
+/**
+ * Rebuild the projection a given `owner_mandates` entry signed, from the
+ * attestation's own signed fields. Field absence is defined, not incidental:
+ * `intent_disclosure_hash` is included iff the attestation carries one.
+ */
+export function buildMandateProjection(
+  payload: AttestationPayload,
+  entry: Pick<OwnerMandate, 'did' | 'nonce'>,
+): MandateProjection {
+  const { profile_id, bounds_hash, context_hash, execution_context_hash, gate_content_hashes, commitment_mode, expires_at } = payload;
+  if (!bounds_hash || !context_hash || !commitment_mode) {
+    throw new MandateError('MALFORMED_ATTESTATION', 'mandate projection requires bounds_hash, context_hash and commitment_mode');
+  }
+  const projection: MandateProjection = {
+    typ: 'HAP-mandate',
+    version: '0.6',
+    profile_id,
+    owner_did: entry.did,
+    bounds_hash,
+    context_hash,
+    execution_context_hash,
+    gate_content_hashes,
+    commitment_mode,
+    expires_at,
+    nonce: entry.nonce,
+  };
+  if (payload.intent_disclosure_hash !== undefined) {
+    projection.intent_disclosure_hash = payload.intent_disclosure_hash;
+  }
+  return projection;
+}
+
+/** The exact bytes an owner signs: RFC 8785 (JCS) canonical UTF-8. */
+export function mandateSigningBytes(projection: MandateProjection): Uint8Array {
+  return new TextEncoder().encode(canonicalize(projection));
+}
+
+/** The exact bytes an owner signs for a per-action approval. */
+export function approvalSigningBytes(approval: ApprovalObject): Uint8Array {
+  return new TextEncoder().encode(canonicalize(approval));
+}
+
+function base64urlToBytes(s: string): Uint8Array {
+  const base64 = s.replace(/-/g, '+').replace(/_/g, '/');
+  const padding = base64.length % 4 === 0 ? '' : '='.repeat(4 - (base64.length % 4));
+  return new Uint8Array(Buffer.from(base64 + padding, 'base64'));
+}
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Sign a mandate projection with a raw Ed25519 private key — the `raw`
+ * binding: tests and CI only, no custody claim. WebAuthn (`webauthn`) and
+ * wallet (`eudi`) bindings sign the same bytes through their own custody;
+ * they are implemented by the platforms that hold those keys, not here.
+ */
+export async function signMandateProjection(
+  projection: MandateProjection,
+  privateKey: Uint8Array,
+): Promise<string> {
+  const sig = await ed.signAsync(mandateSigningBytes(projection), privateKey);
+  return bytesToBase64url(sig);
+}
+
+/** Sign an approval object with a raw Ed25519 private key (`raw` binding). */
+export async function signApproval(approval: ApprovalObject, privateKey: Uint8Array): Promise<string> {
+  const sig = await ed.signAsync(approvalSigningBytes(approval), privateKey);
+  return bytesToBase64url(sig);
+}
+
+/**
+ * Verify ONE `owner_mandates` entry against the attestation that carries it.
+ *
+ * Steps (protocol.md → "Verification procedure", steps 4 of 6): membership in
+ * `resolved_owners`, key-bearing DID, projection reconstruction, Ed25519 over
+ * JCS bytes. The DID is authoritative over `alg` — a disagreement is
+ * MANDATE_SIGNATURE_INVALID, never a fallback to the claimed algorithm.
+ *
+ * What this deliberately does NOT verify: that the DID belongs to the person
+ * the verifier expects (out-of-band, step 5) and the AS's own signature over
+ * the attestation (verifyAttestationSignature, step 1).
+ */
+export async function verifyOwnerMandate(attestation: Attestation, entry: OwnerMandate): Promise<void> {
+  const owners = attestation.payload.resolved_owners ?? [];
+  if (!owners.includes(entry.did)) {
+    throw new MandateError('OWNER_NOT_RESOLVED', `signing DID ${entry.did} is not in resolved_owners`);
+  }
+  if (entry.alg !== 'EdDSA') {
+    // The only key type a did:key carries in this protocol version is Ed25519;
+    // an entry claiming otherwise disagrees with its own DID.
+    throw new MandateError('MANDATE_SIGNATURE_INVALID', `alg ${entry.alg} disagrees with the DID's key type (DID is authoritative)`);
+  }
+  let publicKey: Uint8Array;
+  try {
+    publicKey = decodeDidKey(entry.did);
+  } catch (err) {
+    throw new MandateError('NOT_KEY_BEARING', (err as Error).message);
+  }
+
+  const projection = buildMandateProjection(attestation.payload, entry);
+  const ok = await ed.verifyAsync(base64urlToBytes(entry.signature), mandateSigningBytes(projection), publicKey);
+  if (!ok) {
+    throw new MandateError('MANDATE_SIGNATURE_INVALID', `owner mandate signature by ${entry.did} does not verify`);
+  }
+}
+
+/** Verify every `owner_mandates` entry an attestation carries. Resolves to the
+ * verified entries; an attestation with none resolves to `[]` (the v0.5
+ * posture — nothing to check, and nothing claimed). */
+export async function verifyOwnerMandates(attestation: Attestation): Promise<OwnerMandate[]> {
+  const entries = attestation.payload.owner_mandates ?? [];
+  for (const entry of entries) {
+    await verifyOwnerMandate(attestation, entry);
+  }
+  return entries;
+}
+
+/** Verify an approval signature against a signer's key-bearing DID. */
+export async function verifyApproval(approval: ApprovalObject, signature: string, signerDid: string): Promise<void> {
+  let publicKey: Uint8Array;
+  try {
+    publicKey = decodeDidKey(signerDid);
+  } catch (err) {
+    throw new MandateError('NOT_KEY_BEARING', (err as Error).message);
+  }
+  const ok = await ed.verifyAsync(base64urlToBytes(signature), approvalSigningBytes(approval), publicKey);
+  if (!ok) {
+    throw new MandateError('APPROVAL_SIGNATURE_INVALID', `approval signature by ${signerDid} does not verify`);
+  }
+}