@humanagencyp/hap-core 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanagencyp/hap-core",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Core types, cryptographic primitives, and verification logic for the Human Agency Protocol",
   "license": "MIT",
   "repository": {
@@ -33,6 +33,7 @@
     "release:major": "pnpm version major && git push --follow-tags"
   },
   "dependencies": {
+    "@hpke/core": "1.9.0",
     "@noble/ed25519": "^2.1.0"
   },
   "devDependencies": {

package/src/canonicalize.ts

@@ -31,6 +31,9 @@
  * conformance test pins a (payload → canonical bytes) vector that any other
  * implementation can check against.
  */
+/** A high surrogate not followed by a low one, or a low one not preceded by a high one. */
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
 export function canonicalize(value: unknown): string {
   if (value === undefined) {
     throw new Error('canonicalize: undefined is not serializable');
@@ -41,6 +44,12 @@ export function canonicalize(value: unknown): string {
 
   // Primitives: string, finite number, boolean, null — JSON.stringify is already
   // canonical (RFC 8259 string escaping, ECMAScript number formatting).
+  if (typeof value === 'string' && LONE_SURROGATE.test(value)) {
+    // RFC 8785 requires I-JSON, which forbids a lone surrogate. JSON.stringify
+    // would escape it as \udXXX and sign bytes no other serializer produces;
+    // the protocol says refuse, never sign (Signing Canonicalization, rule 5).
+    throw new Error('canonicalize: string contains a lone surrogate and cannot be signed');
+  }
   if (value === null || typeof value !== 'object') {
     return JSON.stringify(value);
   }

package/src/commitment-modes.ts

@@ -1,21 +1,26 @@
 /**
  * Which commitment modes a profile allows its mandates to be signed with
- * (`AgentProfile.commitment_modes`). One source for the Authority Server's
- * refusal and the mandate screen's choice, so the two cannot disagree.
+ * (`AgentProfile.commitment_modes`; protocol.md → *Commitment Modes*, rule
+ * 8). One source for the Authority Server's refusal and the mandate screen's
+ * choice, so the two cannot disagree.
  */
-import type { AgentProfile, SignableCommitmentMode } from './types';
+import type { AgentProfile, CommitmentMode, SignableCommitmentMode } from './types';
 
 /** Every mode a signer can choose, in the order a mandate screen shows them. */
 export const SIGNABLE_COMMITMENT_MODES: readonly SignableCommitmentMode[] = ['review', 'automatic'];
 
+/** Every mode a signed mandate can carry. */
+export const COMMITMENT_MODES: readonly CommitmentMode[] = ['automatic', 'review', 'review_above_cap'];
+
 const isSignable = (v: unknown): v is SignableCommitmentMode =>
   typeof v === 'string' && (SIGNABLE_COMMITMENT_MODES as readonly string[]).includes(v);
 
 /**
- * The modes a mandate under this profile may carry, in display order.
- * No declaration → all of them. A declaration is read fail-closed: entries
- * that are not a signable mode are dropped, so a malformed list can only
- * narrow — `[]`, `"review"` (not a list) or `["reveiw"]` allow nothing.
+ * The signable modes a mandate under this profile may carry, in display
+ * order. No declaration → all of them. A declaration is read fail-closed:
+ * entries that are not a signable mode are dropped (`review_above_cap` is
+ * ignored by rule 8 — it follows from `automatic`), so a malformed list can
+ * only narrow — `[]`, `"review"` (not a list) or `["reveiw"]` allow nothing.
  */
 export function allowedCommitmentModes(profile: AgentProfile): readonly SignableCommitmentMode[] {
   const declared = (profile as { commitment_modes?: unknown }).commitment_modes;
@@ -24,7 +29,14 @@ export function allowedCommitmentModes(profile: AgentProfile): readonly Signable
   return SIGNABLE_COMMITMENT_MODES.filter((m) => declared.includes(m));
 }
 
-/** Whether a mandate under this profile may be signed with `mode`. */
+/**
+ * Whether a mandate under this profile may be SIGNED with `mode` (rule 8):
+ * `automatic` and `review` where listed; `review_above_cap` if and only if
+ * `automatic` is admitted. The Authority Server refuses any other with
+ * `COMMITMENT_MODE_NOT_ALLOWED`.
+ */
 export function isCommitmentModeAllowed(profile: AgentProfile, mode: string): boolean {
-  return isSignable(mode) && allowedCommitmentModes(profile).includes(mode);
+  const allowed = allowedCommitmentModes(profile);
+  if (mode === 'review_above_cap') return allowed.includes('automatic');
+  return isSignable(mode) && allowed.includes(mode);
 }

package/src/errors.ts

@@ -1,16 +1,12 @@
 /**
- * Canonical v0.7 error codes — protocol.md → *Error Codes*.
+ * Canonical v0.8 error codes — protocol.md → *Error Codes*.
  *
  * "Error codes are canonical across the protocol. Implementations MUST emit
  * exactly these codes and MUST NOT alias them under different names." This
  * module is the single list both the Gatekeeper (local checks) and any AS
  * client built on this library read from, so the two cannot drift.
  *
- * v0.7 renamed every code that carried a retired word (attestation → mandate,
- * context → scope, receipt → ticket) — see protocol.md → *Migration from
- * v0.6* → "Error-code renames" for the old→new map. There is no alias: a v0.6
- * code name is simply gone from this list, by design (no backward
- * compatibility — CLAUDE.md "Decided by the owner").
+ * v0.8 adds codes and retires none; every v0.7 code keeps its name.
  */
 
 /** Codes an Authority Server (or a local Gatekeeper check) emits refusing a mandate request. */
@@ -30,11 +26,14 @@ export const MANDATE_ERROR_CODES = [
   'BOUNDS_INVALID_VALUE',
   'SCOPE_INVALID_VALUE',
   'ABOVE_CAP_CONFIG_INVALID',
+  'COMMITMENT_MODE_NOT_ALLOWED', // v0.8
+  'GROUP_CAP_EXCEEDED', // v0.8
   'OWNER_SIGNATURE_REQUIRED',
   'OWNER_SIGNATURE_INVALID',
 ] as const;
 
-/** Codes an Authority Server emits refusing a ticket request. */
+/** Codes an Authority Server emits refusing a ticket request, plus the
+ * Gatekeeper-local and verifier codes of the same table. */
 export const TICKET_ERROR_CODES = [
   'MANDATE_NOT_FOUND',
   'MANDATE_EXPIRED',
@@ -45,6 +44,8 @@ export const TICKET_ERROR_CODES = [
   'PROFILE_NOT_FOUND',
   'INVALID_ACTION_TYPE',
   'APPROVAL_REQUIRED',
+  'APPROVAL_IMPOSSIBLE', // v0.8
+  'PROPOSAL_CONTENT_MISMATCH', // v0.8
   'PROPOSAL_REQUIRED',
   'PROPOSAL_NOT_FOUND',
   'PROPOSAL_NOT_APPROVED',
@@ -53,15 +54,30 @@ export const TICKET_ERROR_CODES = [
   'PROPOSAL_MISMATCH',
   'PROPOSAL_MANDATE_MISMATCH',
   'PROPOSAL_ALREADY_EXECUTED',
+  'PROPOSAL_WITHDRAWN', // v0.8
   'MALFORMED_TICKET_REQUEST',
+  'CONTENT_BINDING_INCOMPLETE', // v0.8, Gatekeeper · local
   'IDEMPOTENCY_KEY_REQUIRED',
   'IDEMPOTENCY_MISMATCH',
   'APPROVAL_SIGNATURE_REQUIRED',
   'APPROVAL_SIGNATURE_INVALID',
+  'TICKET_REQUEST_MISMATCH', // v0.8, Gatekeeper · local
+  'POLICY_UNMET', // v0.8, Verifier
+] as const;
+
+/** Codes an Authority Server emits refusing a proposal submission or a decision (v0.8). */
+export const PROPOSAL_ERROR_CODES = [
+  'PROPOSAL_NOT_ENCRYPTED',
+  'DECIDER_INVALID',
+  'PROPOSAL_ALREADY_DECIDED',
+  'PROPOSAL_APPROVERS_INVALID',
 ] as const;
 
 /** The full canonical surface — every code a conformant implementation may emit. */
-export type HapErrorCode = (typeof MANDATE_ERROR_CODES)[number] | (typeof TICKET_ERROR_CODES)[number];
+export type HapErrorCode =
+  | (typeof MANDATE_ERROR_CODES)[number]
+  | (typeof TICKET_ERROR_CODES)[number]
+  | (typeof PROPOSAL_ERROR_CODES)[number];
 
 /**
  * A refusal carrying one of the canonical codes above. Thrown by local

package/src/gatekeeper.ts

@@ -1,5 +1,6 @@
 /**
- * Gatekeeper — local (Phase 1) verification for bounded execution (v0.7).
+ * Gatekeeper — local (Phase 1) verification for bounded execution (v0.8;
+ * v0.7 mandates verified under their own rules).
  *
  * protocol.md → *Validation Steps* (Phase 1, never reaches the wire):
  *   1. Resolve profile from bounds.profile
@@ -24,12 +25,13 @@
  * frame-based path is retired entirely (CLAUDE.md "Decided by the owner").
  */
 
-import { decodeMandateBlob, verifyMandateSignature, checkMandateExpiry, validateMandateOwners } from './mandate';
+import { decodeMandateBlob, verifyMandateSignature, checkMandateExpiry, validateMandateOwners, validateAboveCapFields } from './mandate';
+import { checkExecutionValues, missingSumFields } from './issuance';
 import { canonicalBounds, canonicalScope, computeBoundsHash, computeScopeHash, CanonicalValueError } from './frame';
 import { computeProfileHash } from './profile';
 import { getProfile } from './profiles';
 import { HapError, type HapErrorCode } from './errors';
-import { PROTOCOL_VERSION } from './versions';
+import { isSupportedVersion, SUPPORTED_VERSIONS } from './versions';
 import type {
   GatekeeperRequest,
   GatekeeperResult,
@@ -112,8 +114,9 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
 
   // 3. Verify every mandate blob.
   const errors: GatekeeperError[] = [];
+  const verifiedPayloads: MandatePayload[] = [];
   for (const blob of request.mandates) {
-    const mandateErrors = await verifyOneMandate(blob, {
+    const { errors: mandateErrors, payload } = await verifyOneMandate(blob, {
       expectedBoundsHash,
       expectedScopeHash,
       expectedProfileHash,
@@ -121,6 +124,7 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
       now,
     });
     errors.push(...mandateErrors);
+    if (payload) verifiedPayloads.push(payload);
   }
   if (errors.length > 0) {
     return { approved: false, errors };
@@ -144,7 +148,37 @@ export async function verify(request: GatekeeperRequest, opts: VerifyOptions = {
     }
   }
 
-  // 5. per_transaction bounds and enum capability flags, locally.
+  // 5. Every value a bound reads is a finite, non-negative number
+  // (Validation Steps, step 8; v0.8) — before any bound is compared.
+  try {
+    checkExecutionValues(request.execution, profile);
+  } catch (err) {
+    return { approved: false, errors: [{ code: codeFromThrown(err), message: (err as Error).message }] };
+  }
+  // A cumulative_sum bound that governs this action type and reads an absent
+  // field is refused locally too — unless an above-cap approval is in play:
+  // where a mandate caps that field, an absent value is "above the cap" and
+  // the AS routes it to approval (Ticket Issuance, stage 7).
+  if (actionType !== undefined) {
+    const capped = new Set<string>();
+    for (const p of verifiedPayloads) {
+      for (const name of Object.keys(p.above_cap_caps ?? {})) {
+        const bt = profile.boundsSchema?.fields[name]?.boundType;
+        if (bt && bt.kind === 'per_transaction') capped.add(bt.of);
+      }
+    }
+    const missing = missingSumFields(request.execution, profile, actionType).filter((m) => !capped.has(m.field));
+    if (missing.length > 0) {
+      return {
+        approved: false,
+        errors: missing.map(({ bound, field }) => ({
+          code: 'BOUND_EXCEEDED' as const,
+          field,
+          message: `Bound "${bound}" governs "${actionType}" and reads "${field}", but this call exposes no ${field}. Refusing: an action without an amount would consume nothing of the limit (v0.8: a missing amount fails safe).`,
+        })),
+      };
+    }
+  }
   const boundsErrors = checkBounds(request, profile, actionType);
   if (boundsErrors.length > 0) {
     return { approved: false, errors: boundsErrors };
@@ -197,7 +231,16 @@ function codeFromThrown(err: unknown): HapErrorCode {
   return 'MALFORMED_MANDATE';
 }
 
-async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promise<GatekeeperError[]> {
+async function verifyOneMandate(
+  blob: string,
+  opts: MandateCheckOptions,
+): Promise<{ errors: GatekeeperError[]; payload?: MandatePayload }> {
+  const errors = await verifyOneMandateErrors(blob, opts);
+  if (errors.length > 0) return { errors };
+  return { errors, payload: decodeMandateBlob(blob).payload };
+}
+
+async function verifyOneMandateErrors(blob: string, opts: MandateCheckOptions): Promise<GatekeeperError[]> {
   let mandate: Mandate;
   try {
     mandate = decodeMandateBlob(blob);
@@ -205,10 +248,10 @@ async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promis
     return [{ code: 'MALFORMED_MANDATE', message: (err as Error).message }];
   }
 
-  if (mandate.payload.version !== PROTOCOL_VERSION) {
+  if (!isSupportedVersion(mandate.payload.version)) {
     return [{
       code: 'VERSION_UNSUPPORTED',
-      message: `mandate version ${JSON.stringify(mandate.payload.version)} is not verifiable by this Gatekeeper (verifies ${PROTOCOL_VERSION} only)`,
+      message: `mandate version ${JSON.stringify(mandate.payload.version)} is not verifiable by this Gatekeeper (verifies [${SUPPORTED_VERSIONS.join(', ')}])`,
     }];
   }
 
@@ -226,6 +269,7 @@ async function verifyOneMandate(blob: string, opts: MandateCheckOptions): Promis
 
   try {
     validateMandateOwners(mandate.payload);
+    validateAboveCapFields(mandate.payload);
   } catch (err) {
     return [{ code: codeFromThrown(err), message: (err as Error).message }];
   }

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * HAP Core — v0.7 ("mandate" / "ticket" / "scope" / "Mandate Owner")
+ * HAP Core — v0.8 (issues 0.8; verifies 0.8 and 0.7, each under its own rules)
  *
  * Shared protocol logic for agent-oriented bounded execution.
  */
@@ -18,6 +18,10 @@ export * from './profile';
 export * from './mandate';
 export * from './owner-signature';
 export * from './ticket';
+export * from './ticket-projection';
+export * from './verifier-policy';
+export * from './proposal-content';
+export * from './issuance';
 export * from './gatekeeper';
 export * from './profiles';
 export * from './did-key';

package/src/issuance.ts

@@ -0,0 +1,250 @@
+/**
+ * Pure checks both enforcement points apply around issuance and execution
+ * (v0.8). An Authority Server composes them into its stage order
+ * (protocol.md → *Mandate Issuance & Validation*, *Ticket Issuance*); a
+ * Gatekeeper applies the execution-side ones locally (*Validation Steps*).
+ * They live here so the two cannot disagree about what a value means.
+ */
+
+import { createHash } from 'crypto';
+import { canonicalize } from './canonicalize';
+import { HapError } from './errors';
+import { isKeyBearingDid } from './did-key';
+import type { AgentProfile, AgentBoundsParams, MandatePayload, ProfileBoundsField } from './types';
+
+/**
+ * `execution_context_hash` — sha256 over the JCS of the profile's
+ * `executionContextSchema`, or of `{}` when the profile has none (protocol.md
+ * → *Execution Context Schema*, stated in v0.8).
+ */
+export function computeExecutionContextHash(profile: Pick<AgentProfile, 'executionContextSchema'>): string {
+  const schema = profile.executionContextSchema ?? {};
+  return `sha256:${createHash('sha256').update(canonicalize(schema), 'utf8').digest('hex')}`;
+}
+
+/** The execution-context fields some bound of the profile reads
+ * (`boundType.of` of every `per_transaction` and `cumulative_sum` bound). */
+export function boundReadFields(profile: AgentProfile): Set<string> {
+  const fields = new Set<string>();
+  for (const def of Object.values(profile.boundsSchema?.fields ?? {})) {
+    const bt = def.boundType;
+    if (bt && (bt.kind === 'per_transaction' || bt.kind === 'cumulative_sum')) fields.add(bt.of);
+  }
+  return fields;
+}
+
+/**
+ * Build the wire execution context (*Validation Steps*, step 11; *Ticket
+ * Request Schema*, rules 7–8): only what a bound reads travels. `action_type`
+ * travels as the request's own `actionType`, scope values never travel,
+ * `_`-prefixed keys are advisory metadata. A `null` value is no value.
+ */
+export function wireExecutionContext(
+  execution: Record<string, unknown>,
+  profile: AgentProfile,
+): Record<string, unknown> {
+  const allowed = boundReadFields(profile);
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(execution)) {
+    if (!allowed.has(k) || k.startsWith('_') || v === undefined || v === null) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Every value present for a field some bound reads MUST be a finite,
+ * non-negative number (*Ticket Issuance*, stage 7; *Validation Steps*, step
+ * 8). `null` counts as absent. A `_`-prefixed key is refused.
+ * @throws HapError `MALFORMED_TICKET_REQUEST`
+ */
+export function checkExecutionValues(execution: Record<string, unknown>, profile: AgentProfile): void {
+  for (const k of Object.keys(execution)) {
+    if (k.startsWith('_')) {
+      throw new HapError('MALFORMED_TICKET_REQUEST', `executionContext key "${k}" is reserved and MUST NOT travel`);
+    }
+  }
+  for (const field of boundReadFields(profile)) {
+    const v = execution[field];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) {
+      throw new HapError(
+        'MALFORMED_TICKET_REQUEST',
+        `executionContext.${field} MUST be a finite, non-negative number, got ${JSON.stringify(v)}`,
+      );
+    }
+  }
+}
+
+/** Whether a cumulative bound governs this action type: its `appliesTo`
+ * names it, or it has none (Bounds Schema rule 7). */
+export function boundGoverns(def: ProfileBoundsField, actionType: string): boolean {
+  return !def.appliesTo || def.appliesTo.includes(actionType);
+}
+
+/**
+ * The `cumulative_sum` bounds that govern this action type and whose field is
+ * absent from the execution context (*Ticket Issuance*, stage 7): each is a
+ * `BOUND_EXCEEDED`, unless a committed above-cap approval covers the action.
+ */
+export function missingSumFields(
+  execution: Record<string, unknown>,
+  profile: AgentProfile,
+  actionType: string,
+): Array<{ bound: string; field: string }> {
+  const missing: Array<{ bound: string; field: string }> = [];
+  for (const [name, def] of Object.entries(profile.boundsSchema?.fields ?? {})) {
+    const bt = def.boundType;
+    if (!bt || bt.kind !== 'cumulative_sum' || !boundGoverns(def, actionType)) continue;
+    const v = execution[bt.of];
+    if (v === undefined || v === null) missing.push({ bound: name, field: bt.of });
+  }
+  return missing;
+}
+
+/**
+ * Bounds values against the profile at issuance (*Mandate Issuance*, stage
+ * 4): a number where the field is numeric (`"100"` is refused), no higher
+ * than a declared `maximum`, and an `enum` value in its `values`.
+ * @throws HapError `BOUNDS_INVALID_VALUE`
+ */
+export function checkBoundsValues(bounds: AgentBoundsParams, profile: AgentProfile): void {
+  for (const [name, def] of Object.entries(profile.boundsSchema?.fields ?? {})) {
+    if (name === 'profile') continue;
+    const v = bounds[name];
+    if (v === undefined || v === null) continue;
+    if (def.type === 'number' || def.maximum !== undefined) {
+      if (typeof v !== 'number' || !Number.isFinite(v)) {
+        throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" MUST be a number, got ${JSON.stringify(v)}`);
+      }
+      if (def.maximum !== undefined && v > def.maximum) {
+        throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" = ${v} exceeds the profile's maximum ${def.maximum}`);
+      }
+    }
+    const bt = def.boundType;
+    if (bt?.kind === 'enum' && !bt.values.includes(String(v))) {
+      throw new HapError('BOUNDS_INVALID_VALUE', `bound "${name}" = ${JSON.stringify(v)} is not in [${bt.values.join(', ')}]`);
+    }
+  }
+}
+
+/** A group's caps for one profile, as the AS holds them. */
+export interface GroupCaps {
+  /** Caps a proposal may lift (`approval` kind) — numeric per_transaction fields only. */
+  approval?: Record<string, number>;
+  /** Hard caps: refused at signing, never routed. Numeric or enum values. */
+  hard?: Record<string, number | string>;
+}
+
+/**
+ * Whether a bound value exceeds a cap. For an `enum` bound the cap is one of
+ * its values, and a value that comes EARLIER in the profile's `values` order
+ * (more permissive) exceeds it (Bounds Schema rule 10; *Group ceilings*).
+ */
+export function exceedsCap(value: string | number, cap: string | number, def: ProfileBoundsField): boolean {
+  const bt = def.boundType;
+  if (bt?.kind === 'enum') {
+    const order = bt.values;
+    const vi = order.indexOf(String(value));
+    const ci = order.indexOf(String(cap));
+    if (vi < 0 || ci < 0) return true; // an unknown value or cap fails closed
+    return vi < ci;
+  }
+  return typeof value !== 'number' || typeof cap !== 'number' || value > cap;
+}
+
+/**
+ * Hard group ceilings at signing (*Group ceilings*; *Group roles*, rule 5):
+ * a cap on a bound the Gatekeeper alone enforces (`enforcedBy: "gatekeeper"`)
+ * or on an `enum` bound is always hard, as is every cap in `hard`; a bound
+ * above one, or an optional bound omitted where a cap exists, is refused.
+ * Caps in `approval` on a cumulative bound are hard too (Commitment Modes,
+ * rule 7). An omitted REQUIRED bound is `MALFORMED_MANDATE`, checked
+ * elsewhere.
+ * @throws HapError `GROUP_CAP_EXCEEDED`
+ */
+export function checkGroupCeilings(bounds: AgentBoundsParams, profile: AgentProfile, caps: GroupCaps): void {
+  const fields = profile.boundsSchema?.fields ?? {};
+  const hard: Record<string, number | string> = { ...(caps.hard ?? {}) };
+  for (const [name, cap] of Object.entries(caps.approval ?? {})) {
+    const def = fields[name];
+    const bt = def?.boundType;
+    if (!def || !bt) continue;
+    if (bt.kind !== 'per_transaction' || def.enforcedBy === 'gatekeeper') hard[name] = cap;
+  }
+  for (const [name, def] of Object.entries(fields)) {
+    if (name === 'profile') continue;
+    const cap = hard[name];
+    if (cap === undefined) continue;
+    const v = bounds[name];
+    if (v === undefined || v === null) {
+      if (!def.required) {
+        throw new HapError('GROUP_CAP_EXCEEDED', `bound "${name}" is omitted under a group ceiling of ${JSON.stringify(cap)} — an omitted bound is unlimited`);
+      }
+      continue;
+    }
+    if (exceedsCap(v, cap, def)) {
+      throw new HapError('GROUP_CAP_EXCEEDED', `bound "${name}" = ${JSON.stringify(v)} exceeds the group's hard cap ${JSON.stringify(cap)}`);
+    }
+  }
+}
+
+/**
+ * The above-cap configuration a mandate request or a group supplies
+ * (*Commitment Modes*, rule 7; *Group roles*, rules 2 and 4; Mandate rule
+ * 10): caps name numeric `per_transaction` bounds of the profile and never
+ * `profile`; approvers are key-bearing DIDs; outside a group the count is an
+ * integer ≥ 1 and no greater than the approvers other than the owner.
+ * @throws HapError `ABOVE_CAP_CONFIG_INVALID`
+ */
+export function validateAboveCapConfig(
+  config: { caps?: Record<string, number>; approvers?: readonly string[]; approvals?: number },
+  profile: AgentProfile,
+  opts: { ownerDid: string; inGroup: boolean },
+): void {
+  const fields = profile.boundsSchema?.fields ?? {};
+  for (const name of Object.keys(config.caps ?? {})) {
+    if (name === 'profile') throw new HapError('ABOVE_CAP_CONFIG_INVALID', 'above_cap_caps MUST NOT name profile');
+    const def = fields[name];
+    if (!def || def.boundType?.kind !== 'per_transaction' || def.type !== 'number') {
+      throw new HapError('ABOVE_CAP_CONFIG_INVALID', `above_cap_caps names "${name}", which is not a numeric per_transaction bound of ${profile.id}`);
+    }
+  }
+  for (const did of config.approvers ?? []) {
+    if (!isKeyBearingDid(did)) {
+      throw new HapError('ABOVE_CAP_CONFIG_INVALID', `above-cap approver ${did} is not a key-bearing DID`);
+    }
+  }
+  if (config.approvers !== undefined && !opts.inGroup) {
+    const others = config.approvers.filter((d) => d !== opts.ownerDid).length;
+    const n = config.approvals;
+    if (n === undefined || !Number.isInteger(n) || n < 1 || n > others) {
+      throw new HapError(
+        'ABOVE_CAP_CONFIG_INVALID',
+        `above_cap_approvals MUST be an integer between 1 and the ${others} approver(s) other than the owner, got ${JSON.stringify(n)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Whether a request exceeds an approval-kind cap of the mandate, or — v0.8 —
+ * the field the cap reads is absent (an action of unknown amount is above
+ * the cap). Returns the offending caps.
+ */
+export function capsExceeded(
+  execution: Record<string, unknown>,
+  mandate: Pick<MandatePayload, 'above_cap_caps'>,
+  profile: AgentProfile,
+): Array<{ bound: string; field: string; cap: number; value: unknown }> {
+  const out: Array<{ bound: string; field: string; cap: number; value: unknown }> = [];
+  for (const [name, cap] of Object.entries(mandate.above_cap_caps ?? {})) {
+    const bt = profile.boundsSchema?.fields[name]?.boundType;
+    if (!bt || bt.kind !== 'per_transaction') continue;
+    const v = execution[bt.of];
+    if (v === undefined || v === null || typeof v !== 'number' || v > cap) {
+      out.push({ bound: name, field: bt.of, cap, value: v });
+    }
+  }
+  return out;
+}

package/src/mandate.ts

@@ -4,9 +4,10 @@
  * Renamed from `attestation.ts` (protocol.md → *Migration from v0.6*:
  * `header.typ: "HAP-attestation"` → `"HAP-mandate"`, `attestation_id` →
  * `mandate_id`). v0.3's frame-hash path and v0.4's dual frame/bounds
- * verification are retired with the rest of pre-v0.5 — this module issues
- * and verifies `version: "0.7"` mandates only (CLAUDE.md "Decided by the
- * owner": no backward-compat verify path for 0.5/0.6).
+ * verification are retired with the rest of pre-v0.5. This module issues
+ * `version: "0.8"` mandates and verifies `"0.8"` and `"0.7"` ones, each
+ * under its own rules (protocol.md → *Version negotiation*, rule 4): v0.8
+ * is a re-grant release, and a v0.7 artifact stays verifiable as evidence.
  */
 
 import { createHash } from 'crypto';
@@ -15,7 +16,7 @@ import { canonicalize } from './canonicalize';
 import { toBase64Url, fromBase64Url } from './base64url';
 import { decodeDidKey, isKeyBearingDid } from './did-key';
 import { HapError } from './errors';
-import { PROTOCOL_VERSION } from './versions';
+import { assertSupportedVersion, SUPPORTED_VERSIONS } from './versions';
 import type { Mandate, MandateHeader, MandatePayload } from './types';
 
 /** Clock-skew tolerance (Mandate rule 9): `issued_at`/`expires_at` checks
@@ -162,7 +163,7 @@ export function validateMandateOwners(payload: MandatePayload): void {
   if (!Array.isArray(owners) || owners.length !== 1) {
     throw new HapError(
       'MALFORMED_MANDATE',
-      `mandate_owners MUST contain exactly one entry in v0.7, got ${Array.isArray(owners) ? owners.length : typeof owners}`,
+      `mandate_owners MUST contain exactly one entry (Mandate rule 7), got ${Array.isArray(owners) ? owners.length : typeof owners}`,
     );
   }
   const entry = owners[0];
@@ -184,15 +185,57 @@ export function validateMandateOwners(payload: MandatePayload): void {
   }
 }
 
+/**
+ * The above-cap fields travel together (Mandate rule 10; *Group roles*,
+ * rule 7). Under v0.8 `above_cap_approvals` is present exactly when
+ * `above_cap_approvers` is, an integer ≥ 1; under v0.7 there is no count and
+ * caps + approvers are present exactly under `review_above_cap`.
+ *
+ * @throws HapError `MALFORMED_MANDATE`
+ */
+export function validateAboveCapFields(payload: MandatePayload): void {
+  const hasCaps = payload.above_cap_caps !== undefined;
+  const hasApprovers = payload.above_cap_approvers !== undefined;
+  const hasCount = payload.above_cap_approvals !== undefined;
+  if (hasCaps !== hasApprovers) {
+    throw new HapError('MALFORMED_MANDATE', 'above_cap_caps and above_cap_approvers are present together or absent together');
+  }
+  if (payload.commitment_mode === 'review_above_cap' && !hasApprovers) {
+    throw new HapError('MALFORMED_MANDATE', 'a review_above_cap mandate MUST carry above_cap_caps and above_cap_approvers');
+  }
+  if (payload.version === '0.7') {
+    if (hasCount) {
+      throw new HapError('MALFORMED_MANDATE', 'a v0.7 mandate carries no above_cap_approvals');
+    }
+    if (hasApprovers && payload.commitment_mode !== 'review_above_cap') {
+      throw new HapError('MALFORMED_MANDATE', 'a v0.7 mandate carries above-cap fields only under review_above_cap');
+    }
+    return;
+  }
+  if (hasApprovers !== hasCount) {
+    throw new HapError('MALFORMED_MANDATE', 'above_cap_approvals is present exactly when above_cap_approvers is (Mandate rule 10)');
+  }
+  if (hasCount) {
+    const n = payload.above_cap_approvals as unknown;
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+      throw new HapError('MALFORMED_MANDATE', `above_cap_approvals MUST be an integer >= 1, got ${JSON.stringify(n)}`);
+    }
+  }
+  if (hasApprovers && payload.commitment_mode === 'automatic') {
+    throw new HapError('MALFORMED_MANDATE', 'an automatic mandate carries no above-cap fields');
+  }
+}
+
 /**
  * Full mandate verification: decode, check `version`, verify the AS
- * signature, check expiry, validate `mandate_owners` shape.
+ * signature, check expiry, validate `mandate_owners` shape and the above-cap
+ * fields.
  *
  * Deliberately does NOT verify any `mandate_owners` co-signature — that is
  * `verifyOwnerSignature` in `owner-signature.ts`, a separate trust axis the
  * caller opts into.
  *
- * @throws HapError `VERSION_UNSUPPORTED` for anything other than `"0.7"`.
+ * @throws HapError `VERSION_UNSUPPORTED` for a version outside {@link SUPPORTED_VERSIONS}.
  * @throws Error (`INVALID_SIGNATURE:` / `TTL_EXPIRED:` / `MALFORMED_MANDATE:`
  * prefixed, or `OWNER_SIGNATURE_INVALID` as a HapError) on any other failure.
  */
@@ -202,17 +245,12 @@ export async function verifyMandate(
 ): Promise<MandatePayload> {
   const mandate = decodeMandateBlob(blob);
 
-  if (mandate.payload.version !== PROTOCOL_VERSION) {
-    throw new HapError(
-      'VERSION_UNSUPPORTED',
-      `mandate version ${JSON.stringify(mandate.payload.version)} is not verifiable by this implementation ` +
-        `(verifies ${PROTOCOL_VERSION} only — re-issue the mandate)`,
-    );
-  }
+  assertSupportedVersion(mandate.payload.version, 'mandate');
 
   await verifyMandateSignature(mandate, opts);
   checkMandateExpiry(mandate.payload, opts?.now);
   validateMandateOwners(mandate.payload);
+  validateAboveCapFields(mandate.payload);
 
   return mandate.payload;
 }