didbot_policy_records/

records.rs

//! The `bot.did.policy` and `bot.did.policyBinding` records, as didbot reads
//! and writes them.
//!
//! Both records are written by an operator into the operator's own
//! repository, which this server can read but never write to — the same
//! asymmetry `didbot-pds`'s `operator::OperatorClaim` relies on. So, like that
//! claim, each is parsed here by hand from a foreign repository's JSON, and
//! a malformed record reads as no record at all rather than charitably. The
//! failure carries a path, exactly as the lexicon checker's own
//! [`InvalidRecord`] does, because the reader is an operator looking at
//! their own record and the field that matters is where.
//!
//! # Two checks, one stricter than the other
//!
//! The lexicon documents under `lexicons/bot/did/` are the first check, run
//! by [`didbot_schema::validate_shape`]. They bound lengths, check formats
//! and require fields. This module is the second: it refuses a field
//! neither record declares, because a field silently dropped is a narrowing
//! the operator wrote and the server never applied. What the lexicon leaves
//! open — an action outside its known values, a document of a `$type` it
//! does not name — is carried here as written; whether this server can
//! answer the action or read the document is the policy build's question,
//! not the reader's. The one open value refused here is an `includes` word
//! outside `subjects` and `descendants`: it names a set of accounts this
//! server cannot enumerate, so no later step could apply it.

use serde_json::{json, Map, Value};
use time::format_description::well_known::Rfc3339;
use time::OffsetDateTime;

use didbot_schema::InvalidRecord;

/// The collection a [`PolicyRecord`] is written under.
pub const POLICY_COLLECTION: &str = didbot_lexicon::nsid::POLICY;

/// The collection a [`PolicyBinding`] is written under.
pub const BINDING_COLLECTION: &str = didbot_lexicon::nsid::POLICY_BINDING;

/// The `$type` of a [`Document::Regex`].
pub const REGEX_DOCUMENT: &str = "bot.did.policy#regex";

/// The `$type` of a [`Document::Cedar`].
pub const CEDAR_DOCUMENT: &str = "bot.did.policy#cedar";

/// The `$type` of a [`Document::Count`].
pub const COUNT_DOCUMENT: &str = "bot.did.policy#count";

/// The fields a `bot.did.policy` record declares.
const POLICY_FIELDS: &[&str] = &[
    "name",
    "description",
    "actions",
    "document",
    "lookups",
    "createdAt",
];

/// The fields one `lookups` entry declares.
const LOOKUP_FIELDS: &[&str] = &["name", "accounts", "collection", "rkey"];

/// The `accounts` word for the accounts the written record names.
const NAMED: &str = "named";

/// The `includes` word for the subjects themselves.
const SUBJECTS: &str = "subjects";

/// The `includes` word for every account admitted beneath a subject.
const DESCENDANTS: &str = "descendants";

/// The fields a `bot.did.policyBinding` record declares.
const BINDING_FIELDS: &[&str] = &["policies", "subjects", "includes", "excludes", "createdAt"];

/// One `bot.did.policy` record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyRecord {
    /// What a refusal calls this policy. The record key stands in when
    /// absent — see [`PolicyRecord::display_name`].
    pub name: Option<String>,
    /// The operator's own note, never shown to an agent.
    pub description: Option<String>,
    /// The actions this policy is consulted on.
    pub actions: Vec<Action>,
    /// The policy document, typed by the engine that reads it.
    pub document: Document,
    /// The records in other repositories this policy's statements read,
    /// each under the name a statement calls it by.
    pub lookups: Vec<Lookup>,
    /// When the operator wrote the record.
    pub created_at: OffsetDateTime,
}

/// One action a policy is consulted on. Open: the lexicon names some and
/// carries any other, so the reader does too.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Action {
    /// A record write by an account on the server.
    RecordWrite,
    /// A blob upload by an account on the server.
    BlobWrite,
    /// An application's authorization request.
    OauthAuthorize,
    /// An application's token request.
    OauthToken,
    /// Where a new account lands.
    AccountCreate,
    /// An action outside the lexicon's known values.
    Other(String),
}

impl Action {
    /// Reads an action as the wire spells it.
    #[must_use]
    pub fn parse(name: &str) -> Self {
        match name {
            "record.write" => Self::RecordWrite,
            "blob.write" => Self::BlobWrite,
            "oauth.authorize" => Self::OauthAuthorize,
            "oauth.token" => Self::OauthToken,
            "account.create" => Self::AccountCreate,
            other => Self::Other(other.to_owned()),
        }
    }

    /// The action as the wire spells it.
    #[must_use]
    pub fn as_str(&self) -> &str {
        match self {
            Self::RecordWrite => "record.write",
            Self::BlobWrite => "blob.write",
            Self::OauthAuthorize => "oauth.authorize",
            Self::OauthToken => "oauth.token",
            Self::AccountCreate => "account.create",
            Self::Other(other) => other,
        }
    }
}

impl std::fmt::Display for Action {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// A policy's document, by the `$type` that names its engine.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Document {
    /// Statements in the regex engine's grammar, each opaque here: the
    /// engine is what reads one.
    Regex {
        /// The statements, in the order written.
        statements: Vec<Value>,
    },
    /// Cedar policy text.
    Cedar {
        /// The source.
        source: String,
    },
    /// Statements in the counting engine's grammar, each opaque here: the
    /// engine is what reads one.
    Count {
        /// The statements, in the order written.
        statements: Vec<Value>,
    },
    /// A document of a `$type` outside the lexicon's union, carried by its
    /// type alone: no engine here reads its fields.
    Other {
        /// The `$type` written.
        r#type: String,
    },
}

impl Document {
    /// The `$type` this document was written under.
    #[must_use]
    pub fn type_name(&self) -> &str {
        match self {
            Self::Regex { .. } => REGEX_DOCUMENT,
            Self::Cedar { .. } => CEDAR_DOCUMENT,
            Self::Count { .. } => COUNT_DOCUMENT,
            Self::Other { r#type } => r#type,
        }
    }

    /// Parses a `document` union member. Paths in a failure are relative
    /// to it.
    fn from_json(value: &Value) -> Result<Self, InvalidRecord> {
        let object = object(value, "")?;
        let type_name = string(object, "$type")?;
        match type_name {
            REGEX_DOCUMENT => {
                only_fields(object, &["$type", "statements"], "a `#regex` document")?;
                let statements = array(object, "statements")?.to_vec();
                if statements.is_empty() {
                    return Err(InvalidRecord::at("statements", "holds no statement"));
                }
                Ok(Self::Regex { statements })
            }
            CEDAR_DOCUMENT => {
                only_fields(object, &["$type", "source"], "a `#cedar` document")?;
                Ok(Self::Cedar {
                    source: string(object, "source")?.to_owned(),
                })
            }
            COUNT_DOCUMENT => {
                only_fields(object, &["$type", "statements"], "a `#count` document")?;
                let statements = array(object, "statements")?.to_vec();
                if statements.is_empty() {
                    return Err(InvalidRecord::at("statements", "holds no statement"));
                }
                Ok(Self::Count { statements })
            }
            other => Ok(Self::Other {
                r#type: other.to_owned(),
            }),
        }
    }

    /// The document as it appears inside a record.
    #[must_use]
    pub fn to_json(&self) -> Value {
        match self {
            Self::Regex { statements } => json!({
                "$type": REGEX_DOCUMENT,
                "statements": statements,
            }),
            Self::Cedar { source } => json!({
                "$type": CEDAR_DOCUMENT,
                "source": source,
            }),
            Self::Count { statements } => json!({
                "$type": COUNT_DOCUMENT,
                "statements": statements,
            }),
            Self::Other { r#type } => json!({ "$type": r#type }),
        }
    }
}

/// One record a policy reads from a repository this server does not hold.
///
/// The declaration says where to look, never what to conclude: the write
/// path reads it and hands the answer to the engine under [`name`](Self::name),
/// and a statement decides what a value, an absence and an unknown each
/// mean for it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Lookup {
    /// What a statement calls this lookup's answer.
    pub name: String,
    /// Whose repositories to read.
    pub accounts: Accounts,
    /// The collection to read in each of them.
    pub collection: String,
    /// The record key to read, or `None` to read the whole collection.
    pub rkey: Option<String>,
}

/// Whose repositories a [`Lookup`] reads. Open: the lexicon names one word
/// and carries any other, so the reader does too, and a word this build
/// does not know reads nothing.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum Accounts {
    /// Every account the written record names.
    Named,
    /// A word outside the lexicon's known values.
    Other(String),
}

impl Accounts {
    /// Reads the word as the wire spells it.
    #[must_use]
    pub fn parse(word: &str) -> Self {
        match word {
            NAMED => Self::Named,
            other => Self::Other(other.to_owned()),
        }
    }

    /// The word as the wire spells it.
    #[must_use]
    pub fn as_str(&self) -> &str {
        match self {
            Self::Named => NAMED,
            Self::Other(other) => other,
        }
    }
}

/// The `lookups` a record's JSON declares, read the way
/// [`PolicyRecord::from_json`] reads them.
///
/// For a caller holding a record as JSON rather than as a [`PolicyRecord`]
/// -- the built-ins, which are records written in Rust.
///
/// # Errors
///
/// See [`InvalidRecord`]: anything `lookups` may not hold.
pub fn lookups_of(record: &Value) -> Result<Vec<Lookup>, InvalidRecord> {
    let object = object(record, "")?;
    match object.get("lookups") {
        None => Ok(Vec::new()),
        Some(_) => array(object, "lookups")?
            .iter()
            .enumerate()
            .map(|(at, entry)| {
                Lookup::from_json(entry).map_err(|error| error.under(&index("lookups", at)))
            })
            .collect(),
    }
}

impl Lookup {
    /// Parses one `lookups` entry. Paths in a failure are relative to it.
    fn from_json(value: &Value) -> Result<Self, InvalidRecord> {
        let object = object(value, "")?;
        only_fields(object, LOOKUP_FIELDS, "a `lookups` entry")?;
        let name = string(object, "name")?;
        if name.is_empty() {
            return Err(InvalidRecord::at("name", "is empty"));
        }
        let collection = string(object, "collection")?;
        didbot_lexicon::nsid_syntax::validate(collection)
            .map_err(|error| InvalidRecord::at("collection", format!("is not an nsid: {error}")))?;
        Ok(Self {
            name: name.to_owned(),
            accounts: Accounts::parse(string(object, "accounts")?),
            collection: collection.to_owned(),
            rkey: optional_string(object, "rkey")?.map(str::to_owned),
        })
    }

    /// The entry as it appears inside a record.
    #[must_use]
    pub fn to_json(&self) -> Value {
        let mut value = json!({
            "name": self.name,
            "accounts": self.accounts.as_str(),
            "collection": self.collection,
        });
        if let Some(rkey) = &self.rkey {
            value["rkey"] = Value::String(rkey.clone());
        }
        value
    }

    /// The at-uri this lookup reads in `did`'s repository: the record, or
    /// the collection when it names no key.
    #[must_use]
    pub fn uri(&self, did: &str) -> String {
        match &self.rkey {
            Some(rkey) => format!("at://{did}/{}/{rkey}", self.collection),
            None => format!("at://{did}/{}", self.collection),
        }
    }
}

impl PolicyRecord {
    /// Parses a `bot.did.policy` record's `value` object.
    pub fn from_json(value: &Value) -> Result<Self, InvalidRecord> {
        let object = object(value, "")?;
        typed_as(object, POLICY_COLLECTION)?;
        only_fields(object, POLICY_FIELDS, "a `bot.did.policy` record")?;

        let actions = array(object, "actions")?
            .iter()
            .enumerate()
            .map(|(at, entry)| {
                let path = index("actions", at);
                entry
                    .as_str()
                    .map(Action::parse)
                    .ok_or_else(|| expected("a string", entry, &path))
            })
            .collect::<Result<Vec<_>, _>>()?;
        if actions.is_empty() {
            return Err(InvalidRecord::at("actions", "names no action"));
        }

        let document = Document::from_json(required(object, "document")?)
            .map_err(|error| error.under("document"))?;

        let lookups = match object.get("lookups") {
            None => Vec::new(),
            Some(_) => array(object, "lookups")?
                .iter()
                .enumerate()
                .map(|(at, entry)| {
                    Lookup::from_json(entry).map_err(|error| error.under(&index("lookups", at)))
                })
                .collect::<Result<Vec<_>, _>>()?,
        };
        let mut seen = std::collections::HashSet::new();
        for (at, lookup) in lookups.iter().enumerate() {
            if !seen.insert(lookup.name.as_str()) {
                return Err(InvalidRecord::at(
                    &index("lookups", at),
                    format!(
                        "names `{}`, which an earlier entry already names",
                        lookup.name
                    ),
                ));
            }
        }

        Ok(Self {
            name: optional_string(object, "name")?.map(str::to_owned),
            description: optional_string(object, "description")?.map(str::to_owned),
            actions,
            document,
            lookups,
            created_at: datetime(object, "createdAt")?,
        })
    }

    /// The record body, field for field what [`Self::from_json`] reads.
    #[must_use]
    pub fn to_json(&self) -> Value {
        let mut value = json!({
            "$type": POLICY_COLLECTION,
            "actions": self.actions.iter().map(Action::as_str).collect::<Vec<_>>(),
            "document": self.document.to_json(),
            "createdAt": didbot_schema::format::datetime::render(self.created_at),
        });
        if let Some(name) = &self.name {
            value["name"] = Value::String(name.clone());
        }
        if let Some(description) = &self.description {
            value["description"] = Value::String(description.clone());
        }
        if !self.lookups.is_empty() {
            value["lookups"] = Value::Array(self.lookups.iter().map(Lookup::to_json).collect());
        }
        value
    }

    /// What a refusal calls this policy: its `name`, or `key` — the record
    /// key it was written at — when it has none.
    #[must_use]
    pub fn display_name<'a>(&'a self, key: &'a str) -> &'a str {
        self.name.as_deref().unwrap_or(key)
    }
}

/// One `bot.did.policy` record a binding names, by the repository it is
/// in and its record key: the parts of the `at://` URI it is written as.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct PolicyRef {
    /// The DID of the repository the policy is written in.
    pub repository: String,
    /// The policy's record key in that repository.
    pub key: String,
}

impl PolicyRef {
    /// The URI this reference is written as.
    #[must_use]
    pub fn uri(&self) -> String {
        format!("at://{}/{POLICY_COLLECTION}/{}", self.repository, self.key)
    }
}

impl std::fmt::Display for PolicyRef {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.uri())
    }
}

/// One `bot.did.policyBinding` record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyBinding {
    /// The policies bound, each by URI.
    pub policies: Vec<PolicyRef>,
    /// The accounts the binding starts from, by DID. A server's own
    /// service DID stands for the whole server.
    pub subjects: Vec<String>,
    /// Which accounts, relative to the subjects, the policies reach.
    pub includes: Includes,
    /// Accounts the policies do not apply to, nor to anything admitted
    /// beneath them.
    pub excludes: Vec<String>,
    /// When the operator wrote the record.
    pub created_at: OffsetDateTime,
}

/// The set a binding's `includes` names. At least one member is set, and
/// the set with every member set writes every word the reader accepts.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Includes {
    /// The subjects themselves.
    pub subjects: bool,
    /// Every account admitted beneath a subject.
    pub descendants: bool,
}

impl Includes {
    /// Reads the `includes` array. Paths in a failure are relative to the
    /// record.
    fn from_json(object: &Map<String, Value>) -> Result<Self, InvalidRecord> {
        let mut includes = Self {
            subjects: false,
            descendants: false,
        };
        for (at, entry) in array(object, "includes")?.iter().enumerate() {
            let path = index("includes", at);
            match entry.as_str() {
                Some(SUBJECTS) => includes.subjects = true,
                Some(DESCENDANTS) => includes.descendants = true,
                Some(other) => {
                    return Err(InvalidRecord::at(
                        &path,
                        format!("`{other}` is neither `{SUBJECTS}` nor `{DESCENDANTS}`"),
                    ))
                }
                None => return Err(expected("a string", entry, &path)),
            }
        }
        if !includes.subjects && !includes.descendants {
            return Err(InvalidRecord::at("includes", "names nobody"));
        }
        Ok(includes)
    }

    /// The set as it appears inside a record.
    #[must_use]
    pub fn to_json(self) -> Value {
        let mut members = Vec::new();
        if self.subjects {
            members.push(SUBJECTS);
        }
        if self.descendants {
            members.push(DESCENDANTS);
        }
        json!(members)
    }
}

impl PolicyBinding {
    /// Parses a `bot.did.policyBinding` record's `value` object.
    pub fn from_json(value: &Value) -> Result<Self, InvalidRecord> {
        let object = object(value, "")?;
        typed_as(object, BINDING_COLLECTION)?;
        only_fields(object, BINDING_FIELDS, "a `bot.did.policyBinding` record")?;

        let policies = array(object, "policies")?
            .iter()
            .enumerate()
            .map(|(at, entry)| policy_ref(entry, &index("policies", at)))
            .collect::<Result<Vec<_>, _>>()?;
        if policies.is_empty() {
            return Err(InvalidRecord::at("policies", "names no policy"));
        }

        let subjects = dids(object, "subjects")?;
        if subjects.is_empty() {
            return Err(InvalidRecord::at("subjects", "names nobody"));
        }

        let includes = Includes::from_json(object)?;
        let excludes = if object.contains_key("excludes") {
            dids(object, "excludes")?
        } else {
            Vec::new()
        };

        Ok(Self {
            policies,
            subjects,
            includes,
            excludes,
            created_at: datetime(object, "createdAt")?,
        })
    }

    /// The record body, field for field what [`Self::from_json`] reads.
    #[must_use]
    pub fn to_json(&self) -> Value {
        let mut value = json!({
            "$type": BINDING_COLLECTION,
            "policies": self.policies.iter().map(PolicyRef::uri).collect::<Vec<_>>(),
            "subjects": self.subjects,
            "includes": self.includes.to_json(),
            "createdAt": didbot_schema::format::datetime::render(self.created_at),
        });
        if !self.excludes.is_empty() {
            value["excludes"] = json!(self.excludes);
        }
        value
    }
}

// ---------------------------------------------------------------------------
// JSON field readers, each naming the field it failed at
// ---------------------------------------------------------------------------

/// Refuses a `$type` naming anything but `collection`. A record listed out
/// of a repository carries its collection as `$type`; a record body built
/// by hand may omit it.
fn typed_as(object: &Map<String, Value>, collection: &str) -> Result<(), InvalidRecord> {
    match object.get("$type") {
        None => Ok(()),
        Some(Value::String(named)) if named == collection => Ok(()),
        Some(other) => Err(InvalidRecord::at(
            "$type",
            format!("is {other}, not `{collection}`"),
        )),
    }
}

/// Refuses any field of `object` outside `declared` (and `$type`).
fn only_fields(
    object: &Map<String, Value>,
    declared: &[&str],
    what: &str,
) -> Result<(), InvalidRecord> {
    for name in object.keys() {
        if name != "$type" && !declared.contains(&name.as_str()) {
            return Err(InvalidRecord::at(
                name,
                format!("is not a field {what} declares"),
            ));
        }
    }
    Ok(())
}

fn expected(what: &str, found: &Value, path: &str) -> InvalidRecord {
    InvalidRecord::at(path, format!("expected {what}, found {}", kind_of(found)))
}

fn object<'a>(value: &'a Value, path: &str) -> Result<&'a Map<String, Value>, InvalidRecord> {
    value
        .as_object()
        .ok_or_else(|| expected("an object", value, path))
}

fn required<'a>(object: &'a Map<String, Value>, name: &str) -> Result<&'a Value, InvalidRecord> {
    object
        .get(name)
        .ok_or_else(|| InvalidRecord::at(name, "is required and is missing"))
}

fn string<'a>(object: &'a Map<String, Value>, name: &str) -> Result<&'a str, InvalidRecord> {
    let value = required(object, name)?;
    value
        .as_str()
        .ok_or_else(|| expected("a string", value, name))
}

fn optional_string<'a>(
    object: &'a Map<String, Value>,
    name: &str,
) -> Result<Option<&'a str>, InvalidRecord> {
    match object.get(name) {
        None => Ok(None),
        Some(_) => string(object, name).map(Some),
    }
}

fn array<'a>(object: &'a Map<String, Value>, name: &str) -> Result<&'a [Value], InvalidRecord> {
    let value = required(object, name)?;
    value
        .as_array()
        .map(Vec::as_slice)
        .ok_or_else(|| expected("an array", value, name))
}

/// Reads an array of DIDs at `name`.
fn dids(object: &Map<String, Value>, name: &str) -> Result<Vec<String>, InvalidRecord> {
    array(object, name)?
        .iter()
        .enumerate()
        .map(|(at, entry)| did(entry, &index(name, at)))
        .collect()
}

fn did(value: &Value, path: &str) -> Result<String, InvalidRecord> {
    let text = value
        .as_str()
        .ok_or_else(|| expected("a string", value, path))?;
    didbot_identity::validate_did(text)
        .map_err(|error| InvalidRecord::at(path, format!("is not a did: {error}")))?;
    Ok(text.to_owned())
}

/// Reads one `policies` entry: an `at://` URI naming a `bot.did.policy`
/// record by the DID of its repository and its record key.
fn policy_ref(value: &Value, path: &str) -> Result<PolicyRef, InvalidRecord> {
    let text = value
        .as_str()
        .ok_or_else(|| expected("a string", value, path))?;
    let uri = didbot_schema::AtUri::parse(text)
        .map_err(|error| InvalidRecord::at(path, format!("is not an at-uri: {error}")))?;
    let repository = uri.authority();
    if didbot_identity::validate_did(repository).is_err() {
        return Err(InvalidRecord::at(
            path,
            format!("names its repository by the handle `{repository}`, not by did"),
        ));
    }
    match uri.collection() {
        Some(POLICY_COLLECTION) => {}
        Some(other) => {
            return Err(InvalidRecord::at(
                path,
                format!("names a `{other}` record, not a `{POLICY_COLLECTION}`"),
            ))
        }
        None => {
            return Err(InvalidRecord::at(
                path,
                format!("names a repository, not a `{POLICY_COLLECTION}` record"),
            ))
        }
    }
    let key = uri.rkey().ok_or_else(|| {
        InvalidRecord::at(
            path,
            format!("names the `{POLICY_COLLECTION}` collection, not a record in it"),
        )
    })?;
    Ok(PolicyRef {
        repository: repository.to_owned(),
        key: key.to_owned(),
    })
}

fn datetime(object: &Map<String, Value>, name: &str) -> Result<OffsetDateTime, InvalidRecord> {
    let text = string(object, name)?;
    OffsetDateTime::parse(text, &Rfc3339)
        .map_err(|error| InvalidRecord::at(name, format!("is not an RFC 3339 datetime: {error}")))
}

fn index(path: &str, at: usize) -> String {
    format!("{path}[{at}]")
}

fn kind_of(value: &Value) -> &'static str {
    match value {
        Value::Null => "null",
        Value::Bool(_) => "a boolean",
        Value::Number(_) => "a number",
        Value::String(_) => "a string",
        Value::Array(_) => "an array",
        Value::Object(_) => "an object",
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use didbot_schema::validate_shape;

    /// The repository every fixture binding lives in.
    const OPERATOR: &str = "did:web:operator.example.com";

    /// The URI of `key` in the operator's `bot.did.policy` collection.
    fn policy_uri(key: &str) -> String {
        format!("at://{OPERATOR}/{POLICY_COLLECTION}/{key}")
    }

    /// A well-formed policy, as the operator's repository would hold it.
    fn policy() -> Value {
        json!({
            "name": "fixed-display-name",
            "description": "an agent keeps the display name it was given",
            "actions": ["record.write"],
            "document": {
                "$type": REGEX_DOCUMENT,
                "statements": [{
                    "kind": "denyPathChange",
                    "collection": "^app\\.bsky\\.actor\\.profile$",
                    "path": "^displayName$",
                    "reason": "the display name is fixed",
                }],
            },
            "createdAt": "2026-08-25T10:00:00Z",
        })
    }

    /// A well-formed binding, as the operator's repository would hold it.
    fn binding() -> Value {
        json!({
            "policies": [policy_uri("fixed-display-name"), policy_uri("3jzfcijpj2z2a")],
            "subjects": ["did:web:pool.agents.example.com"],
            "includes": ["descendants"],
            "excludes": ["did:web:kestrel.agents.example.com"],
            "createdAt": "2026-08-25T10:00:00Z",
        })
    }

    /// Both checks, in the order a record meets them.
    fn accept_policy(value: &Value) -> PolicyRecord {
        validate_shape(POLICY_COLLECTION, value).expect("satisfies the lexicon");
        PolicyRecord::from_json(value).expect("parses")
    }

    fn accept_binding(value: &Value) -> PolicyBinding {
        validate_shape(BINDING_COLLECTION, value).expect("satisfies the lexicon");
        PolicyBinding::from_json(value).expect("parses")
    }

    fn without_type(mut value: Value) -> Value {
        value.as_object_mut().expect("an object").remove("$type");
        value
    }

    #[test]
    fn a_policy_round_trips_through_its_wire_type() {
        let parsed = accept_policy(&policy());
        assert_eq!(parsed.actions, vec![Action::RecordWrite]);
        assert!(
            matches!(parsed.document, Document::Regex { ref statements } if statements.len() == 1)
        );
        assert_eq!(parsed.display_name("rkey"), "fixed-display-name");
        let written = parsed.to_json();
        assert_eq!(written["$type"], POLICY_COLLECTION);
        assert_eq!(without_type(written.clone()), policy());
        assert_eq!(accept_policy(&written), parsed);
    }

    #[test]
    fn a_cedar_policy_round_trips_and_a_nameless_one_is_called_by_its_key() {
        let value = json!({
            "actions": ["record.write", "oauth.authorize"],
            "document": {
                "$type": CEDAR_DOCUMENT,
                "source": "forbid(principal, action, resource);",
            },
            "createdAt": "2026-08-25T10:00:00Z",
        });
        let parsed = accept_policy(&value);
        assert_eq!(
            parsed.document,
            Document::Cedar {
                source: "forbid(principal, action, resource);".to_owned()
            }
        );
        assert_eq!(parsed.display_name("3jzfcijpj2z2a"), "3jzfcijpj2z2a");
        assert_eq!(without_type(parsed.to_json()), value);
    }

    #[test]
    fn a_binding_round_trips_through_its_wire_type() {
        let parsed = accept_binding(&binding());
        assert_eq!(
            parsed.policies[0],
            PolicyRef {
                repository: OPERATOR.to_owned(),
                key: "fixed-display-name".to_owned()
            }
        );
        assert_eq!(parsed.policies[0].uri(), policy_uri("fixed-display-name"));
        assert_eq!(
            parsed.includes,
            Includes {
                subjects: false,
                descendants: true
            }
        );
        assert_eq!(parsed.excludes.len(), 1);
        let written = parsed.to_json();
        assert_eq!(written["$type"], BINDING_COLLECTION);
        assert_eq!(without_type(written.clone()), binding());
        assert_eq!(accept_binding(&written), parsed);
    }

    #[test]
    fn a_field_neither_record_declares_is_refused() {
        let mut value = policy();
        value["engine"] = json!("regex");
        validate_shape(POLICY_COLLECTION, &value).expect("the lexicon's object is open");
        let error = PolicyRecord::from_json(&value).expect_err("an undeclared field");
        assert_eq!(error.path, "engine");

        let mut value = binding();
        value["audience"] = json!(["did:web:agents.example.com"]);
        let error = PolicyBinding::from_json(&value).expect_err("an undeclared field");
        assert_eq!(error.path, "audience");
    }

    #[test]
    fn a_type_naming_another_collection_is_refused() {
        let mut value = policy();
        value["$type"] = json!(BINDING_COLLECTION);
        let error = PolicyRecord::from_json(&value).expect_err("the wrong collection");
        assert_eq!(error.path, "$type");
    }

    #[test]
    fn an_action_outside_the_known_values_is_carried() {
        let mut value = policy();
        value["actions"] = json!(["record.write", "account.lifecycle"]);
        let parsed = accept_policy(&value);
        assert_eq!(
            parsed.actions[1],
            Action::Other("account.lifecycle".to_owned())
        );
        assert_eq!(parsed.actions[1].as_str(), "account.lifecycle");
    }

    /// A `lookups` entry round-trips, and a lookup with no `rkey` reads the
    /// whole collection rather than a record named by the empty key.
    #[test]
    fn a_lookup_round_trips_and_says_which_uri_it_reads() {
        let mut value = policy();
        value["lookups"] = json!([
            {
                "name": "declaredAiPreference",
                "accounts": "named",
                "collection": "community.lexicon.preference.ai",
            },
            {
                "name": "replyGate",
                "accounts": "named",
                "collection": "app.bsky.feed.threadgate",
                "rkey": "3lbwaaaaaaa2a",
            },
        ]);
        let parsed = accept_policy(&value);
        assert_eq!(
            parsed.lookups[0].uri("did:web:person.example"),
            "at://did:web:person.example/community.lexicon.preference.ai"
        );
        assert_eq!(
            parsed.lookups[1].uri("did:web:person.example"),
            "at://did:web:person.example/app.bsky.feed.threadgate/3lbwaaaaaaa2a"
        );
        assert_eq!(parsed.lookups[0].accounts, Accounts::Named);
        assert_eq!(without_type(parsed.to_json()), value);
    }

    /// Two entries under one name would leave a statement naming one of
    /// them and getting whichever the write path attached last.
    #[test]
    fn two_lookups_under_one_name_are_refused() {
        let mut value = policy();
        let entry = json!({
            "name": "declaredAiPreference",
            "accounts": "named",
            "collection": "community.lexicon.preference.ai",
        });
        value["lookups"] = json!([entry, entry]);
        validate_shape(POLICY_COLLECTION, &value).expect("satisfies the lexicon");
        let refused = PolicyRecord::from_json(&value).expect_err("two entries share a name");
        assert_eq!(refused.path, "lookups[1]");
    }

    #[test]
    fn a_policy_naming_no_action_is_refused_by_both_checks() {
        let mut value = policy();
        value["actions"] = json!([]);
        assert!(validate_shape(POLICY_COLLECTION, &value).is_err());
        let error = PolicyRecord::from_json(&value).expect_err("no action");
        assert_eq!(error.path, "actions");

        value["actions"] = json!([7]);
        let error = PolicyRecord::from_json(&value).expect_err("not a string");
        assert_eq!(error.path, "actions[0]");
    }

    #[test]
    fn a_document_without_a_type_is_refused_by_both_checks() {
        let mut value = policy();
        value["document"] = json!({ "statements": [{}] });
        assert!(validate_shape(POLICY_COLLECTION, &value).is_err());
        let error = PolicyRecord::from_json(&value).expect_err("no $type");
        assert_eq!(error.path, "document.$type");

        value["document"] = json!("forbid(principal, action, resource);");
        let error = PolicyRecord::from_json(&value).expect_err("not an object");
        assert_eq!(error.path, "document");
    }

    #[test]
    fn a_regex_document_holds_statements_and_nothing_else() {
        let mut value = policy();
        value["document"] = json!({ "$type": REGEX_DOCUMENT, "statements": [] });
        assert!(validate_shape(POLICY_COLLECTION, &value).is_err());
        let error = PolicyRecord::from_json(&value).expect_err("no statements");
        assert_eq!(error.path, "document.statements");

        value["document"] = json!({ "$type": REGEX_DOCUMENT });
        let error = PolicyRecord::from_json(&value).expect_err("statements missing");
        assert_eq!(error.path, "document.statements");

        value["document"] = json!({ "$type": REGEX_DOCUMENT, "statements": [{}], "source": "x" });
        let error = PolicyRecord::from_json(&value).expect_err("a cedar field");
        assert_eq!(error.path, "document.source");
    }

    #[test]
    fn a_cedar_document_holds_its_source_and_nothing_else() {
        let mut value = policy();
        value["document"] = json!({ "$type": CEDAR_DOCUMENT });
        assert!(validate_shape(POLICY_COLLECTION, &value).is_err());
        let error = PolicyRecord::from_json(&value).expect_err("source missing");
        assert_eq!(error.path, "document.source");

        value["document"] = json!({ "$type": CEDAR_DOCUMENT, "source": "x", "statements": [] });
        let error = PolicyRecord::from_json(&value).expect_err("a regex field");
        assert_eq!(error.path, "document.statements");
    }

    #[test]
    fn a_document_of_an_unknown_type_is_carried_by_its_type() {
        let mut value = policy();
        value["document"] = json!({ "$type": "bot.did.policy#regex2", "statements": [{}] });
        let parsed = accept_policy(&value);
        assert_eq!(
            parsed.document,
            Document::Other {
                r#type: "bot.did.policy#regex2".to_owned()
            }
        );
        assert_eq!(parsed.document.type_name(), "bot.did.policy#regex2");
    }

    /// A policy is named by the URI of a `bot.did.policy` record, with its
    /// repository given by DID. The lexicon checks only that it is a URI;
    /// the reader checks what it names.
    #[test]
    fn a_policy_is_named_by_the_uri_of_a_policy_record() {
        let mut value = binding();
        value["policies"] = json!(["fixed-display-name"]);
        assert!(validate_shape(BINDING_COLLECTION, &value).is_err());
        let error = PolicyBinding::from_json(&value).expect_err("a bare record key");
        assert_eq!(error.path, "policies[0]");

        for (uri, names) in [
            (
                format!("at://{OPERATOR}/{BINDING_COLLECTION}/x"),
                BINDING_COLLECTION,
            ),
            (format!("at://{OPERATOR}"), "a repository"),
            (
                format!("at://{OPERATOR}/{POLICY_COLLECTION}"),
                "not a record",
            ),
            (
                format!("at://operator.example.com/{POLICY_COLLECTION}/x"),
                "handle",
            ),
        ] {
            value["policies"] = json!([uri]);
            validate_shape(BINDING_COLLECTION, &value).expect("a well-formed at-uri");
            let error = PolicyBinding::from_json(&value).expect_err(&uri);
            assert_eq!(error.path, "policies[0]", "{uri}");
            assert!(error.reason.contains(names), "{uri}: {}", error.reason);
        }

        value["policies"] = json!(["at://did:plc:other/bot.did.policy/x"]);
        let parsed = accept_binding(&value);
        assert_eq!(parsed.policies[0].repository, "did:plc:other");
        assert_eq!(parsed.policies[0].key, "x");

        value["policies"] = json!([]);
        let error = PolicyBinding::from_json(&value).expect_err("no policy");
        assert_eq!(error.path, "policies");
    }

    #[test]
    fn a_subject_or_exclusion_that_is_not_a_did_is_refused_by_both_checks() {
        let mut value = binding();
        value["subjects"] = json!(["pool.agents.example.com"]);
        assert!(validate_shape(BINDING_COLLECTION, &value).is_err());
        let error = PolicyBinding::from_json(&value).expect_err("not a did");
        assert_eq!(error.path, "subjects[0]");

        let mut value = binding();
        value["excludes"] = json!(["did:web:ok.example", "kestrel"]);
        let error = PolicyBinding::from_json(&value).expect_err("not a did");
        assert_eq!(error.path, "excludes[1]");

        let mut value = binding();
        value["subjects"] = json!([]);
        let error = PolicyBinding::from_json(&value).expect_err("nobody");
        assert_eq!(error.path, "subjects");
    }

    #[test]
    fn includes_is_a_non_empty_set_of_two_words() {
        let mut value = binding();
        value["includes"] = json!([]);
        assert!(validate_shape(BINDING_COLLECTION, &value).is_err());
        let error = PolicyBinding::from_json(&value).expect_err("nobody");
        assert_eq!(error.path, "includes");

        value["includes"] = json!(["self"]);
        validate_shape(BINDING_COLLECTION, &value).expect("the lexicon leaves the words open");
        let error = PolicyBinding::from_json(&value).expect_err("an old word");
        assert_eq!(error.path, "includes[0]");
        assert!(error.reason.contains("`self`"), "{}", error.reason);

        value["includes"] = json!(["subjects", "subjects"]);
        let parsed = accept_binding(&value);
        assert_eq!(
            parsed.includes,
            Includes {
                subjects: true,
                descendants: false
            }
        );
        assert_eq!(parsed.includes.to_json(), json!(["subjects"]));

        value["includes"] = json!(["descendants", "subjects"]);
        let parsed = accept_binding(&value);
        assert_eq!(
            parsed.includes.to_json(),
            json!(["subjects", "descendants"])
        );
    }

    #[test]
    fn a_binding_without_exclusions_writes_none() {
        let mut value = binding();
        value.as_object_mut().expect("an object").remove("excludes");
        let parsed = accept_binding(&value);
        assert!(parsed.excludes.is_empty());
        assert!(parsed.to_json().get("excludes").is_none());
    }

    #[test]
    fn a_missing_required_field_names_itself() {
        for (collection, sample, field) in [
            (POLICY_COLLECTION, policy(), "actions"),
            (POLICY_COLLECTION, policy(), "document"),
            (POLICY_COLLECTION, policy(), "createdAt"),
            (BINDING_COLLECTION, binding(), "policies"),
            (BINDING_COLLECTION, binding(), "subjects"),
            (BINDING_COLLECTION, binding(), "includes"),
            (BINDING_COLLECTION, binding(), "createdAt"),
        ] {
            let mut value = sample;
            value.as_object_mut().expect("an object").remove(field);
            assert!(validate_shape(collection, &value).is_err(), "{field}");
            let error = match collection {
                POLICY_COLLECTION => PolicyRecord::from_json(&value).map(|_| ()),
                _ => PolicyBinding::from_json(&value).map(|_| ()),
            }
            .expect_err(field);
            assert_eq!(error.path, field);
        }
    }
}