aph_core/

envelope.rs

//! NotarizationEnvelope — the W3C VC 2.0-shaped credential carrying an
//! APH notarization. This is the canonical on-wire shape.
//!
//! The envelope is a JSON-LD compatible W3C Verifiable Credential 2.0
//! payload. The `@context` field carries the JSON-LD contexts; the `type`
//! field MUST include `"VerifiableCredential"` plus
//! `"AgentSendAuthorizationCredential"`. All struct field names use
//! snake_case in Rust and camelCase on the wire (via
//! `#[serde(rename_all = "camelCase")]`), except `@context` (JSON-LD
//! convention) and `type` (Rust reserved keyword routed through `r#type`
//! + explicit `#[serde(rename = "type")]` for defense in depth).
//!
//! This module is shape-only — `proof.proof_value` is a String; no
//! cryptographic validation occurs in this module. The STRUCTURAL rules of
//! spec §7.1.11 (chain length, proof purposes, `previousProof` linkage,
//! label/structure agreement) live in [`crate::verification`]; signature
//! checking lives in [`crate::crypto`].

/// Top-level APH envelope. JSON-LD compatible W3C VC 2.0 credential.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct NotarizationEnvelope {
  /// APH version pin (`"0.1"`).
  pub aph_version: String,
  /// JSON-LD `@context` array. Always begins with W3C VC 2.0 context.
  #[serde(rename = "@context")]
  pub context: Vec<String>,
  /// JSON-LD `type` array; MUST include `"VerifiableCredential"` and
  /// `"AgentSendAuthorizationCredential"`.
  #[serde(rename = "type")]
  pub r#type: Vec<String>,
  /// `urn:uuid:...` envelope identifier.
  pub id: String,
  /// DID of the notary service.
  pub issuer: String,
  /// RFC 3339 issuance timestamp.
  pub valid_from: String,
  /// RFC 3339 expiry timestamp.
  pub valid_until: String,
  /// Inner credential subject (the notarized claim).
  pub credential_subject: CredentialSubject,
  /// Optional link to an AP2 IntentMandate (for cross-protocol mandates).
  #[serde(default)]
  pub linked_mandate: std::option::Option<LinkedMandate>,
  /// Revocation status reference for the **parent Delegation Mandate** named
  /// by `credentialSubject.policy.delegationMandateId` — NOT for this
  /// envelope (spec §6.3.3.1 narrows the W3C reading, and
  /// [`crate::credential_status`] carries the argument).
  ///
  /// **`skip_serializing_if` is load-bearing, not tidiness.** Unlike
  /// `linked_mandate` directly above — which §7.1.1 permits to appear as an
  /// explicit `null` — this field is OMITTED when absent, so an envelope
  /// carrying no status reference is BYTE-IDENTICAL to one written before
  /// the field existed. That identity is what keeps every published example,
  /// every golden fixture and all four real Ed25519 signatures valid without
  /// regeneration: the signing base is this struct serialized and
  /// canonicalized (`crate::crypto::proof_base::signing_base`), so a bare
  /// `#[serde(default)]` here would emit `"credentialStatus":null`, change
  /// those bytes, and invalidate every signature over them.
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub credential_status:
    std::option::Option<crate::credential_status::CredentialStatusEntry>,
  /// Cryptographic proof: a single notary proof, or a two-element proof
  /// chain (spec §7.1.11). See [`EnvelopeProofs`].
  pub proof: EnvelopeProofs,
}

/// One proof, or a two-element chain (spec §7.1.11).
///
/// Untagged because the wire carries either a JSON object or a JSON array
/// under the same `proof` key; the shape IS the discriminator.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(untagged)]
pub enum EnvelopeProofs {
  /// A single notary proof. The envelope is `NotaryAttested` (§7.1.11).
  Single(EnvelopeProof),
  /// An ordered proof chain: principal proof, then notary countersignature.
  Chain(std::vec::Vec<EnvelopeProof>),
}

impl EnvelopeProofs {
  /// Every proof, in wire order.
  pub fn all(&self) -> &[EnvelopeProof] {
    match self {
      // `from_ref` gives the single form the same slice shape as the chain
      // form, so callers that iterate never branch on the variant.
      Self::Single(proof) => std::slice::from_ref(proof),
      Self::Chain(proofs) => proofs.as_slice(),
    }
  }

  /// The principal proof — the head of a well-formed two-element chain.
  /// `None` for a single proof or a chain of any other length.
  ///
  /// A chain of any other length is malformed under §7.1.11, so refusing to
  /// name a "principal proof" inside one is deliberate: a caller that got a
  /// proof back from a three-element array would be reading a structure the
  /// spec rejects as though it were valid.
  pub fn principal(&self) -> std::option::Option<&EnvelopeProof> {
    match self {
      Self::Single(_) => std::option::Option::None,
      Self::Chain(proofs) => {
        if proofs.len() == 2 {
          proofs.first()
        } else {
          std::option::Option::None
        }
      }
    }
  }

  /// The notary proof: the lone proof, or the tail of a two-element chain.
  pub fn notary(&self) -> std::option::Option<&EnvelopeProof> {
    match self {
      Self::Single(proof) => std::option::Option::Some(proof),
      Self::Chain(proofs) => {
        if proofs.len() == 2 {
          proofs.get(1)
        } else {
          std::option::Option::None
        }
      }
    }
  }

  /// True when this is the array form, whatever its length.
  pub fn is_chain(&self) -> bool {
    std::matches!(self, Self::Chain(_))
  }
}

/// Which of the two attestation modes an envelope declares (spec §7.1.7).
///
/// The wire spells these exactly as written, so no serde rename is needed.
/// ABSENT means `NotaryAttested` — see [`PolicyDescriptor::effective_attestation_mode`].
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::marker::Copy,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
pub enum AttestationMode {
  /// The human's own key signed this envelope; `proof` is a chain.
  PrincipalSigned,
  /// A notary asserts the human authorized this. Strictly weaker.
  NotaryAttested,
}

impl AttestationMode {
  /// The exact wire spelling, for error messages and logs.
  ///
  /// Returned as `&'static str` rather than via `Display` so an error
  /// constructor can name a mode without allocating, and so the string an
  /// operator reads in a log is byte-identical to the one on the wire.
  pub fn label(&self) -> &'static str {
    match self {
      Self::PrincipalSigned => "PrincipalSigned",
      Self::NotaryAttested => "NotaryAttested",
    }
  }
}

impl std::fmt::Display for AttestationMode {
  fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    std::write!(f, "{}", self.label())
  }
}

/// The notarized claim: who authorized what, on which channel, under
/// which policy, attested by which notary.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CredentialSubject {
  /// The human on whose behalf the agent acted.
  pub human_principal: HumanPrincipalRef,
  /// The agent that produced the communication.
  pub agent: AgentRef,
  /// Delivery channel and recipient addressing.
  pub channel: ChannelDescriptor,
  /// What was sent: content class, body hash, size, preview.
  pub communication: CommunicationDescriptor,
  /// The authorization decision and the scope it matched.
  pub policy: PolicyDescriptor,
  /// Which notary decided, when, and how long it took.
  pub notarization: NotarizationMetadata,
  /// Last-position additive field. Optional Apple Foundation Models AUR
  /// acceptance claim per `(user_id, device_id, aur_version_hash)`.
  /// `#[serde(default, skip_serializing_if = "Option::is_none")]` preserves
  /// wire back-compat (legacy envelopes omit the field and continue to
  /// deserialize cleanly).
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub apple_aur_acceptance: std::option::Option<AppleAurAcceptanceClaim>,
}

/// Reference to the human on whose behalf the agent acted.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct HumanPrincipalRef {
  /// DID of the human principal.
  pub id: String,
  /// Human-readable name, for display in consent UIs and audit logs.
  pub display_name: String,
}

/// Reference to the agent that produced the communication.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct AgentRef {
  /// DID of the agent (typically `did:web:...`).
  pub id: String,
  /// Optional URI of the agent's A2A Agent Card.
  #[serde(default)]
  pub agent_card_uri: std::option::Option<String>,
  /// Human-readable agent name.
  pub display_name: String,
  /// Agent version string, so a recipient can tell releases apart.
  pub version: String,
}

/// Delivery channel and its channel-shaped recipient addressing.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ChannelDescriptor {
  /// Channel kind: `"slack" | "email" | "discord" | ...`.
  pub kind: String,
  /// Channel-shaped opaque blob (opaque to APH core).
  pub recipient_addressing: serde_json::Value,
}

/// What was sent: classification plus the hash that binds this credential
/// to a specific message body.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CommunicationDescriptor {
  /// Content classification (`"Reply"`, `"New"`, `"DM"`, ...).
  pub content_class: String,
  /// SHA-256 of the message body, 64 lowercase hex characters.
  pub body_sha256: String,
  /// Body length in bytes.
  pub body_size: u64,
  /// Number of body lines included in `preview`.
  pub preview_lines: u32,
  /// Truncated body excerpt for human review at decision time.
  pub preview: String,
}

/// The authorization decision and the scope that produced it.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct PolicyDescriptor {
  /// `"AlwaysAllow" | "AskEveryTime" | "NeverAllow"`.
  pub decision: String,
  /// e.g., `"per-channel" | "per-recipient" | "global"`.
  pub matched_scope: String,
  /// Parent delegation mandate, absent for one-shot AskEveryTime grants.
  #[serde(default)]
  pub delegation_mandate_id: std::option::Option<String>,
  /// OAuth 2.0 Token Exchange `act` chain (RFC 8693) — optional cross-system
  /// principal chain. Each element is a DID string.
  #[serde(default)]
  pub act_chain: Vec<String>,
  /// Who proved the authorization (§7.1.7). ABSENT means `NotaryAttested`.
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub attestation_mode: std::option::Option<AttestationMode>,
  /// The complete parent mandate, embedded so the human's signature on it
  /// verifies offline (§7.1.7.1).
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub delegation_mandate: std::option::Option<crate::delegation_mandate::DelegationMandate>,
}

impl PolicyDescriptor {
  /// The declared mode, resolving ABSENT to `NotaryAttested` per §7.1.7.
  ///
  /// Absence is not "unknown": §7.1.7 fixes it as `NotaryAttested` so that
  /// every envelope written before `attestationMode` existed keeps a single,
  /// unambiguous meaning — the weaker one. Defaulting the other way would
  /// silently promote every legacy envelope to a claim no one made.
  pub fn effective_attestation_mode(&self) -> AttestationMode {
    match self.attestation_mode {
      std::option::Option::Some(mode) => mode,
      std::option::Option::None => AttestationMode::NotaryAttested,
    }
  }
}

/// Which notary made the decision, when, and how long it took.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct NotarizationMetadata {
  /// The notary service that decided.
  pub notary_service: NotaryServiceRef,
  /// RFC 3339 decision timestamp.
  pub decision_timestamp: String,
  /// Decision latency in milliseconds — audit evidence for whether a human
  /// was plausibly in the loop.
  pub decision_latency_ms: u64,
}

/// Identity of the notary service, used for key discovery (spec §8.4).
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct NotaryServiceRef {
  /// DID of the notary.
  pub id: String,
  /// Human-readable notary service name.
  pub name: String,
  /// Notary implementation version.
  pub version: String,
  /// Content digest of the attested release this notary reports running
  /// (spec §7.1.9, §15.3). Declared here because parsing is strict: a
  /// field a conformant notary may send must exist in the shape a
  /// conformant verifier parses. `#[serde(default)]` keeps every envelope
  /// written before this field byte-identical.
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub attested_digest: std::option::Option<String>,
  /// Where the k-of-3 attestation for `attested_digest` may be fetched
  /// (spec §15.3). Carrying it proves nothing on its own — an attestation
  /// attests what was PUBLISHED, never what is RUNNING (§15.7).
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub attestation_uri: std::option::Option<String>,
}

/// Cross-protocol links carried alongside the send authorization.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct LinkedMandate {
  /// URI of an AP2 IntentMandate cross-linking payment authorization.
  #[serde(default)]
  pub ap2_intent_mandate_uri: std::option::Option<String>,
  /// Optional base64-encoded AP2 SignedPayload for self-contained
  /// verification when the verifier cannot dereference
  /// `ap2_intent_mandate_uri`. `#[serde(default)]` preserves wire
  /// back-compat for envelopes written before this field was added.
  #[serde(default)]
  pub ap2_signed_payload_b64: std::option::Option<String>,
  /// Optional cross-vault mutation mandate for LinkedMandates issued by a
  /// cross-vault federation engine.
  /// `#[serde(default, skip_serializing_if = "...")]` preserves
  /// wire back-compat (legacy envelopes omit the field).
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub vault_mutation: std::option::Option<
    crate::vault_mutation::VaultMutationMandate,
  >,
}

#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
/// The cryptographic proof block: either a W3C Data Integrity Proof or a
/// detached JWS, per spec §8.2.
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct EnvelopeProof {
  /// Always `"DataIntegrityProof"` for the JCS-canonicalized cryptosuites,
  /// or `"JsonWebSignature2020"` for compact JWS detached.
  #[serde(rename = "type")]
  pub r#type: String,
  /// Required for DataIntegrityProof. e.g., `"eddsa-jcs-2022"` or
  /// `"ecdsa-jcs-2019"`.
  #[serde(default)]
  pub cryptosuite: std::option::Option<String>,
  /// DID URL referencing the verifying key
  /// (e.g., `did:key:z6Mk...#z6Mk...`).
  pub verification_method: String,
  /// RFC 3339.
  pub created: String,
  /// `"assertionMethod"` for a principal proof or a lone notary proof;
  /// `"authentication"` for the notary countersignature of a chain (§7.1.11).
  pub proof_purpose: String,
  /// Multibase or base64url-encoded signature bytes.
  pub proof_value: String,
  /// Identifier for this proof, unique within the envelope. REQUIRED when
  /// `proof` is a chain, absent for a lone proof, which links to nothing.
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub id: std::option::Option<String>,
  /// The `id` of the proof this one countersigns. Present on the notary
  /// proof of a chain; absent on the principal proof, its head.
  #[serde(default, skip_serializing_if = "std::option::Option::is_none")]
  pub previous_proof: std::option::Option<String>,
}

/// Last-position sibling struct. Carries Apple Foundation Models AUR
/// acceptance per `(user_id, device_id, aur_version_hash)` tuple.
/// Embedded as `Option<AppleAurAcceptanceClaim>` on
/// `CredentialSubject.apple_aur_acceptance`. The field is
/// `#[serde(default, skip_serializing_if = "...")]` so legacy envelopes that
/// predate this claim continue to deserialize cleanly.
#[derive(
  std::fmt::Debug,
  std::clone::Clone,
  std::cmp::PartialEq,
  std::cmp::Eq,
  serde::Serialize,
  serde::Deserialize,
)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct AppleAurAcceptanceClaim {
  /// User-scoped DID for whom acceptance was recorded.
  pub user_id: String,
  /// Device-scoped opaque identifier (acceptance is recorded per
  /// `(user_id, device_id)` pair).
  pub device_id: String,
  /// SHA-256 hex of the Apple AUR snapshot text accepted.
  pub aur_version_hash: String,
  /// RFC 3339 acceptance timestamp.
  pub accepted_at: String,
  /// `"foundation_models_framework_aur"` for forward-compat with future Apple legal documents.
  pub document_kind: String,
}

#[cfg(test)]
mod tests {
  // -------- helpers --------

  fn sample_human_principal() -> super::HumanPrincipalRef {
    super::HumanPrincipalRef {
      id: "did:key:z6MkfAkfRZ3v9zJWh9LM2YQbWLh6hqGYDVxxC7ueoVcd5dGy".to_string(),
      display_name: "Scott Wyatt".to_string(),
    }
  }

  fn sample_agent() -> super::AgentRef {
    super::AgentRef {
      id: "did:web:agent.squillo.com".to_string(),
      agent_card_uri: std::option::Option::Some(
        "https://agent.squillo.com/.well-known/agent-card.json".to_string(),
      ),
      display_name: "Squillo Concierge".to_string(),
      version: "1.0".to_string(),
    }
  }

  fn sample_channel() -> super::ChannelDescriptor {
    super::ChannelDescriptor {
      kind: "slack".to_string(),
      recipient_addressing: serde_json::json!({
        "teamId": "T01234567",
        "channelId": "C01234567",
        "parentTs": "1716249600.000100"
      }),
    }
  }

  fn sample_communication() -> super::CommunicationDescriptor {
    super::CommunicationDescriptor {
      content_class: "Reply".to_string(),
      body_sha256: "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855".to_string(),
      body_size: 1842,
      preview_lines: 3,
      preview: "hello world".to_string(),
    }
  }

  fn sample_policy() -> super::PolicyDescriptor {
    super::PolicyDescriptor {
      decision: "AskEveryTime".to_string(),
      matched_scope: "per-channel".to_string(),
      delegation_mandate_id: std::option::Option::None,
      act_chain: std::vec::Vec::new(),
      attestation_mode: std::option::Option::None,
      delegation_mandate: std::option::Option::None,
    }
  }

  #[test]
  fn attestation_fields_are_omitted_when_absent_and_accepted_when_present() {
    // The two §15.3 attestation fields were added to a struct that parses
    // with `deny_unknown_fields` and whose output is signed. Two things must
    // both hold: a notary that makes no attestation claim serializes
    // byte-identically to before the fields existed (or every signature over
    // an existing envelope breaks), and a notary that does make one is not
    // rejected as carrying unknown fields (or conformant verifiers would
    // refuse conformant notaries).
    let bare = sample_notary_service();
    let json = serde_json::to_string(&bare).unwrap();
    std::assert!(
      !json.contains("attestedDigest") && !json.contains("attestationUri"),
      "absent attestation fields must not appear on the wire: {}",
      json
    );

    let with_claim: super::NotaryServiceRef = serde_json::from_str(
      r#"{"id":"did:web:notary.squillo.com","name":"Squillo Notary Service","version":"0.1.0","attestedDigest":"sha256:abc","attestationUri":"https://notary.squillo.com/.well-known/aph-attestation.json"}"#,
    )
    .expect("a notary advertising an attestation must parse");
    std::assert_eq!(
      with_claim.attested_digest.as_deref(),
      std::option::Option::Some("sha256:abc")
    );
  }

  fn sample_notary_service() -> super::NotaryServiceRef {
    super::NotaryServiceRef {
      id: "did:web:notary.squillo.com".to_string(),
      name: "Squillo Notary Service".to_string(),
      version: "0.1.0".to_string(),
      attested_digest: std::option::Option::None,
      attestation_uri: std::option::Option::None,
    }
  }

  fn sample_notarization_metadata() -> super::NotarizationMetadata {
    super::NotarizationMetadata {
      notary_service: sample_notary_service(),
      decision_timestamp: "2026-05-21T00:00:01Z".to_string(),
      decision_latency_ms: 1834,
    }
  }

  fn sample_credential_subject() -> super::CredentialSubject {
    super::CredentialSubject {
      human_principal: sample_human_principal(),
      agent: sample_agent(),
      channel: sample_channel(),
      communication: sample_communication(),
      policy: sample_policy(),
      notarization: sample_notarization_metadata(),
      apple_aur_acceptance: std::option::Option::None,
    }
  }

  fn sample_linked_mandate() -> super::LinkedMandate {
    super::LinkedMandate {
      ap2_intent_mandate_uri: std::option::Option::Some(
        "urn:uuid:11111111-1111-4111-8111-111111111111".to_string(),
      ),
      ap2_signed_payload_b64: std::option::Option::None,
      vault_mutation: std::option::Option::None,
    }
  }

  fn sample_proof() -> super::EnvelopeProof {
    super::EnvelopeProof {
      r#type: "DataIntegrityProof".to_string(),
      cryptosuite: std::option::Option::Some("eddsa-jcs-2022".to_string()),
      verification_method:
        "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV#z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV"
          .to_string(),
      created: "2026-05-21T00:00:01Z".to_string(),
      proof_purpose: "assertionMethod".to_string(),
      proof_value:
        "z3WgvA9JHkbV3qLZHcM4FxBp4xHfQVnVnPKKDdyazQwQGdGzxsRdmZWBxXwQvN6P2sLZbLP4HnRy9LcZdpFLLM6h"
          .to_string(),
      id: std::option::Option::None,
      previous_proof: std::option::Option::None,
    }
  }

  fn sample_envelope() -> super::NotarizationEnvelope {
    super::NotarizationEnvelope {
      aph_version: "0.1".to_string(),
      context: std::vec![
        "https://www.w3.org/ns/credentials/v2".to_string(),
        "https://w3id.org/aph/v1".to_string(),
      ],
      r#type: std::vec![
        "VerifiableCredential".to_string(),
        "AgentSendAuthorizationCredential".to_string(),
      ],
      id: "urn:uuid:00000000-0000-4000-8000-000000000001".to_string(),
      issuer: "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV".to_string(),
      valid_from: "2026-05-21T00:00:00Z".to_string(),
      valid_until: "2026-05-22T00:00:00Z".to_string(),
      credential_subject: sample_credential_subject(),
      linked_mandate: std::option::Option::None,
      // Pattern A (§7.1.1): absent here means NO `credentialStatus` key on
      // the wire, which is what keeps this fixture byte-identical to the
      // pre-revocation shape its signatures were made over.
      credential_status: std::option::Option::None,
      proof: super::EnvelopeProofs::Single(sample_proof()),
    }
  }

  fn sample_principal_proof() -> super::EnvelopeProof {
    super::EnvelopeProof {
      r#type: "DataIntegrityProof".to_string(),
      cryptosuite: std::option::Option::Some("eddsa-jcs-2022".to_string()),
      // The human principal's own DID URL — the same DID
      // `sample_human_principal()` carries, which is what §7.1.11 binds.
      verification_method:
        "did:key:z6MkfAkfRZ3v9zJWh9LM2YQbWLh6hqGYDVxxC7ueoVcd5dGy#z6MkfAkfRZ3v9zJWh9LM2YQbWLh6hqGYDVxxC7ueoVcd5dGy"
          .to_string(),
      created: "2026-05-21T00:00:02Z".to_string(),
      proof_purpose: "assertionMethod".to_string(),
      proof_value: "z-illustrative-principal-proof-value".to_string(),
      id: std::option::Option::Some("urn:uuid:00000000-0000-4000-8000-0000000000a1".to_string()),
      previous_proof: std::option::Option::None,
    }
  }

  fn sample_notary_countersignature() -> super::EnvelopeProof {
    super::EnvelopeProof {
      r#type: "DataIntegrityProof".to_string(),
      cryptosuite: std::option::Option::Some("eddsa-jcs-2022".to_string()),
      verification_method:
        "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV#z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV"
          .to_string(),
      created: "2026-05-21T00:00:03Z".to_string(),
      proof_purpose: "authentication".to_string(),
      proof_value: "z-illustrative-notary-countersignature".to_string(),
      id: std::option::Option::Some("urn:uuid:00000000-0000-4000-8000-0000000000b1".to_string()),
      previous_proof: std::option::Option::Some(
        "urn:uuid:00000000-0000-4000-8000-0000000000a1".to_string(),
      ),
    }
  }

  // -------- Test 1: per-struct round-trip --------

  #[test]
  fn round_trip_human_principal_ref() {
    // Per-struct round-trips exist because deny_unknown_fields makes every
    // sub-struct independently strict: a field lost or renamed here would
    // fail only when that specific object is parsed. This one carries the
    // human's DID — the identity the whole credential attests.
    let v = sample_human_principal();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::HumanPrincipalRef = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_agent_ref() {
    // The agent identity a recipient checks against the delegation; its
    // optional agentCardUri must survive round-tripping alongside the
    // required fields.
    let v = sample_agent();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::AgentRef = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_channel_descriptor() {
    // Holds the opaque recipientAddressing blob (§7.4), the one place
    // arbitrary JSON is preserved verbatim — this pins that it survives
    // untouched rather than being normalized or dropped.
    let v = sample_channel();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::ChannelDescriptor = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_communication_descriptor() {
    // Carries bodySha256 and bodySize — the binding between the credential
    // and the actual message. Any loss here breaks the APH_E009 body-hash
    // check that stops a signature being reused for a different body.
    let v = sample_communication();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::CommunicationDescriptor = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_policy_descriptor() {
    // The authorization record itself (decision, matched scope, delegation
    // id, act chain). Dropping actChain or delegationMandateId would erase
    // the evidence a verifier uses to trace authority back to the human.
    let v = sample_policy();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::PolicyDescriptor = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_notary_service_ref() {
    // Identifies which notary made the decision — needed for key discovery
    // (§8.4) and for auditing which service to hold accountable.
    let v = sample_notary_service();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::NotaryServiceRef = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_notarization_metadata() {
    // Decision timestamp and latency: audit evidence for whether a human
    // was plausibly in the loop, so it must survive intact.
    let v = sample_notarization_metadata();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::NotarizationMetadata = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_credential_subject() {
    // Composition test: the six sub-objects must nest correctly together.
    // Per-struct round-trips above cannot catch a broken assembly (e.g. a
    // field attached at the wrong level).
    let v = sample_credential_subject();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::CredentialSubject = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_linked_mandate() {
    // Cross-protocol link (AP2 payment authorization, vault mutation). It
    // holds three independently-optional fields, so round-tripping proves
    // none of them is lost when the others are absent.
    let v = sample_linked_mandate();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::LinkedMandate = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_envelope_proof() {
    // The signature block itself. If any proof field failed to round-trip,
    // a re-serialized envelope would carry an unverifiable proof.
    let v = sample_proof();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::EnvelopeProof = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  #[test]
  fn round_trip_notarization_envelope() {
    // The whole credential end to end — the exact operation a relaying
    // verifier performs. This is the last line of defense against any
    // field being silently dropped in transit.
    let v = sample_envelope();
    let s = serde_json::to_string(&v).unwrap();
    let v2: super::NotarizationEnvelope = serde_json::from_str(&s).unwrap();
    std::assert_eq!(v, v2);
  }

  // -------- Test 2: wire-key shape for reserved/JSON-LD names --------

  #[test]
  fn envelope_serializes_type_as_type_and_context_as_at_context() {
    // Two JSON-LD keys Rust cannot name directly: "@context" (illegal
    // identifier) and "type" (keyword, written r#type). Both depend on
    // explicit #[serde(rename)] attributes — drop one and the envelope
    // stops being a valid W3C Verifiable Credential.
    let v = sample_envelope();
    let s = serde_json::to_string(&v).unwrap();
    std::assert!(
      s.contains("\"type\":"),
      "envelope must serialize r#type as \"type\": {}",
      s
    );
    std::assert!(
      s.contains("\"@context\":"),
      "envelope must serialize context as \"@context\": {}",
      s
    );
    std::assert!(
      !s.contains("\"rType\""),
      "envelope must NOT serialize as \"rType\": {}",
      s
    );
    std::assert!(
      !s.contains("\"r#type\""),
      "envelope must NOT serialize as \"r#type\": {}",
      s
    );
  }

  #[test]
  fn proof_serializes_type_as_type() {
    // Same r#type rename, applied on the nested proof block — pinned
    // separately because the attribute must be repeated per struct and is
    // easy to omit on a newly added one.
    let v = sample_proof();
    let s = serde_json::to_string(&v).unwrap();
    std::assert!(
      s.contains("\"type\":"),
      "proof must serialize r#type as \"type\": {}",
      s
    );
    std::assert!(
      !s.contains("\"rType\""),
      "proof must NOT serialize as \"rType\": {}",
      s
    );
  }

  // -------- Test 3: deny_unknown_fields rejection --------

  #[test]
  fn envelope_rejects_unknown_field() {
    // Strict parsing (§7.1, §8.3 step 1) is normative: an unknown envelope
    // field must be a hard error. Accepting-and-ignoring would let a
    // producer smuggle a claim the verifier never evaluates.
    let s = serde_json::json!({
      "aphVersion": "0.1",
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/aph/v1"
      ],
      "type": ["VerifiableCredential", "AgentSendAuthorizationCredential"],
      "id": "urn:uuid:00000000-0000-4000-8000-000000000001",
      "issuer": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV",
      "validFrom": "2026-05-21T00:00:00Z",
      "validUntil": "2026-05-22T00:00:00Z",
      "credentialSubject": {
        "humanPrincipal": {
          "id": "did:key:abc",
          "displayName": "X"
        },
        "agent": {
          "id": "did:web:agent.squillo.com",
          "displayName": "X",
          "version": "1.0"
        },
        "channel": {
          "kind": "slack",
          "recipientAddressing": {}
        },
        "communication": {
          "contentClass": "Reply",
          "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "bodySize": 0,
          "previewLines": 0,
          "preview": ""
        },
        "policy": {
          "decision": "AskEveryTime",
          "matchedScope": "per-channel"
        },
        "notarization": {
          "notaryService": {
            "id": "did:web:notary.squillo.com",
            "name": "Squillo Notary Service",
            "version": "0.1.0"
          },
          "decisionTimestamp": "2026-05-21T00:00:01Z",
          "decisionLatencyMs": 0
        }
      },
      "proof": {
        "type": "DataIntegrityProof",
        "verificationMethod": "did:key:abc#abc",
        "created": "2026-05-21T00:00:01Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z..."
      },
      "extraKey": "x"
    })
    .to_string();
    let r: std::result::Result<super::NotarizationEnvelope, _> = serde_json::from_str(&s);
    std::assert!(
      r.is_err(),
      "deny_unknown_fields must reject extraKey: {:?}",
      r
    );
  }

  #[test]
  fn human_principal_ref_rejects_unknown_field() {
    // deny_unknown_fields does NOT cascade to nested structs — each one
    // needs its own attribute. This pins that the nested case is covered,
    // not merely the top level.
    let s = serde_json::json!({
      "id": "did:key:abc",
      "displayName": "X",
      "rogue": true
    })
    .to_string();
    let r: std::result::Result<super::HumanPrincipalRef, _> = serde_json::from_str(&s);
    std::assert!(
      r.is_err(),
      "deny_unknown_fields must reject rogue field: {:?}",
      r
    );
  }

  // -------- Test 4: defaults on optional fields --------

  #[test]
  fn envelope_deserializes_without_linked_mandate() {
    // Most envelopes carry no cross-protocol link, so the common case must
    // parse with the key absent — under deny_unknown_fields this works
    // only while #[serde(default)] is present.
    let s = serde_json::json!({
      "aphVersion": "0.1",
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/aph/v1"
      ],
      "type": ["VerifiableCredential", "AgentSendAuthorizationCredential"],
      "id": "urn:uuid:00000000-0000-4000-8000-000000000001",
      "issuer": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV",
      "validFrom": "2026-05-21T00:00:00Z",
      "validUntil": "2026-05-22T00:00:00Z",
      "credentialSubject": {
        "humanPrincipal": {
          "id": "did:key:abc",
          "displayName": "X"
        },
        "agent": {
          "id": "did:web:agent.squillo.com",
          "displayName": "X",
          "version": "1.0"
        },
        "channel": {
          "kind": "slack",
          "recipientAddressing": {}
        },
        "communication": {
          "contentClass": "Reply",
          "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "bodySize": 0,
          "previewLines": 0,
          "preview": ""
        },
        "policy": {
          "decision": "AskEveryTime",
          "matchedScope": "per-channel"
        },
        "notarization": {
          "notaryService": {
            "id": "did:web:notary.squillo.com",
            "name": "Squillo Notary Service",
            "version": "0.1.0"
          },
          "decisionTimestamp": "2026-05-21T00:00:01Z",
          "decisionLatencyMs": 0
        }
      },
      "proof": {
        "type": "DataIntegrityProof",
        "verificationMethod": "did:key:abc#abc",
        "created": "2026-05-21T00:00:01Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z..."
      }
    })
    .to_string();
    let v: super::NotarizationEnvelope =
      serde_json::from_str(&s).expect("must deserialize with linkedMandate omitted");
    std::assert!(v.linked_mandate.is_none());
  }

  #[test]
  fn envelope_round_trips_a_credential_status_under_the_camel_case_wire_key() {
    // Why this exists: until it did, NOTHING in the repo parsed or emitted a
    // `credentialStatus` ON THE WIRE. The §6.3.3 tests set the field in Rust
    // and the golden test only asserts the key is ABSENT, so the camelCase
    // spelling the field exists to produce — and `deny_unknown_fields`
    // accepting it on `NotarizationEnvelope` at all — were pinned by nothing.
    // A rename to `credential_status`, or the field being dropped from the
    // struct, would have passed the entire suite while making every
    // status-bearing envelope from a conformant notary unparseable.
    //
    // What it pins, in order: the key is ACCEPTED by the strict parser; the
    // nested entry lands in the typed field with its closed enums resolved;
    // and serializing re-emits under exactly `credentialStatus` with exactly
    // the four required members (Pattern A drops the absent `id` — a `null`
    // there would change the JCS bytes a proof covers).
    let s = serde_json::json!({
      "aphVersion": "0.1",
      "@context": [
        "https://www.w3.org/ns/credentials/v2",
        "https://w3id.org/aph/v1"
      ],
      "type": ["VerifiableCredential", "AgentSendAuthorizationCredential"],
      "id": "urn:uuid:00000000-0000-4000-8000-000000000001",
      "issuer": "did:key:z6MkpTHR8VNsBxYAAWHut2Geadd9jSdoVTwBaPaeT1KhFmkV",
      "validFrom": "2026-05-21T00:00:00Z",
      "validUntil": "2026-05-22T00:00:00Z",
      "credentialSubject": {
        "humanPrincipal": {
          "id": "did:key:abc",
          "displayName": "X"
        },
        "agent": {
          "id": "did:web:agent.squillo.com",
          "displayName": "X",
          "version": "1.0"
        },
        "channel": {
          "kind": "slack",
          "recipientAddressing": {}
        },
        "communication": {
          "contentClass": "Reply",
          "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
          "bodySize": 0,
          "previewLines": 0,
          "preview": ""
        },
        "policy": {
          "decision": "AskEveryTime",
          "matchedScope": "per-channel",
          // §6.3.3.1 forbids a status reference with no parent mandate to be
          // the status OF, so the wire sample carries both or it is not a
          // sample of anything a notary may emit.
          "delegationMandateId": "urn:uuid:00000000-0000-4000-8000-0000000000d1"
        },
        "notarization": {
          "notaryService": {
            "id": "did:web:aph-notary.squillo.com",
            "name": "Squillo Notary Service",
            "version": "0.1.0"
          },
          "decisionTimestamp": "2026-05-21T00:00:01Z",
          "decisionLatencyMs": 0
        }
      },
      "credentialStatus": {
        "type": "BitstringStatusListEntry",
        "statusPurpose": "revocation",
        "statusListIndex": "94567",
        "statusListCredential": "https://aph-notary.squillo.com/.well-known/aph-status.json"
      },
      "proof": {
        "type": "DataIntegrityProof",
        "verificationMethod": "did:key:abc#abc",
        "created": "2026-05-21T00:00:01Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z..."
      }
    })
    .to_string();
    let v: super::NotarizationEnvelope = serde_json::from_str(&s)
      .expect("deny_unknown_fields must ACCEPT the credentialStatus key");
    let entry = v
      .credential_status
      .as_ref()
      .expect("the wire key must land in the typed field");
    std::assert_eq!(
      entry.r#type,
      crate::credential_status::StatusEntryType::BitstringStatusListEntry
    );
    std::assert_eq!(
      entry.status_purpose,
      crate::credential_status::StatusPurpose::Revocation
    );
    std::assert_eq!(entry.index().expect("the index is readable"), 94567u64);

    // Re-emitted under the SAME key: compared as parsed JSON, not as a
    // substring, so a serializer that wrote the right characters in the
    // wrong place could not pass.
    let back = serde_json::to_string(&v).expect("envelope serializes");
    let reparsed: serde_json::Value = serde_json::from_str(&back).expect("round-trip is JSON");
    let emitted = reparsed
      .get("credentialStatus")
      .expect("the member must be re-emitted as `credentialStatus`");
    std::assert_eq!(
      emitted,
      &serde_json::json!({
        "type": "BitstringStatusListEntry",
        "statusPurpose": "revocation",
        "statusListIndex": "94567",
        "statusListCredential": "https://aph-notary.squillo.com/.well-known/aph-status.json"
      }),
      "the absent optional `id` must not appear, as a null or otherwise"
    );
    // And the member is INSIDE the bytes the notary proof covers. That is
    // what makes the reference unstrippable in flight: an attacker who
    // deleted `credentialStatus` to force §6.3.3.4 case 1 — the skip — would
    // be altering the signing base, and the proof would stop verifying.
    // Asserted on the canonical base rather than on the struct because the
    // base is the only place the property is actually true or false.
    let base = crate::crypto::proof_base::signing_base(
      &v,
      crate::crypto::proof_base::ProofRole::Notary,
    )
    .expect("a single notary proof builds a notary base");
    std::assert!(
      base.contains("\"credentialStatus\""),
      "the status reference must be covered by the notary signature"
    );
  }

  #[test]
  fn agent_ref_deserializes_without_agent_card_uri() {
    // Not every agent publishes an A2A AgentCard; omitting the URI must
    // stay legal rather than making those agents unable to be notarized.
    let s = serde_json::json!({
      "id": "did:web:agent.squillo.com",
      "displayName": "X",
      "version": "1.0"
    })
    .to_string();
    let v: super::AgentRef =
      serde_json::from_str(&s).expect("must deserialize with agentCardUri omitted");
    std::assert!(v.agent_card_uri.is_none());
  }

  #[test]
  fn policy_descriptor_deserializes_without_optionals() {
    // The one-shot AskEveryTime shape has no delegation and no act chain,
    // so both optional fields must be omissible together — the defaults
    // that make a human-present decision representable at all.
    let s = serde_json::json!({
      "decision": "AskEveryTime",
      "matchedScope": "per-channel"
    })
    .to_string();
    let v: super::PolicyDescriptor =
      serde_json::from_str(&s).expect("must deserialize with optionals omitted");
    std::assert!(v.delegation_mandate_id.is_none());
    std::assert!(v.act_chain.is_empty());
    std::assert!(v.attestation_mode.is_none());
    std::assert!(v.delegation_mandate.is_none());
  }

  #[test]
  fn linked_mandate_deserializes_without_ap2_uri() {
    // A linkedMandate may carry a vault mutation with no payment link, so
    // its fields must be independently optional rather than all-or-nothing.
    let s = serde_json::json!({}).to_string();
    let v: super::LinkedMandate =
      serde_json::from_str(&s).expect("must deserialize with ap2IntentMandateUri omitted");
    std::assert!(v.ap2_intent_mandate_uri.is_none());
  }

  #[test]
  fn envelope_proof_deserializes_without_cryptosuite() {
    // cryptosuite applies to DataIntegrityProof but not to the
    // JsonWebSignature2020 form (§8.2), so a JWS-style proof must parse
    // without it instead of being rejected as malformed.
    let s = serde_json::json!({
      "type": "JsonWebSignature2020",
      "verificationMethod": "did:key:abc#abc",
      "created": "2026-05-21T00:00:01Z",
      "proofPurpose": "assertionMethod",
      "proofValue": "z..."
    })
    .to_string();
    let v: super::EnvelopeProof =
      serde_json::from_str(&s).expect("must deserialize with cryptosuite omitted");
    std::assert!(v.cryptosuite.is_none());
  }

  // -------- Test 5: camelCase wire form --------

  #[test]
  fn human_principal_ref_serializes_camel_case() {
    // Rust field names are snake_case; the wire is camelCase. This pins
    // that the rename_all attribute is actually applied — without it every
    // key would silently change and no other implementation could parse it.
    let v = super::HumanPrincipalRef {
      id: "did:key:abc".to_string(),
      display_name: "Scott".to_string(),
    };
    let s = serde_json::to_string(&v).unwrap();
    std::assert!(
      s.contains("\"displayName\""),
      "must serialize display_name as displayName: {}",
      s
    );
    std::assert!(
      !s.contains("\"display_name\""),
      "must NOT serialize as display_name: {}",
      s
    );
  }

  // -------- Test 6: AppleAurAcceptanceClaim round-trip --------

  #[test]
  fn apple_aur_acceptance_claim_round_trip() {
    // Registered optional extension (spec §7.5.1). It must round-trip
    // fully when present while staying absent-by-default, so that
    // extension-free envelopes keep their exact pre-extension bytes.
    let claim = super::AppleAurAcceptanceClaim {
      user_id: "did:key:z6MkUserAbc123".to_string(),
      device_id: "device-opaque-id-001".to_string(),
      aur_version_hash:
        "a3b4c5d6e7f8091011121314151617181920212223242526272829303132333435".to_string(),
      accepted_at: "2026-06-09T00:00:00Z".to_string(),
      document_kind: "foundation_models_framework_aur".to_string(),
    };
    let subject = super::CredentialSubject {
      human_principal: sample_human_principal(),
      agent: sample_agent(),
      channel: sample_channel(),
      communication: sample_communication(),
      policy: sample_policy(),
      notarization: sample_notarization_metadata(),
      apple_aur_acceptance: std::option::Option::Some(claim.clone()),
    };
    let s = serde_json::to_string(&subject).unwrap();
    // wire form must use camelCase key
    std::assert!(
      s.contains("\"appleAurAcceptance\""),
      "must serialize apple_aur_acceptance as appleAurAcceptance: {}",
      s
    );
    let v2: super::CredentialSubject = serde_json::from_str(&s).unwrap();
    std::assert_eq!(subject, v2);
    let recovered = v2.apple_aur_acceptance.expect("must be Some after round-trip");
    std::assert_eq!(recovered.document_kind, "foundation_models_framework_aur");
    std::assert_eq!(recovered.user_id, claim.user_id);
    std::assert_eq!(recovered.device_id, claim.device_id);
    std::assert_eq!(recovered.aur_version_hash, claim.aur_version_hash);
    std::assert_eq!(recovered.accepted_at, claim.accepted_at);
  }

  // -------- Test 7: legacy wire back-compat (field absent) --------

  #[test]
  fn credential_subject_legacy_omit_apple_aur_acceptance() {
    // A legacy CredentialSubject JSON payload that does NOT contain
    // `appleAurAcceptance` must still deserialize cleanly with
    // `apple_aur_acceptance == None` (wire back-compat).
    let s = serde_json::json!({
      "humanPrincipal": {
        "id": "did:key:z6MkLegacyUser",
        "displayName": "Legacy User"
      },
      "agent": {
        "id": "did:web:agent.squillo.com",
        "displayName": "Squillo Concierge",
        "version": "1.0"
      },
      "channel": {
        "kind": "slack",
        "recipientAddressing": {}
      },
      "communication": {
        "contentClass": "Reply",
        "bodySha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "bodySize": 0,
        "previewLines": 0,
        "preview": ""
      },
      "policy": {
        "decision": "AskEveryTime",
        "matchedScope": "per-channel"
      },
      "notarization": {
        "notaryService": {
          "id": "did:web:notary.squillo.com",
          "name": "Squillo Notary Service",
          "version": "0.1.0"
        },
        "decisionTimestamp": "2026-05-21T00:00:01Z",
        "decisionLatencyMs": 0
      }
    })
    .to_string();
    let v: super::CredentialSubject = serde_json::from_str(&s)
      .expect("legacy payload without appleAurAcceptance must deserialize cleanly");
    std::assert!(
      v.apple_aur_acceptance.is_none(),
      "apple_aur_acceptance must be None when absent from legacy wire payload"
    );
  }

  // -------- Test 8: proof-chain wire forms (§7.1.11) --------

  #[test]
  fn envelope_proofs_round_trips_the_single_object_wire_form() {
    // `proof` is untagged: the JSON SHAPE is the only discriminator between
    // a lone notary proof and a chain. If the object form ever deserialized
    // into `Chain` (or failed), every one of the eight published envelopes
    // — all of which carry a single object — would stop parsing.
    let single = super::EnvelopeProofs::Single(sample_proof());
    let s = serde_json::to_string(&single).unwrap();
    std::assert!(
      s.starts_with('{'),
      "the single form must serialize as a JSON OBJECT, not an array: {}",
      s
    );
    let back: super::EnvelopeProofs = serde_json::from_str(&s).unwrap();
    std::assert_eq!(single, back);
  }

  #[test]
  fn envelope_proofs_round_trips_the_array_wire_form() {
    // The other half of the untagged discrimination. §7.2.1 makes the array
    // form load-bearing: `[{…}]` and `{…}` canonicalize to different bytes,
    // which is what domain-separates a principal proof from a lone notary
    // proof. Collapsing the array to an object on re-serialization would
    // silently forge that domain separation away.
    let chain = super::EnvelopeProofs::Chain(std::vec![
      sample_principal_proof(),
      sample_notary_countersignature(),
    ]);
    let s = serde_json::to_string(&chain).unwrap();
    std::assert!(
      s.starts_with('['),
      "the chain form must serialize as a JSON ARRAY: {}",
      s
    );
    let back: super::EnvelopeProofs = serde_json::from_str(&s).unwrap();
    std::assert_eq!(chain, back);
  }

  #[test]
  fn envelope_with_absent_additive_fields_emits_none_of_their_keys() {
    // `attestationMode`, `id` and `previousProof` were added to structs
    // whose serialized bytes are what signatures cover. An envelope that
    // sets none of them MUST serialize byte-identically to one written
    // before the fields existed, or every already-issued signature breaks.
    let json = serde_json::to_string(&sample_envelope()).unwrap();
    std::assert!(
      !json.contains("attestationMode"),
      "absent attestationMode must not appear on the wire: {}",
      json
    );
    std::assert!(
      !json.contains("delegationMandate\""),
      "absent embedded delegationMandate must not appear on the wire: {}",
      json
    );
    std::assert!(
      !json.contains("previousProof"),
      "absent previousProof must not appear on the wire: {}",
      json
    );
    std::assert!(
      !json.contains("\"id\":null"),
      "absent proof id must be omitted, never emitted as null: {}",
      json
    );
  }

  #[test]
  fn all_returns_every_proof_for_both_wire_forms() {
    // `all()` is what lets a caller iterate proofs without branching on the
    // variant. If the single form returned an empty slice, a verifier
    // looping over `all()` would verify NOTHING and report success.
    std::assert_eq!(
      super::EnvelopeProofs::Single(sample_proof()).all().len(),
      1
    );
    std::assert_eq!(
      super::EnvelopeProofs::Chain(std::vec![
        sample_principal_proof(),
        sample_notary_countersignature(),
      ])
      .all()
      .len(),
      2
    );
  }

  #[test]
  fn principal_is_none_for_a_single_proof() {
    // A lone proof is the NOTARY's (§7.1.11). Reporting it as the principal
    // proof would let a caller present a notary attestation as the human's
    // own signature — the exact confusion `attestationMode` exists to stop.
    std::assert!(
      super::EnvelopeProofs::Single(sample_proof())
        .principal()
        .is_none()
    );
  }

  #[test]
  fn notary_is_the_lone_proof_and_the_tail_of_a_chain() {
    // Both wire forms carry a notary proof, and it is the proof steps 2-9 of
    // §8.3 verify. A caller must be able to reach it identically either way.
    let single = super::EnvelopeProofs::Single(sample_proof());
    std::assert_eq!(
      single.notary().map(|p| p.proof_purpose.as_str()),
      std::option::Option::Some("assertionMethod")
    );
    let chain = super::EnvelopeProofs::Chain(std::vec![
      sample_principal_proof(),
      sample_notary_countersignature(),
    ]);
    std::assert_eq!(
      chain.notary().map(|p| p.proof_purpose.as_str()),
      std::option::Option::Some("authentication")
    );
  }

  #[test]
  fn accessors_refuse_to_name_proofs_inside_a_malformed_chain() {
    // §7.1.11 fixes chain length at exactly two. A three-element array is
    // rejected there, but these accessors are called by code that has not
    // run that check yet, so they must not hand back a "principal proof" or
    // "notary proof" from a structure the spec refuses — a caller would
    // verify one signature out of three and believe the chain sound.
    let over_long = super::EnvelopeProofs::Chain(std::vec![
      sample_principal_proof(),
      sample_notary_countersignature(),
      sample_notary_countersignature(),
    ]);
    std::assert!(over_long.principal().is_none());
    std::assert!(over_long.notary().is_none());
  }

  #[test]
  fn is_chain_reports_the_array_form_at_any_length() {
    // The distinction is the WIRE form, not validity: a one-element array is
    // still a chain (an invalid one). If `is_chain()` reported false for it,
    // §7.2.1's stripped-notary-proof attack would slip past — the whole
    // point is that a one-element array is recognised and then rejected.
    std::assert!(
      super::EnvelopeProofs::Chain(std::vec![sample_principal_proof()]).is_chain()
    );
    std::assert!(!super::EnvelopeProofs::Single(sample_proof()).is_chain());
  }

  #[test]
  fn absent_attestation_mode_resolves_to_notary_attested() {
    // §7.1.7 fixes ABSENT as `NotaryAttested`, the WEAKER claim. All eight
    // published envelopes omit the field; defaulting the other way would
    // silently promote every one of them to asserting the human personally
    // signed, which no party ever claimed.
    std::assert_eq!(
      sample_policy().effective_attestation_mode(),
      super::AttestationMode::NotaryAttested
    );
  }

  #[test]
  fn declared_attestation_mode_is_returned_verbatim() {
    // The default must apply only to absence. If it overrode a present
    // value, a `PrincipalSigned` envelope would be downgraded to the notary's
    // assertion and the human's signature would go unchecked.
    let mut policy = sample_policy();
    policy.attestation_mode = std::option::Option::Some(super::AttestationMode::PrincipalSigned);
    std::assert_eq!(
      policy.effective_attestation_mode(),
      super::AttestationMode::PrincipalSigned
    );
  }

  #[test]
  fn attestation_mode_wire_spelling_matches_the_closed_enum() {
    // §7.1.7 fixes a CLOSED enum with these exact spellings, and other
    // implementations compare the string. A serde rename or a variant
    // rename would make our envelopes unreadable to them, and `label()` is
    // what error messages show an operator, so both must agree.
    std::assert_eq!(
      serde_json::to_string(&super::AttestationMode::PrincipalSigned).unwrap(),
      "\"PrincipalSigned\""
    );
    std::assert_eq!(
      serde_json::to_string(&super::AttestationMode::NotaryAttested).unwrap(),
      "\"NotaryAttested\""
    );
    std::assert_eq!(super::AttestationMode::PrincipalSigned.label(), "PrincipalSigned");
    std::assert_eq!(super::AttestationMode::NotaryAttested.label(), "NotaryAttested");
  }

  #[test]
  fn envelope_parses_a_chain_and_the_principal_signed_label_from_the_wire() {
    // End-to-end wire acceptance of the §7.1.11 shape: a verifier written
    // against this crate must be able to receive a real `PrincipalSigned`
    // envelope. Both additive fields sit under `deny_unknown_fields`, so
    // without the declarations a conformant producer would be rejected.
    let mut envelope = sample_envelope();
    envelope.credential_subject.policy.attestation_mode =
      std::option::Option::Some(super::AttestationMode::PrincipalSigned);
    envelope.proof = super::EnvelopeProofs::Chain(std::vec![
      sample_principal_proof(),
      sample_notary_countersignature(),
    ]);
    let s = serde_json::to_string(&envelope).unwrap();
    let back: super::NotarizationEnvelope =
      serde_json::from_str(&s).expect("a PrincipalSigned chain envelope must parse");
    std::assert_eq!(envelope, back);
  }
}