Skip to main content

instruction_md/
policy.rs

1//! The integrations policy in the front matter (proposal S34): which of a document's MCP servers, skills and agents
2//! may be used, and which of a server's tools. Two layers, one shape: `host-integrations`, which only the host that
3//! serves the document writes (a workspace's policy, put in at serve time), and `integrations`, which the author may
4//! write to narrow it. The effective policy ([`Policy`], [`crate::Reading::policy`]) is both at once: a target is
5//! allowed only where every layer that lists targets lists it, and a tool is blocked where any layer blocks it, so an
6//! author can narrow the host's policy and never widen it. A port of the reference's `policy.ts` (packages/spec).
7//!
8//! The host's block sits outside the signed bytes: a host writes it as its own lines right after the front matter's
9//! opening `---` (or as a front matter of its own, when the source has none, [`with_host_block`]), and
10//! [`authored_candidates`] takes them out again, so an author signature still verifies over the served text.
11//!
12//! ```
13//! use instruction_md::{read, ReadOptions, check_reading};
14//!
15//! let served = "---\nhost-integrations:\n  servers:\n    \"https://cal.example.org/mcp\": {\"blocked\": [\"events.delete\"]}\n---\n\n\
16//!               ::mcp{id=cal src=\"https://cal.example.org/mcp\" tools=\"events.list,events.delete\"}\n";
17//! let r = read(served, &ReadOptions::default());
18//! let policy = r.policy.as_ref().unwrap();
19//! assert!(policy.tool_blocked(&["https://cal.example.org/mcp/"], "events.delete"));
20//! assert!(!policy.tool_blocked(&["https://cal.example.org/mcp"], "events.list"));
21//! let d = &check_reading(&r)[0];
22//! assert_eq!((d.code, d.message.as_str()), ("tool-blocked", "events.delete: this tool is blocked in your workspace"));
23//! ```
24
25use std::collections::{BTreeMap, HashMap};
26
27use serde_json::{Map, Value};
28
29use crate::js::{js_space, js_trim, js_value, utf16_cmp};
30use crate::types::{Attrs, Node, Object};
31
32/// The front matter key only the host that serves a document writes.
33pub const HOST_POLICY_KEY: &str = "host-integrations";
34/// The front matter key an author may write to narrow the host's policy.
35pub const AUTHOR_POLICY_KEY: &str = "integrations";
36
37/// What a server's tools not named in a layer are: `allowed` (the default) or `blocked` (new tools blocked until
38/// reviewed).
39#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
40pub enum ToolDefault {
41    #[default]
42    Allowed,
43    Blocked,
44}
45
46impl ToolDefault {
47    pub fn as_str(self) -> &'static str {
48        match self {
49            ToolDefault::Allowed => "allowed",
50            ToolDefault::Blocked => "blocked",
51        }
52    }
53}
54
55/// One server's tools in a layer, as written (lists trimmed, deduplicated and sorted): those blocked, those allowed,
56/// and what any other tool is (`None`: allowed).
57#[derive(Clone, Debug, Default, PartialEq, Eq)]
58pub struct ServerTools {
59    pub allowed: Option<Vec<String>>,
60    pub blocked: Option<Vec<String>>,
61    pub default: Option<ToolDefault>,
62}
63
64/// One layer (a `host-integrations` or `integrations` value, [`layer_of`]): `allowed`, when present, is every target
65/// its connected objects may use (an empty list allows none); `servers`, by a server's normalized target, its tools.
66/// Also what a host passes as [`crate::ReadOptions::host`].
67#[derive(Clone, Debug, Default, PartialEq, Eq)]
68pub struct PolicyLayer {
69    pub allowed: Option<Vec<String>>,
70    pub servers: Option<BTreeMap<String, ServerTools>>,
71}
72
73/// A server's tools in the effective policy: `blocked`, the `default` for any other tool and, when the default is
74/// `blocked`, the tools `allowed`.
75#[derive(Clone, Debug, PartialEq, Eq)]
76pub struct ServerPolicy {
77    pub blocked: Vec<String>,
78    pub default: ToolDefault,
79    pub allowed: Option<Vec<String>>,
80}
81
82/// Which layers an effective policy was made from.
83#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
84pub struct PolicyFrom {
85    pub host: bool,
86    pub author: bool,
87}
88
89/// The effective policy ([`merge_policy`]): the layers merged, targets normalized ([`normalize_target`]), lists
90/// sorted. `allowed` is `None` when no layer restricts the targets.
91#[derive(Clone, Debug, PartialEq, Eq)]
92pub struct Policy {
93    pub allowed: Option<Vec<String>>,
94    pub servers: BTreeMap<String, ServerPolicy>,
95    pub from: PolicyFrom,
96}
97
98impl Policy {
99    /// Whether a tool is blocked on a server known by these targets: blocked on any of them.
100    pub fn tool_blocked<S: AsRef<str>>(&self, targets: &[S], tool: &str) -> bool {
101        targets.iter().any(|t| {
102            self.servers.get(&normalize_target(t.as_ref())).is_some_and(|s| {
103                s.blocked.iter().any(|x| x == tool)
104                    || (s.default == ToolDefault::Blocked && !s.allowed.as_deref().unwrap_or_default().iter().any(|x| x == tool))
105            })
106        })
107    }
108
109    /// Whether a connected object reaching these targets ([`remote_targets`]) is allowed: every one of them listed,
110    /// when the policy lists any. An object with no remote target is its document's own, and always allowed.
111    pub fn targets_allowed<S: AsRef<str>>(&self, targets: &[S]) -> bool {
112        let Some(allowed) = &self.allowed else { return true };
113        targets.iter().all(|t| allowed.contains(&normalize_target(t.as_ref())))
114    }
115
116    /// The policy as JSON, as the reference's `ReadResult.policy` is (the vectors' `policy`).
117    pub fn to_json(&self) -> Value {
118        let list = |xs: &[String]| Value::Array(xs.iter().cloned().map(Value::String).collect());
119        let mut m = Map::new();
120        if let Some(a) = &self.allowed {
121            m.insert("allowed".into(), list(a));
122        }
123        let mut servers = Map::new();
124        for (t, s) in &self.servers {
125            let mut e = Map::new();
126            e.insert("blocked".into(), list(&s.blocked));
127            e.insert("default".into(), s.default.as_str().into());
128            if let Some(a) = &s.allowed {
129                e.insert("allowed".into(), list(a));
130            }
131            servers.insert(t.clone(), Value::Object(e));
132        }
133        m.insert("servers".into(), Value::Object(servers));
134        let mut from = Map::new();
135        from.insert("host".into(), self.from.host.into());
136        from.insert("author".into(), self.from.author.into());
137        m.insert("from".into(), Value::Object(from));
138        Value::Object(m)
139    }
140}
141
142/// What is wrong with a layer as written: its key, and the message of the `invalid-metadata` error the reader gives.
143#[derive(Clone, Debug, PartialEq, Eq)]
144pub struct LayerProblem {
145    pub key: String,
146    pub message: String,
147}
148
149/// Strings deduplicated and sorted as ECMAScript sorts them (by UTF-16 code units).
150fn sorted(xs: impl IntoIterator<Item = String>) -> Vec<String> {
151    let mut v: Vec<String> = xs.into_iter().collect();
152    v.sort_by(|a, b| utf16_cmp(a, b));
153    v.dedup();
154    v
155}
156
157/// A list of non-blank strings, trimmed; `None` for anything else.
158fn names(v: Option<&Value>) -> Option<Vec<String>> {
159    let Some(Value::Array(a)) = v else { return None };
160    a.iter().map(|x| x.as_str().map(js_trim).filter(|s| !s.is_empty()).map(str::to_string)).collect()
161}
162
163/// Is a key an array index (a canonical integer below 2^32 - 1), which ECMAScript lists first, in numeric order?
164fn array_index(k: &str) -> Option<u32> {
165    let n: u32 = k.parse().ok()?;
166    (n != u32::MAX && n.to_string() == k).then_some(n)
167}
168
169/// A mapping's keys in ECMAScript's order (`Object.keys`): array indexes ascending, then the rest as written.
170fn js_keys(written: Vec<String>) -> Vec<String> {
171    let (mut idx, rest): (Vec<String>, Vec<String>) = written.into_iter().partition(|k| array_index(k).is_some());
172    idx.sort_by_key(|k| array_index(k));
173    idx.extend(rest);
174    idx
175}
176
177/// How a mapping at a path (its keys from the layer's own value) lists its keys as written.
178type Order<'a> = &'a dyn Fn(&[&str], &Object) -> Vec<String>;
179
180/// A layer from its front matter value, normalized, with what is wrong with it (each problem an `invalid-metadata`
181/// error). Keys are taken in the order a `serde_json` mapping keeps them; the reader takes them in the order written.
182pub fn layer_of(value: &Value, key: &str) -> (Option<PolicyLayer>, Vec<LayerProblem>) {
183    layer_in_order(value, key, &|_, m| m.keys().cloned().collect())
184}
185
186pub(crate) fn layer_in_order(value: &Value, key: &str, order: Order<'_>) -> (Option<PolicyLayer>, Vec<LayerProblem>) {
187    let mut problems = Vec::new();
188    let mut bad =
189        |message: String| problems.push(LayerProblem { key: key.into(), message: format!("the front matter's {key}: {message}") });
190    let Value::Object(value) = value else {
191        bad("is a mapping of allowed and servers".into());
192        return (None, problems);
193    };
194    let mut layer = PolicyLayer::default();
195    for k in js_keys(order(&[], value)) {
196        if k != "allowed" && k != "servers" {
197            bad(format!("\"{k}\" is not one of its keys (allowed, servers)"));
198        }
199    }
200    if value.contains_key("allowed") {
201        match names(value.get("allowed")) {
202            None => bad("allowed is a list of targets (addresses or registry names)".into()),
203            Some(xs) => layer.allowed = Some(sorted(xs.iter().map(|x| normalize_target(x)))),
204        }
205    }
206    if let Some(servers) = value.get("servers") {
207        match servers {
208            Value::Object(servers) => {
209                let mut out: BTreeMap<String, ServerTools> = BTreeMap::new();
210                for target in js_keys(order(&["servers"], servers)) {
211                    let Some(Value::Object(entry)) = servers.get(&target) else {
212                        bad(format!("servers.\"{target}\" is a mapping of allowed, blocked and default"));
213                        continue;
214                    };
215                    let mut t = ServerTools::default();
216                    for k in js_keys(order(&["servers", &target], entry)) {
217                        if !["allowed", "blocked", "default"].contains(&k.as_str()) {
218                            bad(format!("servers.\"{target}\": \"{k}\" is not one of its keys (allowed, blocked, default)"));
219                        }
220                    }
221                    for k in ["allowed", "blocked"] {
222                        if entry.contains_key(k) {
223                            match names(entry.get(k)) {
224                                None => bad(format!("servers.\"{target}\".{k} is a list of tool names")),
225                                Some(xs) => {
226                                    let xs = Some(sorted(xs));
227                                    if k == "allowed" { t.allowed = xs } else { t.blocked = xs }
228                                }
229                            }
230                        }
231                    }
232                    if let Some(d) = entry.get("default") {
233                        match d.as_str() {
234                            Some("allowed") => t.default = Some(ToolDefault::Allowed),
235                            Some("blocked") => t.default = Some(ToolDefault::Blocked),
236                            _ => bad(format!("servers.\"{target}\".default is allowed or blocked")),
237                        }
238                    }
239                    // (two spellings of one target are one server: what either blocks is blocked)
240                    let n = normalize_target(&target);
241                    let merged = match out.remove(&n) {
242                        Some(was) => merge_tools(&[&was, &t]),
243                        None => t,
244                    };
245                    out.insert(n, merged);
246                }
247                layer.servers = Some(out);
248            }
249            _ => bad("servers is a mapping of a server's target to its tools".into()),
250        }
251    }
252    (Some(layer), problems)
253}
254
255/// A server's tools in several layers at once: blocked where any blocks; blocked by default where any is; then
256/// allowed only where every layer that blocks by default allows.
257fn merge_tools(ts: &[&ServerTools]) -> ServerTools {
258    let blocked = sorted(ts.iter().flat_map(|t| t.blocked.iter().flatten().cloned()));
259    let closed: Vec<&&ServerTools> = ts.iter().filter(|t| t.default == Some(ToolDefault::Blocked)).collect();
260    let Some(first) = closed.first() else {
261        return ServerTools { allowed: None, blocked: Some(blocked), default: Some(ToolDefault::Allowed) };
262    };
263    let mut allowed: Vec<String> = first.allowed.clone().unwrap_or_default();
264    for t in &closed[1..] {
265        let theirs = t.allowed.as_deref().unwrap_or_default();
266        allowed.retain(|x| theirs.contains(x));
267    }
268    let allowed = sorted(allowed.into_iter().filter(|x| !blocked.contains(x)));
269    ServerTools { allowed: Some(allowed), blocked: Some(blocked), default: Some(ToolDefault::Blocked) }
270}
271
272/// The layers merged (the host's, then the author's): `None` when neither is given.
273pub fn merge_policy(host: Option<&PolicyLayer>, author: Option<&PolicyLayer>) -> Option<Policy> {
274    let layers: Vec<&PolicyLayer> = [host, author].into_iter().flatten().collect();
275    if layers.is_empty() {
276        return None;
277    }
278    let mut allowed: Option<Vec<String>> = None;
279    for l in &layers {
280        let Some(theirs) = &l.allowed else { continue };
281        allowed = Some(match allowed {
282            None => theirs.clone(),
283            Some(mut a) => {
284                a.retain(|t| theirs.contains(t));
285                a
286            }
287        });
288    }
289    let targets = sorted(layers.iter().flat_map(|l| l.servers.iter().flat_map(|s| s.keys().cloned())));
290    let mut servers = BTreeMap::new();
291    for target in targets {
292        let ts: Vec<&ServerTools> = layers.iter().filter_map(|l| l.servers.as_ref()?.get(&target)).collect();
293        let m = merge_tools(&ts);
294        let default = m.default.unwrap_or_default();
295        let allowed = (default == ToolDefault::Blocked).then(|| m.allowed.unwrap_or_default());
296        servers.insert(target, ServerPolicy { blocked: m.blocked.unwrap_or_default(), default, allowed });
297    }
298    Some(Policy { allowed: allowed.map(sorted), servers, from: PolicyFrom { host: host.is_some(), author: author.is_some() } })
299}
300
301// ---- targets ----
302
303/// The kinds an integration stands for: MCP servers, skills, A2A agents, and APIs (a `service`, proposal S32).
304pub const INTEGRATED_KINDS: &[&str] = &["mcp", "skill", "agent", "service"];
305
306/// A target as a policy compares it (RFC-0038 ยง3): an http(s) URL with its scheme and host lower-cased and its
307/// default port, credentials, fragment and trailing slash dropped (its path keeps its case), parsed as the WHATWG URL
308/// standard parses it; any other target, a registry's server name, trimmed and lower-cased.
309///
310/// One difference from the reference's `new URL`: a host with non-ASCII characters is lower-cased, not converted to
311/// its IDNA (punycode) form.
312///
313/// ```
314/// use instruction_md::normalize_target;
315///
316/// assert_eq!(normalize_target(" HTTPS://Cal.Example.org:443/MCP/#x"), "https://cal.example.org/MCP");
317/// assert_eq!(normalize_target("IO.Example/Weather"), "io.example/weather");
318/// ```
319pub fn normalize_target(target: &str) -> String {
320    let t = js_trim(target);
321    if is_http(t)
322        && let Some(u) = url::normalize(t)
323    {
324        return u;
325    }
326    t.to_lowercase()
327}
328
329/// Does it start with `http://` or `https://`, in any case?
330fn is_http(s: &str) -> bool {
331    let b = s.as_bytes();
332    let starts = |p: &[u8]| b.len() >= p.len() && b[..p.len()].eq_ignore_ascii_case(p);
333    starts(b"http://") || starts(b"https://")
334}
335
336/// The targets by which a connected object reaches outside its document: an http(s) `src` or `endpoint`, a
337/// `registry` or `server` name, normalized. Never a relative path (a resource of the document's own bundle) or a
338/// `#id`; nothing for a kind that is not an integration's ([`INTEGRATED_KINDS`]).
339pub fn remote_targets(kind: &str, attrs: &Attrs) -> Vec<String> {
340    if !INTEGRATED_KINDS.contains(&kind) {
341        return Vec::new();
342    }
343    let mut out = Vec::new();
344    for key in ["src", "endpoint", "registry", "server"] {
345        let Some(Value::String(v)) = attrs.get(key) else { continue };
346        let t = js_trim(v);
347        if t.is_empty() || t.starts_with('#') {
348            continue;
349        }
350        let relative = t.starts_with('/') || t.starts_with("./") || t.starts_with("../");
351        if is_http(t) || ((key == "registry" || key == "server") && !relative) {
352            out.push(normalize_target(v));
353        }
354    }
355    out
356}
357
358/// A list attribute's names: a list, or a string of names apart by commas or whitespace.
359fn names_of(v: Option<&Value>) -> Vec<String> {
360    let raw: Vec<String> = match v {
361        Some(Value::Array(a)) => a.iter().map(|x| js_value(Some(x))).collect(),
362        Some(Value::String(s)) => s.split(|c: char| c == ',' || js_space(c)).map(str::to_string).collect(),
363        _ => Vec::new(),
364    };
365    raw.iter().map(|x| js_trim(x)).filter(|x| !x.is_empty()).map(str::to_string).collect()
366}
367
368/// The tools a connected object names for use, and the targets of the server they are on.
369#[derive(Clone, Debug, Default, PartialEq, Eq)]
370pub struct NamedTools {
371    pub targets: Vec<String>,
372    pub tools: Vec<String>,
373}
374
375/// The tools a connected object names for use, and its server's targets: an `mcp`'s `tools` and `allow` (its `deny`
376/// names what not to use), a `tool`'s `name` on its `server` โ€” the document's MCP server (or service) it references
377/// (`#id`, looked up in `body`), or a server named outright. `None` for any other object.
378pub fn named_tools(n: &Node, body: &[Node]) -> Option<NamedTools> {
379    let by_id = objects_by_id(body);
380    named_in(n, &by_id)
381}
382
383fn named_in(n: &Node, by_id: &HashMap<&str, &Node>) -> Option<NamedTools> {
384    if n.kind == "mcp" {
385        let mut tools: Vec<String> = Vec::new();
386        for t in names_of(n.attrs.get("tools")).into_iter().chain(names_of(n.attrs.get("allow"))) {
387            if !tools.contains(&t) {
388                tools.push(t);
389            }
390        }
391        return Some(NamedTools { targets: remote_targets("mcp", &n.attrs), tools });
392    }
393    let name = match n.attrs.get("name") {
394        Some(Value::String(s)) if n.kind == "tool" && !js_trim(s).is_empty() => js_trim(s).to_string(),
395        _ => return None,
396    };
397    let server = n.attrs.get("server").and_then(Value::as_str).map(js_trim).unwrap_or("");
398    // (the server a tool is on: an MCP server, or a service โ€” an API's operation, S32)
399    let targets = if let Some(id) = server.strip_prefix('#') {
400        match by_id.get(id) {
401            Some(on) if on.kind == "mcp" || on.kind == "service" => remote_targets(&on.kind, &on.attrs),
402            Some(_) => Vec::new(),
403            None => remote_targets("mcp", &server_attrs(server)),
404        }
405    } else if !server.is_empty() {
406        remote_targets("mcp", &server_attrs(server))
407    } else {
408        Vec::new()
409    };
410    Some(NamedTools { targets, tools: vec![name] })
411}
412
413fn server_attrs(server: &str) -> Attrs {
414    let mut a = Attrs::new();
415    a.insert("server".into(), server.into());
416    a
417}
418
419/// The document's directives by their ids (the first of an id wins), for a `tool`'s `server=#id`.
420fn objects_by_id(body: &[Node]) -> HashMap<&str, &Node> {
421    let mut all = HashMap::new();
422    crate::objects::walk(body, &mut |n, _| {
423        if let Some(Value::String(id)) = n.attrs.get("id") {
424            all.entry(id.as_str()).or_insert(n);
425        }
426        true
427    });
428    all
429}
430
431// ---- the reader's checks ----
432
433/// The reader's S34 checks: each layer's shape (`invalid-metadata` errors), then each connected object against the
434/// effective policy โ€” `tool-blocked` and `integration-not-allowed` warnings. Returns the effective policy.
435pub(crate) fn check(
436    front: &Object,
437    order: &crate::types::KeyOrder,
438    at: u32,
439    host_option: Option<&PolicyLayer>,
440    body: &[Node],
441    out: &mut Vec<crate::types::Diagnostic>,
442) -> Option<Policy> {
443    use crate::types::{Diagnostic, Severity};
444    let mut layer = |key: &str| -> Option<PolicyLayer> {
445        let v = front.get(key)?;
446        let written = |path: &[&str], m: &Object| order.keys(&crate::types::KeyOrder::path(key, path), m);
447        let (l, problems) = layer_in_order(v, key, &written);
448        for p in problems {
449            out.push(Diagnostic::new("invalid-metadata", Severity::Error, p.message, at));
450        }
451        l
452    };
453    let from_matter = layer(HOST_POLICY_KEY);
454    let author = layer(AUTHOR_POLICY_KEY);
455    let host = from_matter.as_ref().or(host_option);
456    let policy = merge_policy(host, author.as_ref())?;
457    let host_only = merge_policy(host, None);
458    let by_id = objects_by_id(body);
459    crate::objects::walk(body, &mut |n, _| {
460        let line = n.range.map_or(0, |r| r.start);
461        if let Some(named) = named_in(n, &by_id) {
462            for tool in &named.tools {
463                if !policy.tool_blocked(&named.targets, tool) {
464                    continue;
465                }
466                let by_host = host_only.as_ref().is_some_and(|p| p.tool_blocked(&named.targets, tool));
467                let whose = if by_host { "in your workspace" } else { "by this instruction's integrations" };
468                let mut d = Diagnostic::new("tool-blocked", Severity::Warning, format!("{tool}: this tool is blocked {whose}"), line);
469                d.target = tool.clone();
470                d.remedy = if by_host {
471                    "Use another tool, or ask an admin to allow it in Integrations"
472                } else {
473                    "Use another tool, or allow it in the front matter's integrations"
474                }
475                .into();
476                out.push(d);
477            }
478        }
479        let targets = remote_targets(&n.kind, &n.attrs);
480        if !policy.targets_allowed(&targets) {
481            let name = match (n.attrs.get("title"), n.attrs.get("id")) {
482                (Some(Value::String(t)), _) => t.clone(),
483                (_, Some(Value::String(id))) => format!("#{id}"),
484                _ => n.kind.clone(),
485            };
486            let noun = match n.kind.as_str() {
487                "mcp" => "MCP server",
488                k => k,
489            };
490            let by_host = host_only.as_ref().is_some_and(|p| !p.targets_allowed(&targets));
491            let whose = if by_host { "your workspace's" } else { "this instruction's" };
492            let mut d = Diagnostic::new(
493                "integration-not-allowed",
494                Severity::Warning,
495                format!("{name}: this {noun} is not one of {whose} integrations, so it is not used"),
496                line,
497            );
498            d.target = targets[0].clone();
499            d.remedy = if by_host {
500                "Use one of your integrations, or ask an admin to add it"
501            } else {
502                "Use one of the integrations the front matter allows"
503            }
504            .into();
505            out.push(d);
506        }
507        true
508    });
509    Some(policy)
510}
511
512// ---- the host's block in the served text ----
513
514fn json_string(s: &str) -> String {
515    serde_json::to_string(s).unwrap_or_default()
516}
517
518fn flow_list(xs: &[String]) -> String {
519    format!("[{}]", xs.iter().map(|x| json_string(x)).collect::<Vec<_>>().join(", "))
520}
521
522/// A host's layer as the lines it serves: `host-integrations:`, then each key on a line of its own indented two
523/// spaces (a server's tools as a JSON object), each line ending in LF; `None` when the layer says nothing.
524pub fn host_block(layer: Option<&PolicyLayer>) -> Option<String> {
525    let layer = layer?;
526    if layer.allowed.is_none() && layer.servers.is_none() {
527        return None;
528    }
529    let mut out = format!("{HOST_POLICY_KEY}:\n");
530    if let Some(a) = &layer.allowed {
531        out += &format!("  allowed: {}\n", flow_list(&sorted(a.iter().cloned())));
532    }
533    let servers = layer.servers.as_ref().map(|s| sorted(s.keys().cloned())).unwrap_or_default();
534    if !servers.is_empty() {
535        out += "  servers:\n";
536        for s in servers {
537            let t = &layer.servers.as_ref().expect("servers")[&s];
538            let mut parts = Vec::new();
539            if let Some(a) = &t.allowed {
540                parts.push(format!("\"allowed\": {}", flow_list(&sorted(a.iter().cloned()))));
541            }
542            if let Some(b) = &t.blocked {
543                parts.push(format!("\"blocked\": {}", flow_list(&sorted(b.iter().cloned()))));
544            }
545            if let Some(d) = t.default {
546                parts.push(format!("\"default\": \"{}\"", d.as_str()));
547            }
548            out += &format!("    {}: {{{}}}\n", json_string(&s), parts.join(", "));
549        }
550    }
551    Some(out)
552}
553
554/// The text as a host serves it with its block: right after the front matter's opening line, or, with no front
555/// matter, in one of its own before the text (after a byte-order mark, which stays first).
556pub fn with_host_block(text: &str, block: Option<&str>) -> String {
557    let Some(block) = block else { return text.to_string() };
558    let bom = if text.starts_with('\u{feff}') { "\u{feff}" } else { "" };
559    let rest = &text[bom.len()..];
560    match fence(rest.as_bytes()) {
561        Some(n) => format!("{bom}{}{block}{}", &rest[..n], &rest[n..]),
562        None => format!("{bom}---\n{block}---\n{rest}"),
563    }
564}
565
566const BOM: &[u8] = "\u{feff}".as_bytes();
567
568/// The length of a `---` line with its line ending at the start of `b`, if it is one.
569fn fence(b: &[u8]) -> Option<usize> {
570    let rest = b.strip_prefix(b"---")?;
571    match rest {
572        [b'\r', b'\n', ..] => Some(5),
573        [b'\r', ..] | [b'\n', ..] => Some(4),
574        _ => None,
575    }
576}
577
578/// The length of a line ending in LF with no CR in it, at the start of `b`.
579fn lf_line(b: &[u8]) -> Option<usize> {
580    let end = b.iter().position(|&c| c == b'\n' || c == b'\r')?;
581    (b[end] == b'\n').then_some(end + 1)
582}
583
584/// What an author may have signed, given a served text: the text itself and, when its front matter opens with the
585/// host's block, the text without it โ€” and without the front matter left empty, for a host that made one.
586pub fn authored_candidates(text: &[u8]) -> Vec<Vec<u8>> {
587    let bom = if text.starts_with(BOM) { BOM.len() } else { 0 };
588    let rest = &text[bom..];
589    let Some(open) = fence(rest) else { return vec![text.to_vec()] };
590    let after = &rest[open..];
591    let key = format!("{HOST_POLICY_KEY}:");
592    if !after.starts_with(key.as_bytes()) {
593        return vec![text.to_vec()];
594    }
595    let Some(mut n) = lf_line(after) else { return vec![text.to_vec()] };
596    while matches!(after.get(n), Some(b' ' | b'\t')) {
597        match lf_line(&after[n..]) {
598            Some(k) => n += k,
599            None => break,
600        }
601    }
602    let mut stripped = text[..bom + open].to_vec();
603    stripped.extend_from_slice(&after[n..]);
604    let mut out = vec![text.to_vec(), stripped.clone()];
605    if let Some(a) = fence(&stripped[bom..])
606        && let Some(b) = fence(&stripped[bom + a..])
607    {
608        let mut empty = text[..bom].to_vec();
609        empty.extend_from_slice(&stripped[bom + a + b..]);
610        out.push(empty);
611    }
612    out
613}
614
615/// The WHATWG URL parser's answer for an http(s) URL, as `normalize_target` serializes it: what ECMAScript's
616/// `new URL` gives (`protocol//host` + the path without trailing slashes + `search`), or `None` where it throws.
617mod url {
618    const HEX: &[u8; 16] = b"0123456789ABCDEF";
619
620    fn encode(out: &mut String, s: &str, set: impl Fn(u8) -> bool) {
621        for &b in s.as_bytes() {
622            if !(0x20..=0x7e).contains(&b) || set(b) {
623                out.push('%');
624                out.push(HEX[(b >> 4) as usize] as char);
625                out.push(HEX[(b & 15) as usize] as char);
626            } else {
627                out.push(b as char);
628            }
629        }
630    }
631
632    fn path_set(b: u8) -> bool {
633        matches!(b, b' ' | b'"' | b'#' | b'<' | b'>' | b'?' | b'`' | b'{' | b'}')
634    }
635
636    fn query_set(b: u8) -> bool {
637        matches!(b, b' ' | b'"' | b'#' | b'<' | b'>' | b'\'')
638    }
639
640    fn percent_decode(s: &str) -> Vec<u8> {
641        let b = s.as_bytes();
642        let mut out = Vec::with_capacity(b.len());
643        let mut i = 0;
644        while i < b.len() {
645            if b[i] == b'%'
646                && i + 2 < b.len()
647                && let (Some(h), Some(l)) = ((b[i + 1] as char).to_digit(16), (b[i + 2] as char).to_digit(16))
648            {
649                out.push((h * 16 + l) as u8);
650                i += 3;
651                continue;
652            }
653            out.push(b[i]);
654            i += 1;
655        }
656        out
657    }
658
659    pub(super) fn normalize(input: &str) -> Option<String> {
660        // leading and trailing C0 controls and spaces go, and every tab and newline
661        let s: String = input.trim_matches(|c: char| c <= ' ').chars().filter(|c| !matches!(c, '\t' | '\n' | '\r')).collect();
662        let colon = s.find(':')?;
663        let scheme = s[..colon].to_ascii_lowercase();
664        let default_port = match scheme.as_str() {
665            "http" => "80",
666            "https" => "443",
667            _ => return None,
668        };
669        let rest = s[colon + 1..].trim_start_matches(['/', '\\']);
670        let end = rest.find(['/', '\\', '?', '#']).unwrap_or(rest.len());
671        let (authority, rest) = rest.split_at(end);
672        let host_port = match authority.rfind('@') {
673            Some(at) => &authority[at + 1..],
674            None => authority,
675        };
676        let (host, port) = split_port(host_port)?;
677        let host = parse_host(host)?;
678        let port = match port {
679            None | Some("") => String::new(),
680            Some(p) => {
681                if !p.bytes().all(|b| b.is_ascii_digit()) {
682                    return None;
683                }
684                let digits = p.trim_start_matches('0');
685                if digits.len() > 5 {
686                    return None;
687                }
688                let n: u32 = if digits.is_empty() { 0 } else { digits.parse().ok()? };
689                if n > 65535 {
690                    return None;
691                }
692                let n = n.to_string();
693                if n == default_port { String::new() } else { format!(":{n}") }
694            }
695        };
696        let rest = rest.split('#').next().unwrap_or("");
697        let (path, query) = match rest.find('?') {
698            Some(q) => (&rest[..q], Some(&rest[q + 1..])),
699            None => (rest, None),
700        };
701        let pathname = pathname(path);
702        let mut out = format!("{scheme}://{host}{port}");
703        if pathname.len() > 1 {
704            out.push_str(pathname.trim_end_matches('/'));
705        }
706        if let Some(q) = query
707            && !q.is_empty()
708        {
709            out.push('?');
710            encode(&mut out, q, query_set);
711        }
712        Some(out)
713    }
714
715    /// The host and the port, split at the first colon outside brackets.
716    fn split_port(s: &str) -> Option<(&str, Option<&str>)> {
717        let mut inside = false;
718        for (i, c) in s.char_indices() {
719            match c {
720                '[' => inside = true,
721                ']' => inside = false,
722                ':' if !inside => return Some((&s[..i], Some(&s[i + 1..]))),
723                _ => {}
724            }
725        }
726        Some((s, None))
727    }
728
729    fn pathname(path: &str) -> String {
730        let mut segments: Vec<String> = Vec::new();
731        let raw: Vec<&str> = if path.is_empty() { vec![""] } else { path[1..].split(['/', '\\']).collect() };
732        let last = raw.len() - 1;
733        for (i, seg) in raw.iter().enumerate() {
734            let mut buf = String::new();
735            encode(&mut buf, seg, path_set);
736            let lower = buf.to_ascii_lowercase();
737            let double = matches!(lower.as_str(), ".." | ".%2e" | "%2e." | "%2e%2e");
738            let single = matches!(lower.as_str(), "." | "%2e");
739            if double {
740                segments.pop();
741                if i == last {
742                    segments.push(String::new());
743                }
744            } else if single {
745                if i == last {
746                    segments.push(String::new());
747                }
748            } else {
749                segments.push(buf);
750            }
751        }
752        format!("/{}", segments.join("/"))
753    }
754
755    fn parse_host(s: &str) -> Option<String> {
756        if let Some(inner) = s.strip_prefix('[') {
757            let inner = inner.strip_suffix(']')?;
758            return Some(format!("[{}]", ipv6(inner)?));
759        }
760        if s.is_empty() {
761            return None;
762        }
763        let decoded = String::from_utf8(percent_decode(s)).ok()?;
764        let domain = decoded.to_lowercase();
765        if domain.is_empty()
766            || domain.chars().any(|c| {
767                c < ' ' || matches!(c, ' ' | '#' | '%' | '/' | ':' | '<' | '>' | '?' | '@' | '[' | '\\' | ']' | '^' | '|' | '\u{7f}')
768            })
769        {
770            return None;
771        }
772        if ends_in_number(&domain) {
773            return ipv4(&domain);
774        }
775        Some(domain)
776    }
777
778    fn ends_in_number(s: &str) -> bool {
779        let mut parts: Vec<&str> = s.split('.').collect();
780        if parts.last() == Some(&"") {
781            if parts.len() == 1 {
782                return false;
783            }
784            parts.pop();
785        }
786        let Some(last) = parts.last() else { return false };
787        if !last.is_empty() && last.bytes().all(|b| b.is_ascii_digit()) {
788            return true;
789        }
790        let hex = last.strip_prefix("0x").or_else(|| last.strip_prefix("0X"));
791        hex.is_some_and(|h| h.bytes().all(|b| b.is_ascii_hexdigit()))
792    }
793
794    fn ipv4_number(s: &str) -> Option<u64> {
795        if s.is_empty() {
796            return None;
797        }
798        let (digits, radix) = if let Some(h) = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")) {
799            (h, 16)
800        } else if s.len() > 1 && s.starts_with('0') {
801            (&s[1..], 8)
802        } else {
803            (s, 10)
804        };
805        if digits.is_empty() {
806            return Some(0);
807        }
808        if !digits.chars().all(|c| c.is_digit(radix)) {
809            return None;
810        }
811        let trimmed = digits.trim_start_matches('0');
812        if trimmed.len() > 12 {
813            return Some(u64::MAX);
814        }
815        u64::from_str_radix(if trimmed.is_empty() { "0" } else { trimmed }, radix).ok()
816    }
817
818    fn ipv4(s: &str) -> Option<String> {
819        let mut parts: Vec<&str> = s.split('.').collect();
820        if parts.last() == Some(&"") && parts.len() > 1 {
821            parts.pop();
822        }
823        if parts.len() > 4 {
824            return None;
825        }
826        let nums: Vec<u64> = parts.iter().map(|p| ipv4_number(p)).collect::<Option<_>>()?;
827        let (last, init) = nums.split_last()?;
828        if init.iter().any(|&n| n > 255) || *last >= 256u64.pow(5 - nums.len() as u32) {
829            return None;
830        }
831        let mut v = *last;
832        for (i, &n) in init.iter().enumerate() {
833            v += n * 256u64.pow(3 - i as u32);
834        }
835        Some(format!("{}.{}.{}.{}", v >> 24, (v >> 16) & 255, (v >> 8) & 255, v & 255))
836    }
837
838    fn ipv6(s: &str) -> Option<String> {
839        let mut addr = [0u16; 8];
840        let c: Vec<char> = s.chars().collect();
841        let (mut piece, mut compress, mut p) = (0usize, None::<usize>, 0usize);
842        if c.first() == Some(&':') {
843            if c.get(1) != Some(&':') {
844                return None;
845            }
846            p = 2;
847            piece = 1;
848            compress = Some(1);
849        }
850        while p < c.len() {
851            if piece == 8 {
852                return None;
853            }
854            if c[p] == ':' {
855                if compress.is_some() {
856                    return None;
857                }
858                p += 1;
859                piece += 1;
860                compress = Some(piece);
861                continue;
862            }
863            let (mut value, mut length) = (0u32, 0);
864            while length < 4 && p < c.len() && c[p].is_ascii_hexdigit() {
865                value = value * 16 + c[p].to_digit(16)?;
866                p += 1;
867                length += 1;
868            }
869            if p < c.len() && c[p] == '.' {
870                if length == 0 || piece > 6 {
871                    return None;
872                }
873                p -= length;
874                let mut seen = 0;
875                while p < c.len() {
876                    let mut v4: Option<u32> = None;
877                    if seen > 0 {
878                        if c[p] == '.' && seen < 4 {
879                            p += 1;
880                        } else {
881                            return None;
882                        }
883                    }
884                    if p >= c.len() || !c[p].is_ascii_digit() {
885                        return None;
886                    }
887                    while p < c.len() && c[p].is_ascii_digit() {
888                        let n = c[p].to_digit(10)?;
889                        v4 = match v4 {
890                            None => Some(n),
891                            Some(0) => return None,
892                            Some(x) => Some(x * 10 + n),
893                        };
894                        if v4? > 255 {
895                            return None;
896                        }
897                        p += 1;
898                    }
899                    addr[piece] = (addr[piece] as u32 * 256 + v4?) as u16;
900                    seen += 1;
901                    if seen == 2 || seen == 4 {
902                        piece += 1;
903                    }
904                }
905                if seen != 4 {
906                    return None;
907                }
908                break;
909            } else if p < c.len() && c[p] == ':' {
910                p += 1;
911                if p >= c.len() {
912                    return None;
913                }
914            } else if p < c.len() {
915                return None;
916            }
917            addr[piece] = value as u16;
918            piece += 1;
919        }
920        if let Some(cp) = compress {
921            let mut swaps = piece - cp;
922            piece = 7;
923            while piece != 0 && swaps > 0 {
924                addr.swap(piece, cp + swaps - 1);
925                piece -= 1;
926                swaps -= 1;
927            }
928        } else if piece != 8 {
929            return None;
930        }
931        // the longest run of two or more zero pieces is compressed (the first of equal ones)
932        let (mut best, mut best_len, mut i) = (None::<usize>, 1usize, 0usize);
933        while i < 8 {
934            if addr[i] == 0 {
935                let start = i;
936                while i < 8 && addr[i] == 0 {
937                    i += 1;
938                }
939                if i - start > best_len {
940                    best = Some(start);
941                    best_len = i - start;
942                }
943            } else {
944                i += 1;
945            }
946        }
947        let mut out = String::new();
948        let mut ignore0 = false;
949        for (i, piece) in addr.iter().enumerate() {
950            if ignore0 && *piece == 0 {
951                continue;
952            }
953            ignore0 = false;
954            if best == Some(i) {
955                out.push_str(if i == 0 { "::" } else { ":" });
956                ignore0 = true;
957                continue;
958            }
959            out.push_str(&format!("{piece:x}"));
960            if i != 7 {
961                out.push(':');
962            }
963        }
964        Some(out)
965    }
966}