mkit_server/pipeline/
auth.rs

1//! Stage 0 (authenticate) and stage 1 (identity mapping): pure and
2//! synchronous, writing no state. Bindings call it from their interceptor
3//! through [`super::Pipeline::authenticate`].
4
5use core::fmt;
6
7use mkit_core::hash::hash;
8use subtle::ConstantTimeEq;
9
10use crate::auth_v2::{self, AuthV2Config};
11use crate::error::{Redacted, ServerError};
12use crate::op::{Procedure, VerifiedAuth};
13use crate::principal::Principal;
14use crate::repo::ResolvedRepo;
15
16/// How a deployment authenticates requests.
17#[derive(Debug, Clone)]
18#[non_exhaustive]
19pub enum AuthMode {
20    /// No credentials; every request is `Anonymous` (unsafe-any HTTP, or a
21    /// trusted caller). No replay ledger.
22    Open,
23    /// A shared `Authorization: Bearer <token>`, required on every RPC,
24    /// unary and streaming (as the removed `mkit serve --http` did). The BLAKE3
25    /// digests of the presented and expected values are compared in
26    /// constant time, so neither the content nor the length leaks. No
27    /// replay ledger.
28    Bearer {
29        /// The expected token.
30        token: Redacted,
31    },
32    /// Auth v2 on writes, with the replay ledger and quota; a read that
33    /// carries an auth header is verified in full (SPEC-WRITE-GRANTS
34    /// §9.2), an unsigned read is anonymous.
35    AuthV2(AuthV2Config),
36    /// The binding supplies the principal (ssh forced command, enc peer).
37    /// No replay ledger.
38    TransportIdentity,
39}
40
41/// Multi-value header lookup supplied by a transport adapter.
42pub type HeaderValues<'a> = dyn Fn(&str) -> Vec<String> + 'a;
43
44/// Everything stage 0 needs, without any HTTP or Connect type.
45pub struct RequestMeta<'a> {
46    /// The procedure called.
47    pub procedure: Procedure,
48    /// Looks a request header up by its lowercase name.
49    pub header: &'a dyn Fn(&str) -> Option<String>,
50    /// All values for a header name. Bindings with single-value metadata may omit it.
51    pub header_values: Option<&'a HeaderValues<'a>>,
52    /// The exact unary request bytes (the auth v2 body commitment); for
53    /// `DownloadPack`, the exact framed request body `0x00‖len‖message`;
54    /// `None` for other streams.
55    pub unary_body: Option<&'a [u8]>,
56    /// The identity the transport established (ssh, enc).
57    pub transport_principal: Option<Principal>,
58}
59
60impl fmt::Debug for RequestMeta<'_> {
61    /// Never shows header values or the body.
62    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
63        f.debug_struct("RequestMeta")
64            .field("procedure", &self.procedure)
65            .field("unary_body", &self.unary_body.map(<[u8]>::len))
66            .field("transport_principal", &self.transport_principal)
67            .finish_non_exhaustive()
68    }
69}
70
71/// A request that passed stage 0, bound to the procedure it was
72/// authenticated for. Only [`super::Pipeline::authenticate`] builds one.
73#[derive(Clone, PartialEq, Eq)]
74pub struct Authenticated {
75    /// Who the request acts as.
76    pub principal: Principal,
77    /// The verified auth v2 authorization of a signed request.
78    pub auth: Option<VerifiedAuth>,
79    /// A presented write grant, redacted from debug output.
80    pub write_grant: Option<Redacted>,
81    /// Raw credential header values captured at authentication and validated
82    /// only when admission runs (SPEC-SERVER §6.6); never shown in diagnostics.
83    pub(super) credential_capture: Vec<super::admission::CapturedCredential>,
84    /// Optional repository-local read-your-writes hint (outside auth v2).
85    pub ref_hint: Option<String>,
86    procedure: Procedure,
87    repo: ResolvedRepo,
88    /// Added to the business clock for this request only: the test
89    /// clock-skew directive. Never feeds a commit deadline.
90    pub(crate) business_skew_ms: i64,
91    /// Business time used for auth v2 verification, reused for the grant.
92    pub(crate) business_now_ms: i64,
93    #[cfg(feature = "test-faults")]
94    directives: super::TestDirectives,
95}
96
97impl fmt::Debug for Authenticated {
98    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
99        f.debug_struct("Authenticated")
100            .field("principal", &self.principal)
101            .field("auth", &self.auth)
102            .field("procedure", &self.procedure)
103            .field("repo", &self.repo)
104            .finish_non_exhaustive()
105    }
106}
107
108impl Authenticated {
109    /// The procedure these credentials were checked for; every entry point
110    /// refuses any other.
111    #[must_use]
112    pub fn procedure(&self) -> Procedure {
113        self.procedure
114    }
115
116    /// The repository resolved and bound to this request at stage 0.
117    #[must_use]
118    pub fn repo(&self) -> &ResolvedRepo {
119        &self.repo
120    }
121
122    /// The request's test directives (feature `test-faults` only).
123    #[cfg(feature = "test-faults")]
124    #[must_use]
125    pub fn test_directives(&self) -> &super::TestDirectives {
126        &self.directives
127    }
128
129    #[cfg(feature = "test-faults")]
130    pub(crate) fn set_test_directives(&mut self, directives: super::TestDirectives) {
131        self.directives = directives;
132    }
133}
134
135/// Whether `meta`'s request verifies in full under `mode`: under auth v2,
136/// every write but `SetRepoVisibility` (whose statement mode is unsigned
137/// by design, §9.1) and any request carrying an auth header marker.
138pub(crate) fn signed_request(mode: &AuthMode, meta: &RequestMeta<'_>) -> bool {
139    matches!(mode, AuthMode::AuthV2(_))
140        && (meta.procedure.is_write() && meta.procedure != Procedure::SetRepoVisibility
141            || auth_v2::carries_auth_headers(meta.header))
142}
143
144/// Stage 0 and 1 for `mode` at business time `now_ms`.
145pub(crate) fn authenticate(
146    mode: &AuthMode,
147    meta: &RequestMeta<'_>,
148    now_ms: i64,
149    repo: ResolvedRepo,
150    expected_repository: &str,
151) -> Result<Authenticated, ServerError> {
152    let procedure = meta.procedure;
153    let presented_grant = (meta.header)("x-write-grant").map(Redacted::new);
154    let (principal, auth) = match mode {
155        AuthMode::Bearer { token } => {
156            let got = (meta.header)("authorization").unwrap_or_default();
157            let expected = format!("Bearer {}", token.expose());
158            let same = hash(got.as_bytes()).ct_eq(&hash(expected.as_bytes()));
159            if !bool::from(same) {
160                return Err(ServerError::unauthenticated(
161                    "missing or invalid Authorization: Bearer <token>",
162                ));
163            }
164            (Principal::BearerHolder, None)
165        }
166        AuthMode::AuthV2(cfg) => {
167            let must_sign = procedure.is_write() && procedure != Procedure::SetRepoVisibility;
168            if must_sign || auth_v2::carries_auth_headers(meta.header) {
169                // A request carrying any auth v2 marker verifies in full
170                // (SPEC-TRANSPORT-CONNECT §7.1); a failure never falls
171                // back to anonymous. Signed reads keep no replay ledger.
172                let auth = verify_auth_v2(cfg, expected_repository, meta, now_ms)?;
173                (
174                    Principal::Signer {
175                        ed25519: auth.signer,
176                    },
177                    Some(auth),
178                )
179            } else if procedure == Procedure::IssueObjectUrl {
180                return Err(ServerError::unauthenticated(
181                    "IssueObjectUrl requires auth v2 authorization",
182                ));
183            } else {
184                (Principal::Anonymous, None)
185            }
186        }
187        AuthMode::Open => (Principal::Anonymous, None),
188        AuthMode::TransportIdentity => (
189            meta.transport_principal
190                .clone()
191                .ok_or_else(|| ServerError::unauthenticated("missing transport identity"))?,
192            None,
193        ),
194    };
195    // A presented grant is captured on any procedure
196    // (SPEC-WRITE-GRANTS §4.2); `authenticate_inner` rejects it on an
197    // unsigned Multi request, and a Single/Open deployment ignores it.
198    Ok(Authenticated {
199        principal,
200        auth,
201        write_grant: presented_grant,
202        credential_capture: Vec::new(),
203        procedure,
204        repo,
205        ref_hint: None,
206        business_skew_ms: 0,
207        business_now_ms: now_ms,
208        #[cfg(feature = "test-faults")]
209        directives: super::TestDirectives::default(),
210    })
211}
212
213fn verify_auth_v2(
214    cfg: &AuthV2Config,
215    repository: &str,
216    meta: &RequestMeta<'_>,
217    now_ms: i64,
218) -> Result<VerifiedAuth, ServerError> {
219    let headers = auth_v2::headers_from(meta.header);
220    let path = meta.procedure.connect_path();
221    if meta.procedure.is_streaming() && meta.procedure != Procedure::DownloadPack {
222        return auth_v2::verify_stream_for(cfg, repository, path, now_ms, &headers);
223    }
224    let body = meta.unary_body.ok_or_else(|| {
225        ServerError::internal("authentication failed", "unary request without its body")
226    })?;
227    auth_v2::verify_unary_for(cfg, repository, path, body, now_ms, &headers)
228}
mkit_server/pipeline/auth.rs

mkit_server/pipeline/
auth.rs
