didbot_policy/

subject.rs

//! What a policy is asked about.
//!
//! Per `plan/policy.md`'s "Two trees, one set of mechanics": the same
//! indexing, evaluators and outcomes serve every subject shape.

use time::OffsetDateTime;

use crate::client_id::ClientId;

/// What kind of write this is, carried alongside the diff rather than
/// inferred from it.
///
/// `plan/policy.md` deliberately leaves "what a delete means" unsettled: a
/// diff that happens to remove every path is not the same as an explicit
/// signal that this is a deletion, and different evaluators may want
/// different logic for one. This crate takes no position on that meaning —
/// it only makes the action routable, so a policy can declare that it
/// applies to deletes, or does not, and an evaluator can see which case it
/// is looking at.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum WriteAction {
    /// The record did not exist before this write.
    Create,
    /// The record existed and this write changes it.
    Update,
    /// This write removes the record.
    Delete,
}

impl WriteAction {
    /// The action as a policy document spells it.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            WriteAction::Create => "create",
            WriteAction::Update => "update",
            WriteAction::Delete => "delete",
        }
    }
}

/// One field's value before and after a write, at a dotted path such as
/// `"displayName"` or `"profile.bio"`.
///
/// `before` and `after` are `None` when the path was absent on that side —
/// absence is a value, not a missing entry. This is what lets a rule like
/// *"displayName may not change to a different value"* resolve without an
/// action special case: it is `before.is_some() && after != before`. A
/// create has `before: None` everywhere, so it never trips such a rule —
/// correct, there is no prior identity to protect. A delete has
/// `after: None` everywhere; whether that counts as a change to the path
/// is the evaluator's reading of [`WriteAction`], which is carried
/// alongside the diff for exactly that decision.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Change<'a> {
    /// The field path this change is at, passed through exactly as the
    /// caller supplied it.
    ///
    /// What a path segment *is* — where one ends, what a `.` or a `[0]`
    /// means, whether a literal dot in a field name is possible — is
    /// per-engine, not this crate's to decide or canonicalize. An
    /// evaluator reads this string with whatever segmentation its own
    /// engine uses; this crate does not reinterpret it before handing it
    /// over. (The applicability index's own `path_prefixes` matching does
    /// split on `.` internally, and treats an `[index]` subscript as a
    /// segment boundary too, so a prefix naming a field matches the
    /// elements of that field when it holds an array. That is this
    /// crate's own declarative convention for *routing* — a cheap,
    /// structural pre-filter over which policies are even asked — not a
    /// claim about what `path` means to the evaluator a matched policy
    /// names.)
    pub path: &'a str,
    /// The value before the write, or `None` if the path was absent.
    pub before: Option<&'a serde_json::Value>,
    /// The value after the write, or `None` if the path is now absent.
    pub after: Option<&'a serde_json::Value>,
}

/// What changed in a write, as the applicability index's key.
///
/// The diff has to be computed to evaluate anything, so diffing *is* the
/// indexing step: a write's changed paths are walked through the tree once,
/// and a write matching no policy has paid only for that walk.
///
/// The contract is exact: `changes` holds every path whose value differs
/// between before and after, where absence is a value — so a create lists
/// every path it introduces, a delete lists every path it removes, and
/// there is no case where an evaluator sees an empty diff for a write that
/// changed something. The server computes this, holding both sides of the
/// write already, so it is enforced once in the write path rather than
/// trusted from whatever produced the write.
///
/// This is a minimal, storage-agnostic view, deliberately not the richer
/// diff type that `didbot-data`'s merkle search tree produces. That type
/// carries proof material this crate has no use for, and coupling the
/// policy core to one storage engine's diff shape would be a dependency in
/// the wrong direction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Diff<'a> {
    /// Every path that changed, each with its value before and after.
    pub changes: &'a [Change<'a>],
}

/// One of the four account kinds this build recognizes.
///
/// Mirrors `bot.did.registration`'s `actor` union and
/// `didbot-pds::kind::AccountKind` exactly, but is declared independently
/// rather than reused from that crate — the same reasoning as [`Diff`]'s
/// doc comment on not coupling this crate to one storage engine's shape,
/// applied to an account-kind enum instead of a diff type. A fifth kind
/// added to the lexicon is a silent gap here until this enum is edited to
/// match; nothing checks the two stay in step automatically.
///
/// Agents are the *typical* `did.bot` subject, not the only one: a policy
/// or an evaluator that quietly assumes every subject is an agent is wrong
/// about the other three, which is exactly what made `AgentAttributes` the
/// wrong name for [`SubjectAttributes`] in an earlier draft of this type.
///
/// This type is deliberately closed — the four kinds this build knows how
/// to reason about by name — and is not, by itself, what a subject's kind
/// is typed as. That is [`SubjectKind`], below, because the union it names
/// is open.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum AccountKind {
    /// A harness session with a model and a parent.
    Agent,
    /// A CI identity bound to a workflow.
    Pipeline,
    /// A machine. No model, no harness, no parent.
    Host,
    /// This software itself.
    Service,
}

impl AccountKind {
    /// The kind as `bot.did.registration` spells it.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            AccountKind::Agent => "agent",
            AccountKind::Pipeline => "pipeline",
            AccountKind::Host => "host",
            AccountKind::Service => "service",
        }
    }
}

/// What kind of account a subject is, including a kind this build has never
/// heard of.
///
/// `bot.did.registration`'s `actor` union is declared `"closed": false`: a
/// fifth kind can appear in a record this server did not write, admitted by
/// a future version of some deployment's software or a fork's. A type that
/// could only ever be one of [`AccountKind`]'s four variants would have
/// nowhere to put that value, forcing a choice between failing to parse the
/// record, or coercing an unrecognized kind into a known one — silently
/// making a claim about it nobody established. [`Unknown`](Self::Unknown)
/// exists so neither happens: the string is preserved and the subject still
/// routes, and see [`KindSet`](crate::policy::KindSet)'s doc comment for
/// what an applicability declaration is and is not allowed to conclude from
/// one.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubjectKind<'a> {
    /// One of the four kinds this build recognizes by name.
    Known(AccountKind),
    /// A kind this build does not recognize, carrying the string the
    /// record named it with.
    Unknown(&'a str),
}

impl<'a> SubjectKind<'a> {
    /// The kind as the record spells it, known or not.
    #[must_use]
    pub fn as_str(self) -> &'a str {
        match self {
            SubjectKind::Known(kind) => kind.as_str(),
            SubjectKind::Unknown(kind) => kind,
        }
    }
}

/// Attributes about the writing account a policy may need beyond its DID,
/// explicit and extensible rather than a bag.
///
/// This is the contract between this crate, the write path that populates
/// it, and the evaluators that read it: an evaluator names the attribute it
/// needs from here, and the write path knows, from this same type, what it
/// is obliged to fill in. Every attribute past `kind` is kind-dependent —
/// a host has no model to report, the way it has no harness and no parent —
/// so `None` here means "this kind does not have one, or the write path
/// could not resolve it for this write", never an error an evaluator needs
/// to handle specially; it is a normal, expected value to see.
///
/// Adding an allowlist-shaped policy — *"displayName may be set only to the
/// account's handle or a small fixed list of values"* — does not reintroduce
/// an allow: it is expressed as *deny if the new value matches none of
/// them*, read off [`Change::after`](crate::subject::Change::after) and
/// this handle, which subtracts from what is permitted exactly like every
/// other policy. Monotonicity does not distinguish an allowlist from a
/// blocklist; both are deny rules, just aimed at different values.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SubjectAttributes<'a> {
    /// What kind of account this subject is — one of the four this build
    /// recognizes, or a kind it does not. See [`SubjectKind`].
    pub kind: SubjectKind<'a>,
    /// This account's current handle, if the write path resolved one for
    /// this write and this kind has one.
    pub handle: Option<&'a str>,
    /// How many edges lie between this account and the deployment's
    /// operator: 1 for an account the operator runs directly, 2 for one
    /// such an account created, and so on. `None` when the write path did
    /// not resolve it.
    pub depth: Option<u32>,
}

/// Facts about this deployment a policy may reference, independent of the
/// account or the write — a different kind of fact from
/// [`SubjectAttributes`], which is why it is its own type rather than a
/// field folded into that one. An evaluator asking for the PDS's own DID or
/// hostname is asking a different question than one asking about the
/// account, and naming them separately keeps that visible at the call site
/// — for a rule like *"deny a handle that is not under this deployment's
/// zone"*.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct DeploymentAttributes<'a> {
    /// This PDS's own DID.
    pub pds_did: &'a str,
    /// This PDS's own hostname.
    pub pds_hostname: &'a str,
    /// The DID of the account that vouches for this deployment. `None`
    /// until this server has observed its operator's claim, and on every
    /// subject but a write, which is the only one a rule reads it from
    /// today.
    pub operator_did: Option<&'a str>,
}

/// Facts that do not belong to the account or the write, but that a
/// stateless predicate is still allowed to reference — grouped into one
/// field per [`Subject`] variant rather than left flat, since the field
/// list otherwise grows by one every time a new universal fact is added.
///
/// # Why `now` lives here instead of an evaluator calling a clock
///
/// Time is an input, never an ambient read: nothing in this crate lets an
/// evaluator call `SystemTime::now()` or its equivalent, for the same
/// reason [`evaluate`](crate::outcome::Evaluator::evaluate) takes no store
/// handle — a capability not reachable from the arguments cannot be reached
/// at all. Passing `now` explicitly instead means:
///
/// - An evaluator implementing a time-shaped rule stays a pure function of
///   its inputs, testable by constructing a `Subject` with the instant a
///   test wants, never by sleeping or mocking a global clock.
/// - The instant a decision used is exactly what was passed in, so the
///   write path can record it in the evaluation log. `plan/policy.md`
///   already says decisions are not reproducible and the log records the
///   decision rather than re-deriving it; a time-dependent rule is a
///   second, independent reason that holds, and the recorded instant is
///   what makes such a decision explicable later.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Universal<'a> {
    /// Facts about this deployment. See [`DeploymentAttributes`].
    pub deployment: DeploymentAttributes<'a>,
    /// The instant this subject is being evaluated at, supplied by the
    /// caller rather than read from a clock inside an evaluator.
    pub now: OffsetDateTime,
}

/// What a policy's declared lookup found in somebody else's repository.
///
/// A policy declares the records its statements read in its own `lookups`
/// list. The write path reads each one before the write is judged and hands
/// the answers over here, so an engine reads them as ordinary fields of the
/// subject and [`Evaluator::evaluate`](crate::outcome::Evaluator::evaluate)
/// still takes a subject and nothing else. See `docs/write-pipeline.md` for
/// where the reading happens.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Lookup<'a> {
    /// The name the policy's `lookups` entry gave this record, which is
    /// what a statement calls it.
    pub name: &'a str,
    /// The DID of the repository that was read.
    pub account: &'a str,
    /// The handle the written record itself calls that account by, when it
    /// carries one: a mention's text. Nothing checks the DID answers to it,
    /// so it is for telling the writer who their own record named.
    pub handle: Option<&'a str>,
    /// The at-uri that was read, so a refusal can carry something a person
    /// can open. A lookup with no `rkey` reads a collection, and this is
    /// the collection's uri.
    pub uri: &'a str,
    /// What was there. See [`Found`].
    pub found: Found<'a>,
}

/// What reading one declared lookup established.
///
/// Three cases, and the third is the one that decides the design: a reader
/// that turned "somebody's server did not answer" into a value would have a
/// rule refuse, or permit, on a fact nobody established. So the reader says
/// it does not know, and each statement declares what an unknown means for
/// itself.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Found<'a> {
    /// The records found: an array, each element `{"uri": …, "value": …}`.
    /// A lookup naming one record finds at most one; a lookup naming a
    /// collection finds every record in it. One shape means a statement
    /// reads both the same way, and each uri is what a refusal carries so
    /// a person can open the record it came from.
    Records(&'a serde_json::Value),
    /// The repository answered, and holds nothing there.
    Nothing,
    /// Neither was established, carrying the short word the reader named
    /// the case with: not fetched, past its deadline, refused,
    /// unresolvable, unreachable.
    Unknown(&'a str),
}

/// What one policy is asked to decide about.
///
/// A client appears on all three variants, so a rule denying a client
/// answers the same way at sign-in, at token issue, and at the write. The
/// write matters most: a token issued before a denial still reaches it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Subject<'a> {
    /// A write to this account's own repository. Typically an agent's, but
    /// see [`AccountKind`] — the field is named for what it is, an account
    /// DID, not for the kind that happens to be the common case.
    Write {
        /// The account whose repository this is.
        account: &'a str,
        /// Other attributes of that account a policy may reference — see
        /// [`SubjectAttributes`].
        attributes: SubjectAttributes<'a>,
        /// Deployment and clock facts a policy may reference — see
        /// [`Universal`].
        universal: Universal<'a>,
        /// The application whose OAuth token presented the write. `None`
        /// when the account wrote with its own credential.
        client_id: Option<&'a ClientId>,
        /// The collection (NSID) being written.
        collection: &'a str,
        /// Create, update or delete — see [`WriteAction`].
        action: WriteAction,
        /// What changed.
        diff: Diff<'a>,
        /// The whole record as it was before this write, or `None` when the
        /// key held nothing.
        ///
        /// [`Diff::changes`] is the index key and says what *moved*; this is
        /// the record itself. An evaluator that reads fields rather than
        /// changed paths reads them from here, because a record cannot be
        /// recovered from a diff: a path string is not a parse of the key
        /// that produced it, so two different fields can spell the same
        /// path, and an update's diff names only the fields it touched.
        before: Option<&'a serde_json::Value>,
        /// The whole record as this write leaves it, or `None` for a delete.
        /// See [`before`](Self::Write::before).
        after: Option<&'a serde_json::Value>,
        /// What the policies applicable to this write declared they read,
        /// and what was found. See [`Lookup`]. Empty when no applicable
        /// policy declares one, which is the ordinary case.
        lookups: &'a [Lookup<'a>],
    },
    /// A blob uploaded to this account. It is judged when the upload
    /// starts, on what the request claims; at checkpoints while the body
    /// arrives, each of which can refuse the upload but not admit it; and
    /// once the bytes are in and before they are stored. A fact the first
    /// judgment does not have is `None` — what is not known yet cannot deny.
    Blob {
        /// The account the blob is uploaded to.
        account: &'a str,
        /// Other attributes of that account — see [`SubjectAttributes`].
        attributes: SubjectAttributes<'a>,
        /// Deployment and clock facts — see [`Universal`].
        universal: Universal<'a>,
        /// The application whose OAuth token presented the upload. `None`
        /// when the account uploaded with its own credential.
        client_id: Option<&'a ClientId>,
        /// The MIME type the uploader declared.
        mime_type: &'a str,
        /// The MIME type read from the blob's own bytes. `None` before the
        /// body is read.
        sniffed: Option<&'a str>,
        /// The blob's size in bytes. Before the body, the length the request
        /// declared, or `None` when it declared none. While the body
        /// arrives, that length, or the bytes received so far when there is
        /// none. After, what arrived.
        size: Option<u64>,
    },
    /// A pushed authorization request, judged on the application and the
    /// scopes it asks for, before any account is known.
    ///
    /// It names no account because it is asked before the request's
    /// `login_hint` is resolved, which is what keeps a client the gate
    /// refuses indistinguishable from a hint naming nobody — so only a
    /// policy bound to the whole server reaches it. A rule about one
    /// account is asked where the account is known: [`Subject::Token`], on
    /// every token issue and every rotation, and [`Subject::Write`].
    Grant {
        /// Deployment and clock facts a policy may reference — see
        /// [`Universal`].
        universal: Universal<'a>,
        /// The application requesting the grant.
        client_id: &'a ClientId,
        /// The scopes it is asking for.
        requested_scopes: &'a [&'a str],
    },
    /// A token about to be issued to an application for an account: an
    /// authorization code exchanged, or a refresh token rotated.
    Token {
        /// The account the token would authenticate as.
        account: &'a str,
        /// Other attributes of that account — see [`SubjectAttributes`].
        attributes: SubjectAttributes<'a>,
        /// Deployment and clock facts — see [`Universal`].
        universal: Universal<'a>,
        /// The application the token would be issued to.
        client_id: &'a ClientId,
        /// The scopes the token would carry.
        scopes: &'a [&'a str],
    },
    /// Where a new account lands: `account.create`, asked once for each
    /// pool and zone a create could land in, before a name is made.
    Create {
        /// The account creating it. The operator's own create names the
        /// operator's DID, which this server does not host.
        account: &'a str,
        /// Other attributes of the creating account, when this server
        /// hosts it — see [`SubjectAttributes`].
        attributes: Option<SubjectAttributes<'a>>,
        /// Deployment and clock facts — see [`Universal`].
        universal: Universal<'a>,
        /// What the new account is.
        kind: SubjectKind<'a>,
        /// How the create asked for its name.
        asked: Asked,
        /// The pool the name would come from.
        pool: &'a str,
        /// The zone it would sit under.
        zone: &'a str,
        /// The whole name, when the create gave one. A name the pool makes
        /// does not exist yet when this is asked.
        name: Option<&'a str>,
        /// The name's label under `zone`, when the create gave a name.
        label: Option<&'a str>,
    },
}

/// How a create asked for its account's name.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Asked {
    /// A whole name, taken exactly or refused.
    Name,
    /// A pool, and optional fragments the pool fills its name with.
    Pool,
    /// Nothing: the first pool policy permits makes the name.
    Nothing,
}

impl Asked {
    /// How a policy reads it: `name`, `pool` or `none`.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Asked::Name => "name",
            Asked::Pool => "pool",
            Asked::Nothing => "none",
        }
    }
}

impl Subject<'_> {
    /// The application presenting this subject, if one is.
    pub fn client_id(&self) -> Option<&ClientId> {
        match self {
            Subject::Write { client_id, .. } | Subject::Blob { client_id, .. } => *client_id,
            Subject::Grant { client_id, .. } | Subject::Token { client_id, .. } => Some(client_id),
            Subject::Create { .. } => None,
        }
    }

    /// What this write's applicable policies read from other repositories.
    /// Empty for every subject that is not a write, since only a write
    /// names anybody.
    pub fn lookups(&self) -> &[Lookup<'_>] {
        match self {
            Subject::Write { lookups, .. } => lookups,
            _ => &[],
        }
    }

    /// Deployment and clock facts, common to every variant — see
    /// [`Universal`].
    pub fn universal(&self) -> &Universal<'_> {
        match self {
            Subject::Write { universal, .. }
            | Subject::Blob { universal, .. }
            | Subject::Grant { universal, .. }
            | Subject::Token { universal, .. }
            | Subject::Create { universal, .. } => universal,
        }
    }
}