didbot_identity/

document.rs

//! The DID document that backs an agent account.
//!
//! A document says where an account is and who signs for it. atproto reads
//! the `id`, the `alsoKnownAs` handle, the `#atproto` signing key and the
//! `#atproto_pds` service entry. Beside those, every hosted account names
//! its `operator`: the human who answers for it, one read away from any
//! depth of the tree. How a process logs in as the account is not in the
//! document at all; that is the account's `bot.did.credential` records.

use std::collections::BTreeSet;

use serde::{Deserialize, Serialize};

use crate::did::AccountDid;

/// JSON-LD contexts a spec-compliant atproto DID document declares.
pub const DEFAULT_CONTEXT: [&str; 3] = [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/multikey/v1",
    "https://w3id.org/security/suites/secp256k1-2019/v1",
];

/// Fragment identifying the atproto signing key within a DID document.
pub const ATPROTO_KEY_FRAGMENT: &str = "#atproto";

/// Fragment identifying the account's PDS within a DID document.
pub const ATPROTO_PDS_FRAGMENT: &str = "#atproto_pds";

/// The `type` atproto requires on the signing key's verification method.
pub const MULTIKEY_TYPE: &str = "Multikey";

/// The `type` atproto requires on the PDS service entry.
pub const PDS_SERVICE_TYPE: &str = "AtprotoPersonalDataServer";

/// The property naming the human who answers for a hosted account. Not a
/// DID Core property: a didbot deployment writes it, and a reader that does
/// not know it ignores it, which is what every atproto resolver does.
pub const OPERATOR_PROPERTY: &str = "operator";

/// A DID document, reduced to the fields this crate consumes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct DidDocument {
    /// JSON-LD contexts. Serialized first, under the literal name
    /// `@context`.
    #[serde(rename = "@context")]
    pub context: Vec<String>,
    /// The DID this document describes. A resolver must check it against the
    /// DID it asked for; see [`mod@crate::resolve`].
    pub id: String,
    /// Claimed handles, as `at://` URIs. Ordered: the first syntactically
    /// valid entry is the claimed handle.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub also_known_as: Vec<String>,
    /// Public keys. The atproto signing key is the entry whose `id` ends in
    /// `#atproto`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub verification_method: Vec<VerificationMethod>,
    /// DID Core's `authentication`, read from other documents and never
    /// written into this deployment's own.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub authentication: Vec<String>,
    /// Service endpoints. The PDS is the entry whose `id` ends in
    /// `#atproto_pds`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub service: Vec<Service>,
    /// The DID of the human who answers for this account, from the
    /// document's [`OPERATOR_PROPERTY`]. The same fact as the account's
    /// `bot.did.registration` names, published here so one HTTP GET answers
    /// it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub operator: Option<String>,
}

/// One public key in a DID document.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct VerificationMethod {
    /// Fully qualified or relative fragment, e.g. `did:web:x.example#atproto`.
    pub id: String,
    /// Always [`MULTIKEY_TYPE`] for the atproto signing key.
    #[serde(rename = "type")]
    pub type_: String,
    /// The DID that controls this key.
    pub controller: String,
    /// The public key, multibase-encoded.
    pub public_key_multibase: String,
}

/// One service endpoint in a DID document.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Service {
    /// Fragment naming the service, e.g. `#atproto_pds`.
    pub id: String,
    /// Always [`PDS_SERVICE_TYPE`] for a personal data server.
    #[serde(rename = "type")]
    pub type_: String,
    /// Scheme, hostname and optional port. No path, query or fragment.
    pub service_endpoint: String,
}

/// The OpenID Connect identity an account is.
///
/// An ID token from `issuer` whose claims carry every entry of `claims`,
/// each with the value given, authenticates as the account.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct OidcIdentity {
    /// The issuer, as the `iss` claim spells it.
    pub issuer: String,
    /// Claims the token must carry, in the order given.
    pub claims: Vec<Claim>,
}

/// One claim an ID token must carry to be this account.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Claim {
    /// The claim's name, e.g. `sub`.
    pub name: String,
    /// The value the claim must hold.
    pub value: String,
}

impl Claim {
    /// The claim this names in an ID token, as a JSON pointer (RFC 6901)
    /// spelled one way.
    ///
    /// A name beginning with `/` is a pointer into the token's claims,
    /// unescaped the way `serde_json::Value::pointer` reads one. Any other
    /// name is one top-level claim. Every spelling of one claim gives the
    /// same pointer: `repository` and `/repository` are both `/repository`.
    #[must_use]
    pub fn pointer(&self) -> String {
        let tokens: Vec<String> = match self.name.strip_prefix('/') {
            Some(pointer) => pointer
                .split('/')
                .map(|token| token.replace("~1", "/").replace("~0", "~"))
                .collect(),
            None => vec![self.name.clone()],
        };
        tokens
            .iter()
            .map(|token| format!("/{}", token.replace('~', "~0").replace('/', "~1")))
            .collect()
    }
}

impl OidcIdentity {
    /// An identity at `issuer` matched by every `(name, value)` claim given.
    pub fn new<I, N, V>(issuer: &str, claims: I) -> Self
    where
        I: IntoIterator<Item = (N, V)>,
        N: Into<String>,
        V: Into<String>,
    {
        Self {
            issuer: issuer.to_owned(),
            claims: claims
                .into_iter()
                .map(|(name, value)| Claim {
                    name: name.into(),
                    value: value.into(),
                })
                .collect(),
        }
    }

    /// Every claim this identity names, by its [`Claim::pointer`], with the
    /// value it must hold. A claim named twice with one value is here once.
    #[must_use]
    pub fn claims_by_pointer(&self) -> BTreeSet<(String, &str)> {
        self.claims
            .iter()
            .map(|claim| (claim.pointer(), claim.value.as_str()))
            .collect()
    }

    /// The first claim whose [`Claim::pointer`] an earlier claim already
    /// names, in either spelling.
    #[must_use]
    pub fn repeated_claim(&self) -> Option<&Claim> {
        let mut named = BTreeSet::new();
        self.claims
            .iter()
            .find(|claim| !named.insert(claim.pointer()))
    }
}

impl DidDocument {
    /// Builds the document for an agent account.
    ///
    /// `public_key_multibase` is a `&str` on purpose: this crate has no
    /// opinion on how the key was generated, and taking a key type here would
    /// make every consumer of DID documents depend on the key crate.
    ///
    /// Fragment ids are emitted fully qualified. The spec asks readers to
    /// accept both forms, and the qualified one survives being copied out of
    /// the document into some other context without losing its subject.
    pub fn for_account(
        did: &AccountDid,
        public_key_multibase: &str,
        handle: &str,
        pds_endpoint: &str,
    ) -> Self {
        let did_str = did.as_str();
        Self {
            context: DEFAULT_CONTEXT.iter().map(|c| (*c).to_owned()).collect(),
            id: did_str.to_owned(),
            also_known_as: vec![format!("at://{handle}")],
            verification_method: vec![VerificationMethod {
                id: format!("{did_str}{ATPROTO_KEY_FRAGMENT}"),
                type_: MULTIKEY_TYPE.to_owned(),
                controller: did_str.to_owned(),
                public_key_multibase: public_key_multibase.to_owned(),
            }],
            authentication: Vec::new(),
            service: vec![Service {
                id: format!("{did_str}{ATPROTO_PDS_FRAGMENT}"),
                type_: PDS_SERVICE_TYPE.to_owned(),
                service_endpoint: pds_endpoint.to_owned(),
            }],
            operator: None,
        }
    }

    /// Builds the document for the server itself.
    ///
    /// A service document, not an account one: no signing key and no handle,
    /// because the server holds neither on its own behalf. It exists so that
    /// the DID a vouch record names resolves to something that says where the
    /// server is, which is the whole of what a reader needs from it.
    pub fn for_service(did: &str, pds_endpoint: &str) -> Self {
        Self {
            context: DEFAULT_CONTEXT.iter().map(|c| (*c).to_owned()).collect(),
            id: did.to_owned(),
            also_known_as: Vec::new(),
            verification_method: Vec::new(),
            authentication: Vec::new(),
            service: vec![Service {
                id: format!("{did}{ATPROTO_PDS_FRAGMENT}"),
                type_: PDS_SERVICE_TYPE.to_owned(),
                service_endpoint: pds_endpoint.to_owned(),
            }],
            operator: None,
        }
    }

    /// The first claimed handle, with the `at://` prefix stripped.
    ///
    /// "First *valid* entry" is the spec's rule and now the implementation's:
    /// `alsoKnownAs` is an ordered list a DID controller writes, it may hold
    /// entries in other URI schemes, and it is not this crate's to trust. An
    /// entry that is not a syntactically valid handle is skipped rather than
    /// returned, so a document whose first entry is `at://not a handle` and
    /// whose second is real resolves to the real one instead of to garbage a
    /// caller would then try to look up.
    pub fn handle(&self) -> Option<&str> {
        self.also_known_as
            .iter()
            .filter_map(|aka| aka.strip_prefix("at://"))
            .find(|handle| crate::handle::validate(handle).is_ok())
    }

    /// Whether this document claims `handle` as its own.
    ///
    /// The other half of atproto's bidirectional rule. A handle resolves to a
    /// DID, and that is only half an answer: the DID's document has to claim
    /// the handle back, or what has been resolved is somebody asserting a name
    /// they do not hold. A resolver that stops after the first half will file
    /// records under whichever account was quickest to claim the name.
    ///
    /// Only the *first valid* `alsoKnownAs` entry counts, which is [`handle`]
    /// and the specification's own rule. Deliberately not "any entry mentions
    /// it": `alsoKnownAs` is an ordered list its controller writes, so a
    /// document could list a real handle second and have this answer yes to a
    /// name no resolver would ever return for it.
    ///
    /// Compared case-insensitively, because a handle is a hostname.
    ///
    /// [`handle`]: Self::handle
    pub fn claims_handle(&self, handle: &str) -> bool {
        self.handle()
            .is_some_and(|claimed| claimed.eq_ignore_ascii_case(handle))
    }

    /// Whether `id` is this document's own `fragment` entry.
    ///
    /// A DID URL is a DID plus a fragment, and the DID half is what says
    /// whose entry it is. `ends_with` alone does not read it, so a document
    /// for `did:web:victim.example` could list
    /// `did:web:attacker.example#atproto` and have it answered as the
    /// victim's signing key — a well-formed entry that does not belong to
    /// the subject, accepted because the only field that says so was never
    /// looked at. The relative form (`#atproto`, no DID at all) is the other
    /// spelling the spec asks readers to accept, and it can only mean the
    /// document's own subject.
    fn owns_fragment(&self, id: &str, fragment: &str) -> bool {
        owns_fragment(&self.id, id, fragment)
    }

    /// Names the human who answers for this account.
    #[must_use]
    pub fn with_operator(mut self, operator: impl Into<String>) -> Self {
        self.operator = Some(operator.into());
        self
    }

    /// The human who answers for this account, if the document says.
    pub fn operator(&self) -> Option<&str> {
        self.operator.as_deref()
    }

    /// The multibase signing key, taking the first `#atproto` entry of the
    /// correct type and ignoring any others, as the spec directs.
    ///
    /// The entry must also be this document's own: an `id` whose DID half is
    /// this document's `id`, or absent entirely.
    pub fn signing_key_multibase(&self) -> Option<&str> {
        self.verification_method
            .iter()
            .find(|vm| {
                self.owns_fragment(&vm.id, ATPROTO_KEY_FRAGMENT) && vm.type_ == MULTIKEY_TYPE
            })
            .map(|vm| vm.public_key_multibase.as_str())
    }

    /// The PDS endpoint, taking the first `#atproto_pds` entry of the correct
    /// type and ignoring any others.
    ///
    /// The entry must also be this document's own: an `id` whose DID half is
    /// this document's `id`, or absent entirely.
    pub fn pds_endpoint(&self) -> Option<&str> {
        self.service
            .iter()
            .find(|s| {
                self.owns_fragment(&s.id, ATPROTO_PDS_FRAGMENT) && s.type_ == PDS_SERVICE_TYPE
            })
            .map(|s| s.service_endpoint.as_str())
    }

    /// The endpoint of the service whose id is `#service`, of whatever
    /// type: the entry an `atproto-proxy` header names, as
    /// `did:web:api.bsky.app#bsky_appview` names `bsky_appview`.
    ///
    /// The entry must be this document's own, as for [`Self::pds_endpoint`].
    pub fn service_endpoint(&self, service: &str) -> Option<&str> {
        let fragment = format!("#{service}");
        self.service
            .iter()
            .find(|s| self.owns_fragment(&s.id, &fragment))
            .map(|s| s.service_endpoint.as_str())
    }
}

/// Whether `id` is `subject`'s own `fragment` entry; see
/// [`DidDocument::owns_fragment`].
fn owns_fragment(subject: &str, id: &str, fragment: &str) -> bool {
    matches!(id.strip_suffix(fragment), Some(base) if base.is_empty() || base == subject)
}

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

    fn claim(name: &str) -> Claim {
        Claim {
            name: name.to_owned(),
            value: "x".to_owned(),
        }
    }

    /// A top-level name and the pointer to it are one claim, and so are two
    /// spellings of one pointer. A pointer into a nested claim is not a
    /// top-level name with a slash in it.
    #[test]
    fn every_spelling_of_one_claim_is_one_pointer() {
        for (one, other) in [
            ("repository", "/repository"),
            ("kubernetes.io/namespace", "/kubernetes.io~1namespace"),
            ("a~b", "/a~0b"),
            ("/a~2b", "/a~02b"),
        ] {
            assert_eq!(
                claim(one).pointer(),
                claim(other).pointer(),
                "{one}, {other}"
            );
        }
        assert_ne!(
            claim("kubernetes.io/namespace").pointer(),
            claim("/kubernetes.io/namespace").pointer()
        );
        let identity = OidcIdentity {
            issuer: "https://issuer.example".to_owned(),
            claims: vec![claim("repository"), claim("sub"), claim("/repository")],
        };
        assert_eq!(identity.repeated_claim(), Some(&claim("/repository")));
        assert_eq!(identity.claims_by_pointer().len(), 2);
    }
}