@emilia-protocol/gate 0.18.2 → 0.20.0

package/src/action-refusal-statement.ts

@@ -0,0 +1,396 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exact-action technical refusal evidence. It is not a legal determination,
+ * an adverse-benefit denial, an authorization grant, or proof of delivery.
+ */
+import {
+  RISK_CAID, RISK_DIGEST, riskClone, riskDigest, riskExact, riskIdentifier,
+  riskInstant, riskRecord, signRiskBody, verifyRiskBody, type RiskRecord,
+  type TrustedRiskKeys,
+} from './reliance-risk-crypto.js';
+
+export const ACTION_REFUSAL_STATEMENT_VERSION = 'EP-ACTION-REFUSAL-STATEMENT-v1';
+export const ACTION_REFUSAL_CLAIM_BOUNDARY = 'technical_refusal_not_legal_or_benefit_determination';
+export const ACTION_REFUSAL_CLASSES = Object.freeze([
+  'verification_failed',
+  'action_mismatch',
+  'evidence_unsatisfied',
+  'authorization_refused',
+  'replay_detected',
+  'expired',
+  'indeterminate',
+]);
+
+const PROGRAM_KEYS = ['program_id', 'version', 'source_digest', 'program_digest'] as const;
+const DELIVERY_KEYS = ['channel', 'recipient_id', 'delivered_at', 'custody_digest'] as const;
+const CUSTODY_KEYS = ['custodian_id', 'acknowledged_at', 'evidence_digest'] as const;
+const ANCHOR_KEYS = ['method', 'evidence_digest'] as const;
+const SEMANTIC_KEYS = ['verification', 'match', 'satisfaction', 'authorization'] as const;
+const BODY_KEYS = [
+  '@version', 'refusal_id', 'relying_party_id', 'caid', 'action_digest',
+  'program', 'failed_requirement_ids', 'evidence_digests',
+  'challenge_digests', 'nonce', 'refused_at', 'expires_at', 'refusal_class',
+  'semantics', 'delivery', 'custody', 'transparency_anchor', 'claim_boundary',
+] as const;
+const INPUT_KEYS = new Set([
+  ...BODY_KEYS.filter((key) => key !== '@version' && key !== 'semantics'
+    && key !== 'delivery' && key !== 'custody' && key !== 'transparency_anchor'
+    && key !== 'challenge_digests'),
+  'semantics', 'delivery', 'custody', 'transparency_anchor',
+  'challenge_digest', 'challenge_digests',
+]);
+const EXPECTED_KEYS = [
+  'caid', 'action_digest', 'relying_party_id', 'program_id', 'program_version',
+  'source_digest', 'program_digest', 'nonce',
+] as const;
+
+const VERIFICATION = new Set(['VERIFIED', 'NOT_VERIFIED', 'INDETERMINATE']);
+const MATCH = new Set(['MATCH', 'MISMATCH', 'INDETERMINATE']);
+const SATISFACTION = new Set(['SATISFIED', 'NOT_SATISFIED', 'INDETERMINATE']);
+const AUTHORIZATION = new Set(['AUTHORIZED', 'NOT_AUTHORIZED', 'NOT_EVALUATED', 'INDETERMINATE']);
+
+export type ActionRefusalExpectedBindings = {
+  caid?: string;
+  action_digest?: string;
+  relying_party_id?: string;
+  program_id?: string;
+  program_version?: number;
+  source_digest?: string;
+  program_digest?: string;
+  nonce?: string;
+};
+
+export type ActionRefusalReplayStore = {
+  durable: boolean;
+  consume(
+    relyingPartyId: string,
+    nonce: string,
+    refusalDigest: string,
+  ): Promise<{ accepted: boolean; reason: string | null }>;
+};
+
+function canonicalSet(
+  value: unknown,
+  validator: (entry: unknown) => boolean,
+  maximum: number,
+  requireNonEmpty: boolean,
+): value is string[] {
+  if (!Array.isArray(value) || value.length > maximum
+      || (requireNonEmpty && value.length === 0) || !value.every(validator)
+      || new Set(value).size !== value.length) return false;
+  return value.every((entry, index) => index === 0
+    || Buffer.from(value[index - 1]).compare(Buffer.from(entry)) < 0);
+}
+
+function sortedUnique(
+  value: unknown,
+  validator: (entry: unknown) => boolean,
+  maximum: number,
+  label: string,
+  requireNonEmpty: boolean,
+): string[] {
+  if (!Array.isArray(value) || value.length > maximum
+      || (requireNonEmpty && value.length === 0) || !value.every(validator)) {
+    throw new TypeError(`action refusal ${label} are invalid`);
+  }
+  if (new Set(value).size !== value.length) {
+    throw new TypeError(`action refusal ${label} are duplicate`);
+  }
+  return [...value].sort((left, right) => Buffer.from(left).compare(Buffer.from(right)));
+}
+
+function defaultSemantics(refusalClass: unknown): RiskRecord {
+  const base = {
+    verification: 'VERIFIED',
+    match: 'MATCH',
+    satisfaction: 'NOT_SATISFIED',
+    authorization: 'NOT_EVALUATED',
+  };
+  if (refusalClass === 'verification_failed') return { ...base, verification: 'NOT_VERIFIED' };
+  if (refusalClass === 'action_mismatch') return { ...base, match: 'MISMATCH' };
+  if (refusalClass === 'authorization_refused') return { ...base, authorization: 'NOT_AUTHORIZED' };
+  if (refusalClass === 'indeterminate') return { ...base, satisfaction: 'INDETERMINATE' };
+  return base;
+}
+
+function validSemantics(value: unknown, refusalClass: unknown): value is RiskRecord {
+  if (!riskExact(value, SEMANTIC_KEYS)
+      || !VERIFICATION.has(value.verification) || !MATCH.has(value.match)
+      || !SATISFACTION.has(value.satisfaction) || !AUTHORIZATION.has(value.authorization)
+      || value.satisfaction === 'SATISFIED') return false;
+  if (refusalClass === 'verification_failed') return value.verification === 'NOT_VERIFIED';
+  if (refusalClass === 'action_mismatch') return value.match === 'MISMATCH';
+  if (refusalClass === 'evidence_unsatisfied') return value.satisfaction === 'NOT_SATISFIED';
+  if (refusalClass === 'authorization_refused') return value.authorization === 'NOT_AUTHORIZED';
+  if (refusalClass === 'indeterminate') return Object.values(value).includes('INDETERMINATE');
+  return true;
+}
+
+function validate(value: unknown): asserts value is RiskRecord {
+  if (!riskRecord(value)) throw new TypeError('action refusal statement shape is invalid');
+  const { issuer, ...body } = value;
+  if (issuer !== undefined && (!riskExact(issuer, ['id', 'key_id'])
+      || !riskIdentifier(issuer.id) || !riskIdentifier(issuer.key_id))) {
+    throw new TypeError('action refusal issuer is invalid');
+  }
+  if (!riskExact(body, BODY_KEYS) || body['@version'] !== ACTION_REFUSAL_STATEMENT_VERSION
+      || !riskIdentifier(body.refusal_id) || !riskIdentifier(body.relying_party_id)
+      || typeof body.caid !== 'string' || !RISK_CAID.test(body.caid)
+      || typeof body.action_digest !== 'string' || !RISK_DIGEST.test(body.action_digest)
+      || !riskExact(body.program, PROGRAM_KEYS) || !riskIdentifier(body.program.program_id)
+      || !Number.isSafeInteger(body.program.version) || body.program.version < 1
+      || typeof body.program.source_digest !== 'string' || !RISK_DIGEST.test(body.program.source_digest)
+      || typeof body.program.program_digest !== 'string' || !RISK_DIGEST.test(body.program.program_digest)
+      || !riskIdentifier(body.nonce) || !ACTION_REFUSAL_CLASSES.includes(body.refusal_class)
+      || !validSemantics(body.semantics, body.refusal_class)
+      || body.claim_boundary !== ACTION_REFUSAL_CLAIM_BOUNDARY) {
+    throw new TypeError('action refusal statement shape is invalid');
+  }
+  if (!canonicalSet(body.failed_requirement_ids, riskIdentifier, 128, true)) {
+    throw new TypeError('action refusal requirements are invalid, duplicate, or unsorted');
+  }
+  if (!canonicalSet(
+    body.evidence_digests,
+    (entry) => typeof entry === 'string' && RISK_DIGEST.test(entry),
+    256,
+    false,
+  ) || !canonicalSet(
+    body.challenge_digests,
+    (entry) => typeof entry === 'string' && RISK_DIGEST.test(entry),
+    256,
+    true,
+  )) throw new TypeError('action refusal evidence or challenge binding is invalid');
+  const refused = riskInstant(body.refused_at);
+  const expires = riskInstant(body.expires_at);
+  if (!Number.isFinite(refused) || !Number.isFinite(expires) || expires <= refused) {
+    throw new TypeError('action refusal time window is invalid');
+  }
+  if (body.delivery !== null && (!riskExact(body.delivery, DELIVERY_KEYS)
+      || !riskIdentifier(body.delivery.channel) || !riskIdentifier(body.delivery.recipient_id)
+      || !Number.isFinite(riskInstant(body.delivery.delivered_at))
+      || riskInstant(body.delivery.delivered_at) < refused
+      || riskInstant(body.delivery.delivered_at) > expires
+      || typeof body.delivery.custody_digest !== 'string'
+      || !RISK_DIGEST.test(body.delivery.custody_digest))) {
+    throw new TypeError('action refusal delivery evidence is invalid');
+  }
+  if (body.custody !== null && (body.delivery === null
+      || !riskExact(body.custody, CUSTODY_KEYS)
+      || !riskIdentifier(body.custody.custodian_id)
+      || !Number.isFinite(riskInstant(body.custody.acknowledged_at))
+      || riskInstant(body.custody.acknowledged_at) < riskInstant(body.delivery.delivered_at)
+      || riskInstant(body.custody.acknowledged_at) > expires
+      || typeof body.custody.evidence_digest !== 'string'
+      || !RISK_DIGEST.test(body.custody.evidence_digest))) {
+    throw new TypeError('action refusal custody evidence is invalid');
+  }
+  if (body.transparency_anchor !== null && (!riskExact(body.transparency_anchor, ANCHOR_KEYS)
+      || !riskIdentifier(body.transparency_anchor.method)
+      || typeof body.transparency_anchor.evidence_digest !== 'string'
+      || !RISK_DIGEST.test(body.transparency_anchor.evidence_digest))) {
+    throw new TypeError('action refusal transparency anchor is invalid');
+  }
+}
+
+function normalizedInput(input: RiskRecord): RiskRecord {
+  const required = [
+    'refusal_id', 'relying_party_id', 'caid', 'action_digest', 'program',
+    'failed_requirement_ids', 'evidence_digests', 'nonce', 'refused_at',
+    'expires_at', 'refusal_class', 'claim_boundary',
+  ];
+  if (!riskRecord(input) || !required.every((key) => Object.hasOwn(input, key))
+      || !Object.keys(input).every((key) => INPUT_KEYS.has(key))
+      || (Object.hasOwn(input, 'challenge_digest') === Object.hasOwn(input, 'challenge_digests'))) {
+    throw new TypeError('action refusal input shape is invalid');
+  }
+  const rawChallenges = input.challenge_digests ?? [input.challenge_digest];
+  return {
+    '@version': ACTION_REFUSAL_STATEMENT_VERSION,
+    refusal_id: input.refusal_id,
+    relying_party_id: input.relying_party_id,
+    caid: input.caid,
+    action_digest: input.action_digest,
+    program: input.program,
+    failed_requirement_ids: sortedUnique(
+      input.failed_requirement_ids, riskIdentifier, 128, 'requirements', true,
+    ),
+    evidence_digests: sortedUnique(
+      input.evidence_digests,
+      (entry) => typeof entry === 'string' && RISK_DIGEST.test(entry),
+      256,
+      'evidence digests',
+      false,
+    ),
+    challenge_digests: sortedUnique(
+      rawChallenges,
+      (entry) => typeof entry === 'string' && RISK_DIGEST.test(entry),
+      256,
+      'challenge digests',
+      true,
+    ),
+    nonce: input.nonce,
+    refused_at: input.refused_at,
+    expires_at: input.expires_at,
+    refusal_class: input.refusal_class,
+    semantics: input.semantics ?? defaultSemantics(input.refusal_class),
+    delivery: input.delivery ?? null,
+    custody: input.custody ?? null,
+    transparency_anchor: input.transparency_anchor ?? null,
+    claim_boundary: input.claim_boundary,
+  };
+}
+
+export function signActionRefusalStatement(
+  input: RiskRecord,
+  signer: { issuer_id: string; key_id: string; private_key: any },
+) {
+  const body = normalizedInput(input);
+  validate(body);
+  return signRiskBody(ACTION_REFUSAL_STATEMENT_VERSION, body, signer);
+}
+
+export function actionRefusalStatementDigest(statement: unknown): string {
+  return riskDigest(statement);
+}
+
+function expectedMismatch(body: RiskRecord, expected: unknown): string | null {
+  if (expected === undefined) return null;
+  if (!riskRecord(expected) || !Object.keys(expected).every((key) => EXPECTED_KEYS.includes(key as any))) {
+    return 'expected_binding_invalid';
+  }
+  const bindings: RiskRecord = {
+    caid: body.caid,
+    action_digest: body.action_digest,
+    relying_party_id: body.relying_party_id,
+    program_id: body.program.program_id,
+    program_version: body.program.version,
+    source_digest: body.program.source_digest,
+    program_digest: body.program.program_digest,
+    nonce: body.nonce,
+  };
+  for (const key of Object.keys(expected)) {
+    if (bindings[key] !== expected[key]) return `${key}_mismatch`;
+  }
+  return null;
+}
+
+export function verifyActionRefusalStatement(statement: unknown, options: {
+  trusted_keys?: TrustedRiskKeys;
+  now?: string | number;
+  max_future_skew_sec?: number;
+  expected?: ActionRefusalExpectedBindings;
+} = {}) {
+  const refuse = (reason: string, refusalDigest: string | null = null) => ({
+    accepted: false as const,
+    verified: false as const,
+    reason,
+    refusal_digest: refusalDigest,
+    semantics: null,
+    delivery_evidence: 'NOT_EVIDENCED' as const,
+    custody_evidence: 'NOT_EVIDENCED' as const,
+    transparency_anchor: 'NOT_REFERENCED' as const,
+    claim_boundary: ACTION_REFUSAL_CLAIM_BOUNDARY,
+  });
+  const signed = verifyRiskBody(statement, ACTION_REFUSAL_STATEMENT_VERSION, options.trusted_keys);
+  if (!signed.valid || !signed.body) return refuse(signed.reason ?? 'refusal_invalid');
+  try { validate(signed.body); } catch { return refuse('refusal_schema_invalid', signed.artifact_digest); }
+  const now = options.now === undefined
+    ? Date.now() : (typeof options.now === 'string' ? Date.parse(options.now) : Number(options.now));
+  const skew = options.max_future_skew_sec ?? 30;
+  if (!Number.isFinite(now) || !Number.isSafeInteger(skew) || skew < 0 || skew > 3600) {
+    return refuse('verification_time_invalid', signed.artifact_digest);
+  }
+  if (riskInstant(signed.body.refused_at) > now + skew * 1000) {
+    return refuse('refusal_from_future', signed.artifact_digest);
+  }
+  if (now >= riskInstant(signed.body.expires_at)) {
+    return refuse('refusal_expired', signed.artifact_digest);
+  }
+  const mismatch = expectedMismatch(signed.body, options.expected);
+  if (mismatch) return refuse(mismatch, signed.artifact_digest);
+  return {
+    accepted: true as const,
+    verified: true as const,
+    reason: null,
+    refusal_digest: signed.artifact_digest,
+    relying_party_id: signed.body.relying_party_id,
+    nonce: signed.body.nonce,
+    semantics: riskClone(signed.body.semantics),
+    delivery_evidence: signed.body.delivery === null ? 'NOT_EVIDENCED' : 'REFERENCED',
+    custody_evidence: signed.body.custody === null ? 'NOT_EVIDENCED' : 'REFERENCED',
+    transparency_anchor: signed.body.transparency_anchor === null
+      ? 'NOT_REFERENCED' : 'REFERENCED_NOT_EXTERNALLY_VERIFIED',
+    claim_boundary: ACTION_REFUSAL_CLAIM_BOUNDARY,
+  };
+}
+
+export function createMemoryActionRefusalReplayStore(): ActionRefusalReplayStore {
+  const consumed = new Map<string, string>();
+  return Object.freeze({
+    durable: false,
+    async consume(relyingPartyId: string, nonce: string, refusalDigest: string) {
+      const key = JSON.stringify([relyingPartyId, nonce]);
+      const existing = consumed.get(key);
+      if (existing === undefined) {
+        consumed.set(key, refusalDigest);
+        return { accepted: true, reason: null };
+      }
+      if (existing === refusalDigest) return { accepted: false, reason: 'statement_replay' };
+      return { accepted: false, reason: 'nonce_equivocation' };
+    },
+  });
+}
+
+export async function acceptActionRefusalStatement(statement: unknown, options: {
+  trusted_keys?: TrustedRiskKeys;
+  now?: string | number;
+  max_future_skew_sec?: number;
+  expected?: ActionRefusalExpectedBindings;
+  replayStore?: ActionRefusalReplayStore;
+  allowEphemeralReplayStore?: boolean;
+} = {}) {
+  const verification = verifyActionRefusalStatement(statement, options);
+  const refused = (reason: string, checked = false, durable = false) => ({
+    ...verification,
+    accepted: false as const,
+    reason,
+    replay_checked: checked,
+    replay_store_durable: durable,
+  });
+  if (!verification.verified) return refused(verification.reason);
+  if (typeof verification.refusal_digest !== 'string') return refused('refusal_digest_missing');
+  if (!riskExact(options.expected, EXPECTED_KEYS)) return refused('complete_expected_binding_required');
+  const store = options.replayStore;
+  if (!store || typeof store.consume !== 'function' || typeof store.durable !== 'boolean') {
+    return refused('replay_store_required');
+  }
+  if (!store.durable && options.allowEphemeralReplayStore !== true) {
+    return refused('durable_replay_store_required');
+  }
+  let result: unknown;
+  try {
+    result = await store.consume(
+      verification.relying_party_id,
+      verification.nonce,
+      verification.refusal_digest,
+    );
+  } catch {
+    return refused('replay_store_unavailable', false, store.durable);
+  }
+  if (!riskExact(result, ['accepted', 'reason']) || typeof result.accepted !== 'boolean'
+      || (result.reason !== null && typeof result.reason !== 'string')) {
+    return refused('replay_store_result_invalid', false, store.durable);
+  }
+  if (!result.accepted) {
+    const reason = result.reason === 'statement_replay' || result.reason === 'nonce_equivocation'
+      ? result.reason : 'replay_store_refused';
+    return refused(reason, true, store.durable);
+  }
+  if (result.reason !== null) return refused('replay_store_result_invalid', true, store.durable);
+  return {
+    ...verification,
+    accepted: true as const,
+    replay_checked: true,
+    replay_store_durable: store.durable,
+  };
+}

package/src/coverage-reconciliation-attestation.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: Apache-2.0
+/** Signed period reconciliation of supplied populations; never proof that the supplied population is complete. */
+import {
+  RISK_DIGEST, riskExact, riskIdentifier, riskInstant,
+  signRiskBody, verifyRiskBody, type RiskRecord, type TrustedRiskKeys,
+} from './reliance-risk-crypto.js';
+
+export const COVERAGE_RECONCILIATION_ATTESTATION_VERSION = 'EP-COVERAGE-RECONCILIATION-ATTESTATION-v1';
+export const COVERAGE_RECONCILIATION_CLAIM_BOUNDARY = 'signed_reconciliation_of_supplied_populations_not_population_completeness';
+const PROGRAM_KEYS = ['program_id', 'version', 'source_digest', 'program_digest'] as const;
+const PERIOD_KEYS = ['start', 'end'] as const;
+const POPULATION_KEYS = ['inventory_id', 'population_root', 'count'] as const;
+const JOIN_KEYS = ['matched', 'effect_without_receipt', 'receipt_without_effect', 'indeterminate', 'excluded', 'exception'] as const;
+const ANCHOR_KEYS = ['method', 'evidence_digest'] as const;
+const BODY_KEYS = ['@version', 'attestation_id', 'relying_party_id', 'program', 'period', 'coverage_report_hash', 'census_digest', 'system_of_record', 'receipt_population', 'joins', 'issued_at', 'expires_at', 'timestamp_anchor', 'claim_boundary'] as const;
+
+function count(value: unknown): value is number { return Number.isSafeInteger(value) && Number(value) >= 0; }
+function sameProgram(actual: RiskRecord, expected: RiskRecord): boolean {
+  return actual.program_id === expected.program_id && actual.version === expected.version
+    && actual.source_digest === expected.source_digest && actual.program_digest === expected.program_digest;
+}
+function validExpectedProgram(value: unknown): value is RiskRecord {
+  return riskExact(value, PROGRAM_KEYS) && riskIdentifier(value.program_id)
+    && Number.isSafeInteger(value.version) && value.version >= 1
+    && RISK_DIGEST.test(value.source_digest) && RISK_DIGEST.test(value.program_digest);
+}
+function validate(value: unknown): asserts value is RiskRecord {
+  if (!riskExact(value, BODY_KEYS) || value['@version'] !== COVERAGE_RECONCILIATION_ATTESTATION_VERSION
+      || !riskIdentifier(value.attestation_id) || !riskIdentifier(value.relying_party_id)
+      || !riskExact(value.program, PROGRAM_KEYS) || !riskIdentifier(value.program.program_id)
+      || !Number.isSafeInteger(value.program.version) || value.program.version < 1
+      || !RISK_DIGEST.test(value.program.source_digest) || !RISK_DIGEST.test(value.program.program_digest)
+      || !riskExact(value.period, PERIOD_KEYS) || !RISK_DIGEST.test(value.coverage_report_hash)
+      || !RISK_DIGEST.test(value.census_digest)
+      || !riskExact(value.system_of_record, POPULATION_KEYS) || !riskExact(value.receipt_population, POPULATION_KEYS)
+      || !riskExact(value.joins, JOIN_KEYS) || value.claim_boundary !== COVERAGE_RECONCILIATION_CLAIM_BOUNDARY) {
+    throw new TypeError('coverage reconciliation attestation shape is invalid');
+  }
+  const start = riskInstant(value.period.start); const end = riskInstant(value.period.end);
+  const issued = riskInstant(value.issued_at); const expires = riskInstant(value.expires_at);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start || !Number.isFinite(issued)
+      || !Number.isFinite(expires) || expires <= issued || issued < end) throw new TypeError('coverage reconciliation period is invalid');
+  for (const population of [value.system_of_record, value.receipt_population]) {
+    if (!riskIdentifier(population.inventory_id) || !RISK_DIGEST.test(population.population_root) || !count(population.count)) {
+      throw new TypeError('coverage reconciliation population is invalid');
+    }
+  }
+  if (!JOIN_KEYS.every((key) => count(value.joins[key]))) throw new TypeError('coverage reconciliation counts are invalid');
+  if (value.system_of_record.count !== value.joins.matched + value.joins.effect_without_receipt + value.joins.excluded + value.joins.exception
+      || value.receipt_population.count !== value.joins.matched + value.joins.receipt_without_effect + value.joins.indeterminate) {
+    throw new TypeError('coverage reconciliation population conservation failed');
+  }
+  if (value.timestamp_anchor !== null && (!riskExact(value.timestamp_anchor, ANCHOR_KEYS)
+      || !riskIdentifier(value.timestamp_anchor.method) || !RISK_DIGEST.test(value.timestamp_anchor.evidence_digest))) {
+    throw new TypeError('coverage timestamp anchor is invalid');
+  }
+}
+
+export function signCoverageReconciliationAttestation(input: RiskRecord, signer: { issuer_id: string; key_id: string; private_key: any }) {
+  const body: RiskRecord = { '@version': COVERAGE_RECONCILIATION_ATTESTATION_VERSION, ...input };
+  validate(body);
+  if (signer.issuer_id !== body.relying_party_id) throw new TypeError('coverage attestation issuer must be relying party');
+  return signRiskBody(COVERAGE_RECONCILIATION_ATTESTATION_VERSION, body, signer);
+}
+
+export function verifyCoverageReconciliationAttestation(attestation: unknown, options: {
+  trusted_keys?: TrustedRiskKeys; now?: string | number; expected_program?: RiskRecord;
+  expected_census_digest?: string; expected_relying_party_id?: string;
+} = {}) {
+  const refuse = (reason: string, verified = false, attestationDigest: string | null = null) => ({
+    accepted: false,
+    verified,
+    reason,
+    attestation_digest: attestationDigest,
+    claim_boundary: COVERAGE_RECONCILIATION_CLAIM_BOUNDARY,
+  });
+  const signed = verifyRiskBody(attestation, COVERAGE_RECONCILIATION_ATTESTATION_VERSION, options.trusted_keys);
+  if (!signed.valid || !signed.body) return refuse(signed.reason ?? 'attestation_invalid');
+  const { issuer, ...payload } = signed.body;
+  if (issuer.id !== payload.relying_party_id) {
+    return refuse('relying_party_issuer_mismatch', true, signed.artifact_digest);
+  }
+  try { validate(payload); } catch {
+    return refuse('population_conservation_or_schema_invalid', true, signed.artifact_digest);
+  }
+  const now = options.now === undefined ? Date.now() : (typeof options.now === 'string' ? Date.parse(options.now) : Number(options.now));
+  if (!Number.isFinite(now)) return refuse('verification_time_invalid', true, signed.artifact_digest);
+  if (now < riskInstant(payload.issued_at)) return refuse('attestation_not_yet_issued', true, signed.artifact_digest);
+  if (now >= riskInstant(payload.expires_at)) return refuse('attestation_expired', true, signed.artifact_digest);
+  if (options.expected_program === undefined || options.expected_census_digest === undefined
+      || options.expected_relying_party_id === undefined) {
+    return refuse('context_binding_required', true, signed.artifact_digest);
+  }
+  if (!validExpectedProgram(options.expected_program)) {
+    return refuse('expected_program_invalid', true, signed.artifact_digest);
+  }
+  if (!sameProgram(payload.program, options.expected_program)) {
+    return refuse('program_binding_mismatch', true, signed.artifact_digest);
+  }
+  if (options.expected_census_digest !== payload.census_digest) {
+    return refuse('census_digest_mismatch', true, signed.artifact_digest);
+  }
+  if (options.expected_relying_party_id !== payload.relying_party_id) {
+    return refuse('relying_party_mismatch', true, signed.artifact_digest);
+  }
+  return { accepted: true, verified: true, reason: null, attestation_digest: signed.artifact_digest, claim_boundary: COVERAGE_RECONCILIATION_CLAIM_BOUNDARY };
+}