didbot_policy_records/

builtin.rs

//! Source 1: policies compiled into the binary, immutable.
//!
//! `plan/policy.md`: "Things unsafe to admit into public existence. An
//! application that does not want agents using it opens a pull request
//! against didbot asking to be denied as a client; that denial ships in the
//! binary." This is where that PR lands: [`builtin_policies`] returns a
//! fixed `Vec`, and the only way to change what it contains is to edit
//! `floor/` and ship a new build. There is no config path, no record, no
//! admin surface that can add to or remove from this list at runtime --
//! that is the whole point of "immutable."
//!
//! A built-in applies to every account on every deployment and cannot be
//! turned off. So it is only for a rule no operator would ever want an
//! agent to break. Anything an operator might reasonably want differently
//! is the operator's own record.
//!
//! # A built-in is a record
//!
//! Each one is the `bot.did.policy` record an operator would write, kept
//! in `floor/` beside this crate and read at startup by the same
//! [`crate::records`] reader, split into statements by the same
//! [`crate::set::declarations`], and compiled by the same
//! [`crate::compile`] against the same engines. So a built-in can be copied
//! into an operator's repository unchanged, the refusal an agent reads is
//! the statement's own reason, it reports on a dashboard the way an
//! operator's record does, and a change to an engine that breaks a built-in
//! breaks this crate's tests rather than a deployment. `floor/README.md`
//! says what each one is for and where its numbers come from, and
//! [`builtin_records`] hands the records out for a dashboard or a test to
//! read.
//!
//! What a built-in gets that an operator's record does not is its
//! applicability: a record from the operator is routed to every write and
//! filters on the collection inside the evaluator, while a built-in names
//! the exact collections it reaches, so a write anywhere else never pays
//! for it. That is `plan/policy.md`'s "a policy gating common writes should
//! be cheap and in-process", applied to rules every write on every server
//! would otherwise consult. A built-in that reaches every collection, such
//! as a client denial, says so with `Scope::Any`.

use didbot_policy::{Applicability, Scope, Staleness};
use serde_json::Value;

use crate::record::ParsedPolicy;
use crate::records::PolicyRecord;

/// One statement of one policy compiled into the binary, under the id a
/// report calls it by: `builtin/{name}/{statement}/{action}`, the same
/// `{key}/{statement}/{action}` shape an operator's record is registered
/// under, with the source in place of a record key.
#[derive(Clone)]
pub struct BuiltinPolicy {
    /// What a report calls this policy.
    pub name: String,
    /// The declaration [`crate::set::declarations`] made of it, which
    /// [`crate::merge::build`] compiles exactly as it compiles an
    /// operator's.
    pub policy: ParsedPolicy,
}

/// A builtin's nominal revision: `0`, always. A builtin is not an
/// observation of anything -- it ships with the binary and has no author
/// writing successive edits for [`didbot_policy::Revision`] to order, so
/// there is nothing for this value to compare against. It exists only
/// because [`didbot_policy::PolicyDeclaration`] always carries one, for
/// `plan/policy.md`'s "record which policy version admitted each write".
pub const BUILTIN_REVISION: didbot_policy::Revision = didbot_policy::Revision(0);

/// The `createdAt` a built-in's record carries when its file leaves it
/// out, the way the recommended catalogue's files do.
///
/// The field is the record's, and a built-in has no author writing it on a
/// date, so nothing reads it; the reader requires one.
const WRITTEN_AT: &str = "1970-01-01T00:00:00.000Z";

/// One built-in: its record as written, the collections it reaches, and
/// how stale its evaluator's view may be.
struct Builtin {
    record: Value,
    collections: Scope<&'static str>,
    staleness: Staleness,
}

/// The record `source` holds.
fn record(source: &str) -> Value {
    serde_json::from_str(source).expect("a built-in record is JSON")
}

/// The built-in `record` is, reaching `collections`.
fn builtin(mut record: Value, collections: Scope<&'static str>) -> Builtin {
    if record.get("createdAt").is_none() {
        record["createdAt"] = Value::String(WRITTEN_AT.to_owned());
    }
    Builtin {
        record,
        collections,
        // Every floor engine is deterministic, exact and in process, and
        // the counting one routes every write on the server, so none of
        // them may answer from a view that has fallen behind.
        staleness: Staleness::Linearized,
    }
}

/// The built-ins this binary ships. See `ships_exactly_these_builtins` for
/// the list as a reviewer reads it, and `floor/README.md` for what each one
/// is for.
fn builtins() -> Vec<Builtin> {
    vec![
        builtin(
            record(DECLARED_AI_PREFERENCE),
            // Every collection: a record in any of them can carry somebody's
            // DID, and a list of the ones that do today is a list that stops
            // being true the next time a lexicon gains a field.
            Scope::Any,
        ),
        builtin(
            record(include_str!("../floor/keep-bot-label.json")),
            Scope::Only(vec!["app.bsky.actor.profile"]),
        ),
        builtin(record(include_str!("../floor/write-rate.json")), Scope::Any),
        builtin(
            record(include_str!("../floor/follow-rate.json")),
            Scope::Only(vec!["app.bsky.graph.follow"]),
        ),
        builtin(
            record(include_str!("../floor/contact-rate.json")),
            Scope::Only(vec![
                "app.bsky.feed.like",
                "app.bsky.feed.post",
                "app.bsky.feed.repost",
            ]),
        ),
    ]
}

/// The floor rule that honours a declared AI preference. See
/// `plan/ai-preference.md`.
pub const DECLARED_AI_PREFERENCE: &str = include_str!("../floor/declared-ai-preference.json");

/// [`builtins`], plus the records this crate's own tests exercise the
/// machinery with. Those records exist only in the test build.
fn loaded() -> Vec<Builtin> {
    #[cfg_attr(not(test), allow(unused_mut))]
    let mut loaded = builtins();
    #[cfg(test)]
    loaded.extend(tests::examples());
    loaded
}

/// Every built-in, as the `bot.did.policy` record it is written as.
#[must_use]
pub fn builtin_records() -> Vec<Value> {
    loaded().into_iter().map(|builtin| builtin.record).collect()
}

/// Every policy this build ships compiled in. Fixed at compile time -- see
/// this module's doc comment.
///
/// One [`BuiltinPolicy`] per statement per action the statement can decide,
/// exactly as an operator's record is registered, because it is the same
/// code that splits it.
///
/// # Adding one
///
/// Write the record in `floor/`, with its cases beside it, and add it to
/// `builtins` with the collections it reaches. A PR asking to be denied as
/// a client is a `denyClient` statement under `oauth.authorize`,
/// `oauth.token` and `record.write`, reaching `Scope::Any` collections, so
/// the application is refused at sign-in and at token issue, and a token it
/// already holds is refused at the write. Then change
/// `ships_exactly_these_builtins`: adding one is its own reviewed change.
///
/// # Panics
///
/// If a built-in's record does not read, or names an action this server
/// does not answer. That is a defect in `floor/`, not a runtime condition:
/// this crate's tests read every one of them. Whether a record's
/// *predicate* compiles is the engine's answer, made where an operator's
/// record gets it -- `crate::compile` -- and `the_floor_compiles` is what
/// holds the floor to compiling cleanly.
#[must_use]
pub fn builtin_policies() -> Vec<BuiltinPolicy> {
    let mut policies = Vec::new();
    for builtin in loaded() {
        let record = PolicyRecord::from_json(&builtin.record)
            .unwrap_or_else(|error| panic!("a built-in record does not read: {error}"));
        let name = record.display_name("builtin");
        let declared = crate::set::declarations(&format!("builtin/{name}"), &record)
            .unwrap_or_else(|error| panic!("built-in {name}: {error}"));
        for (id, mut policy) in declared.policies {
            narrow(&mut policy.applicability, &builtin.collections);
            narrow(&mut policy.observes, &builtin.collections);
            policy.staleness = builtin.staleness;
            policy.revision = BUILTIN_REVISION;
            policies.push(BuiltinPolicy { name: id, policy });
        }
    }
    policies
}

/// Narrows a write's applicability to the collections a built-in reaches,
/// so the tree routes it nowhere else. Leaves every other subject shape
/// alone: a client denial at sign-in has no collection to narrow.
fn narrow(applicability: &mut Applicability, only: &Scope<&'static str>) {
    if let (Applicability::Write { collections, .. }, Scope::Only(named)) = (applicability, only) {
        *collections = Scope::Only(named.iter().map(|name| (*name).to_owned()).collect());
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::engine::build_tree;
    use crate::LastGoodPolicies;
    use didbot_policy::{
        AccountKind, Change, ClientId, DeploymentAttributes, Diff, PolicyTree, Subject,
        SubjectAttributes, SubjectKind, Universal, Verdict, WriteAction,
    };
    use serde_json::json;
    use std::collections::HashMap;

    /// The reason the example built-in refuses with.
    const EXAMPLE_REASON: &str = "app.example.record is refused by the test build's built-in.";

    /// The reason the example client denial refuses with.
    const CLIENT_REASON: &str = "client.example is refused by the test build's built-in.";

    /// Every built-in this module adds to [`loaded`].
    pub(super) fn examples() -> Vec<Builtin> {
        vec![example(), example_client()]
    }

    /// The record this module exercises the machinery with. Its statement
    /// matches every `app.example.*` collection, but it names only
    /// `app.example.record`: a write to `app.example.other` is admitted
    /// because routing never reaches it, not because the regex declined.
    fn example() -> Builtin {
        builtin(
            json!({
                "$type": "bot.did.policy",
                "name": "example",
                "description": "Refuses every write to app.example.record.",
                "actions": ["record.write"],
                "document": {
                    "$type": "bot.did.policy#regex",
                    "statements": [{
                        "kind": "denyPathValueContaining",
                        "collection": r"^app\.example\.",
                        "path": "",
                        "denied": [{"regex": ""}],
                        "reason": EXAMPLE_REASON,
                    }],
                },
            }),
            Scope::Only(vec!["app.example.record"]),
        )
    }

    /// A client denial at sign-in, at token issue and at the write. It
    /// reaches every collection.
    fn example_client() -> Builtin {
        builtin(
            json!({
                "$type": "bot.did.policy",
                "name": "example-client",
                "description": "Refuses client.example everywhere.",
                "actions": ["oauth.authorize", "oauth.token", "record.write"],
                "document": {
                    "$type": "bot.did.policy#regex",
                    "statements": [{
                        "kind": "denyClient",
                        "clientId": r"^https://client\.example/",
                        "reason": CLIENT_REASON,
                    }],
                },
            }),
            Scope::Any,
        )
    }

    /// A tree holding the loaded built-ins and nothing else, built the way
    /// a deployment builds one.
    fn tree() -> PolicyTree {
        let (tree, report) = build_tree(
            builtin_policies(),
            &HashMap::new(),
            &HashMap::new(),
            &LastGoodPolicies::new(),
        );
        assert!(
            report.scoped_denials.is_empty(),
            "a built-in that does not compile denies everything it covers: {:?}",
            report.scoped_denials
        );
        assert!(report
            .registered
            .contains_key("builtin/example/0/record.write"));
        tree
    }

    fn attributes() -> SubjectAttributes<'static> {
        SubjectAttributes {
            kind: SubjectKind::Known(AccountKind::Agent),
            handle: Some("agent.pds.example"),
            depth: None,
        }
    }

    fn universal() -> Universal<'static> {
        Universal {
            deployment: DeploymentAttributes {
                pds_did: "did:web:pds.example",
                pds_hostname: "pds.example",
                operator_did: None,
            },
            now: time::OffsetDateTime::UNIX_EPOCH,
        }
    }

    fn create<'a>(
        client_id: Option<&'a ClientId>,
        collection: &'a str,
        changes: &'a [Change<'a>],
    ) -> Subject<'a> {
        Subject::Write {
            account: "did:web:agent.pds.example",
            attributes: attributes(),
            universal: universal(),
            client_id,
            collection,
            action: WriteAction::Create,
            diff: Diff { changes },
            before: None,
            after: None,
            lookups: &[],
        }
    }

    /// Adding a built-in ships it to every account on every deployment, so
    /// it is a deliberate change reviewed on its own, and this list is the
    /// line it has to edit.
    #[test]
    fn ships_exactly_these_builtins() {
        let mut ids: Vec<String> = builtins()
            .into_iter()
            .flat_map(|builtin| {
                let record = PolicyRecord::from_json(&builtin.record).expect("reads");
                let name = record.display_name("builtin");
                crate::set::declarations(&format!("builtin/{name}"), &record)
                    .expect("declares")
                    .policies
                    .into_iter()
                    .map(|(id, _)| id)
            })
            .collect();
        ids.sort();
        assert_eq!(
            ids,
            [
                "builtin/contact-rate/0/record.write",
                "builtin/contact-rate/1/record.write",
                "builtin/declared-ai-preference/0/record.write",
                "builtin/follow-rate/0/record.write",
                "builtin/follow-rate/1/record.write",
                "builtin/keep-bot-label/keep-bot-label/record.write",
                "builtin/keep-bot-label/keep-the-profile/record.write",
                "builtin/write-rate/0/record.write",
                "builtin/write-rate/1/record.write",
                "builtin/write-rate/2/record.write",
                "builtin/write-rate/3/record.write",
            ]
        );
    }

    /// Every record in `floor/` compiles, for the engine it names, on the
    /// build that ships it. A built-in that did not would deny everything
    /// it covers instead of what it says.
    #[test]
    fn the_floor_compiles() {
        let _ = tree();
    }

    #[test]
    fn a_builtin_compiles_and_routes_by_its_collections() {
        let policies = builtin_policies();
        let policy = policies
            .iter()
            .find(|policy| policy.name == "builtin/example/0/record.write")
            .expect("the example is registered under its name");
        match &policy.policy.applicability {
            Applicability::Write {
                collections: Scope::Only(collections),
                ..
            } => assert_eq!(
                collections.iter().collect::<Vec<_>>(),
                ["app.example.record"]
            ),
            other => panic!("expected a write scoped to its collections, got {other:?}"),
        }
        assert!(builtin_records()
            .iter()
            .any(|record| record["name"] == "example"));
    }

    #[test]
    fn a_builtin_refuses_in_its_collection_and_admits_elsewhere() {
        let text = json!("hello");
        let changes = [Change {
            path: "text",
            before: None,
            after: Some(&text),
        }];
        let tree = tree();
        match didbot_policy::evaluate(&create(None, "app.example.record", &changes), &tree) {
            Verdict::Reject { reason, .. } => assert_eq!(reason, EXAMPLE_REASON),
            other => panic!("expected a refusal, got {other:?}"),
        }
        assert!(matches!(
            didbot_policy::evaluate(&create(None, "app.example.other", &changes), &tree),
            Verdict::Allow
        ));
    }

    #[test]
    fn a_client_denial_reaches_sign_in_token_issue_and_every_write() {
        let tree = tree();
        let client = ClientId::parse("https://client.example/client-metadata.json").unwrap();
        let other = ClientId::parse("https://other.example/client-metadata.json").unwrap();
        let refused = |subject: &Subject<'_>| match didbot_policy::evaluate(subject, &tree) {
            Verdict::Reject { reason, .. } => assert_eq!(reason, CLIENT_REASON),
            other => panic!("expected a refusal, got {other:?}"),
        };
        refused(&Subject::Grant {
            universal: universal(),
            client_id: &client,
            requested_scopes: &["atproto"],
        });
        refused(&Subject::Token {
            account: "did:web:agent.pds.example",
            attributes: attributes(),
            universal: universal(),
            client_id: &client,
            scopes: &["atproto"],
        });
        refused(&create(Some(&client), "app.example.other", &[]));
        assert!(matches!(
            didbot_policy::evaluate(&create(Some(&other), "app.example.other", &[]), &tree),
            Verdict::Allow
        ));
    }

    /// The floor reaches an account no operator record mentions: a profile
    /// write that takes the bot self-label off is refused by a tree built
    /// from the built-ins alone.
    #[test]
    fn the_bot_label_may_not_be_taken_off() {
        let tree = tree();
        let labelled = json!({
            "$type": "app.bsky.actor.profile",
            "labels": {
                "$type": "com.atproto.label.defs#selfLabels",
                "values": [{ "val": "bot" }],
            },
        });
        let bare = json!({ "$type": "app.bsky.actor.profile" });
        let stripping = Subject::Write {
            account: "did:web:agent.pds.example",
            attributes: attributes(),
            universal: universal(),
            client_id: None,
            collection: "app.bsky.actor.profile",
            action: WriteAction::Update,
            diff: Diff { changes: &[] },
            before: Some(&labelled),
            after: Some(&bare),
            lookups: &[],
        };
        match didbot_policy::evaluate(&stripping, &tree) {
            Verdict::Reject { reason, .. } => {
                assert!(
                    reason.contains("the bot self-label may not be removed"),
                    "{reason}"
                );
            }
            other => panic!("expected a refusal, got {other:?}"),
        }
    }
}