mkit-server 0.5.0

Runtime-agnostic core of the mkit server: operation model, errors, runtime and telemetry vocabulary
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

//! Remote hooks: the `mkit.server.hooks.v1` adapter (SPEC-SERVER §§6-8),
//! behind the `remote-hooks` feature.
//!
//! A deployment can run authorization, admission and outcome delivery in a
//! separate service, such as a payment layer. This module holds the whole
//! protocol except the transport:
//!
//! - [`HookChannel`] moves one Connect unary call (`POST <base>/<procedure>`,
//!   `application/json`, `Connect-Protocol-Version: 1`). The native HTTPS
//!   channel (WP-3.8) and the Workers binding (WP-3.9) will implement it.
//! - [`HookSigner`] signs every request over its exact body bytes with the
//!   `mkit-hook:v1` domain, a fresh 32-byte nonce and a validity of at most
//!   300 s. Only a channel that reports [`HookChannel::isolated`] (a service
//!   binding, §7.3) may go unsigned, and [`HookClient::new`] refuses anything
//!   else.
//! - [`HookVerifier`] is the receiving side of that signature (a hook service's
//!   §7.1 checks), free of server-runtime dependencies.
//! - [`RemoteAuthorizer`], [`RemoteAdmission`] and [`RemoteOutcomes`] share
//!   one [`HookClient`] and implement the stage traits, so any subset plugs
//!   into [`Hooks`](crate::pipeline::Hooks).
//! - [`RemoteInspector`] implements synchronous inspection at stage 5. The
//!   pipeline owns complete inspected-set enumeration, batching and stable
//!   inspection ids.
//!
//! # Failure semantics
//!
//! Authorize, Admit and Inspect fail closed (§8): a transport error, timeout, non-2xx
//! status, Connect error body, non-JSON content type, body over 64 KiB,
//! malformed JSON, absent decision/verdict or a failed §6.6 check all answer
//! retryable `unavailable` and write nothing. There is no retry inside a call.
//! A deliberate `deny` in a 2xx answer is a decision, sanitised per §6.2. An
//! Outcome is acknowledged by any 2xx; every other result is a
//! [`DeliveryError`](crate::pipeline::DeliveryError) that kind 8 retries with
//! backoff, signing each attempt afresh.
//!
//! # Credential safety
//!
//! Admit bodies carry admission credentials. Requests and responses are never
//! logged or `Debug`-printed (the generated messages would print values), the
//! request body is serialised once into an exactly sized `Zeroizing` buffer,
//! the credential values of the message are wiped after the call, and every
//! failure reason is a fixed string.
//!
//! # Not here
//!
//! The launch profile accepts synchronous fail-closed inspection only (§18).
//! Async inspection belongs to WP-5.5c. Event belongs to WP-5.2.
//! `AuthorizeAllow.writer_view` becomes `AuthzFacts::caller_view`, which the
//! pipeline honours only under the `authority` role (§10.1). Reservation-id
//! uniqueness is enforced per partition by the pipeline, while §6.6 asks for
//! it per audience: uniqueness across partitions is the hook's obligation.

mod channel;
mod client;
mod inspection;
mod map;
mod roles;
mod sign;

mod proto {
    pub(super) use mkit_rpc::hooks as v1;
}

pub use channel::{ChannelError, HookChannel, HookRequest, HookResponse};
pub use client::{DEFAULT_TIMEOUT, HookClient, HookConfigError, MAX_RESPONSE_BYTES};
pub use inspection::{InspectVerdict, RemoteInspector};
pub use mkit_rpc::hooks::{DEFAULT_VALIDITY, DOMAIN, HookSigner, MAX_VALIDITY, SignerError};
pub use mkit_rpc::hooks::{
    HookVerifier, KeyListError, MAX_CLOCK_LEAD_MS, Verified, VerifierKey, VerifyError,
};
pub use roles::{RemoteAdmission, RemoteAuthorizer, RemoteOutcomes, RemotePurge};
pub use sign::{NonceSource, OsNonces};

#[cfg(test)]
pub(crate) mod tests;