didbot_policy_records/

subject.rs

//! The subjects a policy judges, and the diff a write carries to one.
//!
//! `didbot-pds`'s write and OAuth paths build every subject here, and
//! `didbot-policy-check` builds the same ones in a browser, so a page judges
//! a hypothetical request the way the server judges a real one. Nothing here
//! reads a clock: the instant is the caller's, so the two agree on what "now"
//! was.
//!
//! # The diff carries values, not just paths
//!
//! A rule that means to test a value cannot, from a path alone, tell a
//! legitimate edit from a delete that removed the same path. [`Change`]
//! carries both sides' values instead, with absence itself represented as a
//! value (`None`), so an evaluator can test *what changed to what* rather
//! than merely *that something at this path changed*. [`diff`] computes it
//! completely: every path whose value differs between `before` and `after`,
//! including every path in a wholly new record (a create, `before: None`
//! throughout) and every path in a wholly removed one (a delete, `after:
//! None` throughout). There is no "empty diff for a delete" case, and a gate
//! is entitled to rely on that.
//!
//! Nothing here is a payload log. [`Change`] borrows from the two `Value`s a
//! write already holds in memory for the length of one judgment, and nothing
//! stores, logs, or returns a `Change` past that call.

use didbot_policy::{
    Asked, Change, ClientId, DeploymentAttributes, Diff, Lookup, Subject, SubjectAttributes,
    SubjectKind, Universal, WriteAction,
};
use serde_json::Value;
use time::OffsetDateTime;

/// One field path whose value differs between before and after a write, as
/// this crate computes and holds it.
///
/// `before`/`after` are `None` exactly when the path was absent on that
/// side — absence is a value, not a missing [`OwnedChange`]. A path present
/// with an identical value on both sides is not represented at all: this is
/// a diff, and an unchanged path did not change.
///
/// `path` is an owned `String` here rather than a borrow into the record:
/// the paths themselves are computed while walking the structure
/// (`"foo.bar[2]"` is built, not found), and something has to own the
/// result. [`Change`] is the borrowed view of this a gate actually receives
/// — see [`OwnedChange::as_change`] — so the ownership lives here, once,
/// rather than at every call site that needs one.
#[derive(Debug, Clone, PartialEq)]
pub struct OwnedChange<'a> {
    /// Dot-and-bracket notation from the record's root: `"displayName"`,
    /// `"labels.values[0].val"`.
    pub path: String,
    /// What this path held before the write. `None` if it was absent.
    pub before: Option<&'a Value>,
    /// What this path holds after the write. `None` if it is now absent.
    pub after: Option<&'a Value>,
}

impl OwnedChange<'_> {
    /// Borrows this as the shape a gate receives.
    ///
    /// A cheap reborrow, not a clone of the values: `path` is borrowed for
    /// as long as this `OwnedChange` is, and `before`/`after` were already
    /// borrowed from the record.
    #[must_use]
    pub fn as_change(&self) -> Change<'_> {
        Change {
            path: &self.path,
            before: self.before,
            after: self.after,
        }
    }
}

/// Borrows a whole diff at once. See [`OwnedChange::as_change`].
#[must_use]
pub fn borrow<'a>(owned: &'a [OwnedChange<'_>]) -> Vec<Change<'a>> {
    owned.iter().map(OwnedChange::as_change).collect()
}

/// Computes the complete diff between `before` and `after`.
///
/// Walks both values together, path by path. An object's keys are the union
/// of both sides'; an array is walked by index up to the longer side's
/// length. A path recurses only while both sides at that path are "an object
/// or absent" (respectively "an array or absent"); anywhere the two sides
/// disagree in kind — a scalar replacing an object, an array replacing a
/// scalar, one side absent and the other a leaf — the whole value at that
/// path becomes one [`OwnedChange`], because there is no shared substructure
/// left to walk into. An empty object or array on one side, absent on the
/// other, is reported as a single change at its own path rather than as zero
/// changes over zero children — the container itself is the thing that
/// changed.
///
/// `before: None, after: None` (nothing to diff) produces no changes.
/// `before: None, after: Some(record)` (a create) produces one change per
/// leaf path in `record`, every one with `before: None`. `before:
/// Some(record), after: None` (a delete) is the mirror: one change per leaf
/// path in `record`, every one with `after: None`.
#[must_use]
pub fn diff<'a>(before: Option<&'a Value>, after: Option<&'a Value>) -> Vec<OwnedChange<'a>> {
    let mut changes = Vec::new();
    diff_into("", before, after, &mut changes);
    changes
}

fn join(parent: &str, key: &str) -> String {
    if parent.is_empty() {
        key.to_owned()
    } else {
        format!("{parent}.{key}")
    }
}

fn diff_into<'a>(
    path: &str,
    before: Option<&'a Value>,
    after: Option<&'a Value>,
    out: &mut Vec<OwnedChange<'a>>,
) {
    if before == after {
        return;
    }

    let before_object_or_absent = before.is_none() || matches!(before, Some(Value::Object(_)));
    let after_object_or_absent = after.is_none() || matches!(after, Some(Value::Object(_)));
    if before_object_or_absent && after_object_or_absent {
        let mut keys: Vec<&str> = Vec::new();
        if let Some(Value::Object(map)) = before {
            keys.extend(map.keys().map(String::as_str));
        }
        if let Some(Value::Object(map)) = after {
            keys.extend(map.keys().map(String::as_str));
        }
        keys.sort_unstable();
        keys.dedup();
        if keys.is_empty() {
            // Both sides are objects (or absent) but neither has a key —
            // e.g. `{}` on one side and absent on the other. The container
            // itself is the change; there is nothing under it to recurse
            // into.
            out.push(OwnedChange {
                path: path.to_owned(),
                before,
                after,
            });
        } else {
            for key in keys {
                let child_before = before.and_then(|value| value.get(key));
                let child_after = after.and_then(|value| value.get(key));
                diff_into(&join(path, key), child_before, child_after, out);
            }
        }
        return;
    }

    let before_array_or_absent = before.is_none() || matches!(before, Some(Value::Array(_)));
    let after_array_or_absent = after.is_none() || matches!(after, Some(Value::Array(_)));
    if before_array_or_absent && after_array_or_absent {
        let before_len = before.and_then(Value::as_array).map_or(0, Vec::len);
        let after_len = after.and_then(Value::as_array).map_or(0, Vec::len);
        let len = before_len.max(after_len);
        if len == 0 {
            out.push(OwnedChange {
                path: path.to_owned(),
                before,
                after,
            });
        } else {
            for index in 0..len {
                let child_before = before.and_then(|value| value.get(index));
                let child_after = after.and_then(|value| value.get(index));
                diff_into(&format!("{path}[{index}]"), child_before, child_after, out);
            }
        }
        return;
    }

    // The two sides disagree in kind (object vs. scalar, array vs. object,
    // and so on) with neither side absent, or one side is a leaf scalar
    // that changed. Either way there is no shared substructure to walk
    // into, so the whole value at this path is the change.
    out.push(OwnedChange {
        path: path.to_owned(),
        before,
        after,
    });
}

/// Builds the [`Subject::Write`] a gate judges one write against.
///
/// `client_id` is the application whose OAuth token presented the write, or
/// `None` when the account wrote with its own credential. `now` is the
/// instant the whole request is judged at — see [`Universal::now`] on why an
/// evaluator never reads its own clock.
///
/// `changes` and the two records are two views of one write, and both are
/// passed rather than either derived: the diff is what the applicability
/// index walks, and the records are what an evaluator reading fields reads.
///
/// `lookups` are what the policies applicable to this write declared they
/// read, already read — see [`didbot_policy::Lookup`]. They arrive as an
/// argument for the same reason `now` does: an evaluator judging this
/// subject can reach nothing its arguments do not already hold.
#[allow(clippy::too_many_arguments)]
#[must_use]
pub fn write_subject<'a>(
    account: &'a str,
    kind: SubjectKind<'a>,
    handle: Option<&'a str>,
    pds_did: &'a str,
    pds_hostname: &'a str,
    operator_did: Option<&'a str>,
    client_id: Option<&'a ClientId>,
    collection: &'a str,
    action: WriteAction,
    changes: &'a [Change<'a>],
    before: Option<&'a serde_json::Value>,
    after: Option<&'a serde_json::Value>,
    lookups: &'a [Lookup<'a>],
    now: OffsetDateTime,
) -> Subject<'a> {
    Subject::Write {
        account,
        attributes: SubjectAttributes {
            kind,
            handle,
            depth: None,
        },
        universal: universal(pds_did, pds_hostname, operator_did, now),
        client_id,
        collection,
        action,
        diff: Diff { changes },
        before,
        after,
        lookups,
    }
}

/// Builds the [`Subject::Blob`] a gate judges one upload against.
///
/// `sniffed` and `size` are what is known when the judgment happens: an
/// upload is judged on what the request declares, before a byte is read,
/// again while the bytes arrive, and once they are in. `now` is the instant
/// the request is judged at.
#[allow(clippy::too_many_arguments)]
#[must_use]
pub fn blob_subject<'a>(
    account: &'a str,
    kind: SubjectKind<'a>,
    handle: Option<&'a str>,
    pds_did: &'a str,
    pds_hostname: &'a str,
    client_id: Option<&'a ClientId>,
    mime_type: &'a str,
    sniffed: Option<&'a str>,
    size: Option<u64>,
    now: OffsetDateTime,
) -> Subject<'a> {
    Subject::Blob {
        account,
        attributes: SubjectAttributes {
            kind,
            handle,
            depth: None,
        },
        universal: universal(pds_did, pds_hostname, None, now),
        client_id,
        mime_type,
        sniffed,
        size,
    }
}

/// Builds the [`Subject::Grant`] a gate judges one pushed authorization
/// request against, before any account is known.
///
/// `requested_scopes` is borrowed as the wire strings the request carried,
/// not as a parsed grammar: `didbot_policy` has no scope type, and a rule
/// keyed on a scope matches the atom the client actually sent.
#[must_use]
pub fn grant_subject<'a>(
    pds_did: &'a str,
    pds_hostname: &'a str,
    client_id: &'a ClientId,
    requested_scopes: &'a [&'a str],
    now: OffsetDateTime,
) -> Subject<'a> {
    Subject::Grant {
        universal: universal(pds_did, pds_hostname, None, now),
        client_id,
        requested_scopes,
    }
}

/// Builds the [`Subject::Token`] a gate judges before a token is issued to
/// `client_id` for `account`: an authorization code exchanged, or a refresh
/// token rotated. `scopes` are the wire strings the token would carry.
#[allow(clippy::too_many_arguments)]
#[must_use]
pub fn token_subject<'a>(
    account: &'a str,
    kind: SubjectKind<'a>,
    handle: Option<&'a str>,
    pds_did: &'a str,
    pds_hostname: &'a str,
    client_id: &'a ClientId,
    scopes: &'a [&'a str],
    now: OffsetDateTime,
) -> Subject<'a> {
    Subject::Token {
        account,
        attributes: SubjectAttributes {
            kind,
            handle,
            depth: None,
        },
        universal: universal(pds_did, pds_hostname, None, now),
        client_id,
        scopes,
    }
}

/// Builds the [`Subject::Create`] a gate judges for one pool and zone a
/// create could land in. `attributes` is the creating account's, when this
/// server hosts it; `name` and `label` are set when the create gave a name.
#[allow(clippy::too_many_arguments)]
#[must_use]
pub fn create_subject<'a>(
    account: &'a str,
    attributes: Option<SubjectAttributes<'a>>,
    pds_did: &'a str,
    pds_hostname: &'a str,
    kind: SubjectKind<'a>,
    asked: Asked,
    (pool, zone): (&'a str, &'a str),
    (name, label): (Option<&'a str>, Option<&'a str>),
    now: OffsetDateTime,
) -> Subject<'a> {
    Subject::Create {
        account,
        attributes,
        universal: universal(pds_did, pds_hostname, None, now),
        kind,
        asked,
        pool,
        zone,
        name,
        label,
    }
}

/// A deployment's facts and the instant, as every subject carries them.
fn universal<'a>(
    pds_did: &'a str,
    pds_hostname: &'a str,
    operator_did: Option<&'a str>,
    now: OffsetDateTime,
) -> Universal<'a> {
    Universal {
        deployment: DeploymentAttributes {
            pds_did,
            pds_hostname,
            operator_did,
        },
        now,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn a_create_lists_every_leaf_path_with_no_before() {
        let after = json!({"text": "hi", "labels": {"values": [{"val": "x"}]}});
        let changes = diff(None, Some(&after));
        let mut paths: Vec<&str> = changes.iter().map(|c| c.path.as_str()).collect();
        paths.sort_unstable();
        assert_eq!(paths, vec!["labels.values[0].val", "text"]);
        assert!(changes.iter().all(|c| c.before.is_none()));
    }

    #[test]
    fn a_delete_lists_every_leaf_path_with_no_after() {
        let before = json!({"text": "hi", "tags": ["a", "b"]});
        let changes = diff(Some(&before), None);
        let mut paths: Vec<&str> = changes.iter().map(|c| c.path.as_str()).collect();
        paths.sort_unstable();
        assert_eq!(paths, vec!["tags[0]", "tags[1]", "text"]);
        assert!(
            !changes.is_empty(),
            "a delete of a non-empty record must never produce an empty diff"
        );
        assert!(changes.iter().all(|c| c.after.is_none()));
    }

    #[test]
    fn an_update_reports_only_what_actually_changed() {
        let before = json!({"text": "hi", "unrelated": "same"});
        let after = json!({"text": "bye", "unrelated": "same"});
        let changes = diff(Some(&before), Some(&after));
        assert_eq!(changes.len(), 1);
        assert_eq!(changes[0].path, "text");
        assert_eq!(changes[0].before, Some(&json!("hi")));
        assert_eq!(changes[0].after, Some(&json!("bye")));
    }

    #[test]
    fn clearing_a_field_is_a_value_change_not_a_deletion_of_the_record() {
        let before = json!({"text": "hi", "displayName": "Bot"});
        let after = json!({"text": "hi", "displayName": ""});
        let changes = diff(Some(&before), Some(&after));
        assert_eq!(changes.len(), 1);
        assert_eq!(changes[0].path, "displayName");
        assert_eq!(changes[0].before, Some(&json!("Bot")));
        assert_eq!(changes[0].after, Some(&json!("")));
    }

    #[test]
    fn an_empty_object_replacing_absence_is_its_own_change() {
        let after = json!({"metadata": {}});
        let changes = diff(None, Some(&after));
        let mut paths: Vec<&str> = changes.iter().map(|c| c.path.as_str()).collect();
        paths.sort_unstable();
        assert_eq!(paths, vec!["metadata"]);
        assert_eq!(changes[0].after, Some(&json!({})));
    }

    #[test]
    fn nothing_to_diff_produces_no_changes() {
        assert!(diff(None, None).is_empty());
        let same = json!({"a": 1});
        assert!(diff(Some(&same), Some(&same)).is_empty());
    }
}