//! Issuance errors for the JWT engine.
//!
//! Mirror of `AuthError` shape: 1 variant per named failure mode so audit
//! logs read the cause off the variant name without a lookup table
//! (project_jwt_phase2_design Decision 2). Variants are additive across
//! phases — Phase 3 covers the issue-side baseline; Phase 4+ append.
//!
//! `KeyMismatch` carries both kids in its data because the audit signal
//! ("which mismatch") is far more useful than just the fact of mismatch
//! — operators want to see at a glance which IssueConfig misnames its
//! signing key. KeyParse / JsonEncode wrap the underlying library error
//! as a String so the public API stays free of `jsonwebtoken::*` types
//! (M51 boundary; the lint enforcement lands Phase 7).

#[derive(Debug, thiserror::Error)]
pub enum IssueError {
    /// PEM input cannot be parsed as an Ed25519 private key.
    #[error("issue: failed to parse Ed25519 PEM ({0})")]
    KeyParse(String),

    /// `IssueConfig.kid` does not match the kid associated with the
    /// supplied `SigningKey`. Emitted before any encoding work happens
    /// so a misconfigured pipeline fails closed instead of issuing
    /// tokens against an unrecognized kid.
    #[error("issue: cfg kid '{cfg_kid}' does not match signer kid '{signer_kid}'")]
    KeyMismatch { cfg_kid: String, signer_kid: String },

    /// `jsonwebtoken::encode` failed at the JSON serialization step. In
    /// practice this only fires when a Claims field overflows the JSON
    /// number range — the registered claims are all integers within
    /// `i64`, so production paths cannot hit it.
    #[error("issue: failed to encode JWT ({0})")]
    JsonEncode(String),

    /// System clock is before UNIX_EPOCH. Cannot happen on a correctly
    /// configured machine; surfaces only on hardware-reset / NTP-broken
    /// edge cases. Listed for completeness so the engine refuses to
    /// emit garbage timestamps rather than panicking.
    #[error("issue: system clock is before UNIX_EPOCH")]
    ClockBackwards,
}
