@suveren/gateway 0.19.4 → 0.20.0

package/node_modules/@hap/core/src/owner-signature.ts

@@ -0,0 +1,282 @@
+/**
+ * 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"`).
+ *
+ * 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
+ * PROJECTION: a canonical object every field of which is known at approval
+ * time and reconstructible from the finished mandate — so a verifier
+ * rebuilds it from the mandate 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 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 → "Verification
+ * procedure" step 5), and it is the honest cost of cold verification.
+ */
+
+import * as ed from '@noble/ed25519';
+import type { Mandate, MandatePayload, MandateOwnerEntry, OwnerSignatureBinding, ProfileOwnerSignatureFloor } from './types';
+import { canonicalize } from './canonicalize';
+import { decodeDidKey } from './did-key';
+import { toBase64Url, fromBase64Url } from './base64url';
+import type { HapErrorCode } from './errors';
+
+/** The object the owner signs — a canonical projection of the mandate.
+ * Field absence is defined, not incidental (protocol.md → *The signed
+ * object: HAP-mandate-projection*): each conditional field is included
+ * exactly when the mandate carries it and omitted otherwise. */
+export interface MandateProjection {
+  typ: 'HAP-mandate-projection';
+  /** Projection/canonicalization version. A verifier MUST pin it. */
+  version: '0.7';
+  profile_id: string;
+  /** Covered deliberately: the owner signs the profile's BYTES, not only its id. */
+  profile_hash: string;
+  /** The signing owner's own DID. MUST equal the carrying mandate's `mandate_owners[0].did`. */
+  owner_did: string;
+  bounds_hash: string;
+  scope_hash: string;
+  execution_context_hash: string;
+  gate_content_hashes: Record<string, string>;
+  /** 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"`. */
+  above_cap_caps?: Record<string, number>;
+  above_cap_approvers?: string[];
+  /** 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;
+}
+
+/** 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.7';
+  proposal_id: string;
+  /** Renamed from `attestation_id` in v0.7. */
+  mandate_id: 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. */
+  content_hash: string;
+  decided_at: number;
+  nonce: string;
+}
+
+/** Renamed from `MandateError` in v0.7 — carries a canonical {@link HapErrorCode}. */
+export class OwnerSignatureError extends Error {
+  constructor(public code: HapErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'OwnerSignatureError';
+  }
+}
+
+/** Decode a signature, refusing non-base64url input with THIS artifact's code
+ *  — decoding sits outside the `.catch(() => false)` of the verify call, so
+ *  without this a malformed owner or approval signature escaped with no code. */
+function decodeOrThrow(signature: string, code: HapErrorCode): Uint8Array {
+  try {
+    return fromBase64Url(signature);
+  } catch (err) {
+    throw new OwnerSignatureError(code, (err as Error).message);
+  }
+}
+
+/**
+ * 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.
+ */
+export function buildMandateProjection(
+  payload: MandatePayload,
+  entry: Pick<MandateOwnerEntry, 'did' | 'nonce'>,
+): MandateProjection {
+  const {
+    profile_id, profile_hash, bounds_hash, scope_hash, execution_context_hash,
+    gate_content_hashes, commitment_mode, expires_at,
+  } = payload;
+  if (!profile_hash || !bounds_hash || !scope_hash || !commitment_mode) {
+    throw new OwnerSignatureError(
+      'MALFORMED_MANDATE',
+      'mandate projection requires profile_hash, bounds_hash, scope_hash and commitment_mode',
+    );
+  }
+  const projection: MandateProjection = {
+    typ: 'HAP-mandate-projection',
+    version: '0.7',
+    profile_id,
+    profile_hash,
+    owner_did: entry.did,
+    bounds_hash,
+    scope_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;
+  }
+  if (payload.commitment_mode === 'review_above_cap') {
+    projection.above_cap_caps = payload.above_cap_caps;
+    projection.above_cap_approvers = payload.above_cap_approvers;
+  }
+  if (payload.disclose_fields !== undefined) {
+    projection.disclose_fields = payload.disclose_fields;
+  }
+  return projection;
+}
+
+/** The exact bytes an owner signs: RFC 8785 (JCS) canonical UTF-8. Renamed
+ * from `mandateSigningBytes` in v0.7. */
+export function projectionSigningBytes(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));
+}
+
+/**
+ * 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> {
+  return toBase64Url(await ed.signAsync(projectionSigningBytes(projection), privateKey));
+}
+
+/** Sign an approval object with a raw Ed25519 private key (`raw` binding). */
+export async function signApproval(approval: ApprovalObject, privateKey: Uint8Array): Promise<string> {
+  return toBase64Url(await ed.signAsync(approvalSigningBytes(approval), privateKey));
+}
+
+/**
+ * Verify ONE `mandate_owners` entry against the mandate that carries it.
+ *
+ * Steps (protocol.md → "Verification procedure", step 4 of 6): the entry
+ * names this mandate's sole owner, its signing DID is key-bearing,
+ * projection reconstruction, Ed25519 over JCS bytes. The DID is
+ * authoritative over `alg` — a disagreement is `OWNER_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 mandate (`verifyMandateSignature`, step 1).
+ */
+export async function verifyOwnerSignature(mandate: Mandate, entry: MandateOwnerEntry): Promise<void> {
+  const owners = mandate.payload.mandate_owners ?? [];
+  if (!owners.some((o) => o.did === entry.did)) {
+    throw new OwnerSignatureError('OWNER_SIGNATURE_INVALID', `signing DID ${entry.did} is not this mandate's mandate_owners`);
+  }
+  if (entry.alg !== undefined && 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 OwnerSignatureError('OWNER_SIGNATURE_INVALID', `alg ${entry.alg} disagrees with the DID's key type (DID is authoritative)`);
+  }
+  if (!entry.signature || !entry.nonce) {
+    throw new OwnerSignatureError('OWNER_SIGNATURE_INVALID', `mandate_owners entry for ${entry.did} carries no signature to verify`);
+  }
+
+  let publicKey: Uint8Array;
+  try {
+    publicKey = decodeDidKey(entry.did);
+  } catch (err) {
+    throw new OwnerSignatureError('OWNER_SIGNATURE_INVALID', (err as Error).message);
+  }
+
+  const projection = buildMandateProjection(mandate.payload, entry);
+  const ok = await ed
+    .verifyAsync(decodeOrThrow(entry.signature, 'OWNER_SIGNATURE_INVALID'), projectionSigningBytes(projection), publicKey)
+    .catch(() => false);
+  if (!ok) {
+    throw new OwnerSignatureError('OWNER_SIGNATURE_INVALID', `owner signature by ${entry.did} does not verify`);
+  }
+}
+
+/** Verify every co-signing `mandate_owners` entry a mandate carries (i.e.
+ * every entry that carries a signature). Resolves to the verified entries;
+ * a mandate with none resolves to `[]` — nothing to check, nothing claimed. */
+export async function verifyOwnerSignatures(mandate: Mandate): Promise<MandateOwnerEntry[]> {
+  const entries = (mandate.payload.mandate_owners ?? []).filter((e) => e.signature !== undefined);
+  for (const entry of entries) {
+    await verifyOwnerSignature(mandate, 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 OwnerSignatureError('OWNER_SIGNATURE_INVALID', (err as Error).message);
+  }
+  const ok = await ed.verifyAsync(decodeOrThrow(signature, 'APPROVAL_SIGNATURE_INVALID'), approvalSigningBytes(approval), publicKey).catch(() => false);
+  if (!ok) {
+    throw new OwnerSignatureError('APPROVAL_SIGNATURE_INVALID', `approval signature by ${signerDid} does not verify`);
+  }
+}
+
+/** 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 };
+
+/**
+ * Enforce a profile's `ownerSignature` floor (protocol.md → *Owner
+ * Signatures* → "Where the requirement lives" — the profile-floor tier,
+ * 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).
+ */
+export function checkOwnerSignatureRequirement(
+  payload: MandatePayload,
+  floor: ProfileOwnerSignatureFloor | undefined,
+): void {
+  if (!floor?.required) return;
+  const entry = payload.mandate_owners[0];
+  const signed = entry?.signature !== undefined && entry?.binding !== undefined;
+  if (!signed) {
+    throw new OwnerSignatureError(
+      'OWNER_SIGNATURE_REQUIRED',
+      'this profile requires an owner signature and mandate_owners[0] carries none',
+    );
+  }
+  const minRank = floor.minBinding ? BINDING_RANK[floor.minBinding] : 0;
+  const haveRank = BINDING_RANK[entry!.binding as OwnerSignatureBinding] ?? 0;
+  if (haveRank < minRank) {
+    throw new OwnerSignatureError(
+      'OWNER_SIGNATURE_REQUIRED',
+      `this profile requires binding >= "${floor.minBinding}", mandate_owners[0] carries "${entry!.binding}"`,
+    );
+  }
+}

package/node_modules/@hap/core/src/profile.ts

@@ -0,0 +1,234 @@
+/**
+ * Profile hashing and authoring-time validation (new in v0.7).
+ *
+ * `computeProfileHash` is the AS-side and Gatekeeper-side half of
+ * `profile_hash` (protocol.md → *Profile hash*): "sha256 of the RFC 8785
+ * (JCS) serialization of the profile JSON" — over the PARSED document, never
+ * file bytes, so two parties who provisioned the same profile through
+ * different channels (a git checkout, an npm tarball, a copy with a
+ * trailing newline) always agree.
+ *
+ * `validateProfile` folds together the authoring-time checks that used to
+ * live in three places (`frame.ts`'s `validateBoundsRequiredFor`,
+ * `commitment-modes.ts`'s `validateCommitmentModes`, and nothing at all for
+ * the v0.7 structural rules) into one function returning the canonical
+ * `PROFILE_INVALID` shape an AS can emit directly. Like its predecessors,
+ * it is NOT wired into `registerProfile` — nothing in hap-core validates
+ * profile JSON at load time; call it explicitly from an authoring tool, a
+ * hap-profiles CI check, or a test.
+ */
+import { createHash } from 'crypto';
+import { canonicalize } from './canonicalize';
+import { allowedCommitmentModes, SIGNABLE_COMMITMENT_MODES } from './commitment-modes';
+import type { AgentProfile, BoundType } from './types';
+import { HapError, type HapErrorCode } from './errors';
+
+/** One authoring-time finding. `code` is always a canonical v0.7 code — in
+ * practice always `PROFILE_INVALID`, since that is the only mandate-request
+ * refusal the protocol attributes to "the profile fails validation"
+ * (protocol.md → Error Codes). */
+export interface ProfileValidationError {
+  code: HapErrorCode;
+  field?: string;
+  message: string;
+}
+
+/**
+ * `profile_hash` — `"sha256:" + sha256(JCS(parsed))`, over the PARSED
+ * profile document. Formatting, key order, and a trailing newline on disk
+ * never change it (protocol.md → *Profile hash*; conformance vector set
+ * `profile-hash.json`).
+ */
+export function computeProfileHash(parsed: unknown): string {
+  const hash = createHash('sha256').update(canonicalize(parsed), 'utf8').digest('hex');
+  return `sha256:${hash}`;
+}
+
+/** Keys retired by earlier versions. A profile authored against an old
+ * vocabulary fails loudly here instead of silently losing the field's
+ * effect (protocol.md → *Migration from v0.6*, "Signed-payload, profile, and
+ * wire renames"). */
+const RETIRED_PROFILE_KEYS: Record<string, string> = {
+  contextSchema: 'scopeSchema',
+  ownerMandate: 'ownerSignature',
+  receipt_lookup: 'ticket_lookup',
+  frameSchema: '(removed — v0.3 execution frames are retired)',
+};
+
+/**
+ * Authoring-time structural validation (protocol.md → *Bounds Schema*,
+ * *Owner Signatures* → "Where the requirement lives", *Migration from
+ * v0.6*). Returns `[]` for a clean profile; never throws.
+ */
+export function validateProfile(profile: AgentProfile): ProfileValidationError[] {
+  const errors: ProfileValidationError[] = [];
+  const p = profile as AgentProfile & Record<string, unknown>;
+
+  // ── Retired keys (v0.7 rename table) ────────────────────────────────────
+  for (const [retired, current] of Object.entries(RETIRED_PROFILE_KEYS)) {
+    if (retired in p) {
+      errors.push({
+        code: 'PROFILE_INVALID',
+        field: retired,
+        message: `"${retired}" is retired in v0.7 — use "${current}" instead.`,
+      });
+    }
+  }
+  if (Array.isArray(p.requiredGates) && (p.requiredGates as unknown[]).includes('decision_owner')) {
+    errors.push({
+      code: 'PROFILE_INVALID',
+      field: 'requiredGates',
+      message: '"decision_owner" is retired in v0.7 — the required gate is "mandate_owner".',
+    });
+  }
+
+  // ── Bounds schema ────────────────────────────────────────────────────────
+  const boundsSchema = profile.boundsSchema;
+  if (boundsSchema) {
+    const actionTypes = boundsSchema.actionTypes ? [...boundsSchema.actionTypes] : undefined;
+
+    for (const [fieldName, fieldDef] of Object.entries(boundsSchema.fields)) {
+      if (fieldName === 'profile') continue;
+
+      // Bounds Schema rule 6: no action-routing arrays. v0.4 retired execution
+      // paths; routing is the job of actionType + the tool-gating manifest.
+      const routing = ['path', 'paths'].filter((k) => k in (fieldDef as object));
+      if (routing.length > 0) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}" declares ${routing.map((k) => `"${k}"`).join(' and ')} — action-routing arrays are forbidden (Bounds Schema rule 6); use actionType and appliesTo.`,
+        });
+      }
+
+      if (!fieldDef.boundType) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}" has no boundType — enforcement semantics undefined (Bounds Schema rule 2).`,
+        });
+        continue;
+      }
+      const bt = fieldDef.boundType as BoundType & { requiredFor?: unknown };
+
+      // appliesTo on a per_transaction or enum bound (new in v0.7).
+      if (fieldDef.appliesTo && (bt.kind === 'per_transaction' || bt.kind === 'enum')) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}": appliesTo MUST NOT be declared on a ${bt.kind} bound (Bounds Schema rule 7).`,
+        });
+      }
+
+      // cumulative_count on a v0.7+ profile MUST declare appliesTo.
+      if (bt.kind === 'cumulative_count' && !fieldDef.appliesTo?.length) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}": a cumulative_count bound on a v0.7+ profile MUST declare appliesTo (Bounds Schema rule 7) — absence would silently throttle every action type.`,
+        });
+      }
+
+      // appliesTo members MUST be drawn from the actionTypes registry.
+      if (fieldDef.appliesTo && actionTypes) {
+        for (const at of fieldDef.appliesTo) {
+          if (!actionTypes.includes(at)) {
+            errors.push({
+              code: 'PROFILE_INVALID',
+              field: fieldName,
+              message: `Bounds field "${fieldName}": appliesTo names "${at}", which is not in boundsSchema.actionTypes [${actionTypes.join(', ')}].`,
+            });
+          }
+        }
+      }
+
+      // requiredFor is only meaningful on a per_transaction bound — every
+      // enforcement point ignores it on any other kind.
+      if (bt.kind !== 'per_transaction' && (bt as { requiredFor?: unknown }).requiredFor !== undefined) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: fieldName,
+          message: `Bounds field "${fieldName}": requiredFor is only meaningful on a per_transaction bound (found on kind "${bt.kind}") — every enforcement point ignores it there. Remove it.`,
+        });
+      }
+
+      // per_transaction.requiredFor members MUST also be registered.
+      if (bt.kind === 'per_transaction' && Array.isArray(bt.requiredFor) && actionTypes) {
+        for (const at of bt.requiredFor as string[]) {
+          if (!actionTypes.includes(at)) {
+            errors.push({
+              code: 'PROFILE_INVALID',
+              field: fieldName,
+              message: `Bounds field "${fieldName}": requiredFor names "${at}", which is not in boundsSchema.actionTypes [${actionTypes.join(', ')}].`,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // ── Commitment modes ─────────────────────────────────────────────────────
+  const declaredModes = (p as { commitment_modes?: unknown }).commitment_modes;
+  if (declaredModes !== undefined) {
+    if (!Array.isArray(declaredModes)) {
+      errors.push({ code: 'PROFILE_INVALID', field: 'commitment_modes', message: 'commitment_modes must be a list of modes.' });
+    } else {
+      if (declaredModes.length === 0) {
+        errors.push({
+          code: 'PROFILE_INVALID',
+          field: 'commitment_modes',
+          message: 'commitment_modes is empty — no mandate could ever be signed under this profile.',
+        });
+      }
+      const seen = new Set<unknown>();
+      for (const m of declaredModes) {
+        if (!(SIGNABLE_COMMITMENT_MODES as readonly string[]).includes(m as string)) {
+          errors.push({
+            code: 'PROFILE_INVALID',
+            field: 'commitment_modes',
+            message: `commitment_modes: "${String(m)}" is not a mode a signer can choose (${SIGNABLE_COMMITMENT_MODES.join(', ')}).`,
+          });
+        }
+        if (seen.has(m)) {
+          errors.push({ code: 'PROFILE_INVALID', field: 'commitment_modes', message: `commitment_modes: "${String(m)}" appears twice.` });
+        }
+        seen.add(m);
+      }
+    }
+  }
+  // allowedCommitmentModes is the fail-closed reader; an always-empty result
+  // for a profile that DID declare modes means the declaration is unusable.
+  if (Array.isArray(declaredModes) && declaredModes.length > 0 && allowedCommitmentModes(profile).length === 0) {
+    errors.push({
+      code: 'PROFILE_INVALID',
+      field: 'commitment_modes',
+      message: 'commitment_modes declares no mode this profile can actually use.',
+    });
+  }
+
+  return errors;
+}
+
+/**
+ * A mandate's `disclose_fields` MUST be a subset of the profile's own list
+ * (protocol.md → *Mandate Payload*, conditional field `disclose_fields`: "a
+ * subset of the profile's `disclose_fields` list"). A mandate may narrow
+ * disclosure, never widen it.
+ *
+ * @throws Error prefixed `MALFORMED_MANDATE:` when it is not a subset.
+ */
+export function checkDiscloseSubset(
+  mandateDiscloseFields: readonly string[] | undefined,
+  profileDiscloseFields: readonly string[] | undefined,
+): void {
+  if (!mandateDiscloseFields || mandateDiscloseFields.length === 0) return;
+  const allowed = new Set(profileDiscloseFields ?? []);
+  const widened = mandateDiscloseFields.filter((f) => !allowed.has(f));
+  if (widened.length > 0) {
+    throw new HapError(
+      'MALFORMED_MANDATE',
+      `disclose_fields [${widened.join(', ')}] is not a subset of the profile's ` +
+        `disclose_fields [${[...allowed].join(', ')}] — a mandate may narrow disclosure, never widen it.`,
+    );
+  }
+}

package/node_modules/@hap/core/src/ticket.ts

@@ -0,0 +1,148 @@
+/**
+ * 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").
+ *
+ * Ticket payloads are camelCase on the wire (unlike the snake_case mandate
+ * payload) — a shipped inconsistency the spec documents rather than breaks
+ * (protocol.md → *Migration from v0.6*, "Unchanged on purpose").
+ */
+
+import { HapError } from './errors';
+import * as ed from '@noble/ed25519';
+import type { ContentBinding, Subject } from './types';
+import { canonicalize } from './canonicalize';
+import { toBase64Url, fromBase64Url } from './base64url';
+import { decodeDidKey } from './did-key';
+
+/** Signed mandate ticket — protocol.md → *Ticket Payload Schema*. */
+export interface TicketPayload {
+  id: string;
+  /** The mandate this ticket was issued under (new in v0.7). Audit and
+   * chain-of-custody only — `boundsHash` remains the AS's lookup key. */
+  mandateId: string;
+  groupId: string | null;
+  userId?: string;
+  boundsHash: string;
+  profileId: string;
+  /** Downstream tool name. Audit metadata only — never a dispatch key. */
+  action: string;
+  /** Semantic category — drives cumulative bucketing and bounds dispatch. */
+  actionType: string;
+  executionContext: Record<string, unknown>;
+  cumulativeState?: Record<string, unknown>;
+  /** The mandate's plaintext bounds object, exactly as the AS enforced them
+   * for this ticket (new in v0.7 — required). */
+  limits: Record<string, unknown>;
+  /** Protocol version of the ticket — the version of the mandate it was
+   * issued under (new in v0.7). */
+  version: string;
+  /** The AS DID, as in the mandate (new in v0.7). */
+  issuer: string;
+  timestamp: number;
+  /** Hash of the bound content, computed by the Gatekeeper, copied
+   * verbatim by the AS. The AS never sees the content. */
+  contentHash?: string;
+  /** The binding declaration echoed into the signed ticket, so a
+   * verifier knows exactly what `contentHash` covers. */
+  contentBinding?: Pick<ContentBinding, 'version' | 'kind' | 'fields' | 'required_fields' | 'appliesTo'>;
+  /** Disclosed subset of the mandate's identity overlay. */
+  subjects?: Subject[];
+  /** Review path: the proposal this ticket executed. */
+  proposalId?: 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 };
+  /** Ed25519 over the JCS-canonical payload (this field excluded), base64url. */
+  signature: string;
+}
+
+/**
+ * Sign a ticket payload with the Authority Server's Ed25519 private key —
+ * the same key used for mandates.
+ */
+export async function signTicket(
+  payload: Omit<TicketPayload, 'signature'>,
+  privateKey: Uint8Array,
+): Promise<TicketPayload> {
+  const signature = toBase64Url(await ed.signAsync(new TextEncoder().encode(canonicalize(payload)), privateKey));
+  return { ...payload, signature };
+}
+
+/**
+ * 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}).
+ *
+ * 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.
+ */
+export async function verifyTicketSignature(
+  ticket: TicketPayload,
+  opts?: { trustedIssuers?: readonly string[] },
+): Promise<void> {
+  const { signature, ...unsigned } = ticket;
+  if (!signature) {
+    throw new HapError('INVALID_SIGNATURE', 'ticket carries no signature');
+  }
+  if (opts?.trustedIssuers && !opts.trustedIssuers.includes(ticket.issuer)) {
+    throw new HapError('INVALID_SIGNATURE', `issuer ${JSON.stringify(ticket.issuer)} is not a trusted Authority Server`);
+  }
+
+  let publicKey: Uint8Array;
+  try {
+    publicKey = decodeDidKey(ticket.issuer);
+  } catch (err) {
+    throw new HapError('INVALID_SIGNATURE', `cannot resolve a key from issuer ${JSON.stringify(ticket.issuer)}: ${(err as Error).message}`);
+  }
+
+  const bytes = new TextEncoder().encode(canonicalize(unsigned));
+  let sigBytes: Uint8Array;
+  try {
+    sigBytes = fromBase64Url(signature);
+  } catch (err) {
+    throw new HapError('INVALID_SIGNATURE', `${(err as Error).message}`);
+  }
+
+  const ok = await ed.verifyAsync(sigBytes, bytes, publicKey).catch(() => false);
+  if (!ok) {
+    throw new HapError('INVALID_SIGNATURE', 'ticket signature verification failed');
+  }
+}
+
+/**
+ * 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).
+ *
+ * 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.
+ */
+export function publicTicketView(
+  ticket: TicketPayload,
+  governingDiscloseFields: readonly string[] = [],
+): Omit<TicketPayload, 'userId' | 'cumulativeState' | 'limits'> {
+  const { userId: _userId, cumulativeState: _cumulativeState, limits: _limits, executionContext, ...rest } = ticket;
+  const allowed = new Set(governingDiscloseFields);
+  const disclosedExecutionContext: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(executionContext)) {
+    if (allowed.has(key)) disclosedExecutionContext[key] = value;
+  }
+  return { ...rest, executionContext: disclosedExecutionContext };
+}