didbot_policy_records/

compile.rs

//! Turning a batch of [`ParsedPolicy`] records into declarations registered
//! on a [`PolicyTreeBuilder`] -- the step where "applicability parses, the
//! predicate does not" gets its scoped, fail-closed treatment, by actually
//! calling [`didbot_policy::Evaluator::compile`].
//!
//! # Why this is a separate step from parsing
//!
//! Reading a record cannot tell a well-formed predicate from a malformed
//! one: `predicate` is opaque JSON, and only the evaluator implementation
//! named by `language` knows its own syntax. So the
//! distinction `plan/policy.md` draws --
//! "applicability parses, the predicate does not (bad syntax, or it names
//! an evaluator this build does not have)" -- can only be made here, once a
//! [`Language`] is available to try, and it is made by actually compiling:
//! `didbot_policy::Evaluator::compile` is validation, there is no separate
//! validate step.
//!
//! This module is synchronous and does no I/O of its own: it is handed
//! predicate documents and hands back [`Predicate`]s.
//!
//! # Fail-closed, scoped -- and the core already does the work
//!
//! `didbot_policy::Predicate` has exactly the state this needs:
//! [`Predicate::Evaluator`] for a working one, [`Predicate::Unusable`] for
//! "applicability is known-good, the predicate is not." When a predicate's
//! `language` is not one any registered [`Language`] answers to, or the
//! matching [`Language`]'s evaluator rejects it as malformed, this module
//! registers the record's
//! `applicability` and `observes` with [`Predicate::Unusable`] carrying the
//! reason -- no evaluator, no separate "deny everything" implementation
//! needed, because [`didbot_policy::PolicyTree::decide`] already turns
//! `Unusable` into a scoped [`didbot_policy::Outcome::Reject`] on its own.
//! The tree still routes exactly the writes this policy declared it covers
//! there -- nothing outside its declared scope is touched, and nothing
//! inside it is silently allowed by a predicate that could not be built.

use std::collections::HashMap;
use std::sync::Arc;

use didbot_policy::{
    CompileOutcome, Evaluator, PolicyDeclaration, PolicyId, PolicyTreeBuilder, Predicate,
};

use crate::record::ParsedPolicy;

/// One evaluator language a build carries, and the bridge from this crate's
/// opaque `predicate` payloads into it.
///
/// `didbot-policy-regex` is expected to answer to `"regex"`. Kept as a
/// trait rather than a hard dependency on any specific evaluator crate: this
/// crate's job is turning observed records into declarations the core's
/// tree can be built from, not owning any one evaluator's compiled-predicate
/// format. A build wires in every [`Language`] it ships by passing them to
/// [`compile_policies`].
pub trait Language {
    /// The `language` name a record's wrapper names to select this
    /// evaluator, e.g. `"regex"`. Matched exactly, case-sensitively.
    fn name(&self) -> &str;

    /// A fresh evaluator instance for this language, with nothing compiled
    /// into it yet.
    ///
    /// The actual compiling happens afterward, via
    /// [`didbot_policy::Evaluator::compile`] on the value this returns --
    /// this method's whole job is handing back *something* that
    /// implements the trait, so [`compile_policies`] never needs to know
    /// any evaluator crate's concrete type. One call per policy this
    /// language serves: `didbot-policy-regex`'s evaluator holds exactly one
    /// compiled artifact, so this crate constructs one fresh instance per
    /// predicate document rather than compiling several predicates into a
    /// shared one.
    ///
    /// # Returning a shared instance is a promise about `CompiledId`
    ///
    /// A language backed by shared state may return clones of an `Arc` it
    /// holds internally, but only if its evaluator mints a *distinct*
    /// [`didbot_policy::CompiledId`] per `compile` and dispatches
    /// `evaluate` on it. [`resolve_predicate`] calls `compile` once per
    /// policy on whatever this hands back, so an evaluator that keeps one
    /// artifact and ignores the `compiled` argument -- which the trait
    /// permits, and `didbot-policy-regex` does -- has that artifact
    /// overwritten by the next policy sharing the instance, and every
    /// earlier policy then silently enforces the last one's predicate
    /// instead of its own. That is a fail-open: a policy the tree still
    /// routes writes to stops checking what it was written to check. An
    /// evaluator with one artifact per instance must therefore get one
    /// instance per policy, which is what a fresh construction here gives
    /// it.
    fn new_evaluator(&self) -> Arc<dyn Evaluator>;
}

/// One record this step could not compile into a live [`Evaluator`],
/// alongside why. Its applicability was still registered, scoped, with
/// [`Predicate::Unusable`] -- see this module's doc comment -- so this is a
/// report for the operator, not a sign the record was dropped.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ScopedDenial {
    /// The record's id, as passed to [`compile_policies`].
    pub id: String,
    /// The `language` the record named.
    pub language: String,
    /// Why compiling `predicate` for `language` failed -- either "no
    /// registered `Language` answers to this name" or whatever the matching
    /// evaluator's [`Evaluator::compile`] rejected it with.
    pub reason: String,
}

/// One record [`Evaluator::compile`] accepted, but with something the
/// operator should see -- see [`CompileOutcome::CompiledWithWarnings`].
/// Never blocks the policy: it is registered exactly like a clean compile,
/// this is purely a report.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyWarning {
    /// The record's id, as passed to [`compile_policies`].
    pub id: String,
    /// The `language` the record named.
    pub language: String,
    /// What the evaluator wanted to say about its own compiled form.
    pub warnings: Vec<String>,
}

/// What compiling one batch of records produced: every [`ScopedDenial`] and
/// [`PolicyWarning`] hit along the way, for the operator-facing report, and
/// the [`PolicyId`] each record was registered as.
#[derive(Debug, Clone, Default)]
pub struct CompileReport {
    /// Records whose predicate could not be compiled at all.
    pub denials: Vec<ScopedDenial>,
    /// Records that compiled with something the operator should see.
    pub warnings: Vec<PolicyWarning>,
    /// The tree position each record was registered at, by its id, so a
    /// caller can attach what the tree does not index on -- whom a policy
    /// is bound to -- to the policy the tree names in a verdict.
    pub registered: HashMap<String, PolicyId>,
}

/// Registers every policy in `records` against `builder`, in `records`'
/// iteration order -- callers wanting a specific presentational order (see
/// `plan/policy.md`'s "order is presentational, not semantic") should pass
/// an already-ordered sequence.
///
/// Precedence is not this function's concern: it registers every source's
/// policies into the same tree with no source privileged over another,
/// because `plan/policy.md`'s deny-only monotonicity already makes that
/// correct -- see this crate's top-level doc comment for why no precedence
/// engine belongs here.
pub fn compile_policies<'a>(
    records: impl IntoIterator<Item = (&'a str, &'a ParsedPolicy)>,
    languages: &[&dyn Language],
    builder: &mut PolicyTreeBuilder,
) -> CompileReport {
    let mut report = CompileReport::default();
    for (id, policy) in records {
        let predicate = resolve_predicate(id, policy, languages, builder, &mut report);
        let registered = register(builder, policy, predicate);
        report.registered.insert(id.to_string(), registered);
    }
    report
}

/// Register `predicate` -- whatever [`resolve_predicate`] produced -- as
/// one policy on `builder`, using `policy`'s own applicability, observation
/// surface, staleness and revision.
///
/// Split out from [`resolve_predicate`] because `didbot-pds`'s
/// last-good-revision loader needs to *decide*, from a resolved
/// [`Predicate`], whether to register it or discard it and register a
/// fallback [`ParsedPolicy`] instead -- see [`resolve_predicate`]'s doc
/// comment. Registering unconditionally inside the resolve step would leave
/// a rejected revision's own (unusable, but still applicability-scoped)
/// declaration in the tree alongside the fallback's, denying more than the
/// fallback alone ever would.
pub fn register(
    builder: &mut PolicyTreeBuilder,
    policy: &ParsedPolicy,
    predicate: Predicate,
) -> PolicyId {
    builder.add_policy(PolicyDeclaration {
        applicability: policy.applicability.clone(),
        observes: policy.observes.clone(),
        staleness: policy.staleness,
        predicate,
        revision: policy.revision,
    })
}

/// Resolve one record's [`Predicate`] -- a working [`Predicate::Evaluator`]
/// or a scoped [`Predicate::Unusable`] -- without registering it on
/// `builder` as a policy. Appends any [`ScopedDenial`] or [`PolicyWarning`]
/// hit along the way to `report`.
///
/// Exposed (not just used internally by [`compile_policies`]) because
/// `didbot-pds`'s loader drives this one record at a time for the operator
/// source, so it can substitute a last-good [`ParsedPolicy`] and retry when
/// this call resolves [`Predicate::Unusable`] for a record that previously
/// compiled -- see `plan/policy.md`'s last-good-revision behaviour.
/// `compile_policies` itself has no notion of "the previous revision of
/// this same id"; that state lives with the caller, across rebuilds, not in
/// this crate's stateless compiling step. A caller that resolves a
/// predicate here and decides not to register it (because it is using a
/// fallback instead) has still, harmlessly, registered any evaluator that
/// predicate's compile step created via `builder.register_evaluator` --
/// an unused registration costs a `Vec` slot nothing else ever reaches, not
/// a wrong verdict.
pub fn resolve_predicate(
    id: &str,
    policy: &ParsedPolicy,
    languages: &[&dyn Language],
    builder: &mut PolicyTreeBuilder,
    report: &mut CompileReport,
) -> Predicate {
    let language = languages.iter().find(|l| l.name() == policy.language);
    match language {
        None => {
            let reason = format!(
                "{id}: no evaluator registered for language {:?}",
                policy.language
            );
            report.denials.push(ScopedDenial {
                id: id.to_string(),
                language: policy.language.clone(),
                reason: reason.clone(),
            });
            Predicate::Unusable { reason }
        }
        Some(language) => {
            let evaluator = language.new_evaluator();
            match evaluator.compile(&policy.predicate) {
                CompileOutcome::Compiled(compiled_id) => {
                    let warnings: Vec<String> = local_spelling(&policy.predicate).collect();
                    if !warnings.is_empty() {
                        report.warnings.push(PolicyWarning {
                            id: id.to_string(),
                            language: policy.language.clone(),
                            warnings,
                        });
                    }
                    let evaluator_id = builder.register_evaluator(evaluator);
                    Predicate::Evaluator(evaluator_id, compiled_id)
                }
                CompileOutcome::CompiledWithWarnings(compiled_id, mut warnings) => {
                    warnings.extend(local_spelling(&policy.predicate));
                    report.warnings.push(PolicyWarning {
                        id: id.to_string(),
                        language: policy.language.clone(),
                        warnings,
                    });
                    let evaluator_id = builder.register_evaluator(evaluator);
                    Predicate::Evaluator(evaluator_id, compiled_id)
                }
                CompileOutcome::Rejected(reason) => {
                    let reason = format!(
                        "{id}: predicate rejected by language {:?}: {reason}",
                        policy.language
                    );
                    report.denials.push(ScopedDenial {
                        id: id.to_string(),
                        language: policy.language.clone(),
                        reason: reason.clone(),
                    });
                    Predicate::Unusable { reason }
                }
            }
        }
    }
}

/// What a predicate is told when it names `http://localhost` in a spelling
/// no `client_id` is judged in.
pub const LOCAL_SPELLING: &str =
    "names `http://localhost` in a spelling no client_id is judged in: \
     every local client_id is judged as `http://localhost/?redirect_uri=…&scope=…`, \
     so this part matches no local client; `^http://localhost/` matches every one";

/// [`LOCAL_SPELLING`], once, if any string in `predicate` names
/// `http://localhost` followed by anything but `/` or a port.
///
/// `didbot_policy::ClientId` spells every local `client_id` from
/// `http://localhost/?`, so `http://localhost` alone, or followed by `?`, `$`
/// or a quote, matches none of them. A rule written that way denies nothing,
/// which under default-allow says nothing either.
fn local_spelling(predicate: &serde_json::Value) -> impl Iterator<Item = String> {
    fn any_string(value: &serde_json::Value, found: &dyn Fn(&str) -> bool) -> bool {
        match value {
            serde_json::Value::String(text) => found(text),
            serde_json::Value::Array(items) => items.iter().any(|item| any_string(item, found)),
            serde_json::Value::Object(map) => map.values().any(|item| any_string(item, found)),
            _ => false,
        }
    }
    let names_none = |text: &str| {
        text.match_indices("http://localhost").any(|(at, prefix)| {
            let rest = &text[at + prefix.len()..];
            !(rest.starts_with('/') || rest.starts_with("\\/") || rest.starts_with(':'))
        })
    };
    any_string(predicate, &names_none)
        .then(|| LOCAL_SPELLING.to_owned())
        .into_iter()
}

/// Whether [`resolve_predicate`] produced a working [`Predicate::Evaluator`]
/// -- with or without warnings -- for `id`, judged from what it appended to
/// `report`. `didbot-pds`'s last-good-revision loader uses this to decide
/// whether an id's *current* revision compiled, without duplicating
/// `resolve_predicate`'s own compiling logic.
#[must_use]
pub fn compiled_successfully(report: &CompileReport, id: &str) -> bool {
    !report.denials.iter().any(|denial| denial.id == id)
}

#[cfg(test)]
mod tests {
    use super::*;
    use didbot_policy::{
        ActionSet, Applicability, CompiledId, EvalError, KindSet, Lifecycle, Observed, Outcome,
        PolicyTree, Revision, Scope, Staleness, Subject,
    };
    use serde_json::json;

    fn policy_with_language(language: &str) -> ParsedPolicy {
        ParsedPolicy {
            applicability: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            observes: Applicability::Write {
                kinds: KindSet::ALL,
                collections: Scope::Any,
                actions: ActionSet::ALL,
                path_prefixes: Scope::Any,
            },
            staleness: Staleness::Linearized,
            language: language.to_string(),
            predicate: json!({}),
            revision: Revision(0),
            lookups: Vec::new(),
        }
    }

    struct AlwaysAllow;
    impl Evaluator for AlwaysAllow {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Compiled(CompiledId(0))
        }
        fn evaluate(
            &self,
            _subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            Ok(Outcome::Allow)
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }
    struct AlwaysAllowLanguage;
    impl Language for AlwaysAllowLanguage {
        fn name(&self) -> &str {
            "always-allow"
        }
        fn new_evaluator(&self) -> Arc<dyn Evaluator> {
            Arc::new(AlwaysAllow)
        }
    }

    struct AlwaysRejectsPredicate;
    impl Evaluator for AlwaysRejectsPredicate {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::Rejected("this predicate is never good enough".to_string())
        }
        fn evaluate(
            &self,
            _subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            unreachable!("never compiled")
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }
    struct PickyLanguage;
    impl Language for PickyLanguage {
        fn name(&self) -> &str {
            "picky"
        }
        fn new_evaluator(&self) -> Arc<dyn Evaluator> {
            Arc::new(AlwaysRejectsPredicate)
        }
    }

    struct WarnsOnCompile;
    impl Evaluator for WarnsOnCompile {
        fn compile(&self, _predicate: &serde_json::Value) -> CompileOutcome {
            CompileOutcome::CompiledWithWarnings(
                CompiledId(0),
                vec!["vulnerable to homoglyphs, normalize first".to_string()],
            )
        }
        fn evaluate(
            &self,
            _subject: &Subject<'_>,
            _compiled: CompiledId,
        ) -> Result<Outcome, EvalError> {
            Ok(Outcome::Allow)
        }
        fn observe(&self, _event: &Observed<'_>) {}
        fn lifecycle(&self, _event: &Lifecycle<'_>) {}
        fn staleness(&self) -> Staleness {
            Staleness::Linearized
        }
    }
    struct WarnsLanguage;
    impl Language for WarnsLanguage {
        fn name(&self) -> &str {
            "warns"
        }
        fn new_evaluator(&self) -> Arc<dyn Evaluator> {
            Arc::new(WarnsOnCompile)
        }
    }

    fn dummy_subject() -> Subject<'static> {
        Subject::Write {
            account: "did:plc:agent",
            attributes: didbot_policy::SubjectAttributes {
                kind: didbot_policy::SubjectKind::Known(didbot_policy::AccountKind::Agent),
                handle: None,
                depth: None,
            },
            universal: didbot_policy::Universal {
                deployment: didbot_policy::DeploymentAttributes::default(),
                now: time::macros::datetime!(2026 - 01 - 01 0:00 UTC),
            },
            client_id: None,
            collection: "app.bsky.feed.post",
            action: didbot_policy::WriteAction::Create,
            diff: didbot_policy::Diff::default(),
            before: None,
            after: None,
            lookups: &[],
        }
    }

    #[test]
    fn an_unknown_language_is_scoped_deny_not_dropped() {
        let policy = policy_with_language("nobody-ships-this");
        let mut builder = PolicyTree::builder();
        let report = compile_policies([("id-1", &policy)], &[], &mut builder);
        assert_eq!(report.denials.len(), 1);
        assert_eq!(report.denials[0].language, "nobody-ships-this");

        let tree = builder.build();
        let subject = dummy_subject();
        assert_eq!(tree.decision_candidates(&subject).len(), 1);
        assert!(matches!(
            didbot_policy::evaluate(&subject, &tree),
            didbot_policy::Verdict::Reject { .. }
        ));
    }

    #[test]
    fn a_predicate_a_language_rejects_is_scoped_deny() {
        let policy = policy_with_language("picky");
        let mut builder = PolicyTree::builder();
        let report = compile_policies(
            [("id-1", &policy)],
            &[&PickyLanguage as &dyn Language],
            &mut builder,
        );
        assert_eq!(report.denials.len(), 1);
        assert!(report.denials[0]
            .reason
            .contains("this predicate is never good enough"));

        let tree = builder.build();
        assert!(matches!(
            didbot_policy::evaluate(&dummy_subject(), &tree),
            didbot_policy::Verdict::Reject { .. }
        ));
    }

    #[test]
    fn a_matching_language_compiles_with_no_denial_reported() {
        let policy = policy_with_language("always-allow");
        let mut builder = PolicyTree::builder();
        let report = compile_policies(
            [("id-1", &policy)],
            &[&AlwaysAllowLanguage as &dyn Language],
            &mut builder,
        );
        assert!(report.denials.is_empty());
        assert!(report.warnings.is_empty());

        let tree = builder.build();
        assert_eq!(
            didbot_policy::evaluate(&dummy_subject(), &tree),
            didbot_policy::Verdict::Allow
        );
    }

    /// A compile that succeeds with warnings is registered exactly like a
    /// clean compile -- the policy is not blocked -- but the warning
    /// reaches the report, not silently dropped.
    #[test]
    fn a_compile_with_warnings_still_registers_and_reports_the_warning() {
        let policy = policy_with_language("warns");
        let mut builder = PolicyTree::builder();
        let report = compile_policies(
            [("id-1", &policy)],
            &[&WarnsLanguage as &dyn Language],
            &mut builder,
        );
        assert!(report.denials.is_empty());
        assert_eq!(report.warnings.len(), 1);
        assert!(report.warnings[0].warnings[0].contains("homoglyphs"));

        let tree = builder.build();
        assert_eq!(
            didbot_policy::evaluate(&dummy_subject(), &tree),
            didbot_policy::Verdict::Allow
        );
    }

    /// A rule written against a local client as it was sent before
    /// `ClientId` gave every one a single spelling compiles, matches nothing,
    /// and says so. One that names `http://localhost/` or a port does not.
    #[test]
    fn a_predicate_naming_a_local_spelling_no_client_id_takes_is_warned_of() {
        let mut builder = PolicyTree::builder();
        let mut warned = |predicate: serde_json::Value| {
            let mut policy = policy_with_language("always-allow");
            policy.predicate = predicate;
            let report = compile_policies(
                [("id-1", &policy)],
                &[&AlwaysAllowLanguage as &dyn Language],
                &mut builder,
            );
            report
                .warnings
                .iter()
                .any(|warning| warning.warnings.iter().any(|text| text == LOCAL_SPELLING))
        };
        for stale in [
            json!({"clientId": "^http://localhost$"}),
            json!({"clientId": "^http://localhost\\?redirect_uri="}),
            json!({"source": "resource.id == \"http://localhost\""}),
            json!({"deep": [{"source": "resource.id like \"http://localhost?*\""}]}),
        ] {
            assert!(warned(stale.clone()), "{stale}");
        }
        for current in [
            json!({"clientId": "^http://localhost/"}),
            json!({"clientId": "^http://localhost\\/"}),
            json!({"source": "resource.id like \"http://localhost/*\" || resource.id like \"http://localhost:*\""}),
            json!({"clientId": "^https://client\\.example/"}),
        ] {
            assert!(!warned(current.clone()), "{current}");
        }
    }
}