datumesh_http/domain.rs
1//! Domain validation (since the namespace-validation step): a namespace host is **valid**
2//! when `https://<host>/.well-known/datumesh.json` fetches and passes the key-document rules
3//! (SPEC 9.2, 9.3: [`datumesh_core::key_document_from_response`], declarations included).
4//!
5//! [`Validator::validate`] checks one host and records the outcome in the store:
6//!
7//! * **valid**: the document is recorded with `put_namespace` (so `validated_at` moves
8//! forward and a rotation, SPEC 9.5, replaces the stored key document through the store's
9//! normal path), then [`Store::record_namespace_success`] resets the failure count and
10//! reinstates a suspended namespace;
11//! * **invalid** (no answer, not 200, not a key document for the host, a declaration that
12//! fails): [`Store::record_namespace_failure`] adds one to the consecutive failures, and
13//! the [`SUSPEND_AFTER`]th in a row suspends the namespace (`suspended_at`).
14//!
15//! A suspended namespace refuses **new writes** under it with the store's
16//! [`datumesh_store::Error::NamespaceSuspended`]: a receipt signed by the host
17//! (`put_receipt`), a version of such a receipt (`put_version`), a name under the host
18//! (`bind_name`, so `define` and `publish-stored` too, and the import of a foreign host's
19//! bindings and cells). Reads, verification, the key document the mesh serves and the
20//! receipts already stored are not affected; a cross-mesh import that the store refuses
21//! reaches a request as `E_INPUT_UNAVAILABLE` (the closest code that exists), with the
22//! suspension in its detail.
23//!
24//! The mesh's **own** namespaces ([`Config::namespaces`](crate::Config::namespaces)) are never
25//! validated here, so never suspended: a failed fetch of the mesh's own site must not stop the
26//! mesh publishing. Hosts with no namespace in the store have nothing to suspend; their
27//! failed validation is reported and nothing is recorded.
28//!
29//! `datumesh-mesh validate <host>` and `validate --all` run this from the command line; the
30//! weekly re-check is a cron entry running `validate --all` (`deploy/install_cron.sh`).
31
32use datumesh_core::json::{self, Value};
33use datumesh_core::{key_document_from_response, ErrorCode};
34use datumesh_store::{Error as StoreError, Store};
35
36use crate::client::Client;
37
38/// The largest key document read (SPEC 9.3's suggested bound).
39const MAX_DOC: u64 = 256 << 10;
40
41/// The consecutive failed validations after which a namespace is suspended.
42pub const SUSPEND_AFTER: u32 = 2;
43
44/// How one host's validation came out.
45#[non_exhaustive]
46#[derive(Clone, Debug, PartialEq, Eq)]
47pub enum Outcome {
48 /// The document fetched and passed the rules.
49 Valid,
50 /// It did not: the code of SPEC 9.3 (`E_KEY_UNAVAILABLE`, `E_KEY_DOC`) and why.
51 Invalid {
52 /// `E_KEY_UNAVAILABLE` (no answer, or a status other than 200) or `E_KEY_DOC`.
53 code: ErrorCode,
54 /// Why.
55 detail: String,
56 },
57 /// Not validated: a namespace of this mesh itself.
58 Skipped,
59}
60
61/// The result of validating one host, with what the store now records.
62#[non_exhaustive]
63#[derive(Clone, Debug, PartialEq, Eq)]
64pub struct Validation {
65 /// The host.
66 pub host: String,
67 /// How it came out.
68 pub outcome: Outcome,
69 /// The consecutive failures now recorded (zero after a success; zero for a host with no
70 /// namespace in the store, whose failure is not recorded).
71 pub failures: u32,
72 /// Whether the namespace is suspended now.
73 pub suspended: bool,
74 /// Whether this validation suspended it.
75 pub suspended_now: bool,
76 /// Whether this validation reinstated it.
77 pub reinstated: bool,
78 /// Whether the document differs from the one stored before (a rotation or another
79 /// change), and replaced it.
80 pub rotated: bool,
81}
82
83impl Validation {
84 fn new(host: &str, outcome: Outcome) -> Validation {
85 Validation {
86 host: host.to_string(),
87 outcome,
88 failures: 0,
89 suspended: false,
90 suspended_now: false,
91 reinstated: false,
92 rotated: false,
93 }
94 }
95
96 /// Whether the outcome is [`Outcome::Invalid`].
97 pub fn failed(&self) -> bool {
98 matches!(self.outcome, Outcome::Invalid { .. })
99 }
100
101 /// One canonical JSON object (the `validate` command prints one per host): `host`,
102 /// `outcome` (`valid`, `invalid`, `skipped`), `failures`, `suspended`, `suspended_now`,
103 /// `reinstated`, `rotated`, and for an invalid host `code` and `detail`.
104 pub fn to_json(&self) -> Vec<u8> {
105 let b = |v: bool| Value::Bool(v);
106 let mut m = vec![
107 ("failures".to_string(), json::parse(self.failures.to_string().as_bytes()).unwrap_or(Value::Null)),
108 ("host".to_string(), Value::String(self.host.clone())),
109 ("reinstated".to_string(), b(self.reinstated)),
110 ("rotated".to_string(), b(self.rotated)),
111 ("suspended".to_string(), b(self.suspended)),
112 ("suspended_now".to_string(), b(self.suspended_now)),
113 ];
114 let outcome = match &self.outcome {
115 Outcome::Valid => "valid",
116 Outcome::Skipped => "skipped",
117 Outcome::Invalid { code, detail } => {
118 m.push(("code".to_string(), Value::String(code.as_str().to_string())));
119 m.push(("detail".to_string(), Value::String(detail.clone())));
120 "invalid"
121 }
122 };
123 m.push(("outcome".to_string(), Value::String(outcome.to_string())));
124 Value::Object(m).to_jcs()
125 }
126}
127
128/// Validates namespace hosts against their own sites and records the outcome in a store.
129#[derive(Debug)]
130pub struct Validator {
131 client: Client,
132 own: Vec<String>,
133}
134
135impl Validator {
136 /// A validator fetching with `client` (its peers map `https://<host>` to where a host
137 /// answers; its allowed-host list, if any, applies), skipping `own`, the hosts this mesh
138 /// owns.
139 pub fn new(client: Client, own: Vec<String>) -> Validator {
140 Validator { client, own }
141 }
142
143 /// Fetches `host`'s key document and checks it.
144 fn fetch(&self, host: &str) -> Result<Vec<u8>, (ErrorCode, String)> {
145 let url = format!("https://{host}/.well-known/datumesh.json");
146 let (status, body) = self.client.get(&url, MAX_DOC).map_err(|e| (ErrorCode::KeyUnavailable, e))?;
147 key_document_from_response(host, status, if status == 200 { Some(&body) } else { None })
148 .map_err(|e| (e.code(), e.to_string()))?;
149 Ok(body)
150 }
151
152 /// Validates `host` at `now` (an instant, not earlier than what the store recorded for
153 /// it) and records the outcome as the module documentation says.
154 ///
155 /// Errors are the store's: a host that is not a DNS name, an instant earlier than the
156 /// latest check, a database failure. A failed validation is a [`Validation`], not an error.
157 pub fn validate(&self, store: &dyn Store, host: &str, now: &str) -> Result<Validation, StoreError> {
158 datumesh_core::lexical::check_dns_name(host, "host")?;
159 if self.own.iter().any(|h| h == host) {
160 return Ok(Validation::new(host, Outcome::Skipped));
161 }
162 let before = store.namespace(host)?;
163 match self.fetch(host) {
164 Ok(body) => {
165 let canonical = json::parse(&body)?.to_jcs();
166 let rotated = before.as_ref().is_some_and(|n| n.keydoc != canonical);
167 store.put_namespace(host, &body, now)?;
168 store.record_namespace_success(host, now)?;
169 let mut v = Validation::new(host, Outcome::Valid);
170 v.rotated = rotated;
171 v.reinstated = before.as_ref().is_some_and(|n| n.suspended_at.is_some());
172 Ok(v)
173 }
174 Err((code, detail)) => {
175 let mut v = Validation::new(host, Outcome::Invalid { code, detail });
176 if let Some(after) = store.record_namespace_failure(host, now, SUSPEND_AFTER)? {
177 v.failures = after.consecutive_failures;
178 v.suspended = after.suspended_at.is_some();
179 v.suspended_now = v.suspended && before.as_ref().is_some_and(|n| n.suspended_at.is_none());
180 }
181 Ok(v)
182 }
183 }
184 }
185
186 /// Validates every namespace in the store, by host, at `now`: [`validate`](Validator::validate)
187 /// for each (the mesh's own are [`Outcome::Skipped`]).
188 pub fn validate_all(&self, store: &dyn Store, now: &str) -> Result<Vec<Validation>, StoreError> {
189 store.namespaces()?.iter().map(|n| self.validate(store, &n.host, now)).collect()
190 }
191}