fiki 0.10.0

Sign and verify HTTP requests with a bare Ed25519 key as the identifier. Standard RFC 9421, no KERI dependencies.
Documentation
//! fiki's error taxonomy (`this.i` @8zw78n0v).
//!
//! The variant NAMES are a cross-language contract rather than an implementation detail:
//! `vectors/refusals.json` records the name fiki reports for each refusal, and every port asserts
//! on it. So a port that folds two conditions together fails a vector rather than passing quietly,
//! and heti — which maps these onto its own codes — can be told what happened by a client in any
//! language.
//!
//! The granularity comes from heti's taxonomy, which distinguishes a missing header from an
//! unparsable one, per header, so a sender can be told which header to fix rather than handed the
//! pair.

use std::fmt;

/// Every error fiki returns about a request.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Error {
    pub kind: Kind,
    pub message: String,
    /// The offending value, when there is one. Carried structurally rather than in the message, so
    /// a consumer translating fiki's errors into its own vocabulary is not reading prose.
    pub detail: Option<String>,
}

/// The condition a refusal names. The `Display` spelling is what the shared vectors pin.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Kind {
    // Something the request needs is absent.
    MissingSignature,
    MissingSignatureInput,
    MissingSignatureLabel,
    MissingKey,
    MissingComponent,
    /// A resolver was supplied and does not know the signature's keyid (`this.i` @6g9zjsv9), or
    /// the keyid is not the one the caller expected. Never answered by decoding the keyid instead:
    /// a basic transferable prefix embeds its inception key, which may have been rotated away.
    UnknownKey,
    /// The keyid's key state has no single key that satisfies its threshold alone (@2f227n4r).
    /// fiki knows nothing of key state and never decides this itself: a resolver returns it, and
    /// fiki carries it out unchanged.
    UnsupportedSigner,
    /// An unsigned 401 answered the request. A server that refuses before it knows which agent it
    /// is cannot sign the refusal, so its body is not to be trusted (@2f227n4r).
    Unauthenticated,

    // Something the request carries cannot be read.
    MalformedSignature,
    MalformedSignatureInput,
    MalformedSignatureLabel,
    MalformedSignatureValue,
    MalformedKey,
    MalformedDigest,

    // fiki understood the request and will not handle it.
    UnsupportedComponent,
    UnsupportedAlgorithm,
    /// The covered list names the same component twice, whatever the order of its parameters.
    DuplicateComponent,
    /// The signature covers less than the stated minimum, including a body whose
    /// `content-digest` is not covered. Refused even when it verifies (@7f28p7xk).
    InsufficientCoverage,
    UncoveredBody,

    // The request is signed and a stated policy refuses it anyway (`this.i` @67shl6c5).
    SignatureExpired,
    SignatureTooOld,

    // The request was read, and it does not hold up.
    DigestMismatch,
    SignatureMismatch,

    // The call, not the message, is wrong (`this.i` @5e2phpjy): a minimum smaller than the KERI
    // profile's, both `expected_aid` and `resolve`, or a request body the verifier needs and was
    // not given. No message can cure it, and the KERI profile has no code for it.
    InvalidArgument,
}

impl fmt::Display for Kind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let name = match self {
            Kind::MissingSignature => "MissingSignature",
            Kind::MissingSignatureInput => "MissingSignatureInput",
            Kind::MissingSignatureLabel => "MissingSignatureLabel",
            Kind::MissingKey => "MissingKey",
            Kind::MissingComponent => "MissingComponent",
            Kind::MalformedSignature => "MalformedSignature",
            Kind::MalformedSignatureInput => "MalformedSignatureInput",
            Kind::MalformedSignatureLabel => "MalformedSignatureLabel",
            Kind::MalformedSignatureValue => "MalformedSignatureValue",
            Kind::MalformedKey => "MalformedKey",
            Kind::MalformedDigest => "MalformedDigest",
            Kind::UnsupportedComponent => "UnsupportedComponent",
            Kind::UnsupportedAlgorithm => "UnsupportedAlgorithm",
            Kind::UncoveredBody => "UncoveredBody",
            Kind::SignatureExpired => "SignatureExpired",
            Kind::SignatureTooOld => "SignatureTooOld",
            Kind::DigestMismatch => "DigestMismatch",
            Kind::SignatureMismatch => "SignatureMismatch",
            Kind::UnknownKey => "UnknownKey",
            Kind::UnsupportedSigner => "UnsupportedSigner",
            Kind::Unauthenticated => "Unauthenticated",
            Kind::DuplicateComponent => "DuplicateComponent",
            Kind::InsufficientCoverage => "InsufficientCoverage",
            Kind::InvalidArgument => "InvalidArgument",
        };
        f.write_str(name)
    }
}

impl fmt::Display for Error {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.message)
    }
}

impl std::error::Error for Error {}

impl Error {
    /// An error of `kind`. Public so that a [`Resolver`](crate::Resolver) can refuse a keyid in
    /// fiki's own vocabulary.
    pub fn new(kind: Kind, message: impl Into<String>) -> Self {
        Error {
            kind,
            message: message.into(),
            detail: None,
        }
    }

    /// An error of `kind` carrying the offending value, such as the keyid a resolver refuses.
    pub fn detailed(kind: Kind, message: impl Into<String>, detail: impl Into<String>) -> Self {
        Error {
            kind,
            message: message.into(),
            detail: Some(detail.into()),
        }
    }
}

/// The result of anything fiki can refuse.
pub type Result<T> = std::result::Result<T, Error>;