qhermes_kernel/

lib.rs

// Copyright (c) 2026 Copertino All rights reserved.
// SPDX-License-Identifier: LicenseRef-Copertino-1.0
// Licensed under the Copertino Source License 1.0 — see LICENSE at the repository root.
// Commercial use requires a license from Copertino: hello@copertino.world

//! Cryptographic and authorization primitives for QHermes delegation chains.
//!
//! # Layers
//!
//! ```text
//! Crypto     — key derivation and ML-DSA-65 signing/verification
//! Policy     — permission encoding, scope subset enforcement, caveat evaluation
//! Delegation — credential issuance and chain verification
//! Wire       — credential chain serialization and deserialization
//! ```
//!
//! # Permission format
//!
//! ```text
//! [res_len: u8][resource bytes][verb_len: u8][verb bytes]
//! ```
//!
//! # Wire format
//!
//! ```text
//! [version: u8 = 0x01][count: u32 LE][credentials...]
//! [issuer_pk: PK_SIZE][signature: SIG_SIZE][payload_len: u32 LE][payload bytes]
//! ```
//!
//! # Timestamps
//!
//! All `Timestamp` values are seconds since the Unix epoch. Passing
//! milliseconds or nanoseconds produces incorrect caveat evaluation.
//!
//! # Domain separation
//!
//! `IdentityIsland::derive` folds `deployment` and `context` into the HKDF
//! info parameter. Different `deployment` values yield independent key material
//! even when sharing the same `master`.

#![no_std]
#![forbid(unsafe_code)]

use hybrid_array::Array;
use hkdf::Hkdf;
use ml_dsa::{EncodedSignature, EncodedVerifyingKey, KeyGen, MlDsa65, SigningKey, VerifyingKey};
use ml_dsa::signature::Verifier;
use sha3::Sha3_512;
use zeroize::Zeroizing;

// ── Constants ─────────────────────────────────────────────────────────────────

/// Byte length of the HKDF seed and derived key material.
pub const SEED_SIZE: usize = 32;

/// Byte length of an ML-DSA-65 public key (verifying key).
pub const PK_SIZE: usize = 1952;

/// Byte length of an ML-DSA-65 signature.
pub const SIG_SIZE: usize = 3309;

/// Maximum byte length of the resource field in a permission.
/// Fits a `u8`-typed TLV length prefix.
pub const RESOURCE_LEN: usize = 255;

/// Maximum byte length of the verb field in a permission.
/// Fits a `u8`-typed TLV length prefix.
pub const VERB_LEN: usize = 255;

/// Maximum byte length of the TLV encoding of one permission:
/// `1 (res_len) + RESOURCE_LEN + 1 (verb_len) + VERB_LEN`.
pub const PERM_TLV_MAX: usize = 1 + RESOURCE_LEN + 1 + VERB_LEN;

/// Byte length of one serialized caveat record: 1-byte tag + 8-byte timestamp.
pub const CAVEAT_SIZE: usize = 9;

/// Maximum number of permissions in a credential scope.
pub const MAX_SCOPE_PERMS: usize = 64;

/// Maximum number of caveats in a credential.
pub const MAX_CAVEATS: usize = 64;

/// Maximum depth of a delegation chain. Longer chains are rejected at
/// issuance, verification, and deserialization.
pub const MAX_DEPTH: u32 = 16;

/// Maximum byte length of a payload, assuming all permissions at maximum TLV
/// size and all caveat slots occupied.
///
/// Layout: `PK_SIZE + 1 (role) + 4 (depth) + 4 (scope_len)
///          + PERM_TLV_MAX * MAX_SCOPE_PERMS + 4 (cav_len) + CAVEAT_SIZE * MAX_CAVEATS`
pub const MAX_PAYLOAD_SIZE: usize =
    PK_SIZE + 1 + 4 + 4 + PERM_TLV_MAX * MAX_SCOPE_PERMS + 4 + CAVEAT_SIZE * MAX_CAVEATS;

/// Fixed bytes per credential record, excluding the payload:
/// `PK_SIZE + SIG_SIZE + 4 (payload_len field)`.
pub const CREDENTIAL_FIXED_SIZE: usize = PK_SIZE + SIG_SIZE + 4;

// Changing SALT invalidates all previously derived key material.
const SALT: &[u8] = b"QHermes-Kernel-v1";

// Increment WIRE_VERSION on any breaking change to the wire format.
const WIRE_VERSION: u8 = 0x01;

const CAVEAT_NOT_BEFORE: u8 = 0x01;
const CAVEAT_NOT_AFTER: u8  = 0x02;

// ── Error ─────────────────────────────────────────────────────────────────────

/// Errors returned by QHermes kernel operations.
///
/// This enum is marked `#[non_exhaustive]`. Match arms must include a wildcard
/// to remain compatible with variants added in minor releases.
#[non_exhaustive]
#[derive(Debug, PartialEq, Eq)]
pub enum KernelError {
    /// HKDF key expansion returned an error.
    HkdfExpandFailed,
    /// The ML-DSA-65 signing operation failed.
    SigningFailed,
    /// The signature does not match the payload under the given public key.
    SignatureInvalid,
    /// The public key bytes are not a valid ML-DSA-65 verifying key.
    KeyDecodingFailed,
    /// The signature bytes are not a valid ML-DSA-65 signature.
    SignatureDecodingFailed,
    /// A `not_before` caveat was evaluated with a timestamp earlier than the caveat value.
    NotBeforeViolation,
    /// A `not_after` caveat was evaluated with a timestamp later than the caveat value.
    NotAfterViolation,
    /// The caveat buffer contains an unrecognized tag byte or has an invalid layout.
    MalformedCaveatBuffer,
    /// A child credential claims a permission not covered by the parent scope.
    ScopeEscalation,
    /// The scope was constructed from an empty slice. Every credential must grant at least one permission.
    ScopeEmpty,
    /// The scope contains more than `MAX_SCOPE_PERMS` permissions.
    ScopeTooLarge,
    /// The caveat buffer exceeds `CAVEAT_SIZE * MAX_CAVEATS` bytes.
    CaveatsTooLarge,
    /// An operation was attempted on an empty credential chain.
    EmptyChain,
    /// The chain depth exceeds `MAX_DEPTH`.
    ChainTooDeep,
    /// The issuer public key in a link does not match the child public key of the previous link.
    ParentKeyMismatch,
    /// A credential with role `Leaf` attempted to issue a further delegation.
    LeafCannotDelegate,
    /// The `depth` field of the payload does not equal the expected sequential position in the chain.
    DepthMismatch,
    /// The role byte in the payload is neither `0` (Leaf) nor `1` (Node).
    InvalidRoleByte,
    /// The first byte of the wire buffer does not match `WIRE_VERSION`.
    WireVersionMismatch,
    /// The wire buffer or a sub-slice ends before the expected bytes.
    WireTruncated,
    /// The wire buffer is structurally inconsistent: a length field, role byte,
    /// or trailing-bytes check failed.
    WireInvalid,
    /// The `resource` argument to `perm_tlv` exceeds `RESOURCE_LEN` bytes.
    ResourceTooLong,
    /// The `verb` argument to `perm_tlv` exceeds `VERB_LEN` bytes.
    VerbTooLong,
}

// ── Domain types ──────────────────────────────────────────────────────────────

/// Reference to a `PK_SIZE`-byte ML-DSA-65 public key.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct PublicKey<'a>(pub &'a [u8; PK_SIZE]);

/// Reference to a `SIG_SIZE`-byte ML-DSA-65 signature.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub struct Signature<'a>(pub &'a [u8; SIG_SIZE]);

/// Role encoded in a credential payload.
///
/// - `Node`: this identity may issue further delegations.
/// - `Leaf`: this identity may not issue further delegations.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Role {
    Leaf = 0,
    Node = 1,
}

impl TryFrom<u8> for Role {
    type Error = KernelError;
    fn try_from(b: u8) -> Result<Self, Self::Error> {
        match b {
            0 => Ok(Role::Leaf),
            1 => Ok(Role::Node),
            _ => Err(KernelError::InvalidRoleByte),
        }
    }
}

/// Timestamp in seconds since the Unix epoch.
///
/// All kernel functions that accept or produce `Timestamp` values operate in
/// seconds. Passing milliseconds or nanoseconds produces incorrect caveat evaluation.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct Timestamp(pub u64);

/// Sequential position of a credential within its delegation chain.
/// The first credential issued by the root has depth 1.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct Depth(pub u32);

/// Validated, non-empty TLV sequence of permissions.
///
/// Each entry has the layout:
///
/// ```text
/// [res_len: u8][resource bytes][verb_len: u8][verb bytes]
/// ```
///
/// `try_new` walks the slice and verifies that:
/// - the slice is non-empty,
/// - every entry is complete (no truncated fields),
/// - the total number of entries does not exceed `MAX_SCOPE_PERMS`.
///
/// After construction the slice is guaranteed to be fully consumed by
/// well-formed entries and iterable via `iter()`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct BoundedScope<'a>(&'a [u8]);

impl<'a> BoundedScope<'a> {
    /// Returns an iterator yielding `(resource, verb)` pairs in order.
    pub fn iter(&self) -> ScopeIter<'a> {
        ScopeIter { raw: self.0, pos: 0 }
    }

    /// Parses and validates a raw TLV slice.
    ///
    /// Returns `ScopeEmpty` if `raw` is empty, `WireInvalid` if any entry is
    /// truncated or structurally incorrect, and `ScopeTooLarge` if the entry
    /// count exceeds `MAX_SCOPE_PERMS`.
    pub fn try_new(raw: &'a [u8]) -> Result<Self, KernelError> {
        if raw.is_empty() {
            return Err(KernelError::ScopeEmpty);
        }
        let mut pos = 0;
        let mut count = 0usize;
        while pos < raw.len() {
            if count >= MAX_SCOPE_PERMS {
                return Err(KernelError::ScopeTooLarge);
            }
            tlv_next_field(raw, &mut pos).ok_or(KernelError::WireInvalid)?; // resource
            tlv_next_field(raw, &mut pos).ok_or(KernelError::WireInvalid)?; // verb
            count += 1;
        }
        Ok(Self(raw))
    }
}

/// Validated sequence of fixed-size caveat records.
///
/// The raw slice must satisfy:
/// - `len % CAVEAT_SIZE == 0`
/// - `len <= CAVEAT_SIZE * MAX_CAVEATS`
/// - every tag byte is `0x01` (not_before) or `0x02` (not_after)
///
/// An empty slice (no caveats) is accepted.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct BoundedCaveats<'a>(&'a [u8]);

impl<'a> BoundedCaveats<'a> {
    /// Parses and validates a raw caveat slice.
    ///
    /// Returns `CaveatsTooLarge` if the slice exceeds the maximum total size,
    /// `MalformedCaveatBuffer` if the length is not a multiple of `CAVEAT_SIZE`
    /// or any tag byte is unrecognized.
    pub fn try_new(raw: &'a [u8]) -> Result<Self, KernelError> {
        if raw.len() > CAVEAT_SIZE * MAX_CAVEATS {
            return Err(KernelError::CaveatsTooLarge);
        }
        if raw.len() % CAVEAT_SIZE != 0 {
            return Err(KernelError::MalformedCaveatBuffer);
        }
        for c in raw.chunks_exact(CAVEAT_SIZE) {
            match c[0] {
                CAVEAT_NOT_BEFORE | CAVEAT_NOT_AFTER => {}
                _ => return Err(KernelError::MalformedCaveatBuffer),
            }
        }
        Ok(Self(raw))
    }
}

/// Parameters for issuing a credential in a delegation chain.
pub struct DelegationManifest<'a> {
    /// Public key of the identity receiving the delegation.
    pub child_pk: PublicKey<'a>,
    /// Role assigned to the child identity.
    pub role:     Role,
    /// Sequential position of this credential in the chain.
    /// The root issues at depth 1; each subsequent link increments by one.
    pub depth:    Depth,
    /// Permissions granted to the child identity, in TLV encoding.
    pub scope:    BoundedScope<'a>,
    /// Time-based restrictions on the validity of the credential.
    pub caveats:  BoundedCaveats<'a>,
}

/// One link in a serialized credential chain as it appears on the wire.
pub struct Credential<'a> {
    /// Public key of the identity that signed this credential.
    pub issuer_pk: PublicKey<'a>,
    /// ML-DSA-65 signature over `payload`.
    pub signature: Signature<'a>,
    /// Signed payload bytes.
    pub payload:   &'a [u8],
}

// ── Crypto ────────────────────────────────────────────────────────────────────

/// Signing interface for any ML-DSA-65 identity: in-memory keys, HSM, TPM, or enclave.
pub trait IdentitySigner {
    /// Returns the public key corresponding to this signer's signing key.
    fn public_key(&self) -> PublicKey<'_>;

    /// Signs `payload` and writes the `SIG_SIZE`-byte signature into `out`.
    ///
    /// Returns `SigningFailed` if the underlying signing operation fails.
    fn sign_into(&self, payload: &[u8], out: &mut [u8; SIG_SIZE]) -> Result<(), KernelError>;
}

/// ML-DSA-65 identity deterministically derived from a master seed via HKDF-SHA3-512.
///
/// For hardware-backed or enclave-resident keys, implement `IdentitySigner` directly.
pub struct IdentityIsland {
    pk: [u8; PK_SIZE],
    sk: SigningKey<MlDsa65>,
}

impl IdentityIsland {
    /// Derives a key pair from `master` (secret), `deployment`, and `context`.
    ///
    /// HKDF info = `deployment || ':' || context`. Different deployments or contexts
    /// yield independent key material from the same master seed.
    ///
    /// Returns `HkdfExpandFailed` if the combined info string exceeds 512 bytes.
    pub fn derive(
        master:     &[u8; SEED_SIZE],
        deployment: &[u8],
        context:    &[u8],
    ) -> Result<Self, KernelError> {
        let mut seed = Zeroizing::new([0u8; SEED_SIZE]);
        Hkdf::<Sha3_512>::new(Some(SALT), master)
            .expand_multi_info(&[deployment, b":", context], seed.as_mut())
            .map_err(|_| KernelError::HkdfExpandFailed)?;

        let kp = MlDsa65::from_seed(&Array::<u8, hybrid_array::typenum::U32>::from(*seed));
        let mut pk = [0u8; PK_SIZE];
        pk.copy_from_slice(kp.verifying_key().encode().as_slice());

        Ok(Self { pk, sk: kp.signing_key().clone() })
    }
}

impl IdentitySigner for IdentityIsland {
    fn public_key(&self) -> PublicKey<'_> {
        PublicKey(&self.pk)
    }

    fn sign_into(&self, payload: &[u8], out: &mut [u8; SIG_SIZE]) -> Result<(), KernelError> {
        let sig = self.sk.sign_deterministic(payload, &[])
            .map_err(|_| KernelError::SigningFailed)?;
        out.copy_from_slice(&sig.encode());
        Ok(())
    }
}

/// Verifies an ML-DSA-65 signature over `payload` under `pk`.
///
/// Returns `Ok(())` if the signature is valid. Returns `KeyDecodingFailed`,
/// `SignatureDecodingFailed`, or `SignatureInvalid` according to the failure.
pub fn verify_signature(
    pk:      PublicKey<'_>,
    payload: &[u8],
    sig:     Signature<'_>,
) -> Result<(), KernelError> {
    let vk = VerifyingKey::<MlDsa65>::decode(
        &EncodedVerifyingKey::<MlDsa65>::try_from(pk.0.as_slice())
            .map_err(|_| KernelError::KeyDecodingFailed)?,
    );
    let decoded = ml_dsa::Signature::<MlDsa65>::decode(
        &EncodedSignature::<MlDsa65>::try_from(sig.0.as_slice())
            .map_err(|_| KernelError::SignatureDecodingFailed)?,
    )
    .ok_or(KernelError::SignatureDecodingFailed)?;

    vk.verify(payload, &decoded).map_err(|_| KernelError::SignatureInvalid)
}

// ── Policy ────────────────────────────────────────────────────────────────────

/// Encodes a `(resource, verb)` permission into `out` using TLV format.
///
/// Written layout: `[res_len: u8][resource bytes][verb_len: u8][verb bytes]`.
///
/// Returns the number of bytes written on success.
/// Returns `ResourceTooLong` if `resource.len() > RESOURCE_LEN`,
/// `VerbTooLong` if `verb.len() > VERB_LEN`,
/// and `WireTruncated` if `out` is too small.
pub fn perm_tlv(resource: &[u8], verb: &[u8], out: &mut [u8]) -> Result<usize, KernelError> {
    if resource.len() > RESOURCE_LEN {
        return Err(KernelError::ResourceTooLong);
    }
    if verb.len() > VERB_LEN {
        return Err(KernelError::VerbTooLong);
    }
    let need = 1 + resource.len() + 1 + verb.len();
    if out.len() < need {
        return Err(KernelError::WireTruncated);
    }
    out[0] = resource.len() as u8;
    out[1..1 + resource.len()].copy_from_slice(resource);
    let v = 1 + resource.len();
    out[v] = verb.len() as u8;
    out[v + 1..v + 1 + verb.len()].copy_from_slice(verb);
    Ok(need)
}

/// Constructs a not-before caveat record.
///
/// The credential is invalid if evaluated with a `Timestamp` (Unix seconds)
/// strictly less than `t`.
pub fn not_before(t: Timestamp) -> [u8; CAVEAT_SIZE] {
    build_caveat(CAVEAT_NOT_BEFORE, t)
}

/// Constructs a not-after caveat record.
///
/// The credential is invalid if evaluated with a `Timestamp` (Unix seconds)
/// strictly greater than `t`.
pub fn not_after(t: Timestamp) -> [u8; CAVEAT_SIZE] {
    build_caveat(CAVEAT_NOT_AFTER, t)
}

fn build_caveat(tag: u8, t: Timestamp) -> [u8; CAVEAT_SIZE] {
    let mut c = [0u8; CAVEAT_SIZE];
    c[0] = tag;
    c[1..].copy_from_slice(&t.0.to_le_bytes());
    c
}

fn tlv_next_field<'a>(raw: &'a [u8], pos: &mut usize) -> Option<&'a [u8]> {
    let len = *raw.get(*pos)? as usize;
    *pos += 1;
    let end = pos.checked_add(len).filter(|&e| e <= raw.len())?;
    let field = &raw[*pos..end];
    *pos = end;
    Some(field)
}

pub struct ScopeIter<'a> {
    raw: &'a [u8],
    pos: usize,
}

impl<'a> Iterator for ScopeIter<'a> {
    type Item = (&'a [u8], &'a [u8]);

    fn next(&mut self) -> Option<Self::Item> {
        let resource = tlv_next_field(self.raw, &mut self.pos)?;
        let verb     = tlv_next_field(self.raw, &mut self.pos)?;
        Some((resource, verb))
    }
}

/// Checks that every permission in `child` is covered by at least one permission in `parent`.
///
/// A parent permission covers a child permission when:
/// - the parent resource equals the child resource, or the parent resource is `*`; and
/// - the parent verb equals the child verb, or the parent verb is `*`.
///
/// **Resources are opaque byte strings compared for exact equality.** The kernel
/// does not interpret path separators, glob patterns, or any structure within a
/// resource value. The only special value is `b"*"`, which matches any single
/// resource. A resource such as `b"src/**"` is treated as a fixed identifier, not
/// as a glob — it covers only another permission whose resource field is the
/// identical byte string `b"src/**"`.
///
/// The correct pattern for hierarchical namespacing is to use consistent literals
/// throughout the chain. If the root grants `(b"src/**", b"WRITE")`, every
/// descendant that needs write access to the same namespace must carry the same
/// `b"src/**"` resource identifier, not a more specific path such as
/// `b"src/main.rs"`. Finer-grained access control belongs in the application
/// layer, not in the credential chain.
///
/// Returns `ScopeEscalation` if any child permission is not covered.
pub fn enforce_scope_subset(
    child:  &BoundedScope<'_>,
    parent: &BoundedScope<'_>,
) -> Result<(), KernelError> {
    for (cr, cv) in child.iter() {
        let covered = parent.iter().any(|(pr, pv)| {
            (pr == b"*" || pr == cr) && (pv == b"*" || pv == cv)
        });
        if !covered {
            return Err(KernelError::ScopeEscalation);
        }
    }
    Ok(())
}

/// Evaluates all caveats in `caveats` against `now`.
///
/// `now` must be a timestamp in seconds since the Unix epoch.
///
/// - `CAVEAT_NOT_BEFORE` (`0x01`): returns `NotBeforeViolation` if `now < ts`.
/// - `CAVEAT_NOT_AFTER`  (`0x02`): returns `NotAfterViolation`  if `now > ts`.
pub fn evaluate_caveats(
    caveats: &BoundedCaveats<'_>,
    now:     Timestamp,
) -> Result<(), KernelError> {
    for c in caveats.0.chunks_exact(CAVEAT_SIZE) {
        let ts = Timestamp(u64::from_le_bytes(c[1..].try_into().unwrap()));
        match c[0] {
            CAVEAT_NOT_BEFORE if now < ts => return Err(KernelError::NotBeforeViolation),
            CAVEAT_NOT_AFTER  if now > ts => return Err(KernelError::NotAfterViolation),
            _ => {}
        }
    }
    Ok(())
}

// ── Delegation ────────────────────────────────────────────────────────────────

/// Serializes `manifest` into `payload_out` and signs it into `sig_out`.
///
/// Returns the number of bytes written. Only `payload_out[..n]` contains the valid payload.
///
/// # Payload layout
///
/// ```text
/// [child_pk: PK_SIZE][role: u8][depth: u32 LE][scope_len: u32 LE][scope bytes]
/// [cav_len: u32 LE][caveat bytes]
/// ```
///
/// # Errors
///
/// - `ChainTooDeep`  — `manifest.depth.0 > MAX_DEPTH`
/// - `SigningFailed` — the underlying signing operation failed
pub fn issue_credential(
    issuer:      &impl IdentitySigner,
    manifest:    &DelegationManifest<'_>,
    payload_out: &mut [u8; MAX_PAYLOAD_SIZE],
    sig_out:     &mut [u8; SIG_SIZE],
) -> Result<usize, KernelError> {
    if manifest.depth.0 > MAX_DEPTH {
        return Err(KernelError::ChainTooDeep);
    }
    let scope   = manifest.scope.0;
    let caveats = manifest.caveats.0;
    let mut pos = 0;

    payload_out[pos..pos + PK_SIZE].copy_from_slice(manifest.child_pk.0);             pos += PK_SIZE;
    payload_out[pos] = manifest.role as u8;                                            pos += 1;
    payload_out[pos..pos + 4].copy_from_slice(&manifest.depth.0.to_le_bytes());       pos += 4;
    payload_out[pos..pos + 4].copy_from_slice(&(scope.len() as u32).to_le_bytes());   pos += 4;
    payload_out[pos..pos + scope.len()].copy_from_slice(scope);                        pos += scope.len();
    payload_out[pos..pos + 4].copy_from_slice(&(caveats.len() as u32).to_le_bytes()); pos += 4;
    payload_out[pos..pos + caveats.len()].copy_from_slice(caveats);                    pos += caveats.len();

    issuer.sign_into(&payload_out[..pos], sig_out)?;
    Ok(pos)
}

/// Verifies a credential chain rooted at `root_pk` against `timestamp`.
///
/// Checks signatures, depth sequence, caveat validity, scope subset enforcement,
/// and Leaf role compliance.
pub fn verify_delegation(
    root_pk:   PublicKey<'_>,
    chain:     &[Credential<'_>],
    timestamp: Timestamp,
) -> Result<(), KernelError> {
    if chain.len() > MAX_DEPTH as usize {
        return Err(KernelError::ChainTooDeep);
    }
    let (first, rest) = chain.split_first().ok_or(KernelError::EmptyChain)?;

    if first.issuer_pk != root_pk {
        return Err(KernelError::ParentKeyMismatch);
    }
    verify_signature(first.issuer_pk, first.payload, first.signature)?;
    let m0 = parse_payload(first.payload)?;
    if m0.depth != Depth(1) {
        return Err(KernelError::DepthMismatch);
    }
    evaluate_caveats(&m0.caveats, timestamp)?;

    let mut prev_child_pk    = m0.child_pk;
    let mut prev_child_scope = m0.scope;
    let mut prev_child_role  = m0.role;

    for (i, cred) in rest.iter().enumerate() {
        if cred.issuer_pk != prev_child_pk {
            return Err(KernelError::ParentKeyMismatch);
        }
        if prev_child_role == Role::Leaf {
            return Err(KernelError::LeafCannotDelegate);
        }
        verify_signature(cred.issuer_pk, cred.payload, cred.signature)?;
        let m = parse_payload(cred.payload)?;
        if m.depth != Depth(i as u32 + 2) {
            return Err(KernelError::DepthMismatch);
        }
        enforce_scope_subset(&m.scope, &prev_child_scope)?;
        evaluate_caveats(&m.caveats, timestamp)?;
        prev_child_pk    = m.child_pk;
        prev_child_scope = m.scope;
        prev_child_role  = m.role;
    }
    Ok(())
}

// ── Wire ──────────────────────────────────────────────────────────────────────

/// Serializes `chain` into `out`. Returns bytes written, or `WireTruncated` if `out` is too small.
pub fn write_credential_chain(
    out:   &mut [u8],
    chain: &[Credential<'_>],
) -> Result<usize, KernelError> {
    if out.len() < 5 {
        return Err(KernelError::WireTruncated);
    }
    out[0] = WIRE_VERSION;
    let count32 = u32::try_from(chain.len()).map_err(|_| KernelError::WireTruncated)?;
    out[1..5].copy_from_slice(&count32.to_le_bytes());
    let mut pos: usize = 5;

    for cred in chain {
        let plen  = cred.payload.len();
        let need  = pos.saturating_add(CREDENTIAL_FIXED_SIZE).saturating_add(plen);
        if out.len() < need {
            return Err(KernelError::WireTruncated);
        }
        let plen32 = u32::try_from(plen).map_err(|_| KernelError::WireTruncated)?;
        out[pos..pos + PK_SIZE].copy_from_slice(cred.issuer_pk.0);  pos += PK_SIZE;
        out[pos..pos + SIG_SIZE].copy_from_slice(cred.signature.0); pos += SIG_SIZE;
        out[pos..pos + 4].copy_from_slice(&plen32.to_le_bytes());   pos += 4;
        out[pos..pos + plen].copy_from_slice(cred.payload);         pos += plen;
    }
    Ok(pos)
}

/// Deserializes `wire` into `chain`. All slices point into `wire`. Returns the credential count.
///
/// Trailing bytes after the last credential are not rejected. Each individual credential payload
/// is parsed with strict no-trailing-bytes enforcement, but the outer buffer may contain extra
/// bytes beyond the last credential without error. This is intentional: the wire chain is
/// typically embedded inside a larger message, and the caller controls how much of the buffer
/// to pass in. `verify_chain` and `verify_delegation` operate on the returned credential slice
/// and are unaffected by any trailing bytes in the original buffer.
///
/// # Errors
///
/// - `WireVersionMismatch` — first byte does not match `WIRE_VERSION`
/// - `EmptyChain`          — count field is zero
/// - `ChainTooDeep`        — count field exceeds `MAX_DEPTH`
/// - `WireInvalid`         — count exceeds length of `chain`
/// - `WireTruncated`       — buffer ends before the expected bytes
pub fn read_credential_chain<'a>(
    wire:  &'a [u8],
    chain: &mut [Credential<'a>],
) -> Result<usize, KernelError> {
    let ([version], rest)   = split_array::<1>(wire)?;
    if *version != WIRE_VERSION {
        return Err(KernelError::WireVersionMismatch);
    }
    let (count_bytes, rest) = split_array::<4>(rest)?;
    let num = usize::try_from(u32::from_le_bytes(*count_bytes)).map_err(|_| KernelError::WireInvalid)?;
    if num == 0 {
        return Err(KernelError::EmptyChain);
    }
    if num > MAX_DEPTH as usize {
        return Err(KernelError::ChainTooDeep);
    }
    if num > chain.len() {
        return Err(KernelError::WireInvalid);
    }
    let mut rest = rest;

    for slot in chain[..num].iter_mut() {
        let (pk_bytes, tail)  = split_array::<PK_SIZE>(rest)?;
        let (sig_bytes, tail) = split_array::<SIG_SIZE>(tail)?;
        let (len_bytes, tail) = split_array::<4>(tail)?;
        let pl_len = usize::try_from(u32::from_le_bytes(*len_bytes)).map_err(|_| KernelError::WireInvalid)?;
        let (payload, tail)   = split_at_checked(tail, pl_len)?;

        *slot = Credential {
            issuer_pk: PublicKey(pk_bytes),
            signature: Signature(sig_bytes),
            payload,
        };
        rest = tail;
    }
    Ok(num)
}

fn split_at_checked(buf: &[u8], n: usize) -> Result<(&[u8], &[u8]), KernelError> {
    if buf.len() < n {
        return Err(KernelError::WireTruncated);
    }
    Ok(buf.split_at(n))
}

fn split_array<const N: usize>(buf: &[u8]) -> Result<(&[u8; N], &[u8]), KernelError> {
    buf.split_first_chunk::<N>().ok_or(KernelError::WireTruncated)
}

// Trailing bytes after all fields return WireInvalid (anti-malleability).
#[cfg(test)]
pub(crate) fn parse_payload_pub(p: &[u8]) -> Result<DelegationManifest<'_>, KernelError> {
    parse_payload(p)
}

fn parse_payload(p: &[u8]) -> Result<DelegationManifest<'_>, KernelError> {
    let (child_pk, rest)        = split_array::<PK_SIZE>(p)?;

    let (role_byte, rest)       = split_array::<1>(rest)?;
    let role = Role::try_from(role_byte[0])?;

    let (depth_bytes, rest)     = split_array::<4>(rest)?;
    let depth = u32::from_le_bytes(*depth_bytes);

    let (scope_len_bytes, rest) = split_array::<4>(rest)?;
    let scope_len = usize::try_from(u32::from_le_bytes(*scope_len_bytes)).map_err(|_| KernelError::WireInvalid)?;
    let (scope_bytes, rest)     = split_at_checked(rest, scope_len)?;

    let (cav_len_bytes, rest)   = split_array::<4>(rest)?;
    let cav_len = usize::try_from(u32::from_le_bytes(*cav_len_bytes)).map_err(|_| KernelError::WireInvalid)?;
    let (cav_bytes, tail)       = split_at_checked(rest, cav_len)?;

    if !tail.is_empty() {
        return Err(KernelError::WireInvalid);
    }

    Ok(DelegationManifest {
        child_pk: PublicKey(child_pk),
        role,
        depth:   Depth(depth),
        scope:   BoundedScope::try_new(scope_bytes)?,
        caveats: BoundedCaveats::try_new(cav_bytes)?,
    })
}

// ── Tests ─────────────────────────────────────────────────────────────────────

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

    extern crate std;
    use std::vec;
    use std::vec::Vec;

    // ── Helpers ──

    /// Derives a test identity using a fixed master seed and the given context.
    fn make_test_identity(context: &[u8]) -> IdentityIsland {
        let master = [0x42u8; SEED_SIZE];
        IdentityIsland::derive(&master, b"test-deploy", context).unwrap()
    }

    /// Builds a single-permission TLV for (/test, GET).
    fn make_test_scope() -> Vec<u8> {
        let mut buf = vec![0u8; PERM_TLV_MAX];
        let n = perm_tlv(b"/test", b"GET", &mut buf).unwrap();
        buf.truncate(n);
        buf
    }

    /// Returns an empty caveats buffer (no time restrictions).
    fn make_test_caveats() -> Vec<u8> {
        vec![]
    }

    // ── Identity / key derivation ──

    #[test]
    fn derive_same_inputs_same_pubkey() {
        let a = make_test_identity(b"ctx-alpha");
        let b = make_test_identity(b"ctx-alpha");
        assert_eq!(a.public_key(), b.public_key());
    }

    #[test]
    fn derive_different_context_different_pubkey() {
        let a = make_test_identity(b"ctx-alpha");
        let b = make_test_identity(b"ctx-beta");
        assert_ne!(a.public_key(), b.public_key());
    }

    #[test]
    fn derive_different_deployment_different_pubkey() {
        let master = [0x42u8; SEED_SIZE];
        let a = IdentityIsland::derive(&master, b"deploy-one", b"ctx").unwrap();
        let b = IdentityIsland::derive(&master, b"deploy-two", b"ctx").unwrap();
        assert_ne!(a.public_key(), b.public_key());
    }

    #[test]
    fn derive_different_master_different_pubkey() {
        let master_a = [0x42u8; SEED_SIZE];
        let master_b = [0x43u8; SEED_SIZE];
        let a = IdentityIsland::derive(&master_a, b"dep", b"ctx").unwrap();
        let b = IdentityIsland::derive(&master_b, b"dep", b"ctx").unwrap();
        assert_ne!(a.public_key(), b.public_key());
    }

    #[test]
    fn derive_valid_master_returns_ok() {
        let master = [0x11u8; SEED_SIZE];
        assert!(IdentityIsland::derive(&master, b"dep", b"ctx").is_ok());
    }

    // ── perm_tlv ──

    #[test]
    fn perm_tlv_single_byte_resource_and_verb() {
        let mut buf = [0u8; 64];
        let n = perm_tlv(b"R", b"V", &mut buf).unwrap();
        // [res_len=1][R][verb_len=1][V] = 4 bytes
        assert_eq!(n, 4);
        assert_eq!(buf[0], 1);
        assert_eq!(buf[1], b'R');
        assert_eq!(buf[2], 1);
        assert_eq!(buf[3], b'V');
    }

    #[test]
    fn perm_tlv_max_resource_succeeds() {
        let resource = vec![0xAAu8; RESOURCE_LEN];
        let mut buf = vec![0u8; PERM_TLV_MAX];
        let n = perm_tlv(&resource, b"V", &mut buf).unwrap();
        assert_eq!(n, 1 + RESOURCE_LEN + 1 + 1);
    }

    #[test]
    fn perm_tlv_max_verb_succeeds() {
        let verb = vec![0xBBu8; VERB_LEN];
        let mut buf = vec![0u8; PERM_TLV_MAX];
        let n = perm_tlv(b"R", &verb, &mut buf).unwrap();
        assert_eq!(n, 1 + 1 + 1 + VERB_LEN);
    }

    #[test]
    fn perm_tlv_resource_256_returns_resource_too_long() {
        let resource = vec![0u8; 256];
        let mut buf = vec![0u8; PERM_TLV_MAX + 4];
        assert!(matches!(
            perm_tlv(&resource, b"V", &mut buf),
            Err(KernelError::ResourceTooLong)
        ));
    }

    #[test]
    fn perm_tlv_verb_256_returns_verb_too_long() {
        let verb = vec![0u8; 256];
        let mut buf = vec![0u8; PERM_TLV_MAX + 4];
        assert!(matches!(
            perm_tlv(b"R", &verb, &mut buf),
            Err(KernelError::VerbTooLong)
        ));
    }

    #[test]
    fn perm_tlv_empty_resource_and_verb() {
        let mut buf = [0u8; 8];
        let n = perm_tlv(b"", b"", &mut buf).unwrap();
        // [res_len=0][verb_len=0] = 2 bytes
        assert_eq!(n, 2);
        assert_eq!(buf[0], 0);
        assert_eq!(buf[1], 0);
    }

    #[test]
    fn perm_tlv_output_too_small_returns_wire_truncated() {
        // Need 4 bytes for (b"R", b"V"), supply only 3.
        let mut buf = [0u8; 3];
        assert!(matches!(
            perm_tlv(b"R", b"V", &mut buf),
            Err(KernelError::WireTruncated)
        ));
    }

    // ── not_before / not_after ──

    #[test]
    fn not_before_returns_nine_bytes() {
        let c = not_before(Timestamp(1_000_000));
        assert_eq!(c.len(), 9);
    }

    #[test]
    fn not_before_first_byte_is_0x01() {
        let c = not_before(Timestamp(42));
        assert_eq!(c[0], 0x01);
    }

    #[test]
    fn not_before_timestamp_little_endian() {
        let ts = 0x0102_0304_0506_0708u64;
        let c = not_before(Timestamp(ts));
        assert_eq!(&c[1..9], &ts.to_le_bytes());
    }

    #[test]
    fn not_after_returns_nine_bytes() {
        let c = not_after(Timestamp(9_999_999));
        assert_eq!(c.len(), 9);
    }

    #[test]
    fn not_after_first_byte_is_0x02() {
        let c = not_after(Timestamp(99));
        assert_eq!(c[0], 0x02);
    }

    #[test]
    fn not_after_timestamp_little_endian() {
        let ts = 0xDEAD_BEEF_CAFE_BABEu64;
        let c = not_after(Timestamp(ts));
        assert_eq!(&c[1..9], &ts.to_le_bytes());
    }

    // ── BoundedScope ──

    #[test]
    fn bounded_scope_empty_slice_returns_scope_empty() {
        assert!(matches!(
            BoundedScope::try_new(&[]),
            Err(KernelError::ScopeEmpty)
        ));
    }

    #[test]
    fn bounded_scope_single_permission_succeeds() {
        let scope_bytes = make_test_scope();
        assert!(BoundedScope::try_new(&scope_bytes).is_ok());
    }

    #[test]
    fn bounded_scope_multi_permission_succeeds() {
        let mut buf = vec![0u8; PERM_TLV_MAX * 2];
        let n1 = perm_tlv(b"/a", b"GET", &mut buf).unwrap();
        let n2 = perm_tlv(b"/b", b"POST", &mut buf[n1..]).unwrap();
        let total = n1 + n2;
        assert!(BoundedScope::try_new(&buf[..total]).is_ok());
    }

    #[test]
    fn bounded_scope_truncated_tlv_returns_wire_invalid() {
        // Write a valid TLV then truncate the resource bytes.
        let mut buf = vec![0u8; PERM_TLV_MAX];
        let n = perm_tlv(b"hello", b"GET", &mut buf).unwrap();
        // Truncate to only the resource length byte — the actual resource bytes are missing.
        assert!(matches!(
            BoundedScope::try_new(&buf[..1]),
            Err(KernelError::WireInvalid)
        ));
        let _ = n; // suppress unused warning
    }

    #[test]
    fn bounded_scope_too_many_perms_returns_scope_too_large() {
        // Build MAX_SCOPE_PERMS + 1 minimal permissions (each 2 bytes: res_len=0, verb_len=0).
        let count = MAX_SCOPE_PERMS + 1;
        let raw = vec![0u8; count * 2]; // each entry = [0x00][0x00]
        assert!(matches!(
            BoundedScope::try_new(&raw),
            Err(KernelError::ScopeTooLarge)
        ));
    }

    // ── BoundedCaveats ──

    #[test]
    fn bounded_caveats_empty_slice_succeeds() {
        assert!(BoundedCaveats::try_new(&[]).is_ok());
    }

    #[test]
    fn bounded_caveats_single_not_before_succeeds() {
        let c = not_before(Timestamp(100));
        assert!(BoundedCaveats::try_new(&c).is_ok());
    }

    #[test]
    fn bounded_caveats_single_not_after_succeeds() {
        let c = not_after(Timestamp(200));
        assert!(BoundedCaveats::try_new(&c).is_ok());
    }

    #[test]
    fn bounded_caveats_length_not_multiple_of_9_returns_malformed() {
        // 10 bytes is not a multiple of CAVEAT_SIZE (9).
        let raw = [0x01u8; 10];
        assert!(matches!(
            BoundedCaveats::try_new(&raw),
            Err(KernelError::MalformedCaveatBuffer)
        ));
    }

    #[test]
    fn bounded_caveats_unknown_tag_returns_malformed() {
        // 9 bytes aligned, but tag = 0xFF is unknown.
        let mut raw = [0u8; CAVEAT_SIZE];
        raw[0] = 0xFF;
        assert!(matches!(
            BoundedCaveats::try_new(&raw),
            Err(KernelError::MalformedCaveatBuffer)
        ));
    }

    #[test]
    fn bounded_caveats_too_large_returns_caveats_too_large() {
        // One byte over the maximum allowed.
        let raw = vec![0x01u8; CAVEAT_SIZE * MAX_CAVEATS + CAVEAT_SIZE];
        assert!(matches!(
            BoundedCaveats::try_new(&raw),
            Err(KernelError::CaveatsTooLarge)
        ));
    }

    // ── enforce_scope_subset ──

    #[test]
    fn enforce_scope_subset_exact_match_passes() {
        let scope_bytes = make_test_scope();
        let scope = BoundedScope::try_new(&scope_bytes).unwrap();
        assert!(enforce_scope_subset(&scope, &scope).is_ok());
    }

    #[test]
    fn enforce_scope_subset_wildcard_resource_covers_child() {
        // Parent grants (*,  GET); child requests (/specific, GET).
        let mut parent_buf = [0u8; PERM_TLV_MAX];
        let pn = perm_tlv(b"*", b"GET", &mut parent_buf).unwrap();
        let parent = BoundedScope::try_new(&parent_buf[..pn]).unwrap();

        let mut child_buf = [0u8; PERM_TLV_MAX];
        let cn = perm_tlv(b"/specific", b"GET", &mut child_buf).unwrap();
        let child = BoundedScope::try_new(&child_buf[..cn]).unwrap();

        assert!(enforce_scope_subset(&child, &parent).is_ok());
    }

    #[test]
    fn enforce_scope_subset_wildcard_verb_covers_child() {
        // Parent grants (/res, *); child requests (/res, DELETE).
        let mut parent_buf = [0u8; PERM_TLV_MAX];
        let pn = perm_tlv(b"/res", b"*", &mut parent_buf).unwrap();
        let parent = BoundedScope::try_new(&parent_buf[..pn]).unwrap();

        let mut child_buf = [0u8; PERM_TLV_MAX];
        let cn = perm_tlv(b"/res", b"DELETE", &mut child_buf).unwrap();
        let child = BoundedScope::try_new(&child_buf[..cn]).unwrap();

        assert!(enforce_scope_subset(&child, &parent).is_ok());
    }

    #[test]
    fn enforce_scope_subset_child_has_extra_perm_returns_scope_escalation() {
        // Parent grants (/test, GET); child requests (/test, POST) which parent does not cover.
        let scope_bytes = make_test_scope(); // (/test, GET)
        let parent = BoundedScope::try_new(&scope_bytes).unwrap();

        let mut child_buf = [0u8; PERM_TLV_MAX];
        let cn = perm_tlv(b"/test", b"POST", &mut child_buf).unwrap();
        let child = BoundedScope::try_new(&child_buf[..cn]).unwrap();

        assert!(matches!(
            enforce_scope_subset(&child, &parent),
            Err(KernelError::ScopeEscalation)
        ));
    }

    // ── evaluate_caveats ──

    #[test]
    fn evaluate_caveats_not_before_now_gte_ts_passes() {
        let c = not_before(Timestamp(1000));
        let caveats = BoundedCaveats::try_new(&c).unwrap();
        // now == ts: passes (not_before fails only when now < ts)
        assert!(evaluate_caveats(&caveats, Timestamp(1000)).is_ok());
        // now > ts: also passes
        assert!(evaluate_caveats(&caveats, Timestamp(2000)).is_ok());
    }

    #[test]
    fn evaluate_caveats_not_before_now_lt_ts_returns_violation() {
        let c = not_before(Timestamp(5000));
        let caveats = BoundedCaveats::try_new(&c).unwrap();
        assert!(matches!(
            evaluate_caveats(&caveats, Timestamp(4999)),
            Err(KernelError::NotBeforeViolation)
        ));
    }

    #[test]
    fn evaluate_caveats_not_after_now_lte_ts_passes() {
        let c = not_after(Timestamp(3000));
        let caveats = BoundedCaveats::try_new(&c).unwrap();
        // now == ts: passes (not_after fails only when now > ts)
        assert!(evaluate_caveats(&caveats, Timestamp(3000)).is_ok());
        // now < ts: also passes
        assert!(evaluate_caveats(&caveats, Timestamp(1000)).is_ok());
    }

    #[test]
    fn evaluate_caveats_not_after_now_gt_ts_returns_violation() {
        let c = not_after(Timestamp(3000));
        let caveats = BoundedCaveats::try_new(&c).unwrap();
        assert!(matches!(
            evaluate_caveats(&caveats, Timestamp(3001)),
            Err(KernelError::NotAfterViolation)
        ));
    }

    #[test]
    fn evaluate_caveats_empty_always_passes() {
        let caveats = BoundedCaveats::try_new(&[]).unwrap();
        assert!(evaluate_caveats(&caveats, Timestamp(u64::MAX)).is_ok());
    }

    // ── issue_credential + parse_payload (round-trip) ──

    #[test]
    fn issue_credential_round_trip_leaf() {
        let issuer = make_test_identity(b"issuer");
        let child  = make_test_identity(b"child");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&caveat_bytes).unwrap();
        let manifest = DelegationManifest {
            child_pk: PublicKey(&child_pk),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_buf = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_buf     = [0u8; SIG_SIZE];
        let n = issue_credential(&issuer, &manifest, &mut payload_buf, &mut sig_buf).unwrap();

        let parsed = parse_payload_pub(&payload_buf[..n]).unwrap();
        assert_eq!(parsed.role, Role::Leaf);
        assert_eq!(parsed.depth, Depth(1));
        assert_eq!(parsed.child_pk.0, &child_pk);
    }

    #[test]
    fn issue_credential_round_trip_node() {
        let issuer = make_test_identity(b"issuer");
        let child  = make_test_identity(b"child-node");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&caveat_bytes).unwrap();
        let manifest = DelegationManifest {
            child_pk: PublicKey(&child_pk),
            role:     Role::Node,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_buf = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_buf     = [0u8; SIG_SIZE];
        let n = issue_credential(&issuer, &manifest, &mut payload_buf, &mut sig_buf).unwrap();

        let parsed = parse_payload_pub(&payload_buf[..n]).unwrap();
        assert_eq!(parsed.role, Role::Node);
    }

    #[test]
    fn issue_credential_depth_too_large_returns_chain_too_deep() {
        let issuer = make_test_identity(b"issuer");
        let child  = make_test_identity(b"child");
        let scope_bytes = make_test_scope();
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&[]).unwrap();
        let manifest = DelegationManifest {
            child_pk: child.public_key(),
            role:     Role::Leaf,
            depth:    Depth(MAX_DEPTH + 1),
            scope,
            caveats,
        };
        let mut payload_out = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_out = [0u8; SIG_SIZE];
        assert!(matches!(
            issue_credential(&issuer, &manifest, &mut payload_out, &mut sig_out),
            Err(KernelError::ChainTooDeep)
        ));
    }

    #[test]
    fn issue_credential_leaf_role_encoded_as_zero() {
        let issuer = make_test_identity(b"issuer");
        let child  = make_test_identity(b"child");
        let scope_bytes = make_test_scope();
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&[]).unwrap();
        let manifest = DelegationManifest {
            child_pk: child.public_key(),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_out = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_out = [0u8; SIG_SIZE];
        let n = issue_credential(&issuer, &manifest, &mut payload_out, &mut sig_out).unwrap();
        // The role byte sits immediately after child_pk (PK_SIZE bytes).
        assert_eq!(payload_out[PK_SIZE], 0u8);
        let _ = n;
    }

    #[test]
    fn issue_credential_node_role_encoded_as_one() {
        let issuer = make_test_identity(b"issuer");
        let child  = make_test_identity(b"child");
        let scope_bytes = make_test_scope();
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&[]).unwrap();
        let manifest = DelegationManifest {
            child_pk: child.public_key(),
            role:     Role::Node,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_out = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_out = [0u8; SIG_SIZE];
        let n = issue_credential(&issuer, &manifest, &mut payload_out, &mut sig_out).unwrap();
        assert_eq!(payload_out[PK_SIZE], 1u8);
        let _ = n;
    }

    // ── write_credential_chain / read_credential_chain (wire round-trip) ──

    /// Builds a single-hop chain: root issues to child, returns the wire bytes and the
    /// original issuer_pk and sig_bytes for comparison.
    fn build_single_hop_wire() -> (Vec<u8>, [u8; PK_SIZE], [u8; SIG_SIZE], Vec<u8>) {
        let issuer = make_test_identity(b"root");
        let child  = make_test_identity(b"child");
        let scope_bytes = make_test_scope();
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&[]).unwrap();
        let manifest = DelegationManifest {
            child_pk: child.public_key(),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_buf = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_buf     = [0u8; SIG_SIZE];
        let payload_len = issue_credential(&issuer, &manifest, &mut payload_buf, &mut sig_buf).unwrap();

        let issuer_pk_copy = *issuer.public_key().0;
        let sig_copy       = sig_buf;
        let payload_copy   = payload_buf[..payload_len].to_vec();

        let cred = Credential {
            issuer_pk: PublicKey(&issuer_pk_copy),
            signature: Signature(&sig_copy),
            payload:   &payload_copy,
        };

        let chain = [cred];
        // Allocate a generously sized wire buffer.
        let mut wire = vec![0u8; 5 + CREDENTIAL_FIXED_SIZE + MAX_PAYLOAD_SIZE];
        let n = write_credential_chain(&mut wire, &chain).unwrap();
        wire.truncate(n);
        (wire, issuer_pk_copy, sig_copy, payload_copy)
    }

    #[test]
    fn wire_round_trip_single_credential() {
        let (wire, expected_pk, expected_sig, expected_payload) = build_single_hop_wire();

        let mut chain_buf: [Credential; 16] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        // Borrow trick: read back from wire slice.
        let n = read_credential_chain(&wire, &mut chain_buf).unwrap();
        assert_eq!(n, 1);
        assert_eq!(chain_buf[0].issuer_pk.0, &expected_pk);
        assert_eq!(chain_buf[0].signature.0, &expected_sig);
        assert_eq!(chain_buf[0].payload, expected_payload.as_slice());
    }

    #[test]
    fn wire_empty_chain_write_then_read_returns_empty_chain() {
        // write_credential_chain with count=0 is valid to write.
        let mut wire = vec![0u8; 16];
        let n = write_credential_chain(&mut wire, &[]).unwrap();
        wire.truncate(n);

        let mut chain_buf: [Credential; 16] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        assert!(matches!(
            read_credential_chain(&wire, &mut chain_buf),
            Err(KernelError::EmptyChain)
        ));
    }

    #[test]
    fn wire_count_exceeds_max_depth_returns_chain_too_deep() {
        // Manually craft a wire buffer with a count of MAX_DEPTH + 1.
        let mut wire = vec![0u8; 16];
        wire[0] = 0x01; // WIRE_VERSION
        let bad_count = (MAX_DEPTH + 1).to_le_bytes();
        wire[1..5].copy_from_slice(&bad_count);

        let mut chain_buf: [Credential; 32] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        assert!(matches!(
            read_credential_chain(&wire, &mut chain_buf),
            Err(KernelError::ChainTooDeep)
        ));
    }

    #[test]
    fn wire_wrong_version_returns_version_mismatch() {
        let (mut wire, _, _, _) = build_single_hop_wire();
        wire[0] = 0xFF; // corrupt version
        let mut chain_buf: [Credential; 16] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        assert!(matches!(
            read_credential_chain(&wire, &mut chain_buf),
            Err(KernelError::WireVersionMismatch)
        ));
    }

    #[test]
    fn wire_truncated_buffer_returns_wire_truncated() {
        let (wire, _, _, _) = build_single_hop_wire();
        // Truncate to just the header, leaving the credential body incomplete.
        let truncated = &wire[..5];
        let mut chain_buf: [Credential; 16] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        assert!(matches!(
            read_credential_chain(truncated, &mut chain_buf),
            Err(KernelError::WireTruncated)
        ));
    }

    #[test]
    fn wire_trailing_bytes_after_valid_chain() {
        // The wire reader stops consuming after the declared credentials;
        // trailing bytes are NOT consumed (no anti-malleability check at the
        // chain level — the function returns Ok with the correct count).
        // This test documents the actual behaviour.
        let (wire, _, _, _) = build_single_hop_wire();
        let mut extended = wire.clone();
        extended.extend_from_slice(&[0xFFu8; 8]);

        let mut chain_buf: [Credential; 16] = core::array::from_fn(|_| Credential {
            issuer_pk: PublicKey(&[0u8; PK_SIZE]),
            signature: Signature(&[0u8; SIG_SIZE]),
            payload:   &[],
        });
        // read_credential_chain does not enforce no-trailing-bytes at the outer
        // level; it returns Ok(1) with trailing bytes ignored.
        let result = read_credential_chain(&extended, &mut chain_buf);
        assert!(result.is_ok());
        assert_eq!(result.unwrap(), 1);
    }

    // ── verify_delegation (full chain) ──

    /// Builds a complete, valid, one-hop Credential value whose lifetime is
    /// tied to the provided storage arrays.  All fields are copied into the
    /// caller-supplied buffers so the returned `Credential` can borrow them.
    fn build_credential<'a>(
        issuer:         &'a impl IdentitySigner,
        child_pk_bytes: &'a [u8; PK_SIZE],
        role:           Role,
        depth:          Depth,
        scope_bytes:    &[u8],
        caveat_bytes:   &[u8],
        payload_store:  &'a mut [u8; MAX_PAYLOAD_SIZE],
        sig_store:      &'a mut [u8; SIG_SIZE],
    ) -> Credential<'a> {
        let scope   = BoundedScope::try_new(scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(caveat_bytes).unwrap();
        let manifest = DelegationManifest {
            child_pk: PublicKey(child_pk_bytes),
            role,
            depth,
            scope,
            caveats,
        };
        let payload_len =
            issue_credential(issuer, &manifest, payload_store, sig_store).unwrap();
        Credential {
            issuer_pk: issuer.public_key(),
            signature: Signature(sig_store),
            payload:   &payload_store[..payload_len],
        }
    }

    #[test]
    fn verify_delegation_single_hop_ok() {
        let root  = make_test_identity(b"root");
        let child = make_test_identity(b"child");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];

        let cred = build_credential(
            &root, &child_pk, Role::Leaf, Depth(1),
            &scope_bytes, &caveat_bytes,
            &mut payload_store, &mut sig_store,
        );

        let chain = [cred];
        assert!(verify_delegation(root.public_key(), &chain, Timestamp(0)).is_ok());
    }

    #[test]
    fn verify_delegation_two_hop_ok() {
        let root  = make_test_identity(b"root");
        let node  = make_test_identity(b"node");
        let leaf  = make_test_identity(b"leaf");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();

        let node_pk = *node.public_key().0;
        let leaf_pk = *leaf.public_key().0;

        // root → node (depth 1, Node role)
        let mut p1 = [0u8; MAX_PAYLOAD_SIZE];
        let mut s1 = [0u8; SIG_SIZE];
        let cred1 = build_credential(
            &root, &node_pk, Role::Node, Depth(1),
            &scope_bytes, &caveat_bytes, &mut p1, &mut s1,
        );

        // node → leaf (depth 2, Leaf role)
        let mut p2 = [0u8; MAX_PAYLOAD_SIZE];
        let mut s2 = [0u8; SIG_SIZE];
        let cred2 = build_credential(
            &node, &leaf_pk, Role::Leaf, Depth(2),
            &scope_bytes, &caveat_bytes, &mut p2, &mut s2,
        );

        let chain = [cred1, cred2];
        assert!(verify_delegation(root.public_key(), &chain, Timestamp(0)).is_ok());
    }

    #[test]
    fn verify_delegation_empty_chain_returns_empty_chain() {
        let root = make_test_identity(b"root");
        assert!(matches!(
            verify_delegation(root.public_key(), &[], Timestamp(0)),
            Err(KernelError::EmptyChain)
        ));
    }

    #[test]
    fn verify_delegation_wrong_root_pk_returns_parent_key_mismatch() {
        let root   = make_test_identity(b"root");
        let wrong  = make_test_identity(b"wrong-root");
        let child  = make_test_identity(b"child");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];

        let cred = build_credential(
            &root, &child_pk, Role::Leaf, Depth(1),
            &scope_bytes, &caveat_bytes,
            &mut payload_store, &mut sig_store,
        );
        let chain = [cred];
        assert!(matches!(
            verify_delegation(wrong.public_key(), &chain, Timestamp(0)),
            Err(KernelError::ParentKeyMismatch)
        ));
    }

    #[test]
    fn verify_delegation_tampered_signature_returns_error() {
        let root  = make_test_identity(b"root");
        let child = make_test_identity(b"child");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];

        build_credential(
            &root, &child_pk, Role::Leaf, Depth(1),
            &scope_bytes, &caveat_bytes,
            &mut payload_store, &mut sig_store,
        );

        // Corrupt one byte of the signature.
        sig_store[100] ^= 0xFF;

        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&caveat_bytes).unwrap();
        let manifest = DelegationManifest {
            child_pk: PublicKey(&child_pk),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };
        let mut payload_buf = [0u8; MAX_PAYLOAD_SIZE];
        let mut dummy_sig   = [0u8; SIG_SIZE];
        let payload_len =
            issue_credential(&root, &manifest, &mut payload_buf, &mut dummy_sig).unwrap();

        let tampered_cred = Credential {
            issuer_pk: root.public_key(),
            signature: Signature(&sig_store),
            payload:   &payload_buf[..payload_len],
        };
        let chain = [tampered_cred];
        let result = verify_delegation(root.public_key(), &chain, Timestamp(0));
        assert!(
            matches!(result, Err(KernelError::SignatureInvalid))
                || matches!(result, Err(KernelError::SignatureDecodingFailed)),
            "expected SignatureInvalid or SignatureDecodingFailed, got {:?}",
            result
        );
    }

    #[test]
    fn verify_delegation_expired_caveat_returns_not_after_violation() {
        let root  = make_test_identity(b"root");
        let child = make_test_identity(b"child");
        let scope_bytes = make_test_scope();

        // expires at t=1000
        let caveat = not_after(Timestamp(1000));
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&caveat).unwrap();
        let child_pk = *child.public_key().0;
        let manifest = DelegationManifest {
            child_pk: PublicKey(&child_pk),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };

        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];
        let payload_len =
            issue_credential(&root, &manifest, &mut payload_store, &mut sig_store).unwrap();

        let cred = Credential {
            issuer_pk: root.public_key(),
            signature: Signature(&sig_store),
            payload:   &payload_store[..payload_len],
        };
        let chain = [cred];
        // now = 1001, after expiry
        assert!(matches!(
            verify_delegation(root.public_key(), &chain, Timestamp(1001)),
            Err(KernelError::NotAfterViolation)
        ));
    }

    #[test]
    fn verify_delegation_not_yet_valid_returns_not_before_violation() {
        let root  = make_test_identity(b"root");
        let child = make_test_identity(b"child");
        let scope_bytes = make_test_scope();

        // valid from t=5000
        let caveat  = not_before(Timestamp(5000));
        let scope   = BoundedScope::try_new(&scope_bytes).unwrap();
        let caveats = BoundedCaveats::try_new(&caveat).unwrap();
        let child_pk = *child.public_key().0;
        let manifest = DelegationManifest {
            child_pk: PublicKey(&child_pk),
            role:     Role::Leaf,
            depth:    Depth(1),
            scope,
            caveats,
        };

        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];
        let payload_len =
            issue_credential(&root, &manifest, &mut payload_store, &mut sig_store).unwrap();

        let cred = Credential {
            issuer_pk: root.public_key(),
            signature: Signature(&sig_store),
            payload:   &payload_store[..payload_len],
        };
        let chain = [cred];
        // now = 4999, before the not_before timestamp
        assert!(matches!(
            verify_delegation(root.public_key(), &chain, Timestamp(4999)),
            Err(KernelError::NotBeforeViolation)
        ));
    }

    #[test]
    fn verify_delegation_leaf_cannot_delegate() {
        let root = make_test_identity(b"root");
        let node = make_test_identity(b"node");
        let leaf = make_test_identity(b"leaf");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();

        let node_pk = *node.public_key().0;
        let leaf_pk = *leaf.public_key().0;

        // root → node with Leaf role (should not be able to sub-delegate)
        let mut p1 = [0u8; MAX_PAYLOAD_SIZE];
        let mut s1 = [0u8; SIG_SIZE];
        let cred1 = build_credential(
            &root, &node_pk, Role::Leaf, Depth(1),
            &scope_bytes, &caveat_bytes, &mut p1, &mut s1,
        );

        // node → leaf: node had Leaf role, so this must fail.
        let mut p2 = [0u8; MAX_PAYLOAD_SIZE];
        let mut s2 = [0u8; SIG_SIZE];
        let cred2 = build_credential(
            &node, &leaf_pk, Role::Leaf, Depth(2),
            &scope_bytes, &caveat_bytes, &mut p2, &mut s2,
        );

        let chain = [cred1, cred2];
        assert!(matches!(
            verify_delegation(root.public_key(), &chain, Timestamp(0)),
            Err(KernelError::LeafCannotDelegate)
        ));
    }

    #[test]
    fn verify_delegation_depth_out_of_sequence_returns_depth_mismatch() {
        let root  = make_test_identity(b"root");
        let child = make_test_identity(b"child");
        let scope_bytes  = make_test_scope();
        let caveat_bytes = make_test_caveats();
        let child_pk = *child.public_key().0;

        // Issue at depth 2 instead of the required 1 for the first credential.
        let mut payload_store = [0u8; MAX_PAYLOAD_SIZE];
        let mut sig_store     = [0u8; SIG_SIZE];
        let cred = build_credential(
            &root, &child_pk, Role::Leaf, Depth(2),
            &scope_bytes, &caveat_bytes,
            &mut payload_store, &mut sig_store,
        );
        let chain = [cred];
        assert!(matches!(
            verify_delegation(root.public_key(), &chain, Timestamp(0)),
            Err(KernelError::DepthMismatch)
        ));
    }
}