didbot_policy_cedar/

load.rs

//! Loading a document: Cedar splits it into statements, and this module
//! holds each to the three rules `plan/cedar-engine.md` sets — every
//! statement carries a unique `@id`, every statement is a forbid with a
//! `@reason`, and every statement validates in strict mode against the
//! schema of each collection it can reach.

use std::collections::{BTreeSet, HashSet};
use std::str::FromStr;

use cedar_policy::{
    ActionConstraint, Effect, Policy, PolicyId, PolicySet, PrincipalConstraint, ValidationMode,
};
use serde_json::Value;

use crate::schema::{ActionName, Shapes};

/// The id of the `permit(principal, action, resource)` the server adds
/// beside every document, so that a document's forbids are the only thing
/// that can turn a request down. Reserved: a statement may not use it.
pub const BASELINE_ID: &str = "baseline";

/// How much a statement's scope says about `principal`, and therefore how
/// much the gate must know about the account for the statement to be
/// judged at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum PrincipalNeed {
    /// `principal` is unconstrained.
    Nothing,
    /// `principal ==` or `principal is`: the account's identity.
    Identity,
    /// `principal in`: the account's admission chain.
    Chain,
}

impl PrincipalNeed {
    fn of(constraint: &PrincipalConstraint) -> Self {
        match constraint {
            PrincipalConstraint::Any => PrincipalNeed::Nothing,
            PrincipalConstraint::Eq(_) | PrincipalConstraint::Is(_) => PrincipalNeed::Identity,
            PrincipalConstraint::In(_) | PrincipalConstraint::IsIn(..) => PrincipalNeed::Chain,
        }
    }
}

impl std::fmt::Display for PrincipalNeed {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(match self {
            PrincipalNeed::Nothing => "nothing about the account",
            PrincipalNeed::Identity => "the account's identity",
            PrincipalNeed::Chain => "the account's admission chain",
        })
    }
}

/// One loaded forbid.
#[derive(Debug, Clone)]
pub struct Statement {
    id: String,
    reason: String,
    source: String,
    actions: BTreeSet<ActionName>,
    principal: PrincipalNeed,
    collections: BTreeSet<String>,
    pools: BTreeSet<String>,
    reads_record: bool,
    reads_client: bool,
    policy: Policy,
}

impl Statement {
    /// The statement's `@id`.
    #[must_use]
    pub fn id(&self) -> &str {
        &self.id
    }

    /// The statement's `@reason`: what a caller is told when it fires.
    #[must_use]
    pub fn reason(&self) -> &str {
        &self.reason
    }

    /// The statement's own text, annotations included, loadable on its own.
    #[must_use]
    pub fn source(&self) -> &str {
        &self.source
    }

    /// The actions the statement's scope admits. A statement with an
    /// unconstrained `action` admits every one.
    #[must_use]
    pub fn actions(&self) -> &BTreeSet<ActionName> {
        &self.actions
    }

    /// What the statement's scope needs to know about the account.
    #[must_use]
    pub fn principal(&self) -> PrincipalNeed {
        self.principal
    }

    /// The collections the statement compares `resource.collection` to.
    /// Empty when it names none, which is not the same as applying to
    /// none: applicability is the gate's business, this is only what the
    /// loader can see.
    #[must_use]
    pub fn collections(&self) -> &BTreeSet<String> {
        &self.collections
    }

    /// The pools the statement compares `resource.pool` to, by `==`, `!=`
    /// or `[..].contains`.
    #[must_use]
    pub fn pools(&self) -> &BTreeSet<String> {
        &self.pools
    }

    /// Whether the statement reads `context.value` or `context.existing`,
    /// the two things only a collection's shape can type.
    #[must_use]
    pub fn reads_record(&self) -> bool {
        self.reads_record
    }

    /// Whether the statement reads or tests `context.client`, the client
    /// a `record.write` was made through.
    #[must_use]
    pub fn reads_client(&self) -> bool {
        self.reads_client
    }
}

/// Why one statement, or the document as a whole, did not load.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Failure {
    /// The statement's `@id`, its position as `#n` when it has no id, or
    /// `document` when the failure is not one statement's.
    pub statement: String,
    /// What was wrong.
    pub reason: String,
}

impl std::fmt::Display for Failure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}: {}", self.statement, self.reason)
    }
}

/// A document that did not load. Every failure the loader found, so the
/// dashboard shows all of them at once.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoadError {
    /// Each failure, in document order.
    pub failures: Vec<Failure>,
}

impl LoadError {
    fn one(statement: impl Into<String>, reason: impl Into<String>) -> Self {
        Self {
            failures: vec![Failure {
                statement: statement.into(),
                reason: reason.into(),
            }],
        }
    }

    /// Whether some failure names `statement`.
    #[must_use]
    pub fn names(&self, statement: &str) -> bool {
        self.failures.iter().any(|f| f.statement == statement)
    }
}

impl std::fmt::Display for LoadError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        for (index, failure) in self.failures.iter().enumerate() {
            if index > 0 {
                f.write_str("; ")?;
            }
            write!(f, "{failure}")?;
        }
        Ok(())
    }
}

impl std::error::Error for LoadError {}

/// A loaded document: its statements keyed by `@id`, and the policy set
/// the authorizer runs, which is those statements plus the baseline permit.
#[derive(Debug, Clone)]
pub struct Document {
    pub(crate) statements: Vec<Statement>,
    pub(crate) set: PolicySet,
    warnings: Vec<String>,
}

impl Document {
    /// Load `source` against `shapes`.
    ///
    /// # Errors
    ///
    /// Every rule the document breaks, each naming its statement.
    pub fn load(source: &str, shapes: &Shapes) -> Result<Self, LoadError> {
        let parsed = PolicySet::from_str(source)
            .map_err(|error| LoadError::one("document", format!("does not parse: {error}")))?;
        let mut failures = Vec::new();
        if parsed.templates().next().is_some() {
            failures.push(Failure {
                statement: "document".to_owned(),
                reason: "holds a template; a document is static forbids only".to_owned(),
            });
        }

        let mut seen = HashSet::new();
        let mut statements = Vec::new();
        for (position, policy) in parsed.policies().enumerate() {
            let label = format!("#{}", position + 1);
            let Some(id) = policy.annotation("id") else {
                failures.push(Failure {
                    statement: label,
                    reason: "has no @id".to_owned(),
                });
                continue;
            };
            let id = id.to_owned();
            if id == BASELINE_ID {
                failures.push(Failure {
                    statement: label,
                    reason: format!("@id(\"{BASELINE_ID}\") is reserved for the server's permit"),
                });
                continue;
            }
            if !seen.insert(id.clone()) {
                failures.push(Failure {
                    statement: label,
                    reason: format!("@id(\"{id}\") is already used by an earlier statement"),
                });
                continue;
            }
            if policy.effect() == Effect::Permit {
                failures.push(Failure {
                    statement: id,
                    reason: "is a permit; a document may only forbid".to_owned(),
                });
                continue;
            }
            let Some(reason) = policy.annotation("reason") else {
                failures.push(Failure {
                    statement: id,
                    reason: "has no @reason".to_owned(),
                });
                continue;
            };
            let actions = match actions_of(&policy.action_constraint()) {
                Ok(actions) => actions,
                Err(unknown) => {
                    failures.push(Failure {
                        statement: id,
                        reason: format!(
                            "names `{unknown}`, which is not one of this server's actions"
                        ),
                    });
                    continue;
                }
            };
            let Some(source) = policy.to_cedar() else {
                failures.push(Failure {
                    statement: id,
                    reason: "has no source text of its own".to_owned(),
                });
                continue;
            };
            let policy = policy.new_id(PolicyId::new(&id));
            let mut collections = BTreeSet::new();
            let mut pools = BTreeSet::new();
            let mut reads_record = false;
            let mut reads_client = false;
            if let Ok(est) = policy.to_json() {
                compared_to(&est, "collection", &["=="], &mut collections);
                compared_to(&est, "pool", &["==", "!="], &mut pools);
                reads_record = reads_context(&est, &["value", "existing"]);
                reads_client = reads_context(&est, &["client"]);
            }
            statements.push(Statement {
                reason: reason.to_owned(),
                source,
                actions,
                principal: PrincipalNeed::of(&policy.principal_constraint()),
                collections,
                pools,
                reads_record,
                reads_client,
                policy,
                id,
            });
        }
        if !failures.is_empty() {
            return Err(LoadError { failures });
        }

        let mut warnings = Vec::new();
        for statement in &statements {
            let alone = PolicySet::from_policies([statement.policy.clone()])
                .expect("a set of one freshly relabelled policy");
            for collection in unvalidated_for(statement, shapes) {
                warnings.push(format!(
                    "{}: unvalidated for {collection}; a field it reads there is checked \
                     at the first write, not here",
                    statement.id
                ));
            }
            for (collection, validator) in validation_targets(statement, shapes) {
                let result = validator.validate(&alone, ValidationMode::Strict);
                let against = collection.map_or(String::new(), |c| format!("for `{c}`: "));
                for error in result.validation_errors() {
                    failures.push(Failure {
                        statement: statement.id.clone(),
                        reason: format!("{against}{error}"),
                    });
                }
                for warning in result.validation_warnings() {
                    warnings.push(format!("{}: {against}{warning}", statement.id));
                }
            }
        }
        if !failures.is_empty() {
            return Err(LoadError { failures });
        }

        let mut set = PolicySet::from_policies(statements.iter().map(|s| s.policy.clone()))
            .expect("statement ids are unique");
        let baseline = Policy::parse(
            Some(PolicyId::new(BASELINE_ID)),
            "permit(principal, action, resource);",
        )
        .expect("the baseline permit is this crate's own text");
        set.add(baseline)
            .expect("no statement may use the baseline id");
        tracing::debug!(
            statements = statements.len(),
            warnings = warnings.len(),
            "loaded a cedar document"
        );
        Ok(Self {
            statements,
            set,
            warnings,
        })
    }

    /// The statements, in document order.
    #[must_use]
    pub fn statements(&self) -> &[Statement] {
        &self.statements
    }

    /// What the validator had to say without refusing the document.
    #[must_use]
    pub fn warnings(&self) -> &[String] {
        &self.warnings
    }
}

/// The schemas a statement is validated against, each labelled with the
/// collection whose record type it carries (`None` for the base schema).
///
/// A statement that can reach `record.write` is checked against every
/// described collection it names, or every described collection when it
/// names none. One that reaches no described collection, or cannot reach
/// `record.write` at all, is checked against the base schema, where no
/// record type is in play — unless it reads the record, which the base
/// schema cannot type; then nothing checks it, and [`unvalidated_for`]
/// says so.
fn validation_targets<'a>(
    statement: &'a Statement,
    shapes: &'a Shapes,
) -> Vec<(Option<&'a str>, &'a cedar_policy::Validator)> {
    let described: Vec<(Option<&str>, &cedar_policy::Validator)> =
        if !statement.actions.contains(&ActionName::RecordWrite) {
            Vec::new()
        } else if statement.collections.is_empty() {
            shapes
                .collections()
                .filter_map(|c| shapes.validator_for(c).map(|v| (Some(c), v)))
                .collect()
        } else {
            statement
                .collections
                .iter()
                .filter_map(|c| shapes.validator_for(c).map(|v| (Some(c.as_str()), v)))
                .collect()
        };
    if described.is_empty() && !statement.reads_record {
        return vec![(None, shapes.base())];
    }
    described
}

/// The collections a statement reads records of without a shape to check
/// them against, as the warning names them: each undescribed collection it
/// names, or "any collection without a shape" when it names none.
fn unvalidated_for(statement: &Statement, shapes: &Shapes) -> Vec<String> {
    if !statement.reads_record || !statement.actions.contains(&ActionName::RecordWrite) {
        return Vec::new();
    }
    if statement.collections.is_empty() {
        return vec!["any collection without a shape".to_owned()];
    }
    statement
        .collections
        .iter()
        .filter(|c| shapes.shape_of(c).is_none())
        .map(|c| format!("`{c}`"))
        .collect()
}

fn actions_of(constraint: &ActionConstraint) -> Result<BTreeSet<ActionName>, String> {
    let named: Vec<&cedar_policy::EntityUid> = match constraint {
        ActionConstraint::Any => return Ok(ActionName::ALL.into_iter().collect()),
        ActionConstraint::Eq(uid) => vec![uid],
        ActionConstraint::In(uids) => uids.iter().collect(),
    };
    named
        .into_iter()
        .map(|uid| ActionName::of_uid(uid).ok_or_else(|| uid.to_string()))
        .collect()
}

/// Collect every string literal the expression compares `resource.<attr>`
/// to, by one of `ops` on either side or by `[..].contains(resource.<attr>)`.
fn compared_to(est: &Value, attr: &str, ops: &[&str], out: &mut BTreeSet<String>) {
    match est {
        Value::Object(map) => {
            for op in ops {
                let Some(args) = map.get(*op) else { continue };
                for (subject, literal) in [("left", "right"), ("right", "left")] {
                    if args.get(subject).is_some_and(|e| is_resource_attr(e, attr)) {
                        if let Some(name) = args.get(literal).and_then(string_literal) {
                            out.insert(name.to_owned());
                        }
                    }
                }
            }
            if let Some(args) = map.get("contains") {
                if args.get("right").is_some_and(|e| is_resource_attr(e, attr)) {
                    if let Some(Value::Array(items)) = args.get("left").and_then(|s| s.get("Set")) {
                        out.extend(items.iter().filter_map(string_literal).map(str::to_owned));
                    }
                }
            }
            for child in map.values() {
                compared_to(child, attr, ops, out);
            }
        }
        Value::Array(items) => {
            for item in items {
                compared_to(item, attr, ops, out);
            }
        }
        _ => {}
    }
}

/// Whether the expression reads or tests any of `attrs` on `context`.
fn reads_context(est: &Value, attrs: &[&str]) -> bool {
    match est {
        Value::Object(map) => {
            for key in [".", "has"] {
                if let Some(access) = map.get(key) {
                    let on_context = access
                        .get("left")
                        .and_then(|v| v.get("Var"))
                        .and_then(Value::as_str)
                        == Some("context");
                    let attr = access.get("attr").and_then(Value::as_str);
                    if on_context && attr.is_some_and(|attr| attrs.contains(&attr)) {
                        return true;
                    }
                }
            }
            map.values().any(|child| reads_context(child, attrs))
        }
        Value::Array(items) => items.iter().any(|item| reads_context(item, attrs)),
        _ => false,
    }
}

fn is_resource_attr(expr: &Value, attr: &str) -> bool {
    let Some(access) = expr.get(".") else {
        return false;
    };
    access
        .get("left")
        .and_then(|v| v.get("Var"))
        .and_then(Value::as_str)
        == Some("resource")
        && access.get("attr").and_then(Value::as_str) == Some(attr)
}

fn string_literal(expr: &Value) -> Option<&str> {
    expr.get("Value")?.as_str()
}