Skip to main content

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}