pkce-std 0.2.1

Handling Proof Key for Code Exchange.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Coupled PKCE code verifier and challenge pairs.
//!
//! The [`Code`] type provides ergonomic and simple methods to generate verifier-challenge pairs.
//!
//! [`Code`] is slightly more than simply using [`Verifier`] and [`Challenge`] together, as it
//! imposes the following invariant: the verifier and challenge are always generated together and
//! the challenge corresponds to the verifier, meaning `verifier.verify(&challenge)` is always true.
//!
//! Therefore it is not possible to access the verifier or challenge separately, and one should use
//! [`into_pair`] to get both parts, consuming the [`Code`] value.
//!
//! # Examples
//!
//! ```
//! use pkce_std::code::Code;
//!
//! let code = Code::generate_default();
//!
//! let (verifier, challenge) = code.into_pair();
//!
//! // this is always true here!
//! assert!(verifier.verify(&challenge));
//! ```
//!
//! [`into_pair`]: Code::into_pair

use std::borrow::Cow;

#[cfg(feature = "static")]
use into_static::IntoStatic;

use crate::{
    challenge::Challenge, count::Count, length::Length, method::Method, verifier::Verifier,
};

/// Represents coupled [`Verifier`] and [`Challenge`] pairs.
///
/// Refer to the [module] documentation for more information.
///
/// [module]: self
#[derive(Debug, Clone)]
pub struct Code<'c> {
    verifier: Verifier<'c>,
    challenge: Challenge,
}

impl<'c> Code<'c> {
    const fn new(verifier: Verifier<'c>, challenge: Challenge) -> Self {
        Self {
            verifier,
            challenge,
        }
    }

    /// Consumes [`Self`], returning the `(verifier, challenge)` pair.
    pub fn into_pair(self) -> Pair<'c> {
        (self.verifier, self.challenge)
    }

    /// Consumes [`Self`], returning `(verifier, secret, method)` parts.
    pub fn into_parts(self) -> Parts<'c> {
        let (secret, method) = self.challenge.into_parts();

        (self.verifier.take(), secret, method)
    }
}

impl Code<'_> {
    /// Generates [`Self`] using the given method and length.
    pub fn generate_using(method: Method, length: Length) -> Self {
        let verifier = Verifier::generate(length);
        let challenge = verifier.challenge_using(method);

        Self::new(verifier, challenge)
    }

    /// Generates [`Self`] using the default method and the given length.
    pub fn generate(length: Length) -> Self {
        Self::generate_using(Method::default(), length)
    }

    /// Generates [`Self`] using the default method and length.
    pub fn generate_default() -> Self {
        Self::generate(Length::default())
    }

    /// Generates [`Self`] using the given method and bytes count.
    pub fn generate_encode_using(method: Method, count: Count) -> Self {
        let verifier = Verifier::generate_encode(count);
        let challenge = verifier.challenge_using(method);

        Self::new(verifier, challenge)
    }

    /// Generates [`Self`] using the default method and the given bytes count.
    pub fn generate_encode(count: Count) -> Self {
        Self::generate_encode_using(Method::default(), count)
    }

    /// Generates [`Self`] using the default method and bytes count.
    pub fn generate_encode_default() -> Self {
        Self::generate_encode(Count::default())
    }
}

/// An alias for [`Code<'static>`].
#[cfg(feature = "static")]
pub type StaticCode = Code<'static>;

#[cfg(feature = "static")]
impl IntoStatic for Code<'_> {
    type Static = StaticCode;

    fn into_static(self) -> Self::Static {
        Self::Static::new(self.verifier.into_static(), self.challenge)
    }
}

/// Represents `(verifier, challenge)` pairs.
pub type Pair<'p> = (Verifier<'p>, Challenge);

/// Represents owned [`Pair`] values.
pub type OwnedPair = Pair<'static>;

impl<'c> From<Code<'c>> for Pair<'c> {
    fn from(code: Code<'c>) -> Self {
        code.into_pair()
    }
}

/// Represents `(verifier, secret, method)` parts.
pub type Parts<'p> = (Cow<'p, str>, String, Method);

/// Represents owned [`Parts`] values.
pub type OwnedParts = Parts<'static>;

impl<'c> From<Code<'c>> for Parts<'c> {
    fn from(code: Code<'c>) -> Self {
        code.into_parts()
    }
}