didbot_policy/

policy.rs

//! What a policy declares about itself, statically — the data the
//! applicability index is built from.
//!
//! `plan/policy.md`: "Split what a policy declares from what it computes.
//! Applicability is static, declarative data — subject kinds, collections,
//! path prefixes, action kinds — and it is what goes in the tree. Evaluation
//! is opaque [...] The core never needs to understand an evaluator's
//! internals, only its declaration."

use crate::outcome::Staleness;
use crate::subject::{AccountKind, SubjectKind, WriteAction};

/// A policy, identified by its position in a [`PolicyTree`](crate::index::PolicyTree).
///
/// Assigned in registration order, which doubles as this server's
/// presentational evaluation order — `plan/policy.md`'s "the order is part
/// of this server's version of the tree, so that the reason reported for a
/// denial is stable."
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct PolicyId(pub(crate) u32);

impl PolicyId {
    /// This policy's position in registration order.
    pub fn index(self) -> u32 {
        self.0
    }
}

/// An evaluator, registered once and referenced by any number of policies.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct EvaluatorId(pub(crate) u32);

/// A compiled predicate, as an evaluator itself names it.
///
/// Minted by [`crate::outcome::Evaluator::compile`] and opaque to this
/// crate beyond equality: not an index, not something this crate can
/// allocate or interpret, because the compiled artifact it names belongs to
/// the evaluator, not the caller. That ownership split is deliberate --
/// see `compile`'s doc comment -- because an evaluator may run out of
/// process, possibly in another language, where a caller-owned handle
/// could only ever be an identifier for state the caller does not hold.
/// [`PolicyId`] is this crate's own bookkeeping, assigned by
/// [`PolicyTreeBuilder`](crate::index::PolicyTreeBuilder) at registration
/// time; `CompiledId` is the evaluator's, assigned at `compile` time, and
/// the two are not interchangeable -- a multi-policy evaluator learns which
/// artifact to use for a subject from `CompiledId`, never from `PolicyId`,
/// which it never sees.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct CompiledId(pub u64);

/// Whether a declarative dimension is unconstrained, or limited to a
/// specific set of values.
///
/// `Any` is not "an empty set of values" — it is the wildcard, matching
/// every value including one the index has never seen. Kept generic rather
/// than repeated per field, since applicability has several such
/// dimensions.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Scope<T> {
    /// Every value matches.
    Any,
    /// Only these values match.
    Only(Vec<T>),
}

impl<T: PartialEq> Scope<T> {
    /// Whether `value` falls inside this scope.
    pub fn matches(&self, value: &T) -> bool {
        match self {
            Scope::Any => true,
            Scope::Only(values) => values.contains(value),
        }
    }
}

/// Which [`WriteAction`]s a write-shaped applicability declaration covers.
///
/// A small closed set, so a bitset rather than a `Vec` — cheap to copy and
/// cheap to test membership in on the hot path.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ActionSet(u8);

const CREATE_BIT: u8 = 0b001;
const UPDATE_BIT: u8 = 0b010;
const DELETE_BIT: u8 = 0b100;

impl ActionSet {
    /// Create, update and delete all match.
    pub const ALL: ActionSet = ActionSet(CREATE_BIT | UPDATE_BIT | DELETE_BIT);

    /// Only the given actions match. `plan/policy.md` takes no position on
    /// what a delete means, so a policy that wants nothing to do with
    /// deletes states that here, explicitly, rather than the core inferring
    /// it from an empty diff.
    pub fn of(actions: &[WriteAction]) -> Self {
        let mut bits = 0u8;
        for action in actions {
            bits |= bit(*action);
        }
        ActionSet(bits)
    }

    /// Whether `action` is in this set.
    pub fn contains(&self, action: WriteAction) -> bool {
        self.0 & bit(action) != 0
    }
}

fn bit(action: WriteAction) -> u8 {
    match action {
        WriteAction::Create => CREATE_BIT,
        WriteAction::Update => UPDATE_BIT,
        WriteAction::Delete => DELETE_BIT,
    }
}

/// Which account kinds a write-shaped applicability declaration covers.
///
/// `plan/policy.md` lists "subject kinds" among applicability's declarative
/// dimensions alongside collections, path prefixes and action kinds; this
/// is that dimension. Filtering here rather than inside every evaluator
/// means a policy that only makes sense for agents routes a host's write
/// past it entirely — the tree walk, not an `Allow` an evaluator had to
/// compute — which keeps the empty-match property doing real work for the
/// kinds a policy does not cover, not just for collections it does not
/// cover.
///
/// # Naming specific kinds does not cover an unrecognized one
///
/// `bot.did.registration`'s `actor` union is open, so a subject can carry a
/// [`SubjectKind::Unknown`] this
/// build has never heard of. [`of`](Self::of) builds a set from named
/// [`AccountKind`]s, and such a set **never** matches an unknown kind, no
/// matter which kinds it names — not even by naming all four.
///
/// This is deliberate, and the conservative-sounding instinct is the
/// opposite: a rule declared over `[Agent]` made a claim about agents. In a
/// deny-only system, silently stretching that claim to cover a kind its
/// author had never seen would deny writes on a premise nobody established
/// — the same shape of mistake as inventing what a delete means instead of
/// routing on an explicit [`WriteAction`]. [`ANY`](Self::ANY) is how an
/// author opts a policy into kinds invented after it was written, and it is
/// the only way to.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct KindSet(Repr);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Repr {
    /// Every kind matches, known or not.
    Any,
    /// Only these named, known kinds match.
    Known(u8),
}

const AGENT_BIT: u8 = 0b0001;
const PIPELINE_BIT: u8 = 0b0010;
const HOST_BIT: u8 = 0b0100;
const SERVICE_BIT: u8 = 0b1000;
const ALL_KNOWN_BITS: u8 = AGENT_BIT | PIPELINE_BIT | HOST_BIT | SERVICE_BIT;

impl KindSet {
    /// All four kinds this build recognizes by name — but, per this type's
    /// doc comment, *not* a kind it does not. For that, use [`ANY`](Self::ANY).
    pub const ALL: KindSet = KindSet(Repr::Known(ALL_KNOWN_BITS));

    /// Every kind matches, including one this build has never heard of. The
    /// explicit opt-in a policy names to cover kinds invented after it was
    /// written.
    pub const ANY: KindSet = KindSet(Repr::Any);

    /// Only the given known kinds match — never an unrecognized one, no
    /// matter which kinds are named.
    pub fn of(kinds: &[AccountKind]) -> Self {
        let mut bits = 0u8;
        for kind in kinds {
            bits |= kind_bit(*kind);
        }
        KindSet(Repr::Known(bits))
    }

    /// Whether `kind` is in this set.
    pub fn contains(&self, kind: SubjectKind<'_>) -> bool {
        match self.0 {
            Repr::Any => true,
            Repr::Known(bits) => match kind {
                SubjectKind::Known(known) => bits & kind_bit(known) != 0,
                // A specific-kind set matches only kinds it named, and it
                // never named this one — it could not have, this build
                // has never seen it.
                SubjectKind::Unknown(_) => false,
            },
        }
    }
}

fn kind_bit(kind: AccountKind) -> u8 {
    match kind {
        AccountKind::Agent => AGENT_BIT,
        AccountKind::Pipeline => PIPELINE_BIT,
        AccountKind::Host => HOST_BIT,
        AccountKind::Service => SERVICE_BIT,
    }
}

/// What a policy statically applies to — the data the tree indexes on.
///
/// One variant per subject shape, matching [`Subject`](crate::subject::Subject).
/// This is used twice per policy: once as its decision surface (what
/// [`evaluate`](crate::evaluate::evaluate) may ask it about) and once,
/// independently, as its observation surface (what
/// [`Evaluator::observe`](crate::outcome::Evaluator::observe) is told
/// about) — see [`PolicyDeclaration`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Applicability {
    /// Applies to writes.
    Write {
        /// Which account kinds. A policy that only makes sense for agents
        /// declares that here, and a host's or a service's write never
        /// reaches its evaluator. See [`KindSet`].
        kinds: KindSet,
        /// Which collections (NSIDs). `Any` for a policy that is not
        /// collection-specific — an application denial, for instance.
        collections: Scope<String>,
        /// Which actions. A policy declaring only [`WriteAction::Delete`]
        /// never sees a create or update, and vice versa.
        actions: ActionSet,
        /// Which changed-path prefixes, matched by splitting on `.` — this
        /// crate's own routing convention, kept separate from whatever
        /// segmentation meaning an evaluator's engine gives
        /// [`Change::path`](crate::subject::Change::path) itself; see that
        /// field's doc comment. `Any` matches the write regardless of its
        /// diff, including one with no changed paths at all.
        path_prefixes: Scope<String>,
    },
    /// Applies to blob uploads.
    Blob,
    /// Applies to pushed authorization requests.
    Grant {
        /// Which applications, by client id. `Any` for a policy that
        /// applies to every requester.
        client_ids: Scope<String>,
    },
    /// Applies to tokens about to be issued: a code exchanged, a refresh
    /// rotated.
    Token {
        /// Which applications, by client id. `Any` for a policy that
        /// applies to every client.
        client_ids: Scope<String>,
    },
    /// Applies to where a new account lands.
    Create,
}

/// What decides this policy's outcome, once its applicability is already
/// established.
///
/// Split from `Applicability` deliberately, because the two fail
/// differently and only one of the failures is a *policy's* failure.
/// `Applicability` is simple declarative data — collections, path
/// prefixes, kinds, actions — that the core itself validates at the
/// boundary, never something an engine interprets. A record whose
/// applicability does not parse is therefore not a malformed policy; it is
/// a malformed record that never becomes a [`PolicyDeclaration`] at all.
/// It enforces nothing, it is surfaced to the operator, and nothing about
/// it is represented anywhere in this crate's types — there is no third
/// state here for it, and there should not be one.
///
/// What *is* real, because a `PolicyDeclaration` can still hold it: the
/// predicate — a regular expression, a hand-rolled matcher, anything an
/// engine actually interprets — fails to parse or load, while its already
/// known-good applicability says exactly what the policy covers. That
/// failure can be scoped the same way an unavailable evaluator's is,
/// denying only the writes it would have judged rather than everything or
/// nothing. [`Unusable`](Self::Unusable) is that state, named rather than
/// left implicit, because a reader needs to tell "this policy denies
/// things because it is broken" apart from "this policy denies things
/// because it says so."
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Predicate {
    /// Applicability and predicate both parsed and compiled; this
    /// evaluator judges it, consulting the artifact named by `CompiledId`
    /// -- see [`CompiledId`]'s doc comment for why that, not [`PolicyId`],
    /// is what an evaluator is handed back at decision time.
    Evaluator(EvaluatorId, CompiledId),
    /// Applicability parsed; the predicate did not. Denies every subject
    /// within this policy's applicability — fail-closed, scoped by the
    /// tree exactly like an [`EvalError`](crate::outcome::EvalError) from
    /// a live evaluator, because from the tree's perspective the two are
    /// the same event at different times: a predicate that cannot be
    /// asked.
    Unusable {
        /// Why the predicate could not be used: bad syntax, an engine this
        /// build does not have, or one that itself failed to load.
        reason: String,
    },
}

/// A policy record's own revision, for detecting a stale observation.
///
/// Policies are independent records and a poll only ever sees a random
/// point of that set — never a snapshot with a version of its own — so a
/// later poll can observe an *older* copy of one particular policy than a
/// previous poll already applied (a slow replica, a retried request
/// racing a fresher one, in any order the transport permits). Applying
/// that older copy over the newer one would silently revert an operator's
/// edit, and in a deny-only system a reversion is a *widening* — the one
/// direction every other property in this crate exists to prevent.
///
/// This crate does not perform that refusal itself: comparing two
/// observations of what is nominally the same policy over *time* is
/// exactly the kind of state this crate has no I/O and no polling to hold
/// — see the crate root's "What is deliberately not here". `Revision` is
/// here because the type that carries one policy's declaration is where
/// the value naturally lives; a loader reading two observations of a
/// policy compares their `Revision`s and refuses to apply the lesser one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Revision(pub u64);

/// One policy: its applicability, its observation surface, its staleness
/// mode, its predicate, and its own revision.
///
/// A policy is not its wrapper — see `plan/policy.md`'s "A policy is not its
/// wrapper". This is the policy itself, already stripped of the
/// transport-shaped metadata (source, format version) that got it here.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PolicyDeclaration {
    /// What this policy may be asked to decide. Feeds the decision tree that
    /// [`PolicyTree::decision_candidates`](crate::index::PolicyTree::decision_candidates)
    /// walks. Simple declarative data, deliberately never delegated to an
    /// engine — see [`Predicate`]'s doc comment for why a
    /// `PolicyDeclaration` is never reached at all when this cannot be
    /// made sense of, and holds only the one real failure: a
    /// known-good applicability paired with a predicate that is not.
    pub applicability: Applicability,
    /// What this policy is told about, whether or not it is the one
    /// deciding. Feeds a second, independent tree — see
    /// [`Evaluator::observe`](crate::outcome::Evaluator::observe)'s doc
    /// comment for why this has to be separate from `applicability`.
    pub observes: Applicability,
    /// How stale this policy's evaluator's view may be. Duplicated per
    /// policy rather than looked up from the evaluator, even though one
    /// evaluator answers the same for all of its policies today, because a
    /// future evaluator serving policies of genuinely different staleness
    /// should not require restructuring this type.
    pub staleness: Staleness,
    /// What decides this policy — a working evaluator, or a named
    /// [`Predicate::Unusable`].
    pub predicate: Predicate,
    /// This policy record's own revision. See [`Revision`].
    pub revision: Revision,
}