mid-verify 0.2.0

mID JWT verifier — RP-side. Runs the four-step verification (genesis self-sig → roster chain → head VM → JWS signature) entirely locally per ADR 0005 Decision 1. Zero runtime calls to MATA infrastructure. Phase 0 of the mID Mission.
Documentation
//! The four cryptographic checks per ADR 0005 Decision 1.
//!
//! Each check is a pure function isolated from the others — easier to
//! reason about, easier to test in isolation. The orchestrator in
//! [`crate::verify`] runs them in order; if any fails, verification
//! short-circuits.

use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine as _};
use mid_issuer::canonical;
use mid_issuer::{EmbeddedRosterChainEntry, MidJwtPayload, VerificationMethod};
use p256::ecdsa::signature::hazmat::PrehashVerifier;
use p256::ecdsa::Signature;
use sha2::{Digest, Sha256};

use crate::error::VerifyError;
use crate::keys::{pubkey_from_did, pubkey_from_multibase};

/// Decode a base64url-encoded ECDSA P-256 signature into the
/// `p256::ecdsa::Signature` type used by `verify_prehash`.
fn decode_signature(b64: &str) -> Result<Signature, VerifyError> {
    let bytes = URL_SAFE_NO_PAD.decode(b64).map_err(|source| VerifyError::Base64Decode {
        segment: "signature",
        source,
    })?;
    signature_from_raw(&bytes)
}

/// Build a `Signature` from raw `r || s` bytes, rejecting the degenerate cases.
///
/// The all-zero check is not redundant with `from_slice`: a wallet whose vault
/// is locked, or whose signing call failed, commonly returns 64 zero bytes as a
/// placeholder. Without this, such a placeholder reaches the verifier as an
/// ordinary signature failure instead of the distinguishable condition it is.
fn signature_from_raw(bytes: &[u8]) -> Result<Signature, VerifyError> {
    if bytes.len() != 64 {
        return Err(VerifyError::SignatureWrongLength {
            actual: bytes.len(),
        });
    }
    if bytes.iter().all(|&b| b == 0) {
        return Err(VerifyError::SignatureInvalidScalars);
    }
    Signature::from_slice(bytes).map_err(|_| VerifyError::SignatureInvalidScalars)
}

/// **Check 1.** Verify the genesis roster's self-signature against the
/// public key recoverable from the DID. Proves "this genesis roster was
/// authored by the holder of the genesis key" — and the genesis key is
/// recoverable from the DID itself, so this is a fully self-contained
/// check (no MATA dependency).
pub fn check_genesis_self_signature(payload: &MidJwtPayload) -> Result<(), VerifyError> {
    // The DID's iss claim encodes the genesis pubkey.
    let genesis_pubkey = pubkey_from_did(&payload.iss)?;

    // The signed bytes are the domain-separated canonical form (excludes
    // the signature field itself).
    let canonical_bytes = canonical::genesis_canonical_bytes(&payload.embedded_genesis_roster);
    let prehash: [u8; 32] = Sha256::digest(&canonical_bytes).into();

    let signature =
        decode_signature(&payload.embedded_genesis_roster.self_signed_by_genesis_key)?;

    genesis_pubkey
        .verify_prehash(&prehash, &signature)
        .map_err(|_| VerifyError::GenesisSignatureInvalid)
}

/// **Check 2.** Verify the roster chain — each entry must be signed by
/// a verification method present in the prior entry's roster, and
/// versions must strictly increase. Proves "the current roster
/// legitimately descends from genesis via signer-in-prior-roster
/// signatures."
pub fn check_roster_chain(payload: &MidJwtPayload) -> Result<(), VerifyError> {
    let mut prior_vms: &[VerificationMethod] =
        &payload.embedded_genesis_roster.verification_methods;
    let mut prior_version: u64 = payload.embedded_genesis_roster.version;

    for entry in &payload.embedded_roster_chain {
        // Every entry is a roster of this identity: a link that names another DID
        // has no business in its history.
        if entry.did != payload.iss {
            return Err(VerifyError::ChainEntryDidMismatch {
                entry_version: entry.version,
                entry_did: entry.did.clone(),
            });
        }
        check_one_chain_entry(entry, prior_vms, prior_version)?;
        prior_vms = &entry.verification_methods;
        prior_version = entry.version;
    }

    Ok(())
}

fn check_one_chain_entry(
    entry: &EmbeddedRosterChainEntry,
    prior_vms: &[VerificationMethod],
    prior_version: u64,
) -> Result<(), VerifyError> {
    // 1. Monotonic version
    if entry.version <= prior_version {
        return Err(VerifyError::ChainVersionNotMonotonic {
            entry_version: entry.version,
            prior_version,
        });
    }

    // 2. Find the signer's VM in the prior roster.
    //
    // `signer_kid` is the bare device kid (e.g., "dev-laptop"); the VM
    // ID in the prior roster is `<did>#<kid>`, exactly. (A suffix match
    // would also accept `<anything>#<kid>`.)
    let signer_id = format!("{}#{}", entry.did, entry.signer_kid);
    let signer_vm = prior_vms
        .iter()
        .find(|vm| vm.id == signer_id)
        .ok_or_else(|| VerifyError::ChainSignerNotInPriorRoster {
            entry_version: entry.version,
            signer_kid: entry.signer_kid.clone(),
        })?;

    // 3. Decode the signer's pubkey and verify the signature.
    let signer_pubkey = pubkey_from_multibase(&signer_vm.public_key_multibase, &signer_vm.id)?;
    let canonical_bytes = canonical::chain_entry_canonical_bytes(entry);
    let prehash: [u8; 32] = Sha256::digest(&canonical_bytes).into();
    let signature = decode_signature(&entry.signed_by_signer_in_prior_roster)?;

    signer_pubkey
        .verify_prehash(&prehash, &signature)
        .map_err(|_| VerifyError::ChainSignatureInvalid { entry_version: entry.version })
}

/// **Check 3.** Verify the embedded verification method (the device that
/// signed this JWT) is present in the head roster. Proves "this device's
/// key is currently authorized for this DID."
///
/// The head roster is the last entry of the chain, or the genesis roster
/// if the chain is empty.
///
/// The whole method must match, key included, not only its id. Check 4
/// verifies the JWS with the key *the token carries*, and rosters are public
/// (every token embeds its owner's), so an id-only match let anyone copy a
/// roster, keep a rostered device id, put their own key beside it and sign:
/// all four checks passed (found 2026-10-05; test
/// `a_rostered_id_with_a_strangers_key_is_rejected`).
pub fn check_current_vm_in_head(payload: &MidJwtPayload) -> Result<(), VerifyError> {
    let head_vms: &[VerificationMethod] = match payload.embedded_roster_chain.last() {
        Some(head) => &head.verification_methods,
        None => &payload.embedded_genesis_roster.verification_methods,
    };
    let current = &payload.embedded_verification_method;
    let current_id = &current.id;
    let rostered = head_vms.iter().any(|vm| {
        vm.id == current.id
            && vm.public_key_multibase == current.public_key_multibase
            && vm.vm_type == current.vm_type
            && vm.controller == current.controller
    });
    if !rostered {
        return Err(VerifyError::CurrentVmNotInHeadRoster {
            vm_id: current_id.clone(),
        });
    }
    Ok(())
}

/// **Check 4.** Verify the JWS outer signature against the embedded
/// verification method's public key. Standard ES256 verification: SHA-256
/// the `header.payload` signing input, verify the ECDSA signature.
///
/// `signing_input` is the `<header_b64>.<payload_b64>` bytes (no leading
/// or trailing chars). `signature_b64` is the third JWS segment.
pub fn check_jws_signature(
    payload: &MidJwtPayload,
    signing_input: &str,
    signature_b64: &str,
) -> Result<(), VerifyError> {
    let current_vm = &payload.embedded_verification_method;
    let current_pubkey = pubkey_from_multibase(&current_vm.public_key_multibase, &current_vm.id)?;

    let prehash: [u8; 32] = Sha256::digest(signing_input.as_bytes()).into();
    let signature_bytes =
        URL_SAFE_NO_PAD.decode(signature_b64).map_err(|source| VerifyError::Base64Decode {
            segment: "signature",
            source,
        })?;
    let signature = signature_from_raw(&signature_bytes)?;

    current_pubkey
        .verify_prehash(&prehash, &signature)
        .map_err(|_| VerifyError::JwtSignatureInvalid)
}

// ─── Shape: parse the JWS into (header_b64, payload_b64, signature_b64) ────

/// Decompose a JWS compact-form string into its three base64url-encoded
/// segments. Returns the bytes of the decoded header + payload alongside
/// the still-encoded signing_input + signature_b64 (the latter two are
/// needed verbatim for check 4).
pub fn split_jws(jwt: &str) -> Result<JwsParts<'_>, VerifyError> {
    let segments: Vec<&str> = jwt.split('.').collect();
    if segments.len() != 3 {
        return Err(VerifyError::InvalidJwsShape(segments.len()));
    }
    let header_b64 = segments[0];
    let payload_b64 = segments[1];
    let signature_b64 = segments[2];

    // Signing input is what the JWS signature was computed over.
    // Equivalent to &jwt[..jwt.rfind('.').unwrap()].
    let signing_input_end = header_b64.len() + 1 + payload_b64.len();
    let signing_input = &jwt[..signing_input_end];

    let header_bytes = URL_SAFE_NO_PAD.decode(header_b64).map_err(|source| {
        VerifyError::Base64Decode { segment: "header", source }
    })?;
    let payload_bytes = URL_SAFE_NO_PAD.decode(payload_b64).map_err(|source| {
        VerifyError::Base64Decode { segment: "payload", source }
    })?;

    Ok(JwsParts {
        header_bytes,
        payload_bytes,
        signing_input,
        signature_b64,
    })
}

/// Decomposed JWS pieces ready for verification.
pub struct JwsParts<'a> {
    /// Decoded header JSON bytes.
    pub header_bytes: Vec<u8>,
    /// Decoded payload JSON bytes.
    pub payload_bytes: Vec<u8>,
    /// `<header_b64>.<payload_b64>` — the bytes the signature covers.
    pub signing_input: &'a str,
    /// The third JWS segment, still base64url-encoded.
    pub signature_b64: &'a str,
}

/// Validate the JWS header asserts the expected algorithm + type. mID v1
/// requires `alg: ES256` and `typ: JWT` exactly.
pub fn validate_jws_header(header_bytes: &[u8]) -> Result<(), VerifyError> {
    let header: serde_json::Value =
        serde_json::from_slice(header_bytes).map_err(|_| VerifyError::InvalidJwsHeader)?;
    let alg = header.get("alg").and_then(|v| v.as_str()).ok_or(VerifyError::InvalidJwsHeader)?;
    let typ = header.get("typ").and_then(|v| v.as_str()).ok_or(VerifyError::InvalidJwsHeader)?;
    if alg != "ES256" || typ != "JWT" {
        return Err(VerifyError::InvalidJwsHeader);
    }
    Ok(())
}

#[cfg(test)]
mod signature_tests {
    use super::*;

    /// A wallet with a locked vault, or whose signing call failed, returns 64
    /// zero bytes as a placeholder. That must be rejected as its own condition,
    /// not accepted and left to fail later as an ordinary bad signature.
    #[test]
    fn all_zero_signature_is_rejected() {
        let zeros = [0u8; 64];
        assert!(matches!(
            signature_from_raw(&zeros),
            Err(VerifyError::SignatureInvalidScalars)
        ));
    }

    #[test]
    fn wrong_length_is_reported_as_length_not_scalars() {
        assert!(matches!(
            signature_from_raw(&[1u8; 63]),
            Err(VerifyError::SignatureWrongLength { actual: 63 })
        ));
    }

    /// Guards the boundary: 64 non-zero bytes must not be rejected by the
    /// all-zero check itself. (They may still fail scalar validation, which is
    /// a different error path.)
    #[test]
    fn a_nonzero_64_byte_input_passes_the_zero_check() {
        let mut sig = [0u8; 64];
        sig[0] = 1;
        sig[32] = 1;
        assert!(!matches!(
            signature_from_raw(&sig),
            Err(VerifyError::SignatureWrongLength { .. })
        ));
    }
}