didbot_policy_records/

named.rs

//! Which accounts a record names.
//!
//! A write names somebody whenever it carries their DID: a reply's parent
//! and root, a quote embed, a mention facet, the subject of a follow, a
//! like or a repost, the parent on a registration. `plan/ai-preference.md`
//! asks the question this module answers — *given a record, which DIDs does
//! it name?* — because a rule about being named needs the list before it
//! can look anybody up.
//!
//! # Why this walks the record instead of holding a table per collection
//!
//! A table of "these fields of these collections carry a DID" is a list
//! that goes out of date on its own. A collection nobody added a row for
//! names nobody, silently, and so does a field added to a lexicon after the
//! row was written — and both failures point the same way: a write that
//! should have been checked is not. Walking the record instead makes the
//! answer structural. There is no row to forget, a new lexicon is covered
//! the day it exists, and a field that starts carrying a DID is covered by
//! the same code that covered the old one.
//!
//! The cost is that it names somebody a narrower reading would not: a DID
//! in a field that is about them rather than addressed to them still
//! counts. That is the direction to err in for a rule about not naming
//! people, and it is the reading `plan/ai-preference.md` settles on.

use serde_json::Value;

/// How deep into a record this walks.
///
/// **Reasonable range: 4 to 32.** A record is already bounded by its
/// lexicon and by the store's own limits, so this is a second bound rather
/// than the one that matters: it stops a pathological `unknown` field from
/// costing a walk proportional to whatever somebody nested inside it. Ten
/// clears every shape this project's own lexicons and `app.bsky.*` reach —
/// a quote of a quote's embedded record is six.
pub const MAX_DEPTH: usize = 10;

/// Every account `record` names, by DID, in the order they are first met
/// and without repeats.
///
/// A string is a DID if it is one, and an `at://` URI names the DID in its
/// authority. `$type` is never read: it is an NSID, not an account, and a
/// lexicon named after something that parses as a DID would otherwise name
/// it on every record.
#[must_use]
pub fn named_accounts(record: &Value) -> Vec<String> {
    let mut found = Vec::new();
    walk(record, 0, &mut found);
    found
}

fn walk(value: &Value, depth: usize, found: &mut Vec<String>) {
    if depth > MAX_DEPTH {
        return;
    }
    match value {
        Value::String(text) => {
            if let Some(did) = did_in(text) {
                if !found.iter().any(|held| held == did) {
                    found.push(did.to_owned());
                }
            }
        }
        Value::Array(items) => {
            for item in items {
                walk(item, depth + 1, found);
            }
        }
        Value::Object(fields) => {
            for (name, field) in fields {
                if name == "$type" {
                    continue;
                }
                walk(field, depth + 1, found);
            }
        }
        _ => {}
    }
}

/// The handle `record` itself calls each account it mentions by, as
/// `(did, handle)` pairs in the order they are first met.
///
/// A mention is a facet: an object holding a `text` string and a `facets`
/// list, each facet a byte range of that text and features naming a DID.
/// The span a feature's facet covers, less its leading `@`, is the handle
/// the writer used for that DID, when it is one. The writer chose it and
/// nothing checks that the DID answers to it, so it is only ever used to
/// tell the writer who their own record named. Like [`named_accounts`],
/// this reads the shape and never `$type`.
#[must_use]
pub fn named_handles(record: &Value) -> Vec<(String, String)> {
    let mut found = Vec::new();
    walk_handles(record, 0, &mut found);
    found
}

fn walk_handles(value: &Value, depth: usize, found: &mut Vec<(String, String)>) {
    if depth > MAX_DEPTH {
        return;
    }
    match value {
        Value::Array(items) => {
            for item in items {
                walk_handles(item, depth + 1, found);
            }
        }
        Value::Object(fields) => {
            if let (Some(Value::String(text)), Some(Value::Array(facets))) =
                (fields.get("text"), fields.get("facets"))
            {
                for facet in facets {
                    mentioned(text, facet, found);
                }
            }
            for (name, field) in fields {
                if name != "$type" {
                    walk_handles(field, depth + 1, found);
                }
            }
        }
        _ => {}
    }
}

/// The `(did, handle)` pairs one facet over `text` carries.
fn mentioned(text: &str, facet: &Value, found: &mut Vec<(String, String)>) {
    let index = facet.get("index");
    let start = index
        .and_then(|i| i.get("byteStart"))
        .and_then(Value::as_u64);
    let end = index.and_then(|i| i.get("byteEnd")).and_then(Value::as_u64);
    let (Some(start), Some(end)) = (start, end) else {
        return;
    };
    let (Ok(start), Ok(end)) = (usize::try_from(start), usize::try_from(end)) else {
        return;
    };
    let Some(span) = text.get(start..end) else {
        return;
    };
    let Some(handle) = span.strip_prefix('@') else {
        return;
    };
    if didbot_identity::validate_handle(handle).is_err() {
        return;
    }
    let Some(Value::Array(features)) = facet.get("features") else {
        return;
    };
    for feature in features {
        let Some(did) = feature.get("did").and_then(Value::as_str) else {
            continue;
        };
        if didbot_identity::validate_did(did).is_err() || found.iter().any(|(held, _)| held == did)
        {
            continue;
        }
        found.push((did.to_owned(), handle.to_owned()));
    }
}

/// The DID a string is, or the DID an `at://` URI's authority is.
fn did_in(text: &str) -> Option<&str> {
    let candidate = match text.strip_prefix("at://") {
        Some(rest) => rest.split('/').next().unwrap_or(rest),
        None => text,
    };
    didbot_identity::validate_did(candidate)
        .is_ok()
        .then_some(candidate)
}

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

    /// A mention's handle is the text its facet spans, and only when that
    /// text is `@` and a handle: a link facet over a URL names nobody.
    #[test]
    fn a_mention_names_its_account_by_the_handle_its_text_spans() {
        let post = json!({
            "text": "hi @wren.example, see https://x.example",
            "facets": [
                {
                    "index": { "byteStart": 3, "byteEnd": 16 },
                    "features": [{ "$type": "app.bsky.richtext.facet#mention", "did": "did:web:wren.example" }],
                },
                {
                    "index": { "byteStart": 22, "byteEnd": 39 },
                    "features": [{ "$type": "app.bsky.richtext.facet#link", "uri": "https://x.example" }],
                },
                {
                    "index": { "byteStart": 0, "byteEnd": 2 },
                    "features": [{ "did": "did:web:not-a-handle.example" }],
                },
            ],
        });
        assert_eq!(
            named_handles(&post),
            [("did:web:wren.example".to_owned(), "wren.example".to_owned())]
        );
    }

    /// One post can name people four ways at once, and each way is a DID
    /// this has to find: a reply's two parents, a quote, and a mention.
    #[test]
    fn a_post_names_its_parents_its_quote_and_its_mentions() {
        let post = json!({
            "$type": "app.bsky.feed.post",
            "text": "@wren.example",
            "createdAt": "2026-09-11T00:00:00.000Z",
            "reply": {
                "root": { "uri": "at://did:web:root.example/app.bsky.feed.post/3lb", "cid": "bafyfake" },
                "parent": { "uri": "at://did:web:parent.example/app.bsky.feed.post/3lc", "cid": "bafyfake" },
            },
            "embed": {
                "$type": "app.bsky.embed.record",
                "record": { "uri": "at://did:web:quoted.example/app.bsky.feed.post/3ld", "cid": "bafyfake" },
            },
            "facets": [{
                "index": { "byteStart": 0, "byteEnd": 13 },
                "features": [{ "$type": "app.bsky.richtext.facet#mention", "did": "did:web:wren.example" }],
            }],
        });
        assert_eq!(
            named_accounts(&post),
            [
                "did:web:root.example",
                "did:web:parent.example",
                "did:web:quoted.example",
                "did:web:wren.example",
            ]
        );
    }

    /// The subject of a follow is a bare DID; the subject of a like or a
    /// repost is an at-uri whose authority is one.
    #[test]
    fn a_follow_a_like_and_a_repost_each_name_one_account() {
        for (record, named) in [
            (
                json!({ "$type": "app.bsky.graph.follow", "subject": "did:web:wren.example" }),
                "did:web:wren.example",
            ),
            (
                json!({
                    "$type": "app.bsky.feed.like",
                    "subject": { "uri": "at://did:web:wren.example/app.bsky.feed.post/3lb", "cid": "bafyfake" },
                }),
                "did:web:wren.example",
            ),
            (
                json!({
                    "$type": "app.bsky.feed.repost",
                    "subject": { "uri": "at://did:web:wren.example/app.bsky.feed.post/3lb", "cid": "bafyfake" },
                }),
                "did:web:wren.example",
            ),
        ] {
            assert_eq!(named_accounts(&record), [named], "{record}");
        }
    }

    /// A record about nobody names nobody, so the write path does no
    /// lookup for it at all.
    #[test]
    fn a_record_carrying_no_did_names_nobody() {
        let post = json!({
            "$type": "app.bsky.feed.post",
            "text": "the tide is out",
            "createdAt": "2026-09-11T00:00:00.000Z",
            "facets": [{
                "index": { "byteStart": 0, "byteEnd": 6 },
                "features": [{ "$type": "app.bsky.richtext.facet#tag", "tag": "tides" }],
            }],
        });
        assert!(named_accounts(&post).is_empty());
    }

    /// A `$type` is an NSID and never an account, and a record nested
    /// deeper than the walk goes stops costing anything.
    #[test]
    fn a_type_is_never_an_account_and_the_walk_is_bounded() {
        let mut nested = json!("did:web:deep.example");
        for _ in 0..MAX_DEPTH + 2 {
            nested = json!({ "inner": nested });
        }
        assert!(named_accounts(&nested).is_empty());

        let shallow =
            json!({ "$type": "did:web:not.an.account", "subject": "did:web:wren.example" });
        assert_eq!(named_accounts(&shallow), ["did:web:wren.example"]);
    }
}