Add Rust example programs for DID:x509, CWT claims, and certificate trust

Add three new example programs to the native Rust workspace:

- did/x509/examples/did_x509_basics.rs: Demonstrates parsing, building,
  validating, and resolving DID:x509 identifiers with ephemeral CA + leaf
  certificate chains created via rcgen.

- signing/headers/examples/cwt_claims_basics.rs: Shows CWT claims builder
  fluent API, CBOR serialization/deserialization roundtrip, header label
  constants, and minimal SCITT claims patterns.

- extension_packs/certificates/examples/certificate_trust_validation.rs:
  Demonstrates X.509 certificate trust validation pipeline including
  COSE_Sign1 message construction with x5chain header, trust pack
  configuration, and custom trust plan building with fluent extensions.

All examples compile and run successfully. Each uses only existing
dev-dependencies (rcgen, hex, sha2) and produces visible stdout output.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Jstatia

native/rust/did/x509/Cargo.toml

@@ -20,5 +20,8 @@ hex = "0.4"
 sha2.workspace = true
 openssl = { workspace = true }
 
-[lints.rust]
+[[example]]
+name = "did_x509_basics"
+
+[lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage,coverage_nightly)'] }

native/rust/did/x509/examples/did_x509_basics.rs

@@ -0,0 +1,143 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! DID:x509 basics — parse, build, validate, and resolve workflows.
+//!
+//! Run with:
+//!   cargo run --example did_x509_basics -p did_x509
+
+use std::borrow::Cow;
+
+use did_x509::{
+    DidX509Builder, DidX509Parser, DidX509Policy, DidX509Resolver, DidX509Validator, SanType,
+};
+use rcgen::{BasicConstraints, CertificateParams, IsCa, Issuer, KeyPair};
+use sha2::{Digest, Sha256};
+
+fn main() {
+    // ── 1. Generate an ephemeral CA + leaf certificate chain ──────────
+    println!("=== Step 1: Create ephemeral certificate chain ===\n");
+
+    let (ca_der, leaf_der) = create_cert_chain();
+    let chain: Vec<&[u8]> = vec![leaf_der.as_slice(), ca_der.as_slice()];
+
+    let ca_thumbprint = hex::encode(Sha256::digest(&ca_der));
+    println!("  CA thumbprint (SHA-256): {}", ca_thumbprint);
+
+    // ── 2. Build a DID:x509 identifier from the chain ────────────────
+    println!("\n=== Step 2: Build DID:x509 identifiers ===\n");
+
+    // Build with an EKU policy (code-signing OID 1.3.6.1.5.5.7.3.3)
+    let eku_policy = DidX509Policy::Eku(vec![Cow::Borrowed("1.3.6.1.5.5.7.3.3")]);
+    let did_eku = DidX509Builder::build_sha256(&ca_der, &[eku_policy.clone()])
+        .expect("build EKU DID");
+    println!("  DID (EKU):     {}", did_eku);
+
+    // Build with a subject policy
+    let subject_policy = DidX509Policy::Subject(vec![
+        ("CN".to_string(), "Example Leaf".to_string()),
+    ]);
+    let did_subject = DidX509Builder::build_sha256(&ca_der, &[subject_policy.clone()])
+        .expect("build subject DID");
+    println!("  DID (Subject): {}", did_subject);
+
+    // Build with a SAN policy
+    let san_policy = DidX509Policy::San(SanType::Dns, "leaf.example.com".to_string());
+    let did_san = DidX509Builder::build_sha256(&ca_der, &[san_policy.clone()])
+        .expect("build SAN DID");
+    println!("  DID (SAN):     {}", did_san);
+
+    // ── 3. Parse DID:x509 identifiers back into components ───────────
+    println!("\n=== Step 3: Parse DID:x509 identifiers ===\n");
+
+    let parsed = DidX509Parser::parse(&did_eku).expect("parse DID");
+    println!("  Hash algorithm:     {}", parsed.hash_algorithm);
+    println!("  CA fingerprint hex: {}", parsed.ca_fingerprint_hex);
+    println!("  Has EKU policy:     {}", parsed.has_eku_policy());
+    println!("  Has subject policy: {}", parsed.has_subject_policy());
+
+    if let Some(eku_oids) = parsed.get_eku_policy() {
+        println!("  EKU OIDs:           {:?}", eku_oids);
+    }
+
+    // ── 4. Validate DID against the certificate chain ────────────────
+    println!("\n=== Step 4: Validate DID against certificate chain ===\n");
+
+    // Validate the SAN-based DID (leaf cert has SAN: dns:leaf.example.com)
+    let result = DidX509Validator::validate(&did_san, &chain).expect("validate DID");
+    println!("  DID (SAN) valid:         {}", result.is_valid);
+    println!("  Matched CA index:        {:?}", result.matched_ca_index);
+
+    // Validate subject-based DID (leaf cert has CN=Example Leaf)
+    let result = DidX509Validator::validate(&did_subject, &chain).expect("validate subject DID");
+    println!("  DID (Subject) valid:     {}", result.is_valid);
+
+    // Demonstrate a failing validation with a wrong subject
+    let wrong_subject = DidX509Policy::Subject(vec![
+        ("CN".to_string(), "Wrong Name".to_string()),
+    ]);
+    let did_wrong = DidX509Builder::build_sha256(&ca_der, &[wrong_subject])
+        .expect("build wrong DID");
+    let result = DidX509Validator::validate(&did_wrong, &chain).expect("validate wrong DID");
+    println!("  DID (wrong CN) valid:    {} (expected false)", result.is_valid);
+    if !result.errors.is_empty() {
+        println!("  Validation errors:       {:?}", result.errors);
+    }
+
+    // ── 5. Resolve DID to a DID Document ─────────────────────────────
+    println!("\n=== Step 5: Resolve DID to DID Document ===\n");
+
+    let doc = DidX509Resolver::resolve(&did_san, &chain).expect("resolve DID");
+    let doc_json = doc.to_json(true).expect("serialize DID Document");
+    println!("{}", doc_json);
+
+    println!("\n=== All steps completed successfully! ===");
+}
+
+/// Create an ephemeral CA and leaf certificate chain using rcgen.
+/// Returns (ca_der, leaf_der) — both DER-encoded.
+fn create_cert_chain() -> (Vec<u8>, Vec<u8>) {
+    // CA certificate
+    let mut ca_params = CertificateParams::new(vec!["Example CA".to_string()]).unwrap();
+    ca_params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
+    ca_params
+        .distinguished_name
+        .push(rcgen::DnType::CommonName, "Example CA");
+    ca_params
+        .distinguished_name
+        .push(rcgen::DnType::OrganizationName, "Example Org");
+
+    let ca_key = KeyPair::generate().unwrap();
+    let ca_cert = ca_params.self_signed(&ca_key).unwrap();
+    let ca_der = ca_cert.der().to_vec();
+
+    // Create an Issuer from the CA params + key for signing the leaf.
+    // Note: Issuer::new consumes the params, so we rebuild them.
+    let mut ca_issuer_params = CertificateParams::new(vec!["Example CA".to_string()]).unwrap();
+    ca_issuer_params.is_ca = IsCa::Ca(BasicConstraints::Unconstrained);
+    ca_issuer_params
+        .distinguished_name
+        .push(rcgen::DnType::CommonName, "Example CA");
+    ca_issuer_params
+        .distinguished_name
+        .push(rcgen::DnType::OrganizationName, "Example Org");
+    let ca_issuer = Issuer::new(ca_issuer_params, ca_key);
+
+    // Leaf certificate signed by CA
+    let mut leaf_params = CertificateParams::new(vec!["leaf.example.com".to_string()]).unwrap();
+    leaf_params.is_ca = IsCa::NoCa;
+    leaf_params
+        .distinguished_name
+        .push(rcgen::DnType::CommonName, "Example Leaf");
+    leaf_params
+        .distinguished_name
+        .push(rcgen::DnType::OrganizationName, "Example Org");
+    // Add code-signing EKU
+    leaf_params.extended_key_usages = vec![rcgen::ExtendedKeyUsagePurpose::CodeSigning];
+
+    let leaf_key = KeyPair::generate().unwrap();
+    let leaf_cert = leaf_params.signed_by(&leaf_key, &ca_issuer).unwrap();
+    let leaf_der = leaf_cert.der().to_vec();
+
+    (ca_der, leaf_der)
+}

native/rust/extension_packs/certificates/Cargo.toml

@@ -35,5 +35,8 @@ cbor_primitives_everparse = { path = "../../primitives/cbor/everparse" }
 cose_sign1_crypto_openssl = { path = "../../primitives/crypto/openssl" }
 openssl = { workspace = true }
 
+[[example]]
+name = "certificate_trust_validation"
+
 [lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage_nightly)'] }

native/rust/extension_packs/certificates/examples/certificate_trust_validation.rs

@@ -0,0 +1,164 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+//! Certificate-based trust validation — create an ephemeral certificate chain,
+//! construct a COSE_Sign1 message with an embedded x5chain header, then validate
+//! using the X.509 certificate trust pack.
+//!
+//! Run with:
+//!   cargo run --example certificate_trust_validation -p cose_sign1_certificates
+
+use std::sync::Arc;
+
+use cbor_primitives::{CborEncoder, CborProvider};
+use cbor_primitives_everparse::EverParseCborProvider;
+use cose_sign1_certificates::validation::pack::{
+    CertificateTrustOptions, X509CertificateTrustPack,
+};
+use cose_sign1_validation::fluent::*;
+use cose_sign1_validation_primitives::CoseHeaderLocation;
+
+fn main() {
+    // ── 1. Generate an ephemeral self-signed certificate ─────────────
+    println!("=== Step 1: Generate ephemeral certificate ===\n");
+
+    let rcgen::CertifiedKey { cert, .. } =
+        rcgen::generate_simple_self_signed(vec!["example-leaf".to_string()])
+            .expect("rcgen failed");
+    let leaf_der = cert.der().to_vec();
+    println!("  Leaf cert DER size: {} bytes", leaf_der.len());
+
+    // ── 2. Build a minimal COSE_Sign1 with x5chain header ───────────
+    println!("\n=== Step 2: Build COSE_Sign1 with x5chain ===\n");
+
+    let payload = b"Hello, COSE world!";
+    let cose_bytes = build_cose_sign1_with_x5chain(&leaf_der, payload);
+    println!("  COSE message size: {} bytes", cose_bytes.len());
+    println!("  Payload: {:?}", std::str::from_utf8(payload).unwrap());
+
+    // ── 3. Set up the certificate trust pack ─────────────────────────
+    println!("\n=== Step 3: Configure certificate trust pack ===\n");
+
+    // For this example, treat the embedded x5chain as trusted.
+    // In production, configure actual trust roots and revocation checks.
+    let cert_pack = Arc::new(X509CertificateTrustPack::new(CertificateTrustOptions {
+        trust_embedded_chain_as_trusted: true,
+        ..Default::default()
+    }));
+    println!("  Trust pack: embedded x5chain treated as trusted");
+
+    let trust_packs: Vec<Arc<dyn CoseSign1TrustPack>> = vec![cert_pack];
+
+    // ── 4. Build a validator with bypass trust + signature bypass ─────
+    //    (We bypass the actual crypto check because the COSE message's
+    //     signature is a dummy — in a real scenario the signing service
+    //     would produce a valid signature.)
+    println!("\n=== Step 4: Validate with trust bypass ===\n");
+
+    let validator = CoseSign1Validator::new(trust_packs.clone()).with_options(|o| {
+        o.certificate_header_location = CoseHeaderLocation::Any;
+        o.trust_evaluation_options.bypass_trust = true;
+    });
+
+    let result = validator
+        .validate_bytes(
+            EverParseCborProvider,
+            Arc::from(cose_bytes.clone().into_boxed_slice()),
+        )
+        .expect("validation pipeline error");
+
+    println!("  resolution: {:?}", result.resolution.kind);
+    println!("  trust:      {:?}", result.trust.kind);
+    println!("  signature:  {:?}", result.signature.kind);
+    println!("  overall:    {:?}", result.overall.kind);
+
+    // ── 5. Demonstrate custom trust plan ─────────────────────────────
+    println!("\n=== Step 5: Custom trust plan (advanced) ===\n");
+
+    use cose_sign1_certificates::validation::fluent_ext::PrimarySigningKeyScopeRulesExt;
+
+    let cert_pack2 = Arc::new(X509CertificateTrustPack::new(CertificateTrustOptions {
+        trust_embedded_chain_as_trusted: true,
+        ..Default::default()
+    }));
+    let packs: Vec<Arc<dyn CoseSign1TrustPack>> = vec![cert_pack2];
+
+    let plan = TrustPlanBuilder::new(packs)
+        .for_primary_signing_key(|key| {
+            key.require_x509_chain_trusted()
+                .and()
+                .require_signing_certificate_present()
+        })
+        .compile()
+        .expect("plan compile");
+
+    let validator2 = CoseSign1Validator::new(plan).with_options(|o| {
+        o.certificate_header_location = CoseHeaderLocation::Any;
+    });
+
+    let result2 = validator2
+        .validate_bytes(
+            EverParseCborProvider,
+            Arc::from(cose_bytes.into_boxed_slice()),
+        )
+        .expect("validation pipeline error");
+
+    println!("  resolution: {:?}", result2.resolution.kind);
+    println!("  trust:      {:?}", result2.trust.kind);
+    println!("  signature:  {:?}", result2.signature.kind);
+    println!("  overall:    {:?}", result2.overall.kind);
+
+    // Print failures if any
+    let stages = [
+        ("resolution", &result2.resolution),
+        ("trust", &result2.trust),
+        ("signature", &result2.signature),
+        ("overall", &result2.overall),
+    ];
+    for (name, stage) in stages {
+        if !stage.failures.is_empty() {
+            println!("\n  {} failures:", name);
+            for f in &stage.failures {
+                println!("    - {}", f.message);
+            }
+        }
+    }
+
+    println!("\n=== Example completed! ===");
+}
+
+/// Build a minimal COSE_Sign1 byte sequence with an embedded x5chain header.
+///
+/// The message structure is:
+///   [protected_headers_bstr, unprotected_headers_map, payload_bstr, signature_bstr]
+///
+/// Protected headers contain:
+///   { 1 (alg): -7 (ES256), 33 (x5chain): bstr(cert_der) }
+fn build_cose_sign1_with_x5chain(leaf_der: &[u8], payload: &[u8]) -> Vec<u8> {
+    let p = EverParseCborProvider;
+    let mut enc = p.encoder();
+
+    // COSE_Sign1 is a 4-element CBOR array
+    enc.encode_array(4).unwrap();
+
+    // Protected headers: CBOR bstr wrapping a CBOR map
+    let mut hdr_enc = p.encoder();
+    hdr_enc.encode_map(2).unwrap();
+    hdr_enc.encode_i64(1).unwrap();   // label: alg
+    hdr_enc.encode_i64(-7).unwrap();  // value: ES256
+    hdr_enc.encode_i64(33).unwrap();  // label: x5chain
+    hdr_enc.encode_bstr(leaf_der).unwrap();
+    let protected_bytes = hdr_enc.into_bytes();
+    enc.encode_bstr(&protected_bytes).unwrap();
+
+    // Unprotected headers: empty map
+    enc.encode_map(0).unwrap();
+
+    // Payload: embedded byte string
+    enc.encode_bstr(payload).unwrap();
+
+    // Signature: dummy (not cryptographically valid)
+    enc.encode_bstr(b"example-signature-placeholder").unwrap();
+
+    enc.into_bytes()
+}

native/rust/signing/headers/Cargo.toml

@@ -17,5 +17,8 @@ did_x509 = { path = "../../did/x509" }
 [dev-dependencies]
 cbor_primitives_everparse = { path = "../../primitives/cbor/everparse" }
 
-[lints.rust]
+[[example]]
+name = "cwt_claims_basics"
+
+[lints.rust]
 unexpected_cfgs = { level = "warn", check-cfg = ['cfg(coverage,coverage_nightly)'] }