feature: atproto-lexicon crate and atproto-lexicon-resolve tool

Cargo.lock

···
 ]
 
 [[package]]
+name = "atproto-lexicon"
+version = "0.12.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "atproto-client",
+ "atproto-identity",
+ "clap",
+ "hickory-resolver",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.12",
+ "tokio",
+ "tracing",
+ "zeroize",
+]
+
+[[package]]
 name = "atproto-oauth"
 version = "0.12.0"
 dependencies = [

Cargo.toml

···
     "crates/atproto-oauth",
     "crates/atproto-record",
     "crates/atproto-xrpcs-helloworld",
-    "crates/atproto-xrpcs",
+    "crates/atproto-xrpcs", "crates/atproto-lexicon",
 ]
 resolver = "3"
 

crates/atproto-lexicon/Cargo.toml

···
+[package]
+name = "atproto-lexicon"
+version = "0.12.0"
+description = "AT Protocol lexicon resolution and validation"
+readme = "README.md"
+homepage = "https://tangled.sh/@smokesignal.events/atproto-identity-rs"
+documentation = "https://docs.rs/atproto-identity"
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[[bin]]
+name = "atproto-lexicon-resolve"
+test = false
+bench = false
+doc = true
+required-features = ["clap", "hickory-dns"]
+
+[features]
+default = ["hickory-dns"]
+zeroize = ["dep:zeroize"]
+hickory-dns = ["dep:hickory-resolver"]
+clap = ["dep:clap"]
+
+[dependencies]
+atproto-identity.workspace = true
+atproto-client.workspace = true
+anyhow.workspace = true
+async-trait.workspace = true
+clap = { workspace = true, optional = true }
+reqwest.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+zeroize = { workspace = true, optional = true }
+hickory-resolver = { workspace = true, optional = true }
+
+[lints]
+workspace = true

crates/atproto-lexicon/README.md

···
+# atproto-lexicon
+
+AT Protocol lexicon resolution and validation library for Rust.
+
+## Overview
+
+This library provides functionality for resolving and validating AT Protocol lexicons, which define the schema and structure of AT Protocol data. It implements the full lexicon resolution chain as specified by the AT Protocol:
+
+1. Convert NSID to DNS name with `_lexicon` prefix
+2. Perform DNS TXT lookup to get the authoritative DID
+3. Resolve the DID to get the DID document
+4. Extract PDS endpoint from the DID document
+5. Make XRPC call to fetch the lexicon schema
+
+## Features
+
+- **Lexicon Resolution**: Resolve NSIDs to their schema definitions via DNS and XRPC
+- **Recursive Resolution**: Automatically resolve referenced lexicons with configurable depth limits
+- **NSID Validation**: Comprehensive validation of Namespace Identifiers
+- **Reference Extraction**: Extract and resolve lexicon references including fragment-only references
+- **Context-Aware Resolution**: Handle fragment-only references using lexicon ID as context
+- **CLI Tool**: Command-line interface for lexicon resolution
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+atproto-lexicon = "0.12.0"
+```
+
+## Usage
+
+### Basic Lexicon Resolution
+
+```rust
+use atproto_lexicon::resolve::{DefaultLexiconResolver, LexiconResolver};
+use atproto_identity::resolve::HickoryDnsResolver;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(vec![]);
+
+    let resolver = DefaultLexiconResolver::new(http_client, dns_resolver);
+
+    // Resolve a single lexicon
+    let lexicon = resolver.resolve("app.bsky.feed.post").await?;
+    println!("Resolved lexicon: {}", serde_json::to_string_pretty(&lexicon)?);
+
+    Ok(())
+}
+```
+
+### Recursive Resolution
+
+```rust
+use atproto_lexicon::resolve_recursive::{RecursiveLexiconResolver, RecursiveResolverConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // ... setup resolver as above ...
+
+    let config = RecursiveResolverConfig {
+        max_depth: 5,  // Maximum recursion depth
+        include_entry: true,  // Include the entry lexicon in results
+    };
+
+    let recursive_resolver = RecursiveLexiconResolver::with_config(resolver, config);
+
+    // Resolve a lexicon and all its dependencies
+    let lexicons = recursive_resolver.resolve_recursive("app.bsky.feed.post").await?;
+
+    for (nsid, schema) in lexicons {
+        println!("Resolved {}: {} bytes", nsid,
+                 serde_json::to_string(&schema)?.len());
+    }
+
+    Ok(())
+}
+```
+
+### NSID Validation
+
+```rust
+use atproto_lexicon::validation::{
+    is_valid_nsid, parse_nsid, nsid_to_dns_name, absolute
+};
+
+// Validate NSIDs
+assert!(is_valid_nsid("app.bsky.feed.post"));
+assert!(!is_valid_nsid("invalid"));
+
+// Parse NSID components
+let parts = parse_nsid("app.bsky.feed.post#reply", None)?;
+assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+assert_eq!(parts.fragment, Some("reply".to_string()));
+
+// Convert NSID to DNS name for resolution
+let dns_name = nsid_to_dns_name("app.bsky.feed.post")?;
+assert_eq!(dns_name, "_lexicon.feed.bsky.app");
+
+// Make fragment-only references absolute
+assert_eq!(absolute("app.bsky.feed.post", "#reply"), "app.bsky.feed.post#reply");
+assert_eq!(absolute("app.bsky.feed.post", "com.example.other"), "com.example.other");
+```
+
+### Extract Lexicon References
+
+```rust
+use atproto_lexicon::resolve_recursive::extract_lexicon_references;
+use serde_json::json;
+
+let schema = json!({
+    "lexicon": 1,
+    "id": "app.bsky.feed.post",
+    "defs": {
+        "main": {
+            "type": "record",
+            "record": {
+                "type": "object",
+                "properties": {
+                    "embed": {
+                        "type": "union",
+                        "refs": [
+                            { "type": "ref", "ref": "app.bsky.embed.images" },
+                            { "type": "ref", "ref": "#localref" }  // Fragment reference
+                        ]
+                    }
+                }
+            }
+        }
+    }
+});
+
+let references = extract_lexicon_references(&schema);
+// References will include:
+// - "app.bsky.embed.images" (external reference)
+// - "app.bsky.feed.post" (from #localref using the lexicon's id as context)
+```
+
+## CLI Tool
+
+The crate includes a command-line tool for lexicon resolution:
+
+```bash
+# Build with CLI support
+cargo build --features clap --bin atproto-lexicon-resolve
+
+# Resolve a single lexicon
+cargo run --features clap --bin atproto-lexicon-resolve -- app.bsky.feed.post
+
+# Pretty print the output
+cargo run --features clap --bin atproto-lexicon-resolve -- --pretty app.bsky.feed.post
+
+# Recursively resolve all referenced lexicons
+cargo run --features clap --bin atproto-lexicon-resolve -- --recursive app.bsky.feed.post
+
+# Limit recursion depth
+cargo run --features clap --bin atproto-lexicon-resolve -- --recursive --max-depth 3 app.bsky.feed.post
+
+# Show dependency graph
+cargo run --features clap --bin atproto-lexicon-resolve -- --recursive --show-deps app.bsky.feed.post
+
+# List only direct references
+cargo run --features clap --bin atproto-lexicon-resolve -- --list-refs app.bsky.feed.post
+```
+
+## Module Structure
+
+- **`resolve`**: Core lexicon resolution implementation following AT Protocol specification
+- **`resolve_recursive`**: Recursive resolution with dependency tracking and cycle detection
+- **`validation`**: NSID validation, parsing, and helper functions
+
+## Key Types
+
+### `NsidParts`
+Represents a parsed NSID with its component parts and optional fragment:
+- `parts`: Vector of NSID components (e.g., `["app", "bsky", "feed", "post"]`)
+- `fragment`: Optional fragment identifier (e.g., `"reply"` for `#reply`)
+
+### `RecursiveResolverConfig`
+Configuration for recursive resolution:
+- `max_depth`: Maximum recursion depth (default: 10)
+- `include_entry`: Whether to include the entry lexicon in results (default: true)
+
+### `RecursiveResolutionResult`
+Detailed results from recursive resolution:
+- `lexicons`: HashMap of resolved lexicons by NSID
+- `failed`: Set of NSIDs that couldn't be resolved
+- `dependencies`: Dependency graph showing which lexicons reference which
+
+## Features
+
+- **Fragment-Only Reference Resolution**: Automatically resolves fragment-only references (e.g., `#localref`) using the lexicon's `id` field as context
+- **Union Type Support**: Extracts references from both `ref` objects and `union` types with `refs` arrays
+- **DNS-based Discovery**: Implements the AT Protocol DNS-based lexicon discovery mechanism
+- **Cycle Detection**: Prevents infinite recursion when resolving circular dependencies
+- **Validation**: Comprehensive NSID validation following AT Protocol specifications
+
+## Error Handling
+
+The library uses structured error types for different failure modes:
+- `ValidationError`: NSID format validation errors
+- `ResolveError`: DNS resolution and DID resolution errors
+- Network and XRPC errors are wrapped in `anyhow::Error`
+
+## Dependencies
+
+- `atproto-identity`: For DID resolution and DNS operations
+- `atproto-client`: For XRPC communication
+- `serde_json`: For JSON schema handling
+- `async-trait`: For async trait definitions
+- `tracing`: For structured logging
+
+## License
+
+This project is part of the atproto-identity-rs workspace. See the root LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

crates/atproto-lexicon/src/bin/atproto-lexicon-resolve.rs

···
+//! CLI tool for resolving AT Protocol lexicons.
+//!
+//! This tool resolves lexicon NSIDs to their schema definitions using the
+//! AT Protocol lexicon resolution process, with support for recursive resolution.
+
+use std::collections::{HashMap, HashSet};
+
+use anyhow::Result;
+use atproto_identity::{
+    config::{CertificateBundles, DnsNameservers, default_env, optional_env, version},
+    resolve::HickoryDnsResolver,
+};
+use atproto_lexicon::{
+    resolve::{DefaultLexiconResolver, LexiconResolver},
+    resolve_recursive::{RecursiveLexiconResolver, RecursiveResolverConfig},
+};
+use clap::Parser;
+use serde_json::Value;
+
+/// AT Protocol Lexicon Resolution CLI
+#[derive(Parser)]
+#[command(
+    name = "atproto-lexicon-resolve",
+    version,
+    about = "Resolve AT Protocol lexicon NSIDs to their schema definitions",
+    long_about = "
+A command-line tool for resolving AT Protocol lexicon NSIDs (Namespace Identifiers) to their
+schema definitions. The resolution process follows the AT Protocol specification:
+
+1. Convert NSID to DNS name with '_lexicon' prefix
+2. Perform DNS TXT lookup to get the authoritative DID
+3. Resolve the DID to get the DID document
+4. Extract PDS endpoint from the DID document
+5. Make XRPC call to fetch the lexicon schema
+
+Supports recursive resolution to automatically resolve all referenced lexicons.
+
+ENVIRONMENT VARIABLES:
+  PLC_HOSTNAME         PLC directory hostname (default: \"plc.directory\")
+  USER_AGENT           HTTP user agent string (default: auto-generated)
+  CERTIFICATE_BUNDLES  Colon-separated paths to additional CA certificates
+  DNS_NAMESERVERS      Comma-separated DNS nameserver addresses
+
+EXAMPLES:
+  # Resolve a single lexicon:
+  atproto-lexicon-resolve app.bsky.feed.post
+
+  # Resolve multiple lexicons:
+  atproto-lexicon-resolve app.bsky.feed.post app.bsky.actor.profile
+
+  # Pretty print the JSON output:
+  atproto-lexicon-resolve --pretty app.bsky.feed.post
+
+  # Recursively resolve all referenced lexicons:
+  atproto-lexicon-resolve --recursive app.bsky.feed.post
+
+  # Resolve recursively with limited depth:
+  atproto-lexicon-resolve --recursive --max-depth 3 app.bsky.feed.post
+
+  # Show dependency graph:
+  atproto-lexicon-resolve --recursive --show-deps app.bsky.feed.post
+
+  # List only the NSIDs of referenced lexicons:
+  atproto-lexicon-resolve --list-refs app.bsky.feed.post
+"
+)]
+struct Args {
+    /// One or more lexicon NSIDs to resolve
+    nsids: Vec<String>,
+
+    /// Pretty print the JSON output
+    #[arg(long)]
+    pretty: bool,
+
+    /// Output only the schema without metadata
+    #[arg(long)]
+    schema_only: bool,
+
+    /// Recursively resolve all referenced lexicons
+    #[arg(long, short = 'r')]
+    recursive: bool,
+
+    /// Maximum depth for recursive resolution (default: 10)
+    #[arg(long, default_value = "10")]
+    max_depth: usize,
+
+    /// Exclude the entry lexicon from recursive results
+    #[arg(long)]
+    exclude_entry: bool,
+
+    /// Show dependency graph for recursive resolution
+    #[arg(long)]
+    show_deps: bool,
+
+    /// List only the NSIDs that were resolved (no schemas)
+    #[arg(long)]
+    list_nsids: bool,
+
+    /// List only the direct references of the lexicon
+    #[arg(long)]
+    list_refs: bool,
+
+    /// Show failed resolutions when using recursive mode
+    #[arg(long)]
+    show_failed: bool,
+
+    /// Output format: json (default), yaml, or compact
+    #[arg(long, default_value = "json")]
+    format: OutputFormat,
+}
+
+#[derive(Debug, Clone, clap::ValueEnum)]
+enum OutputFormat {
+    Json,
+    Compact,
+    Summary,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let args = Args::parse();
+
+    // Configure environment variables
+    let _plc_hostname = default_env("PLC_HOSTNAME", "plc.directory");
+    let certificate_bundles: CertificateBundles = optional_env("CERTIFICATE_BUNDLES").try_into()?;
+    let default_user_agent = format!(
+        "atproto-lexicon-rs ({}; +https://tangled.sh/@smokesignal.events/atproto-identity-rs)",
+        version()?
+    );
+    let user_agent = default_env("USER_AGENT", &default_user_agent);
+    let dns_nameservers: DnsNameservers = optional_env("DNS_NAMESERVERS").try_into()?;
+
+    // Build HTTP client with certificate bundles
+    let mut client_builder = reqwest::Client::builder();
+    for ca_certificate in certificate_bundles.as_ref() {
+        let cert = std::fs::read(ca_certificate)?;
+        let cert = reqwest::Certificate::from_pem(&cert)?;
+        client_builder = client_builder.add_root_certificate(cert);
+    }
+
+    client_builder = client_builder.user_agent(user_agent);
+    let http_client = client_builder.build()?;
+
+    // Create DNS resolver
+    let dns_resolver = HickoryDnsResolver::create_resolver(dns_nameservers.as_ref());
+
+    // Create lexicon resolver
+    let base_resolver = DefaultLexiconResolver::new(http_client, dns_resolver);
+
+    // Process each NSID
+    for nsid in &args.nsids {
+        if args.list_refs {
+            // Just list direct references
+            let recursive_resolver = RecursiveLexiconResolver::new(base_resolver.clone());
+            match recursive_resolver.get_direct_references(nsid).await {
+                Ok(refs) => {
+                    if refs.is_empty() {
+                        eprintln!("{}: no references", nsid);
+                    } else {
+                        println!("{}:", nsid);
+                        let mut sorted_refs: Vec<_> = refs.into_iter().collect();
+                        sorted_refs.sort();
+                        for ref_nsid in sorted_refs {
+                            println!("  - {}", ref_nsid);
+                        }
+                    }
+                }
+                Err(err) => {
+                    eprintln!("Error getting references for {}: {}", nsid, err);
+                }
+            }
+        } else if args.recursive {
+            // Recursive resolution
+            let config = RecursiveResolverConfig {
+                max_depth: args.max_depth,
+                include_entry: !args.exclude_entry,
+            };
+            let recursive_resolver = RecursiveLexiconResolver::with_config(base_resolver.clone(), config);
+
+            if args.show_deps || args.show_failed {
+                // Use detailed resolution for dependency graph
+                match recursive_resolver.resolve_with_details(nsid).await {
+                    Ok(result) => {
+                        if args.list_nsids {
+                            // Just list the NSIDs
+                            let mut nsids: Vec<_> = result.lexicons.keys().cloned().collect();
+                            nsids.sort();
+                            for nsid in nsids {
+                                println!("{}", nsid);
+                            }
+                        } else if args.show_deps {
+                            // Show dependency graph
+                            println!("Dependency graph for {}:", nsid);
+                            print_dependency_graph(&result.dependencies);
+
+                            if args.show_failed && !result.failed.is_empty() {
+                                println!("\nFailed to resolve:");
+                                let mut failed: Vec<_> = result.failed.into_iter().collect();
+                                failed.sort();
+                                for nsid in failed {
+                                    println!("  - {}", nsid);
+                                }
+                            }
+                        } else {
+                            // Output the resolved lexicons
+                            output_lexicons(&result.lexicons, &args)?;
+                        }
+                    }
+                    Err(err) => {
+                        eprintln!("Error recursively resolving {}: {}", nsid, err);
+                    }
+                }
+            } else {
+                // Simple recursive resolution
+                match recursive_resolver.resolve_recursive(nsid).await {
+                    Ok(lexicons) => {
+                        if args.list_nsids {
+                            // Just list the NSIDs
+                            let mut nsids: Vec<_> = lexicons.keys().cloned().collect();
+                            nsids.sort();
+                            for nsid in nsids {
+                                println!("{}", nsid);
+                            }
+                        } else {
+                            output_lexicons(&lexicons, &args)?;
+                        }
+                    }
+                    Err(err) => {
+                        eprintln!("Error recursively resolving {}: {}", nsid, err);
+                    }
+                }
+            }
+        } else {
+            // Single lexicon resolution
+            match base_resolver.resolve(nsid).await {
+                Ok(lexicon) => {
+                    let output = if args.schema_only {
+                        // Extract just the schema portion if requested
+                        lexicon.get("schema").unwrap_or(&lexicon).clone()
+                    } else {
+                        lexicon
+                    };
+
+                    match args.format {
+                        OutputFormat::Json => {
+                            if args.pretty {
+                                println!("{}", serde_json::to_string_pretty(&output)?);
+                            } else {
+                                println!("{}", serde_json::to_string(&output)?);
+                            }
+                        }
+                        OutputFormat::Compact => {
+                            println!("{}", serde_json::to_string(&output)?);
+                        }
+                        OutputFormat::Summary => {
+                            print_lexicon_summary(nsid, &output);
+                        }
+                    }
+                }
+                Err(err) => {
+                    eprintln!("Error resolving {}: {}", nsid, err);
+                    continue;
+                }
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Output multiple lexicons according to the command-line arguments
+fn output_lexicons(lexicons: &HashMap<String, Value>, args: &Args) -> Result<()> {
+    match args.format {
+        OutputFormat::Json => {
+            // Create a single JSON object with all lexicons
+            let output = if args.schema_only {
+                let mut schemas = serde_json::Map::new();
+                for (nsid, lexicon) in lexicons {
+                    let schema = lexicon.get("schema").unwrap_or(lexicon).clone();
+                    schemas.insert(nsid.clone(), schema);
+                }
+                Value::Object(schemas)
+            } else {
+                serde_json::to_value(lexicons)?
+            };
+
+            if args.pretty {
+                println!("{}", serde_json::to_string_pretty(&output)?);
+            } else {
+                println!("{}", serde_json::to_string(&output)?);
+            }
+        }
+        OutputFormat::Compact => {
+            println!("{}", serde_json::to_string(lexicons)?);
+        }
+        OutputFormat::Summary => {
+            println!("Resolved {} lexicons:", lexicons.len());
+            let mut nsids: Vec<_> = lexicons.keys().cloned().collect();
+            nsids.sort();
+            for nsid in nsids {
+                if let Some(lexicon) = lexicons.get(&nsid) {
+                    print_lexicon_summary(&nsid, lexicon);
+                    println!();
+                }
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Print a summary of a lexicon
+fn print_lexicon_summary(nsid: &str, lexicon: &Value) {
+    println!("NSID: {}", nsid);
+
+    // Try to extract description
+    if let Some(desc) = lexicon.get("defs")
+        .and_then(|d| d.get("main"))
+        .and_then(|m| m.get("description"))
+        .and_then(|d| d.as_str()) {
+        println!("  Description: {}", desc);
+    }
+
+    // Count definitions
+    if let Some(defs) = lexicon.get("defs").and_then(|d| d.as_object()) {
+        println!("  Definitions: {}", defs.len());
+
+        // List definition types
+        let mut def_types = HashSet::new();
+        for (_name, def) in defs {
+            if let Some(type_str) = def.get("type").and_then(|t| t.as_str()) {
+                def_types.insert(type_str);
+            }
+        }
+        if !def_types.is_empty() {
+            let mut types: Vec<_> = def_types.into_iter().collect();
+            types.sort();
+            println!("  Types: {}", types.join(", "));
+        }
+    }
+}
+
+/// Print the dependency graph
+fn print_dependency_graph(deps: &HashMap<String, HashSet<String>>) {
+    if deps.is_empty() {
+        println!("No dependencies found.");
+        return;
+    }
+
+    let mut sorted_deps: Vec<_> = deps.iter().collect();
+    sorted_deps.sort_by_key(|(nsid, _)| *nsid);
+
+    for (nsid, refs) in sorted_deps {
+        println!("{}:", nsid);
+        let mut sorted_refs: Vec<_> = refs.iter().cloned().collect();
+        sorted_refs.sort();
+        for ref_nsid in sorted_refs {
+            println!("  → {}", ref_nsid);
+        }
+    }
+}

crates/atproto-lexicon/src/lib.rs

···
+//! AT Protocol lexicon resolution and validation library.
+//!
+//! This library provides functionality for resolving and validating AT Protocol lexicons,
+//! which define the schema and structure of AT Protocol data.
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+pub mod resolve;
+pub mod resolve_recursive;
+pub mod validation;

crates/atproto-lexicon/src/resolve.rs

···
+//! Lexicon resolution functionality for AT Protocol.
+//!
+//! This module handles the resolution of lexicon identifiers to their corresponding
+//! schema definitions according to the AT Protocol specification.
+//!
+//! The resolution process:
+//! 1. Convert NSID to DNS name with "_lexicon" prefix
+//! 2. Perform DNS TXT lookup to get DID
+//! 3. Resolve DID to get DID document
+//! 4. Extract PDS endpoint from DID document
+//! 5. Make XRPC call to com.atproto.repo.getRecord to fetch lexicon
+
+use anyhow::{anyhow, Result};
+use atproto_client::{
+    client::Auth,
+    com::atproto::repo::{get_record, GetRecordResponse},
+};
+use atproto_identity::{
+    errors::ResolveError,
+    resolve::{DnsResolver, resolve_subject},
+};
+use serde_json::Value;
+use tracing::instrument;
+
+use crate::validation;
+
+/// Trait for lexicon resolution implementations.
+#[async_trait::async_trait]
+pub trait LexiconResolver: Send + Sync {
+    /// Resolve a lexicon NSID to its schema definition.
+    async fn resolve(&self, nsid: &str) -> Result<Value>;
+}
+
+/// Default lexicon resolver implementation using DNS and XRPC.
+#[derive(Clone)]
+pub struct DefaultLexiconResolver<R> {
+    http_client: reqwest::Client,
+    dns_resolver: R,
+}
+
+impl<R> DefaultLexiconResolver<R> {
+    /// Create a new lexicon resolver.
+    pub fn new(http_client: reqwest::Client, dns_resolver: R) -> Self {
+        Self {
+            http_client,
+            dns_resolver,
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl<R> LexiconResolver for DefaultLexiconResolver<R>
+where
+    R: DnsResolver + Send + Sync,
+{
+    #[instrument(skip(self), err)]
+    async fn resolve(&self, nsid: &str) -> Result<Value> {
+        // Step 1: Convert NSID to DNS name
+        let dns_name = validation::nsid_to_dns_name(nsid)?;
+
+        // Step 2: Perform DNS lookup to get DID
+        let did = resolve_lexicon_dns(&self.dns_resolver, &dns_name).await?;
+
+        // Step 3: Resolve DID to get DID document
+        let resolved_did = resolve_subject(&self.http_client, &self.dns_resolver, &did).await?;
+
+        // Step 4: Get PDS endpoint from DID document
+        let pds_endpoint = get_pds_from_did(&self.http_client, &resolved_did).await?;
+
+        // Step 5: Fetch lexicon from PDS
+        let lexicon = fetch_lexicon_from_pds(&self.http_client, &pds_endpoint, &resolved_did, nsid).await?;
+
+        Ok(lexicon)
+    }
+}
+
+/// Resolve lexicon DID from DNS TXT records.
+#[instrument(skip(dns_resolver), err)]
+pub async fn resolve_lexicon_dns<R: DnsResolver + ?Sized>(
+    dns_resolver: &R,
+    lookup_dns: &str,
+) -> Result<String, ResolveError> {
+    let txt_records = dns_resolver
+        .resolve_txt(lookup_dns)
+        .await?;
+
+    // Look for did= prefix in TXT records
+    let dids: Vec<String> = txt_records
+        .iter()
+        .filter_map(|record| {
+            record.strip_prefix("did=")
+                .or_else(|| record.strip_prefix("did:"))
+                .map(|did| {
+                    // Ensure proper DID format
+                    if did.starts_with("plc:") || did.starts_with("web:") {
+                        format!("did:{}", did)
+                    } else if did.starts_with("did:") {
+                        did.to_string()
+                    } else {
+                        format!("did:{}", did)
+                    }
+                })
+        })
+        .collect();
+
+    if dids.is_empty() {
+        return Err(ResolveError::NoDIDsFound);
+    }
+
+    if dids.len() > 1 {
+        return Err(ResolveError::MultipleDIDsFound);
+    }
+
+    Ok(dids[0].clone())
+}
+
+/// Get PDS endpoint from DID document.
+#[instrument(skip(http_client), err)]
+async fn get_pds_from_did(http_client: &reqwest::Client, did: &str) -> Result<String> {
+    use atproto_identity::{plc, web, model::Document, resolve::{parse_input, InputType}};
+
+    // Get DID document based on DID method
+    let did_document: Document = match parse_input(did)? {
+        InputType::Plc(did) => {
+            plc::query(http_client, "plc.directory", &did).await?
+        }
+        InputType::Web(did) => {
+            web::query(http_client, &did).await?
+        }
+        _ => return Err(anyhow!("Invalid DID format: {}", did)),
+    };
+
+    // Extract PDS endpoint from service array
+    for service in &did_document.service {
+        if service.r#type == "AtprotoPersonalDataServer" {
+            return Ok(service.service_endpoint.clone());
+        }
+    }
+
+    Err(anyhow!("No PDS endpoint found in DID document"))
+}
+
+/// Fetch lexicon schema from PDS using XRPC.
+#[instrument(skip(http_client), err)]
+async fn fetch_lexicon_from_pds(
+    http_client: &reqwest::Client,
+    pds_endpoint: &str,
+    did: &str,
+    nsid: &str,
+) -> Result<Value> {
+    // Construct the record key for the lexicon
+    // Lexicons are stored under the com.atproto.repo.lexicon collection
+    let collection = "com.atproto.lexicon.schema";
+
+    // Make XRPC call to get the lexicon record without authentication
+    let auth = Auth::None;
+    let response = get_record(
+        http_client,
+        &auth,
+        pds_endpoint,
+        did,
+        collection,
+        nsid,
+        None,
+    )
+    .await
+    .map_err(|e| anyhow!("Failed to fetch lexicon from PDS: {}", e))?;
+
+    // Extract the value from the response
+    match response {
+        GetRecordResponse::Record { value, .. } => Ok(value),
+        GetRecordResponse::Error(err) => {
+            let msg = err.message.or(err.error_description).or(err.error).unwrap_or_else(|| "Unknown error".to_string());
+            Err(anyhow!("Error fetching lexicon for {}: {}", nsid, msg))
+        }
+    }
+}
+

crates/atproto-lexicon/src/resolve_recursive.rs

···
+//! Recursive lexicon resolution functionality for AT Protocol.
+//!
+//! This module provides recursive resolution of lexicons, following references
+//! within lexicon schemas to resolve all dependent lexicons up to a specified depth.
+
+use std::collections::{HashMap, HashSet};
+
+use anyhow::{anyhow, Result};
+use serde_json::Value;
+use tracing::instrument;
+
+use crate::resolve::LexiconResolver;
+use crate::validation::{absolute, extract_nsid_from_ref_object};
+
+/// Configuration for recursive lexicon resolution.
+#[derive(Debug, Clone)]
+pub struct RecursiveResolverConfig {
+    /// Maximum depth for recursive resolution (0 = only resolve the entry lexicon).
+    pub max_depth: usize,
+    /// Whether to include the entry lexicon in the results.
+    pub include_entry: bool,
+}
+
+impl Default for RecursiveResolverConfig {
+    fn default() -> Self {
+        Self {
+            max_depth: 10,
+            include_entry: true,
+        }
+    }
+}
+
+/// A lexicon resolver that recursively resolves referenced lexicons.
+pub struct RecursiveLexiconResolver<R> {
+    /// The underlying lexicon resolver.
+    resolver: R,
+    /// Configuration for recursive resolution.
+    config: RecursiveResolverConfig,
+}
+
+impl<R> RecursiveLexiconResolver<R> {
+    /// Create a new recursive lexicon resolver with default configuration.
+    pub fn new(resolver: R) -> Self {
+        Self {
+            resolver,
+            config: RecursiveResolverConfig::default(),
+        }
+    }
+
+    /// Create a new recursive lexicon resolver with custom configuration.
+    pub fn with_config(resolver: R, config: RecursiveResolverConfig) -> Self {
+        Self { resolver, config }
+    }
+
+    /// Set the maximum depth for recursive resolution.
+    pub fn set_max_depth(&mut self, max_depth: usize) {
+        self.config.max_depth = max_depth;
+    }
+
+    /// Set whether to include the entry lexicon in the results.
+    pub fn set_include_entry(&mut self, include_entry: bool) {
+        self.config.include_entry = include_entry;
+    }
+}
+
+impl<R> RecursiveLexiconResolver<R>
+where
+    R: LexiconResolver,
+{
+    /// Recursively resolve a lexicon and all its referenced lexicons.
+    ///
+    /// Returns a HashMap where keys are NSIDs and values are the resolved lexicon schemas.
+    #[instrument(skip(self), err)]
+    pub async fn resolve_recursive(&self, entry_nsid: &str) -> Result<HashMap<String, Value>> {
+        let mut resolved = HashMap::new();
+        let mut visited = HashSet::new();
+        let mut to_resolve = HashSet::new();
+
+        // Start with the entry lexicon
+        to_resolve.insert(entry_nsid.to_string());
+
+        // Resolve lexicons level by level
+        for depth in 0..=self.config.max_depth {
+            if to_resolve.is_empty() {
+                break;
+            }
+
+            let current_batch = to_resolve.clone();
+            to_resolve.clear();
+
+            for nsid in current_batch {
+                // Skip if already visited
+                if visited.contains(&nsid) {
+                    continue;
+                }
+                visited.insert(nsid.clone());
+
+                // Skip the entry lexicon if configured to exclude it
+                if !self.config.include_entry && nsid == entry_nsid && depth == 0 {
+                    // Still need to extract references from it
+                    match self.resolver.resolve(&nsid).await {
+                        Ok(lexicon) => {
+                            let refs = extract_lexicon_references(&lexicon);
+                            to_resolve.extend(refs);
+                        }
+                        Err(e) => {
+                            tracing::warn!(error = ?e, nsid = %nsid, "Failed to resolve lexicon");
+                            continue;
+                        }
+                    }
+                    continue;
+                }
+
+                // Resolve the lexicon
+                match self.resolver.resolve(&nsid).await {
+                    Ok(lexicon) => {
+                        // Extract references for next level
+                        if depth < self.config.max_depth {
+                            let refs = extract_lexicon_references(&lexicon);
+                            to_resolve.extend(refs);
+                        }
+
+                        // Store the resolved lexicon
+                        resolved.insert(nsid.clone(), lexicon);
+                    }
+                    Err(e) => {
+                        tracing::warn!(error = ?e, nsid = %nsid, "Failed to resolve lexicon");
+                        continue;
+                    }
+                }
+            }
+        }
+
+        if resolved.is_empty() && self.config.include_entry {
+            return Err(anyhow!("Failed to resolve any lexicons"));
+        }
+
+        Ok(resolved)
+    }
+
+    /// Resolve a lexicon and return only its direct references.
+    #[instrument(skip(self), err)]
+    pub async fn get_direct_references(&self, nsid: &str) -> Result<HashSet<String>> {
+        let lexicon = self.resolver.resolve(nsid).await?;
+        Ok(extract_lexicon_references(&lexicon))
+    }
+}
+
+/// Extract all lexicon references from a lexicon schema.
+///
+/// Looks for:
+/// - Objects with `"type": "ref"` and extracts the `"ref"` field value
+/// - Objects with `"type": "union"` and extracts NSIDs from the `"refs"` array
+/// - Handles fragment-only references using the lexicon's `id` field as context
+#[instrument(skip(value))]
+pub fn extract_lexicon_references(value: &Value) -> HashSet<String> {
+    // Extract the lexicon's ID to use as context for fragment-only references
+    let context = value
+        .as_object()
+        .and_then(|obj| obj.get("id"))
+        .and_then(|id| id.as_str())
+        .map(|s| s.to_string());
+
+    let mut references = HashSet::new();
+    extract_references_recursive(value, &mut references, context.as_deref());
+    references
+}
+
+/// Recursively extract references from a JSON value with optional context.
+fn extract_references_recursive(value: &Value, references: &mut HashSet<String>, context: Option<&str>) {
+    match value {
+        Value::Object(map) => {
+            // Check if this is a reference object
+            if let Some(type_val) = map.get("type") {
+                if let Some(type_str) = type_val.as_str() {
+                    if type_str == "ref" {
+                        // Handle ref objects with context for fragment-only refs
+                        if let Some(ref_val) = map.get("ref").and_then(|v| v.as_str()) {
+                            let absolute_ref = if let Some(ctx) = context {
+                                absolute(ctx, ref_val)
+                            } else {
+                                ref_val.to_string()
+                            };
+
+                            // Now extract the NSID from the absolute reference
+                            if let Some(nsid) = extract_nsid_from_ref_object(&serde_json::json!({
+                                "type": "ref",
+                                "ref": absolute_ref
+                            }).as_object().unwrap()) {
+                                references.insert(nsid);
+                            }
+                        }
+                        return; // Don't recurse further into ref objects
+                    } else if type_str == "union" {
+                        // Handle union objects with context for fragment-only refs
+                        if let Some(refs_val) = map.get("refs") {
+                            if let Some(refs_array) = refs_val.as_array() {
+                                for ref_item in refs_array {
+                                    let ref_str = if let Some(s) = ref_item.as_str() {
+                                        s
+                                    } else if let Some(obj) = ref_item.as_object() {
+                                        if let Some(ref_val) = obj.get("ref").and_then(|v| v.as_str()) {
+                                            ref_val
+                                        } else {
+                                            continue;
+                                        }
+                                    } else {
+                                        continue;
+                                    };
+
+                                    // Make fragment-only references absolute
+                                    let absolute_ref = if let Some(ctx) = context {
+                                        absolute(ctx, ref_str)
+                                    } else {
+                                        ref_str.to_string()
+                                    };
+
+                                    // Extract NSID from the absolute reference (stripping fragment)
+                                    let nsid = if let Some(hash_pos) = absolute_ref.find('#') {
+                                        &absolute_ref[..hash_pos]
+                                    } else {
+                                        &absolute_ref
+                                    };
+
+                                    // Validate it's a proper NSID
+                                    if nsid.contains('.') && !nsid.is_empty() {
+                                        references.insert(nsid.to_string());
+                                    }
+                                }
+                            }
+                        }
+                        return; // Don't recurse further into union objects
+                    }
+                }
+            }
+
+            // Otherwise, recursively check all values in the object
+            for (_key, val) in map.iter() {
+                extract_references_recursive(val, references, context);
+            }
+        }
+        Value::Array(arr) => {
+            // Recursively check all elements in the array
+            for val in arr {
+                extract_references_recursive(val, references, context);
+            }
+        }
+        _ => {
+            // Primitive values don't contain references
+        }
+    }
+}
+
+/// Result of recursive lexicon resolution.
+#[derive(Debug, Clone)]
+pub struct RecursiveResolutionResult {
+    /// The resolved lexicons, keyed by NSID.
+    pub lexicons: HashMap<String, Value>,
+    /// NSIDs that were referenced but could not be resolved.
+    pub failed: HashSet<String>,
+    /// The dependency graph showing which lexicons reference which.
+    pub dependencies: HashMap<String, HashSet<String>>,
+}
+
+impl<R> RecursiveLexiconResolver<R>
+where
+    R: LexiconResolver,
+{
+    /// Recursively resolve a lexicon with detailed results.
+    ///
+    /// This provides more information than `resolve_recursive`, including
+    /// failed resolutions and the dependency graph.
+    #[instrument(skip(self), err)]
+    pub async fn resolve_with_details(&self, entry_nsid: &str) -> Result<RecursiveResolutionResult> {
+        let mut lexicons = HashMap::new();
+        let mut failed = HashSet::new();
+        let mut dependencies = HashMap::new();
+        let mut visited = HashSet::new();
+        let mut to_resolve = HashSet::new();
+
+        // Start with the entry lexicon
+        to_resolve.insert(entry_nsid.to_string());
+
+        // Resolve lexicons level by level
+        for depth in 0..=self.config.max_depth {
+            if to_resolve.is_empty() {
+                break;
+            }
+
+            let current_batch = to_resolve.clone();
+            to_resolve.clear();
+
+            for nsid in current_batch {
+                // Skip if already visited
+                if visited.contains(&nsid) {
+                    continue;
+                }
+                visited.insert(nsid.clone());
+
+                // Resolve the lexicon
+                match self.resolver.resolve(&nsid).await {
+                    Ok(lexicon) => {
+                        // Extract references
+                        let refs = extract_lexicon_references(&lexicon);
+
+                        // Record dependencies
+                        if !refs.is_empty() {
+                            dependencies.insert(nsid.clone(), refs.clone());
+                        }
+
+                        // Add references to resolve queue (if within depth limit)
+                        if depth < self.config.max_depth {
+                            to_resolve.extend(refs);
+                        }
+
+                        // Store the resolved lexicon (if configured to include it)
+                        if self.config.include_entry || nsid != entry_nsid || depth > 0 {
+                            lexicons.insert(nsid.clone(), lexicon);
+                        }
+                    }
+                    Err(e) => {
+                        tracing::warn!(error = ?e, nsid = %nsid, "Failed to resolve lexicon");
+                        failed.insert(nsid.clone());
+                        continue;
+                    }
+                }
+            }
+        }
+
+        Ok(RecursiveResolutionResult {
+            lexicons,
+            failed,
+            dependencies,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_extract_references() {
+        let schema = serde_json::json!({
+            "lexicon": 1,
+            "id": "app.bsky.feed.post",
+            "defs": {
+                "main": {
+                    "type": "record",
+                    "record": {
+                        "type": "object",
+                        "properties": {
+                            "text": {
+                                "type": "string"
+                            },
+                            "embed": {
+                                "type": "union",
+                                "refs": [
+                                    { "type": "ref", "ref": "app.bsky.embed.images" },
+                                    { "type": "ref", "ref": "app.bsky.embed.external" },
+                                    { "type": "ref", "ref": "#localref" }
+                                ]
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        assert!(refs.contains("app.bsky.embed.images"));
+        assert!(refs.contains("app.bsky.embed.external"));
+        // Fragment-only reference #localref should be resolved to app.bsky.feed.post
+        // (using the lexicon's id as context)
+        assert!(refs.contains("app.bsky.feed.post"));
+        assert_eq!(refs.len(), 3);
+    }
+
+    #[test]
+    fn test_extract_nested_references() {
+        let schema = serde_json::json!({
+            "defs": {
+                "main": {
+                    "type": "object",
+                    "properties": {
+                        "nested": {
+                            "type": "object",
+                            "properties": {
+                                "ref1": { "type": "ref", "ref": "com.example.schema1" },
+                                "array": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "union",
+                                        "refs": [
+                                            { "type": "ref", "ref": "#localref" },
+                                            { "type": "ref", "ref": "com.example.schema3" }
+                                        ]
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        assert!(refs.contains("com.example.schema1"));
+        assert!(refs.contains("com.example.schema3"));
+        // Without an id field, fragment-only references cannot be resolved
+        assert_eq!(refs.len(), 2);
+    }
+
+    #[test]
+    fn test_fragment_only_with_context() {
+        // Test that fragment-only references are properly resolved when lexicon has an ID
+        let schema = serde_json::json!({
+            "lexicon": 1,
+            "id": "com.example.myschema",
+            "defs": {
+                "main": {
+                    "type": "object",
+                    "properties": {
+                        "directRef": { "type": "ref", "ref": "#localDefinition" },
+                        "unionRefs": {
+                            "type": "union",
+                            "refs": [
+                                "#main",
+                                "#otherDef",
+                                "external.schema.type"
+                            ]
+                        },
+                        "nestedRef": {
+                            "type": "object",
+                            "properties": {
+                                "field": { "type": "ref", "ref": "#nested" }
+                            }
+                        }
+                    }
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        // Fragment-only references should all resolve to com.example.myschema
+        assert!(refs.contains("com.example.myschema"));
+        assert!(refs.contains("external.schema.type"));
+        assert_eq!(refs.len(), 2);
+    }
+
+    #[test]
+    fn test_skip_invalid_references() {
+        let schema = serde_json::json!({
+            "defs": {
+                "main": {
+                    "refs": [
+                        { "type": "ref", "ref": "valid.schema.name" },
+                        { "type": "ref", "ref": "invalid" },  // No dots - should be skipped
+                        { "type": "ref", "ref": "#localref" }, // Fragment-only, no ID context - should be skipped
+                        { "type": "string", "ref": "not.a.ref" }, // Wrong type - should be skipped
+                    ]
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        assert!(refs.contains("valid.schema.name"));
+        // Only valid.schema.name should be extracted (no ID field, so #localref is skipped)
+        assert_eq!(refs.len(), 1);
+    }
+
+    #[test]
+    fn test_extract_union_references() {
+        let schema = serde_json::json!({
+            "defs": {
+                "main": {
+                    "type": "union",
+                    "refs": [
+                        "community.lexicon.calendar.event#uri",
+                        "community.lexicon.location.address",
+                        "community.lexicon.location.fsq",
+                        "community.lexicon.location.geo",
+                        "community.lexicon.location.hthree"
+                    ]
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        // NSIDs should be extracted without fragment identifiers
+        assert!(refs.contains("community.lexicon.calendar.event"));
+        assert!(refs.contains("community.lexicon.location.address"));
+        assert!(refs.contains("community.lexicon.location.fsq"));
+        assert!(refs.contains("community.lexicon.location.geo"));
+        assert!(refs.contains("community.lexicon.location.hthree"));
+        assert_eq!(refs.len(), 5);
+    }
+
+    #[test]
+    fn test_extract_mixed_union_references() {
+        let schema = serde_json::json!({
+            "defs": {
+                "main": {
+                    "type": "union",
+                    "refs": [
+                        "app.bsky.feed.post",
+                        { "type": "ref", "ref": "app.bsky.actor.profile" },
+                        "#app.bsky.graph.follow",  // Fragment-only, no ID context - should be skipped
+                        "invalid",  // No dots - should be skipped
+                    ]
+                },
+                "other": {
+                    "type": "ref",
+                    "ref": "app.bsky.embed.images"
+                }
+            }
+        });
+
+        let refs = extract_lexicon_references(&schema);
+
+        assert!(refs.contains("app.bsky.feed.post"));
+        assert!(refs.contains("app.bsky.actor.profile"));
+        assert!(refs.contains("app.bsky.embed.images"));
+        // #app.bsky.graph.follow is fragment-only with no ID context, should not be included
+        assert!(!refs.contains("app.bsky.graph.follow"));
+        assert!(!refs.contains("invalid"));
+        assert_eq!(refs.len(), 3);
+    }
+}

crates/atproto-lexicon/src/validation.rs

···
+//! Lexicon validation functionality for AT Protocol.
+//!
+//! This module provides validation of lexicon NSIDs, references, and schemas.
+
+use std::fmt;
+
+use anyhow::{anyhow, Result};
+use serde_json::Value;
+use thiserror::Error;
+
+/// Errors that can occur during lexicon validation.
+#[derive(Error, Debug)]
+pub enum ValidationError {
+    /// Invalid NSID format.
+    #[error("Invalid NSID format: {0}")]
+    InvalidNsidFormat(String),
+
+    /// Invalid reference format.
+    #[error("Invalid reference format: {0}")]
+    InvalidReferenceFormat(String),
+
+    /// NSID has too few parts.
+    #[error("NSID must have at least 3 parts: {0}")]
+    InsufficientNsidParts(String),
+
+    /// Invalid DNS name conversion.
+    #[error("Cannot convert NSID to DNS name: {0}")]
+    InvalidDnsNameConversion(String),
+}
+
+/// Components of a parsed NSID.
+#[derive(Debug, Clone, PartialEq)]
+pub struct NsidParts {
+    /// The parts in original order (e.g., ["app", "bsky", "feed", "post"] for "app.bsky.feed.post")
+    pub parts: Vec<String>,
+
+    /// The optional fragment identifier (e.g., "uri" for "community.lexicon.calendar.event#uri")
+    pub fragment: Option<String>,
+}
+
+impl NsidParts {
+    /// Serializes the NSID parts back to a string.
+    ///
+    /// Joins the parts with dots and appends the fragment with '#' if present.
+    ///
+    /// # Examples
+    /// ```
+    /// use atproto_lexicon::validation::NsidParts;
+    ///
+    /// let parts = NsidParts {
+    ///     parts: vec!["app".to_string(), "bsky".to_string(), "feed".to_string(), "post".to_string()],
+    ///     fragment: None,
+    /// };
+    /// assert_eq!(parts.to_string(), "app.bsky.feed.post");
+    ///
+    /// let parts_with_fragment = NsidParts {
+    ///     parts: vec!["app".to_string(), "bsky".to_string(), "feed".to_string(), "post".to_string()],
+    ///     fragment: Some("reply".to_string()),
+    /// };
+    /// assert_eq!(parts_with_fragment.to_string(), "app.bsky.feed.post#reply");
+    /// ```
+    pub fn to_string(&self) -> String {
+        let base = self.parts.join(".");
+        match &self.fragment {
+            Some(fragment) => format!("{}#{}", base, fragment),
+            None => base,
+        }
+    }
+}
+
+impl fmt::Display for NsidParts {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.to_string())
+    }
+}
+
+/// Validates if a string is a valid NSID.
+///
+/// A valid NSID must:
+/// - Contain at least one dot
+/// - Have at least 3 parts when split by dots
+/// - Not be empty
+pub fn is_valid_nsid(nsid: &str) -> bool {
+    if nsid.is_empty() {
+        return false;
+    }
+
+    let parts: Vec<&str> = nsid.split('.').collect();
+    parts.len() >= 3 && parts.iter().all(|p| !p.is_empty())
+}
+
+/// Validates if a string is a valid NSID reference.
+///
+/// This accepts:
+/// - Regular NSIDs (e.g., "app.bsky.feed.post")
+/// - NSIDs with fragment identifiers (e.g., "app.bsky.feed.post#uri")
+///
+/// This rejects:
+/// - Fragment-only references (e.g., "#localref")
+/// - Empty strings
+/// - Invalid NSIDs without dots
+pub fn is_valid_reference(reference: &str) -> bool {
+    extract_nsid_from_reference(reference).is_some()
+}
+
+/// Extracts a clean NSID from a reference string.
+///
+/// Handles:
+/// - Regular NSIDs (e.g., "app.bsky.feed.post")
+/// - NSIDs with fragment identifiers (e.g., "app.bsky.feed.post#uri" -> "app.bsky.feed.post")
+///
+/// Returns None for:
+/// - Fragment-only references (e.g., "#localref")
+/// - Invalid NSIDs without dots
+/// - Empty strings
+pub fn extract_nsid_from_reference(reference: &str) -> Option<String> {
+    if reference.is_empty() {
+        return None;
+    }
+
+    // Fragment-only references (starting with #) are not NSIDs
+    if reference.starts_with('#') {
+        return None;
+    }
+
+    // Extract the NSID part (before any fragment identifier)
+    let nsid = if let Some(hash_pos) = reference.find('#') {
+        &reference[..hash_pos]
+    } else {
+        reference
+    };
+
+    // Validate the NSID part
+    if nsid.is_empty() || !nsid.contains('.') {
+        return None;
+    }
+
+    Some(nsid.to_string())
+}
+
+/// Converts a potentially relative NSID reference to an absolute one.
+///
+/// If the NSID starts with '#' (fragment-only), it concatenates the context with the NSID.
+/// Otherwise, it returns the NSID as-is.
+///
+/// # Examples
+/// ```
+/// use atproto_lexicon::validation::absolute;
+///
+/// assert_eq!(absolute("app.bsky.feed.post", "#reply"), "app.bsky.feed.post#reply");
+/// assert_eq!(absolute("app.bsky.feed.post", "com.example.other"), "com.example.other");
+/// assert_eq!(absolute("app.bsky.feed.post", "#main"), "app.bsky.feed.post#main");
+/// ```
+pub fn absolute(context: &str, nsid: &str) -> String {
+    if nsid.starts_with('#') {
+        format!("{}{}", context, nsid)
+    } else {
+        nsid.to_string()
+    }
+}
+
+/// Parses an NSID into its component parts, optionally with context.
+///
+/// # Parameters
+/// - `nsid`: The NSID or fragment reference to parse
+/// - `context`: Optional context NSID for resolving fragment-only references
+///
+/// # Behavior
+/// - If `nsid` starts with "#" and no context: returns empty parts with fragment
+/// - If `nsid` starts with "#" and context provided: uses context for parts, nsid (without #) for fragment
+/// - Otherwise: splits on "#" to separate NSID from fragment, then splits NSID on "." for parts
+/// - The special fragment "main" is treated as None
+///
+/// # Examples
+/// ```
+/// use atproto_lexicon::validation::parse_nsid;
+///
+/// // Regular NSID
+/// let parts = parse_nsid("app.bsky.feed.post", None).unwrap();
+/// assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+/// assert_eq!(parts.fragment, None);
+///
+/// // NSID with fragment
+/// let parts = parse_nsid("app.bsky.feed.post#uri", None).unwrap();
+/// assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+/// assert_eq!(parts.fragment, Some("uri".to_string()));
+///
+/// // Fragment-only without context
+/// let parts = parse_nsid("#localref", None).unwrap();
+/// assert_eq!(parts.parts, Vec::<String>::new());
+/// assert_eq!(parts.fragment, Some("localref".to_string()));
+///
+/// // Fragment-only with context
+/// let parts = parse_nsid("#localref", Some("app.bsky.feed.post".to_string())).unwrap();
+/// assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+/// assert_eq!(parts.fragment, Some("localref".to_string()));
+///
+/// // "main" fragment is treated as None
+/// let parts = parse_nsid("app.bsky.feed.post#main", None).unwrap();
+/// assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+/// assert_eq!(parts.fragment, None);
+/// ```
+pub fn parse_nsid(nsid: &str, context: Option<String>) -> Result<NsidParts> {
+    // Handle fragment-only references
+    if nsid.starts_with('#') {
+        let fragment_str = &nsid[1..];
+        let fragment = if fragment_str == "main" || fragment_str.is_empty() {
+            None
+        } else {
+            Some(fragment_str.to_string())
+        };
+
+        let parts = if let Some(ctx) = context {
+            ctx.split('.').map(|s| s.to_string()).collect()
+        } else {
+            Vec::new()
+        };
+
+        return Ok(NsidParts { parts, fragment });
+    }
+
+    // Split on '#' to separate NSID from fragment
+    let (nsid_part, fragment_part) = if let Some(hash_pos) = nsid.find('#') {
+        (&nsid[..hash_pos], Some(&nsid[hash_pos + 1..]))
+    } else {
+        (nsid, None)
+    };
+
+    // Parse the NSID part
+    if nsid_part.is_empty() {
+        return Err(ValidationError::InvalidNsidFormat("Empty NSID".to_string()).into());
+    }
+
+    let parts: Vec<String> = nsid_part.split('.').map(|s| s.to_string()).collect();
+
+    // Validate parts (at least 3 components for a valid NSID)
+    if parts.len() < 3 {
+        return Err(ValidationError::InsufficientNsidParts(nsid.to_string()).into());
+    }
+
+    if parts.iter().any(|p| p.is_empty()) {
+        return Err(ValidationError::InvalidNsidFormat(format!("NSID contains empty parts: {}", nsid)).into());
+    }
+
+    // Handle fragment
+    let fragment = match fragment_part {
+        Some("main") | Some("") => None,
+        Some(frag) => Some(frag.to_string()),
+        None => None,
+    };
+
+    Ok(NsidParts { parts, fragment })
+}
+
+/// Converts an NSID to a DNS name for lexicon resolution.
+///
+/// The conversion reverses the authority parts and prepends "_lexicon".
+///
+/// # Example
+/// ```
+/// use atproto_lexicon::validation::nsid_to_dns_name;
+/// assert_eq!(
+///     nsid_to_dns_name("app.bsky.feed.post").unwrap(),
+///     "_lexicon.feed.bsky.app"
+/// );
+/// ```
+pub fn nsid_to_dns_name(nsid: &str) -> Result<String> {
+    let parsed = parse_nsid(nsid, None)?;
+
+    // Need at least 3 parts for a valid NSID (authority + name + record_type)
+    if parsed.parts.len() < 3 {
+        return Err(ValidationError::InvalidNsidFormat(
+            format!("NSID must have at least 3 parts: {}", nsid)
+        ).into());
+    }
+
+    // Build DNS name: _lexicon.<name>.<reversed-authority>
+    let mut dns_parts = vec!["_lexicon".to_string()];
+
+    // The name is the second-to-last part
+    let name_idx = parsed.parts.len() - 2;
+    dns_parts.push(parsed.parts[name_idx].clone());
+
+    // Add authority parts in reverse order (all parts except the last two)
+    for i in (0..name_idx).rev() {
+        dns_parts.push(parsed.parts[i].clone());
+    }
+
+    Ok(dns_parts.join("."))
+}
+
+/// Checks if a JSON object represents a reference type.
+///
+/// A reference object has `"type": "ref"` and a `"ref"` field.
+pub fn is_reference_object(obj: &serde_json::Map<String, Value>) -> bool {
+    matches!(
+        obj.get("type"),
+        Some(Value::String(type_val)) if type_val == "ref"
+    ) && obj.contains_key("ref")
+}
+
+/// Checks if a JSON object represents a union type.
+///
+/// A union object has `"type": "union"` and a `"refs"` array field.
+pub fn is_union_object(obj: &serde_json::Map<String, Value>) -> bool {
+    matches!(
+        obj.get("type"),
+        Some(Value::String(type_val)) if type_val == "union"
+    ) && matches!(obj.get("refs"), Some(Value::Array(_)))
+}
+
+/// Extracts an NSID from a reference object.
+///
+/// Returns None if the object is not a valid reference or the NSID is invalid.
+pub fn extract_nsid_from_ref_object(obj: &serde_json::Map<String, Value>) -> Option<String> {
+    if !is_reference_object(obj) {
+        return None;
+    }
+
+    if let Some(Value::String(ref_val)) = obj.get("ref") {
+        extract_nsid_from_reference(ref_val)
+    } else {
+        None
+    }
+}
+
+/// Extracts NSIDs from a union object's refs array.
+///
+/// Handles both direct string references and nested reference objects.
+pub fn extract_nsids_from_union_object(obj: &serde_json::Map<String, Value>) -> Vec<String> {
+    if !is_union_object(obj) {
+        return Vec::new();
+    }
+
+    let mut nsids = Vec::new();
+
+    if let Some(Value::Array(refs_array)) = obj.get("refs") {
+        for ref_item in refs_array {
+            match ref_item {
+                Value::String(ref_str) => {
+                    if let Some(nsid) = extract_nsid_from_reference(ref_str) {
+                        nsids.push(nsid);
+                    }
+                }
+                Value::Object(ref_obj) => {
+                    if let Some(nsid) = extract_nsid_from_ref_object(ref_obj) {
+                        nsids.push(nsid);
+                    }
+                }
+                _ => {}
+            }
+        }
+    }
+
+    nsids
+}
+
+/// Validates a complete lexicon schema.
+///
+/// Checks for:
+/// - Required fields (lexicon version, id, defs)
+/// - Valid NSID in the id field
+/// - Well-formed definitions
+pub fn validate_lexicon_schema(schema: &Value) -> Result<()> {
+    let obj = schema.as_object()
+        .ok_or_else(|| anyhow!("Lexicon schema must be an object"))?;
+
+    // Check lexicon version
+    if !obj.contains_key("lexicon") {
+        return Err(anyhow!("Missing 'lexicon' version field"));
+    }
+
+    // Check and validate ID
+    let id = obj.get("id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow!("Missing or invalid 'id' field"))?;
+
+    if !is_valid_nsid(id) {
+        return Err(ValidationError::InvalidNsidFormat(id.to_string()).into());
+    }
+
+    // Check defs exists and is an object
+    obj.get("defs")
+        .and_then(|v| v.as_object())
+        .ok_or_else(|| anyhow!("Missing or invalid 'defs' field"))?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_valid_nsid() {
+        assert!(is_valid_nsid("app.bsky.feed.post"));
+        assert!(is_valid_nsid("com.example.service.method"));
+        assert!(is_valid_nsid("a.b.c"));
+
+        assert!(!is_valid_nsid("app.bsky"));  // Too few parts
+        assert!(!is_valid_nsid("app"));  // Too few parts
+        assert!(!is_valid_nsid(""));  // Empty
+        assert!(!is_valid_nsid("app..feed.post"));  // Empty part
+    }
+
+    #[test]
+    fn test_extract_nsid_from_reference() {
+        // Valid NSID
+        assert_eq!(
+            extract_nsid_from_reference("app.bsky.feed.post"),
+            Some("app.bsky.feed.post".to_string())
+        );
+
+        // NSID with fragment identifier
+        assert_eq!(
+            extract_nsid_from_reference("app.bsky.feed.post#uri"),
+            Some("app.bsky.feed.post".to_string())
+        );
+
+        // Fragment-only references should return None
+        assert_eq!(extract_nsid_from_reference("#app.bsky.feed.post"), None);
+        assert_eq!(extract_nsid_from_reference("#localref"), None);
+        assert_eq!(extract_nsid_from_reference("#"), None);
+
+        // Invalid formats
+        assert_eq!(extract_nsid_from_reference("#app.bsky.feed.post#uri"), None);  // Starts with #
+        assert_eq!(extract_nsid_from_reference("invalid"), None);  // No dots
+        assert_eq!(extract_nsid_from_reference(""), None);  // Empty
+        assert_eq!(extract_nsid_from_reference("#com.example#foo"), None);  // Multiple fragments
+    }
+
+    #[test]
+    fn test_absolute() {
+        // Fragment-only references should be made absolute with context
+        assert_eq!(absolute("app.bsky.feed.post", "#reply"), "app.bsky.feed.post#reply");
+        assert_eq!(absolute("com.example.schema", "#main"), "com.example.schema#main");
+        assert_eq!(absolute("a.b.c", "#"), "a.b.c#");
+
+        // Already absolute NSIDs should be returned as-is
+        assert_eq!(absolute("app.bsky.feed.post", "com.example.other"), "com.example.other");
+        assert_eq!(absolute("app.bsky.feed.post", "app.bsky.actor.profile"), "app.bsky.actor.profile");
+        assert_eq!(absolute("ignored.context", "app.bsky.feed.post#uri"), "app.bsky.feed.post#uri");
+    }
+
+    #[test]
+    fn test_parse_nsid() {
+        // Basic 4-part NSID
+        let parts = parse_nsid("app.bsky.feed.post", None).unwrap();
+        assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+        assert_eq!(parts.fragment, None);
+
+        // 4-part NSID with different authority
+        let parts = parse_nsid("com.example.service.method", None).unwrap();
+        assert_eq!(parts.parts, vec!["com", "example", "service", "method"]);
+        assert_eq!(parts.fragment, None);
+
+        // NSID with fragment
+        let parts = parse_nsid("app.bsky.feed.post#reply", None).unwrap();
+        assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+        assert_eq!(parts.fragment, Some("reply".to_string()));
+
+        // "main" fragment should be treated as None
+        let parts = parse_nsid("app.bsky.feed.post#main", None).unwrap();
+        assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+        assert_eq!(parts.fragment, None);
+
+        // Fragment-only without context
+        let parts = parse_nsid("#reply", None).unwrap();
+        assert_eq!(parts.parts, Vec::<String>::new());
+        assert_eq!(parts.fragment, Some("reply".to_string()));
+
+        // Fragment-only with context
+        let parts = parse_nsid("#reply", Some("app.bsky.feed.post".to_string())).unwrap();
+        assert_eq!(parts.parts, vec!["app", "bsky", "feed", "post"]);
+        assert_eq!(parts.fragment, Some("reply".to_string()));
+
+        // Too few parts
+        assert!(parse_nsid("app.bsky", None).is_err());
+        assert!(parse_nsid("", None).is_err());
+    }
+
+    #[test]
+    fn test_nsid_parts_serialization() {
+        // Basic NSID without fragment
+        let parts = NsidParts {
+            parts: vec!["app".to_string(), "bsky".to_string(), "feed".to_string(), "post".to_string()],
+            fragment: None,
+        };
+        assert_eq!(parts.to_string(), "app.bsky.feed.post");
+        assert_eq!(format!("{}", parts), "app.bsky.feed.post");  // Test Display trait
+
+        // NSID with fragment
+        let parts_with_fragment = NsidParts {
+            parts: vec!["com".to_string(), "example".to_string(), "schema".to_string(), "type".to_string()],
+            fragment: Some("reply".to_string()),
+        };
+        assert_eq!(parts_with_fragment.to_string(), "com.example.schema.type#reply");
+        assert_eq!(format!("{}", parts_with_fragment), "com.example.schema.type#reply");
+
+        // Empty parts with fragment (edge case from fragment-only parsing)
+        let fragment_only = NsidParts {
+            parts: vec![],
+            fragment: Some("localref".to_string()),
+        };
+        assert_eq!(fragment_only.to_string(), "#localref");
+
+        // Round-trip test: parse and serialize
+        let original = "app.bsky.feed.post#main";
+        let parsed = parse_nsid(original, None).unwrap();
+        // Note: "main" is treated as None, so this won't round-trip exactly
+        assert_eq!(parsed.to_string(), "app.bsky.feed.post");
+
+        let original_with_fragment = "app.bsky.feed.post#reply";
+        let parsed_with_fragment = parse_nsid(original_with_fragment, None).unwrap();
+        assert_eq!(parsed_with_fragment.to_string(), original_with_fragment);
+    }
+
+    #[test]
+    fn test_nsid_to_dns_name() {
+        assert_eq!(
+            nsid_to_dns_name("app.bsky.feed.post").unwrap(),
+            "_lexicon.feed.bsky.app"
+        );
+
+        assert_eq!(
+            nsid_to_dns_name("com.atproto.repo.getRecord").unwrap(),
+            "_lexicon.repo.atproto.com"
+        );
+
+        assert_eq!(
+            nsid_to_dns_name("org.example.deeply.nested.service.action").unwrap(),
+            "_lexicon.service.nested.deeply.example.org"
+        );
+
+        // "main" fragment doesn't affect DNS name generation
+        assert_eq!(
+            nsid_to_dns_name("app.bsky.feed.main").unwrap(),
+            "_lexicon.feed.bsky.app"
+        );
+
+        assert!(nsid_to_dns_name("app.bsky").is_err());
+    }
+
+    #[test]
+    fn test_reference_object_detection() {
+        let ref_obj = serde_json::json!({
+            "type": "ref",
+            "ref": "app.bsky.feed.post"
+        });
+        assert!(is_reference_object(ref_obj.as_object().unwrap()));
+
+        let not_ref = serde_json::json!({
+            "type": "string",
+            "ref": "app.bsky.feed.post"
+        });
+        assert!(!is_reference_object(not_ref.as_object().unwrap()));
+
+        let missing_ref = serde_json::json!({
+            "type": "ref"
+        });
+        assert!(!is_reference_object(missing_ref.as_object().unwrap()));
+    }
+
+    #[test]
+    fn test_union_object_detection() {
+        let union_obj = serde_json::json!({
+            "type": "union",
+            "refs": ["app.bsky.feed.post", "app.bsky.actor.profile"]
+        });
+        assert!(is_union_object(union_obj.as_object().unwrap()));
+
+        let not_union = serde_json::json!({
+            "type": "ref",
+            "refs": ["app.bsky.feed.post"]
+        });
+        assert!(!is_union_object(not_union.as_object().unwrap()));
+
+        let invalid_refs = serde_json::json!({
+            "type": "union",
+            "refs": "not-an-array"
+        });
+        assert!(!is_union_object(invalid_refs.as_object().unwrap()));
+    }
+
+    #[test]
+    fn test_extract_nsids_from_union() {
+        let union_obj = serde_json::json!({
+            "type": "union",
+            "refs": [
+                "app.bsky.feed.post",
+                "#app.bsky.actor.profile",  // Fragment-only, should be skipped
+                "app.bsky.graph.follow#uri",  // NSID with fragment
+                { "type": "ref", "ref": "app.bsky.embed.images" },
+                "invalid"  // No dots, should be skipped
+            ]
+        });
+
+        let nsids = extract_nsids_from_union_object(union_obj.as_object().unwrap());
+        assert_eq!(nsids.len(), 3);
+        assert!(nsids.contains(&"app.bsky.feed.post".to_string()));
+        assert!(nsids.contains(&"app.bsky.graph.follow".to_string()));  // Fragment removed
+        assert!(nsids.contains(&"app.bsky.embed.images".to_string()));
+        // #app.bsky.actor.profile is fragment-only, so it's not included
+        assert!(!nsids.contains(&"app.bsky.actor.profile".to_string()));
+    }
+
+    #[test]
+    fn test_validate_lexicon_schema() {
+        let valid_schema = serde_json::json!({
+            "lexicon": 1,
+            "id": "app.bsky.feed.post",
+            "defs": {
+                "main": {}
+            }
+        });
+        assert!(validate_lexicon_schema(&valid_schema).is_ok());
+
+        let missing_lexicon = serde_json::json!({
+            "id": "app.bsky.feed.post",
+            "defs": {}
+        });
+        assert!(validate_lexicon_schema(&missing_lexicon).is_err());
+
+        let invalid_id = serde_json::json!({
+            "lexicon": 1,
+            "id": "invalid",
+            "defs": {}
+        });
+        assert!(validate_lexicon_schema(&invalid_id).is_err());
+
+        let missing_defs = serde_json::json!({
+            "lexicon": 1,
+            "id": "app.bsky.feed.post"
+        });
+        assert!(validate_lexicon_schema(&missing_defs).is_err());
+    }
+}

crates/atproto-oauth/src/dpop.rs

···
 use elliptic_curve::JwkEcKey;
 use reqwest::header::HeaderValue;
 use reqwest_chain::Chainer;
-use serde::Deserialize;
 use ulid::Ulid;
 
 use crate::{
···
     jwt::{Claims, Header, JoseClaims, mint},
     pkce::challenge,
 };
-
-/// Simple error response structure for parsing OAuth error responses.
-#[cfg_attr(debug_assertions, derive(Debug))]
-#[derive(Clone, Deserialize)]
-struct SimpleError {
-    /// The error code or message returned by the OAuth server.
-    pub error: Option<String>,
-}
-
-/// Display implementation for SimpleError that shows the error message or "unknown".
-impl std::fmt::Display for SimpleError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        if let Some(value) = &self.error {
-            write!(f, "{}", value)
-        } else {
-            write!(f, "unknown")
-        }
-    }
-}
 
 /// Retry middleware for handling DPoP nonce challenges in HTTP requests.
 ///