@humanagencyp/hap-core 0.12.1 → 0.13.0

package/src/ticket-projection.ts

@@ -0,0 +1,167 @@
+/**
+ * Public ticket projection — `HAP-ticket-projection` (protocol.md → *Public
+ * ticket projection*, new in v0.8, specification-led).
+ *
+ * A ticket is one signature over every field, so a redacted view cannot be
+ * re-verified. Where a ticket is shown to parties other than its holder —
+ * a public page, a machine verifier at an effector, an auditor — the AS
+ * serves a public-only subset, separately signed by the same key, so the
+ * public view verifies on its own. It never widens what the ticket
+ * discloses: `executionContext` carries only the governing
+ * `disclose_fields`, and `userId`, `cumulativeState`, `limits` and `action`
+ * never appear.
+ */
+
+import * as ed from '@noble/ed25519';
+import { canonicalize } from './canonicalize';
+import { toBase64Url, fromBase64Url } from './base64url';
+import { decodeDidKey } from './did-key';
+import { HapError } from './errors';
+import type { Mandate, MandateOwnerEntry, Subject } from './types';
+import type { TicketPayload } from './ticket';
+import { verifyOwnerSignature, OwnerSignatureError } from './owner-signature';
+
+/** The AS may not let a projection be accepted as authorization later than
+ * this after the ticket's timestamp (rule 3). */
+export const PROJECTION_MAX_VALIDITY_SECONDS = 86_400;
+
+export interface TicketProjection {
+  typ: 'HAP-ticket-projection';
+  version: string;
+  id: string;
+  mandateId: string;
+  issuer: string;
+  timestamp: number;
+  /** Set by the AS at projection time; governs acceptance as authorization, not evidence. */
+  valid_until: number;
+  profileId: string;
+  actionType: string;
+  boundsHash: string;
+  contentHash?: string;
+  contentBinding?: TicketPayload['contentBinding'];
+  subjects?: Subject[];
+  /** Exactly the governing `disclose_fields` the ticket carries; absent when none. */
+  executionContext?: Record<string, unknown>;
+  /** The mandate's `mandate_owners` entry, present exactly when it carries a signature. */
+  owner?: MandateOwnerEntry;
+  signature: string;
+}
+
+/**
+ * Build the projection of a ticket (rule 1). `discloseFields` is the
+ * governing list — the mandate's `disclose_fields` where present, else the
+ * profile's; nothing when neither declares one.
+ */
+export function buildTicketProjection(
+  ticket: TicketPayload,
+  mandate: Mandate,
+  opts: { validUntil: number; discloseFields?: readonly string[] },
+): Omit<TicketProjection, 'signature'> {
+  if (ticket.mandateId !== mandate.payload.mandate_id) {
+    throw new HapError('MALFORMED_TICKET_REQUEST', 'the mandate supplied is not the one the ticket names');
+  }
+  if (opts.validUntil > ticket.timestamp + PROJECTION_MAX_VALIDITY_SECONDS) {
+    throw new HapError('MALFORMED_TICKET_REQUEST', `valid_until MUST NOT end later than ${PROJECTION_MAX_VALIDITY_SECONDS}s after the ticket's timestamp`);
+  }
+  const projection: Omit<TicketProjection, 'signature'> = {
+    typ: 'HAP-ticket-projection',
+    version: ticket.version,
+    id: ticket.id,
+    mandateId: ticket.mandateId,
+    issuer: ticket.issuer,
+    timestamp: ticket.timestamp,
+    valid_until: opts.validUntil,
+    profileId: ticket.profileId,
+    actionType: ticket.actionType,
+    boundsHash: ticket.boundsHash,
+  };
+  if (ticket.contentHash !== undefined) projection.contentHash = ticket.contentHash;
+  if (ticket.contentBinding !== undefined) projection.contentBinding = ticket.contentBinding;
+  if (ticket.subjects !== undefined) projection.subjects = ticket.subjects;
+  const disclosed: Record<string, unknown> = {};
+  for (const field of opts.discloseFields ?? []) {
+    if (ticket.executionContext[field] !== undefined) disclosed[field] = ticket.executionContext[field];
+  }
+  if (Object.keys(disclosed).length > 0) projection.executionContext = disclosed;
+  const owner = mandate.payload.mandate_owners[0];
+  if (owner?.signature !== undefined) projection.owner = owner;
+  return projection;
+}
+
+/** Sign a projection with the key that signed its ticket (rule 2). */
+export async function signTicketProjection(
+  projection: Omit<TicketProjection, 'signature'>,
+  privateKey: Uint8Array,
+): Promise<TicketProjection> {
+  const signature = toBase64Url(await ed.signAsync(new TextEncoder().encode(canonicalize(projection)), privateKey));
+  return { ...projection, signature };
+}
+
+/**
+ * Verify a projection on its own: `typ` required, signature under the key
+ * `issuer` names. With `asAuthorization`, a projection past `valid_until`
+ * is refused (rule 3); as evidence it is not.
+ * @throws HapError `INVALID_SIGNATURE`, `POLICY_UNMET` (validity window)
+ */
+export async function verifyTicketProjection(
+  projection: TicketProjection,
+  opts: { trustedIssuers?: readonly string[]; now?: number; asAuthorization?: boolean } = {},
+): Promise<void> {
+  if (projection.typ !== 'HAP-ticket-projection') {
+    throw new HapError('INVALID_SIGNATURE', 'a projection verifier requires typ "HAP-ticket-projection"');
+  }
+  for (const k of ['userId', 'cumulativeState', 'limits', 'action'] as const) {
+    if (k in projection) throw new HapError('INVALID_SIGNATURE', `a projection MUST NOT carry ${k}`);
+  }
+  if (opts.trustedIssuers && !opts.trustedIssuers.includes(projection.issuer)) {
+    throw new HapError('INVALID_SIGNATURE', `issuer ${JSON.stringify(projection.issuer)} is not a trusted Authority Server`);
+  }
+  const { signature, ...unsigned } = projection;
+  if (!signature) throw new HapError('INVALID_SIGNATURE', 'projection carries no signature');
+  let publicKey: Uint8Array;
+  try {
+    publicKey = decodeDidKey(projection.issuer);
+  } catch (err) {
+    throw new HapError('INVALID_SIGNATURE', `cannot resolve a key from issuer ${JSON.stringify(projection.issuer)}: ${(err as Error).message}`);
+  }
+  let sigBytes: Uint8Array;
+  try {
+    sigBytes = fromBase64Url(signature);
+  } catch (err) {
+    throw new HapError('INVALID_SIGNATURE', (err as Error).message);
+  }
+  const ok = await ed.verifyAsync(sigBytes, new TextEncoder().encode(canonicalize(unsigned)), publicKey).catch(() => false);
+  if (!ok) throw new HapError('INVALID_SIGNATURE', 'projection signature verification failed');
+  if (opts.asAuthorization) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (now > projection.valid_until) {
+      throw new HapError('POLICY_UNMET', `projection presented after valid_until ${projection.valid_until}`);
+    }
+  }
+}
+
+/**
+ * Verify the projection's `owner` entry against the mandate obtained through
+ * the third-party verification API (rule 4): the entry is the mandate's
+ * own, and its signature verifies over the projection rebuilt from the
+ * mandate. The projection alone cannot establish this.
+ * @throws HapError `OWNER_SIGNATURE_INVALID`
+ */
+export async function verifyProjectionOwner(projection: TicketProjection, mandate: Mandate): Promise<void> {
+  if (!projection.owner) {
+    throw new HapError('OWNER_SIGNATURE_INVALID', 'projection carries no owner entry');
+  }
+  if (projection.mandateId !== mandate.payload.mandate_id) {
+    throw new HapError('OWNER_SIGNATURE_INVALID', 'the mandate supplied is not the one the projection names');
+  }
+  const own = mandate.payload.mandate_owners[0];
+  if (!own || canonicalize(own) !== canonicalize(projection.owner)) {
+    throw new HapError('OWNER_SIGNATURE_INVALID', 'projection owner entry differs from the mandate\'s mandate_owners entry');
+  }
+  try {
+    await verifyOwnerSignature(mandate, projection.owner);
+  } catch (err) {
+    if (err instanceof OwnerSignatureError) throw new HapError(err.code, err.message);
+    throw err;
+  }
+}

package/src/ticket.ts

@@ -1,9 +1,6 @@
 /**
- * Mandate tickets (v0.7) — the wire type, signing, and holder-side
- * verification. Renamed from `receipt.ts` (protocol.md → *Mandate Tickets*:
- * "v0.4 introduced the object under the name execution receipt; v0.7 renames
- * it because the tense was wrong — a receipt follows payment, and the ticket
- * must come first").
+ * Mandate tickets — the wire type, signing, holder-side verification, and
+ * (v0.8) the Gatekeeper's check that a ticket answers the request it sent.
  *
  * Ticket payloads are camelCase on the wire (unlike the snake_case mandate
  * payload) — a shipped inconsistency the spec documents rather than breaks
@@ -12,10 +9,28 @@
 
 import { HapError } from './errors';
 import * as ed from '@noble/ed25519';
-import type { ContentBinding, Subject } from './types';
+import type { ContentBinding, Mandate, Subject } from './types';
 import { canonicalize } from './canonicalize';
 import { toBase64Url, fromBase64Url } from './base64url';
 import { decodeDidKey } from './did-key';
+import { assertSupportedVersion } from './versions';
+import { verifyApproval, OwnerSignatureError, type ApprovalObject } from './owner-signature';
+
+/** Clock-skew tolerance and freshness window (Mandate rule 9; Ticket rule 4). */
+export const TICKET_FRESHNESS_SECONDS = 300;
+
+/** One verified approval carried by a ticket. */
+export interface ApprovalSignatureEntry {
+  alg: 'EdDSA' | 'ES256';
+  signature: string;
+  nonce: string;
+  decided_at: number;
+}
+
+/** v0.8 — an above-cap approver's entry in `approvalSignatures`. */
+export interface ApproverSignatureEntry extends ApprovalSignatureEntry {
+  approver_did: string;
+}
 
 /** Signed mandate ticket — protocol.md → *Ticket Payload Schema*. */
 export interface TicketPayload {
@@ -42,6 +57,10 @@ export interface TicketPayload {
   /** The AS DID, as in the mandate (new in v0.7). */
   issuer: string;
   timestamp: number;
+  /** v0.8 — copied verbatim from the request, so the ticket names the single
+   * request it answers. Present exactly when the request carried one
+   * (synchronous path). */
+  idempotencyKey?: string;
   /** Hash of the bound content, computed by the Gatekeeper, copied
    * verbatim by the AS. The AS never sees the content. */
   contentHash?: string;
@@ -52,10 +71,15 @@ export interface TicketPayload {
   subjects?: Subject[];
   /** Review path: the proposal this ticket executed. */
   proposalId?: string;
+  /** v0.8, review path: the proposal's content fingerprint, copied verbatim
+   * from the proposal the AS compared it against. */
+  proposalContentHash?: string;
   /** Review path: the owner's HAP-approval signature for the executed
    * proposal, as the object itself — never a hash of it, which a holder
    * could check only by asking the AS. */
-  approvalSignature?: { alg: 'EdDSA' | 'ES256'; signature: string; nonce: string; decided_at: number };
+  approvalSignature?: ApprovalSignatureEntry;
+  /** v0.8, above-cap path: one entry per approver signature the AS verified. */
+  approvalSignatures?: ApproverSignatureEntry[];
   /** Ed25519 over the JCS-canonical payload (this field excluded), base64url. */
   signature: string;
 }
@@ -72,25 +96,50 @@ export async function signTicket(
   return { ...payload, signature };
 }
 
+/**
+ * The structural rules that keep a ticket, a projection and a mandate
+ * payload apart (protocol.md → *Ticket Payload Schema*, "Signature"): a
+ * ticket verifier MUST require `id`, `mandateId`, `actionType`, `timestamp`
+ * and `issuer`, MUST reject an object carrying `typ` (a projection can never
+ * be accepted as a ticket), and MUST reject `mandate_id` or `issued_at`.
+ * @throws HapError `INVALID_SIGNATURE`
+ */
+export function assertTicketShape(ticket: Record<string, unknown>): void {
+  if ('typ' in ticket) {
+    throw new HapError('INVALID_SIGNATURE', 'a ticket carries no typ — an object with one is a projection, not a ticket');
+  }
+  if ('mandate_id' in ticket || 'issued_at' in ticket) {
+    throw new HapError('INVALID_SIGNATURE', 'a ticket carries no mandate_id or issued_at — this object is a mandate payload');
+  }
+  for (const required of ['id', 'mandateId', 'actionType', 'timestamp', 'issuer'] as const) {
+    if (ticket[required] === undefined) {
+      throw new HapError('INVALID_SIGNATURE', `ticket is missing required field ${required}`);
+    }
+  }
+}
+
 /**
  * Verify a ticket's AS signature: strip `signature`, JCS-canonicalize the
  * rest, Ed25519-verify against the key resolved from `issuer` — never
  * against a key offered alongside the ticket (protocol.md → *Ticket
  * Verification* step 1). This is holder-side verification — it needs the
  * COMPLETE ticket; a redacted public view cannot be re-verified this way
- * (see {@link publicTicketView}).
+ * (see `ticket-projection.ts` for the view that can).
  *
  * Content is checked separately: where `contentHash` is present, recompute
  * it from the held artifact via the content-binding module and compare.
  *
  * @param opts.trustedIssuers When supplied, an `issuer` not in this list is
  * rejected before any cryptography runs.
- * @throws Error prefixed `INVALID_SIGNATURE:` when verification fails.
+ * @throws HapError `INVALID_SIGNATURE` when verification fails;
+ * `VERSION_UNSUPPORTED` for a version this package cannot read.
  */
 export async function verifyTicketSignature(
   ticket: TicketPayload,
   opts?: { trustedIssuers?: readonly string[] },
 ): Promise<void> {
+  assertTicketShape(ticket as unknown as Record<string, unknown>);
+  assertSupportedVersion(ticket.version, 'ticket');
   const { signature, ...unsigned } = ticket;
   if (!signature) {
     throw new HapError('INVALID_SIGNATURE', 'ticket carries no signature');
@@ -120,19 +169,204 @@ export async function verifyTicketSignature(
   }
 }
 
+// ─── The request a ticket answers (v0.8) ─────────────────────────────────────
+
+/** The fields of a ticket request a Gatekeeper compares with the ticket it
+ * receives (protocol.md → *Ticket Payload Schema*, rule 4). */
+export interface TicketRequestEcho {
+  profileId: string;
+  actionType: string;
+  boundsHash: string;
+  executionContext: Record<string, unknown>;
+  mandateId?: string;
+  idempotencyKey?: string;
+  contentHash?: string;
+  contentBinding?: TicketPayload['contentBinding'];
+  proposalId?: string;
+  proposalContentHash?: string;
+}
+
+const ECHOED_FIELDS = [
+  'profileId', 'actionType', 'boundsHash', 'executionContext',
+  'contentHash', 'contentBinding', 'proposalId', 'proposalContentHash',
+] as const;
+
 /**
- * A redacted public view of a ticket (new in v0.7 — protocol.md → *Ticket
- * Disclosure Is Declared*, *Ticket Verification*). Hides `userId`,
- * `cumulativeState`, and `limits` unconditionally, and narrows
- * `executionContext` to exactly the keys named by `governingDiscloseFields`
- * (the mandate's `disclose_fields` where present, otherwise the profile's).
+ * v0.8 — the Gatekeeper's half of "a ticket names the request it answers":
+ * every echoed field equals what was sent, the `idempotencyKey` it sent is
+ * the one the ticket carries, `mandateId` and `version` are the verified
+ * mandate's, and a fresh ticket's `timestamp` lies within
+ * {@link TICKET_FRESHNESS_SECONDS}. A replay (`idempotent: true`, unsigned)
+ * is exempt from freshness only; the caller passes `replay: true` and then
+ * applies *One execution per ticket*, rule 2.
  *
- * Disclose NOTHING by default: an empty or absent `governingDiscloseFields`
- * strips `executionContext` entirely. "The holder is the verifier" — this
- * view is NOT independently re-verifiable against `signature` (it is missing
- * signed fields); a "signature valid" indicator on a page showing only this
- * view is the AS re-verifying its own signature, and implementations MUST
- * NOT present it as independently verified.
+ * Does NOT verify the signature — call {@link verifyTicketSignature} first.
+ * @throws HapError `TICKET_REQUEST_MISMATCH`
+ */
+export function verifyTicketAgainstRequest(
+  ticket: TicketPayload,
+  request: TicketRequestEcho,
+  opts: { mandate?: Mandate; now?: number; replay?: boolean } = {},
+): void {
+  for (const field of ECHOED_FIELDS) {
+    const sent = request[field];
+    const got = ticket[field];
+    if (sent === undefined && got === undefined) continue;
+    if (sent === undefined || got === undefined || canonicalize(sent) !== canonicalize(got)) {
+      throw new HapError('TICKET_REQUEST_MISMATCH', `ticket ${field} differs from the request's`);
+    }
+  }
+  if (request.idempotencyKey !== undefined && ticket.idempotencyKey !== request.idempotencyKey) {
+    throw new HapError(
+      'TICKET_REQUEST_MISMATCH',
+      ticket.idempotencyKey === undefined
+        ? 'ticket carries no idempotencyKey although the request sent one'
+        : 'ticket idempotencyKey differs from the one the request sent',
+    );
+  }
+  const expectedMandateId = opts.mandate?.payload.mandate_id ?? request.mandateId;
+  if (expectedMandateId !== undefined && ticket.mandateId !== expectedMandateId) {
+    throw new HapError('TICKET_REQUEST_MISMATCH', `ticket mandateId ${ticket.mandateId} is not the mandate this request was made under`);
+  }
+  if (opts.mandate && ticket.version !== opts.mandate.payload.version) {
+    throw new HapError('TICKET_REQUEST_MISMATCH', `ticket version ${ticket.version} differs from its mandate's ${opts.mandate.payload.version}`);
+  }
+  if (!opts.replay) {
+    const now = opts.now ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - ticket.timestamp) > TICKET_FRESHNESS_SECONDS) {
+      throw new HapError('TICKET_REQUEST_MISMATCH', `ticket timestamp ${ticket.timestamp} is outside the freshness window at ${now}`);
+    }
+  }
+}
+
+// ─── Approvals carried by a ticket ───────────────────────────────────────────
+
+/**
+ * Rebuild the `HAP-approval` a decider signed, from the ticket and the
+ * mandate it names (protocol.md → *Ticket Payload Schema*, `approvalSignature`):
+ * `typ` and `version`; `proposal_id` and `mandate_id` from `proposalId` and
+ * `mandateId`; `action` and `action_type` (v0.8) from `action` and
+ * `actionType`; `proposal_content_hash` from `proposalContentHash`;
+ * `content_hash` from `contentHash` where a binding applies to this action
+ * (the AS copies one only then), else `proposalContentHash`; `decision`
+ * `"commit"`; `approver_did` as given; `decided_at` and `nonce` from the
+ * entry.
+ */
+export function reconstructApproval(
+  ticket: TicketPayload,
+  entry: ApprovalSignatureEntry,
+  approverDid: string,
+): ApprovalObject {
+  if (!ticket.proposalId) {
+    throw new HapError('APPROVAL_SIGNATURE_INVALID', 'ticket carries an approval signature but no proposalId');
+  }
+  if (ticket.version === '0.7') {
+    if (!ticket.contentHash) {
+      throw new HapError('APPROVAL_SIGNATURE_INVALID', 'a v0.7 approval without a content binding is not reconstructible from the ticket alone');
+    }
+    return {
+      typ: 'HAP-approval',
+      version: '0.7',
+      proposal_id: ticket.proposalId,
+      mandate_id: ticket.mandateId,
+      decision: 'commit',
+      content_hash: ticket.contentHash,
+      decided_at: entry.decided_at,
+      nonce: entry.nonce,
+    };
+  }
+  if (!ticket.proposalContentHash) {
+    throw new HapError('APPROVAL_SIGNATURE_INVALID', 'a v0.8 review-path ticket carries proposalContentHash');
+  }
+  return {
+    typ: 'HAP-approval',
+    version: '0.8',
+    approver_did: approverDid,
+    proposal_id: ticket.proposalId,
+    mandate_id: ticket.mandateId,
+    action: ticket.action,
+    action_type: ticket.actionType,
+    decision: 'commit',
+    content_hash: ticket.contentHash ?? ticket.proposalContentHash,
+    proposal_content_hash: ticket.proposalContentHash,
+    decided_at: entry.decided_at,
+    nonce: entry.nonce,
+  };
+}
+
+/** What a ticket's approvals, once verified, establish. */
+export interface VerifiedApprovals {
+  /** The Mandate Owner's DID, when `approvalSignature` verified. */
+  owner?: string;
+  /** Distinct above-cap approver DIDs whose `approvalSignatures` entries verified. */
+  approvers: string[];
+}
+
+/**
+ * Verify every approval a ticket carries against the mandate it names
+ * (protocol.md → *Ticket Payload Schema*, rule 4): `approvalSignature`
+ * under the Mandate Owner's DID; each `approvalSignatures` entry under its
+ * `approver_did`, which MUST be in the signed `above_cap_approvers` and
+ * MUST NOT be the Mandate Owner (the proposer never counts). Whether the
+ * verified set is ENOUGH is {@link approvalsSufficient}, so a verifier can
+ * report what it found and a policy can decide.
+ *
+ * @throws HapError `APPROVAL_SIGNATURE_INVALID`
+ */
+export async function verifyTicketApprovals(ticket: TicketPayload, mandate: Mandate): Promise<VerifiedApprovals> {
+  if (ticket.mandateId !== mandate.payload.mandate_id) {
+    throw new HapError('APPROVAL_SIGNATURE_INVALID', 'the mandate supplied is not the one the ticket names');
+  }
+  const ownerDid = mandate.payload.mandate_owners[0]?.did;
+  const result: VerifiedApprovals = { approvers: [] };
+  try {
+    if (ticket.approvalSignature) {
+      const approval = reconstructApproval(ticket, ticket.approvalSignature, ownerDid);
+      await verifyApproval(approval, ticket.approvalSignature.signature, ownerDid);
+      result.owner = ownerDid;
+    }
+    const signed = new Set(mandate.payload.above_cap_approvers ?? []);
+    for (const entry of ticket.approvalSignatures ?? []) {
+      if (!signed.has(entry.approver_did)) {
+        throw new HapError('APPROVAL_SIGNATURE_INVALID', `approver ${entry.approver_did} is not in the mandate's signed above_cap_approvers`);
+      }
+      if (entry.approver_did === ownerDid) {
+        throw new HapError('APPROVAL_SIGNATURE_INVALID', 'the proposer never counts as an above-cap approver');
+      }
+      const approval = reconstructApproval(ticket, entry, entry.approver_did);
+      await verifyApproval(approval, entry.signature, entry.approver_did);
+      if (!result.approvers.includes(entry.approver_did)) result.approvers.push(entry.approver_did);
+    }
+  } catch (err) {
+    if (err instanceof OwnerSignatureError) throw new HapError(err.code, err.message);
+    throw err;
+  }
+  return result;
+}
+
+/**
+ * Whether the verified approvals satisfy what the mandate requires for a
+ * decision above a cap: at least `above_cap_approvals` distinct approvers
+ * (v0.7: every signed approver), plus the owner's own approval in `review`.
+ */
+export function approvalsSufficient(mandate: Mandate, verified: VerifiedApprovals, aboveCap: boolean): boolean {
+  const p = mandate.payload;
+  const ownerNeeded = p.commitment_mode === 'review';
+  if (ownerNeeded && !verified.owner) return false;
+  if (!aboveCap) return true;
+  const required = p.version === '0.7'
+    ? (p.above_cap_approvers ?? []).length
+    : (p.above_cap_approvals ?? 1);
+  return verified.approvers.length >= required;
+}
+
+/**
+ * A redacted public view of a ticket (protocol.md → *Ticket Disclosure Is
+ * Declared*). Hides `userId`, `cumulativeState`, and `limits`, and narrows
+ * `executionContext` to the governing `disclose_fields`. NOT independently
+ * re-verifiable — since v0.8 a verifiable public view is the separately
+ * signed `HAP-ticket-projection` (`ticket-projection.ts`); a view that is
+ * not one MUST NOT be presented as independently verified.
  */
 export function publicTicketView(
   ticket: TicketPayload,

package/src/types.ts

@@ -84,10 +84,15 @@ export interface Subject {
   verified_at?: number;
 }
 
-/** protocol.md → *Mandate Payload (v0.7)*. */
+/** The protocol version an artifact was issued under. This package verifies
+ * each under its own rules (protocol.md → *Version negotiation*, rule 4). */
+export type ProtocolVersion = '0.8' | '0.7';
+
+/** protocol.md → *Mandate Payload (v0.8)*; a `"0.7"` payload is the same shape
+ * without `above_cap_approvals` and without the v0.8 owner-signed fields. */
 export interface MandatePayload {
   mandate_id: string;
-  version: '0.7';
+  version: ProtocolVersion;
   profile_id: string;
   /** Hash of the canonical bounds string. */
   bounds_hash: string;
@@ -104,10 +109,16 @@ export interface MandatePayload {
   /** Exactly one entry in v0.7 (Mandate rule 7). */
   mandate_owners: MandateOwnerEntry[];
   gate_content_hashes: Record<string, string>;
-  commitment_mode: 'automatic' | 'review' | 'review_above_cap';
-  /** Required, together with `above_cap_approvers`, iff `commitment_mode === "review_above_cap"`. */
+  commitment_mode: CommitmentMode;
+  /** Present together with `above_cap_approvers` and (v0.8) `above_cap_approvals`:
+   * under `review_above_cap`, or `review` in a group with approval-kind caps
+   * the owner's mandate can reach (protocol.md → *Group roles*, rule 7). */
   above_cap_caps?: Record<string, number>;
   above_cap_approvers?: string[];
+  /** v0.8 — how many distinct `above_cap_approvers`, other than the Mandate
+   * Owner, must approve. Integer ≥ 1. Present exactly when
+   * `above_cap_approvers` is (Mandate rule 10). A v0.7 mandate carries none. */
+  above_cap_approvals?: number;
   /**
    * Present iff the mandate carries an encrypted-intent disclosure object
    * (companion spec `intent-disclosure@0.1`) — `sha256:`-prefixed hash
@@ -290,6 +301,15 @@ export interface ProfileBoundsField {
    * min(value, maximum). Absent → no ceiling.
    */
   maximum?: number;
+  /**
+   * v0.8 (Bounds Schema rule 11) — a bound only the Gatekeeper enforces, such
+   * as a read window whose actions produce no ticket. The Authority Server
+   * still verifies the value at issuance (`maximum`, enum membership, any
+   * group ceiling) and never reads it at ticket time. A group cap on such a
+   * bound is always hard, and the signed value is the ceiling (*Group
+   * ceilings*).
+   */
+  enforcedBy?: 'gatekeeper';
 }
 
 /**
@@ -446,6 +466,9 @@ export type ExecutionContextFieldDef = DeclaredFieldDef | CumulativeFieldDef;
  */
 export type SignableCommitmentMode = 'automatic' | 'review';
 
+/** Every commitment mode a signed mandate can carry. */
+export type CommitmentMode = SignableCommitmentMode | 'review_above_cap';
+
 /** protocol.md → *Owner Signatures* → "Where the requirement lives" — the
  * profile-floor tier: `minBinding` names the weakest `OwnerSignatureBinding`
  * this profile accepts for a co-signing owner. */
@@ -504,8 +527,13 @@ export interface AgentProfile {
    * a mandate screen offers only the listed modes. Fail-closed: a declared
    * list with no valid entry allows nothing — a malformed declaration never
    * widens what a profile allows. See {@link allowedCommitmentModes}.
+   *
+   * v0.8 (Commitment Modes, rule 8): `review_above_cap` is admitted if and
+   * only if `automatic` is listed; an entry `review_above_cap` in the list is
+   * ignored, and a list whose only entry is it admits nothing and is
+   * malformed (`PROFILE_INVALID`).
    */
-  commitment_modes?: readonly SignableCommitmentMode[];
+  commitment_modes?: readonly CommitmentMode[];
 
   /**
    * The bounds schema — the enforceable parameters (protocol.md → *Bounds