atproto-identity#

A Rust library for AT Protocol identity resolution and management.

Overview#

atproto-identity provides comprehensive support for resolving and managing identities in the AT Protocol ecosystem. This library handles multiple DID (Decentralized Identifier) methods including did:plc and did:web, as well as AT Protocol handle resolution via both DNS and HTTP methods.

This project was extracted from the open-sourced Smokesignal project and is designed to be a standalone, reusable library for AT Protocol identity operations.

Features#

Handle Resolution: Resolve AT Protocol handles to DIDs using DNS TXT records and HTTP well-known endpoints
DID Document Retrieval: Fetch and parse DID documents for did:plc and did:web identifiers
Multiple Resolution Methods: Supports both DNS and HTTP-based handle resolution with conflict detection
Configurable DNS: Custom DNS nameserver support with fallback to system defaults
Cryptographic Key Operations: Support for P-256 and K-256 key identification, signature validation, and signing
Structured Logging: Built-in tracing support for debugging and monitoring
Type Safety: Comprehensive error handling with structured error types

Supported DID Methods#

did-method-plc: Public Ledger of Credentials DIDs via PLC directory
did-method-web: Web-based DIDs following the did:web specification with URL conversion utilities
ATProtocol Handle Resolution: AT Protocol handles (e.g., ngerakines.me) can be resolved to DIDs

Installation#

Add this to your Cargo.toml:

[dependencies]
atproto-identity = "0.2.0"

Usage#

Basic Handle Resolution#

use atproto_identity::resolve::{resolve_subject, create_resolver};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let http_client = reqwest::Client::new();
    let dns_resolver = create_resolver(&[]);
    
    let did = resolve_subject(&http_client, &dns_resolver, "ngerakines.me").await?;
    println!("Resolved DID: {}", did);
    
    Ok(())
}

DID Document Retrieval#

use atproto_identity::{plc, web};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let http_client = reqwest::Client::new();
    
    // Query PLC DID document
    let plc_doc = plc::query(&http_client, "plc.directory", "did:plc:example123").await?;
    
    // Query Web DID document
    let web_doc = web::query(&http_client, "did:web:example.com").await?;
    
    // Convert Web DID to URL (for custom processing)
    let did_url = web::did_web_to_url("did:web:example.com")?;
    println!("DID document URL: {}", did_url);
    
    Ok(())
}

Web DID URL Conversion#

The web module provides utilities for converting DID identifiers to their HTTPS document URLs:

use atproto_identity::web;

fn main() -> anyhow::Result<()> {
    // Convert simple hostname DID
    let url = web::did_web_to_url("did:web:example.com")?;
    // Returns: "https://example.com/.well-known/did.json"
    
    // Convert DID with path components  
    let url = web::did_web_to_url("did:web:example.com:path:subpath")?;
    // Returns: "https://example.com/path/subpath/did.json"
    
    Ok(())
}

Cryptographic Key Operations#

The key module provides utilities for working with cryptographic keys:

use atproto_identity::key::{identify_key, validate, KeyType};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Identify a key from a DID key string
    let key_data = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
    
    match key_data.0 {
        KeyType::K256Public => println!("K-256 public key"),
        KeyType::P256Public => println!("P-256 public key"),
        KeyType::K256Private => println!("K-256 private key"),
        KeyType::P256Private => println!("P-256 private key"),
    }
    
    // Validate a signature (example with dummy data)
    let content = b"hello world";
    let signature = vec![0u8; 64]; // Replace with actual signature
    validate(&key_data, &signature, content)?;
    
    Ok(())
}

Configuration#

The library supports various configuration options through environment variables:

# Custom PLC directory hostname
export PLC_HOSTNAME=plc.directory

# Custom DNS nameservers (semicolon-separated)
export DNS_NAMESERVERS=8.8.8.8;1.1.1.1

# Custom CA certificate bundles (semicolon-separated paths)
export CERTIFICATE_BUNDLES=/path/to/cert1.pem;/path/to/cert2.pem

# Custom User-Agent string
export USER_AGENT="my-app/1.0"

Command Line Tool#

The library includes a command-line tool for testing and resolution:

# Install the binary
cargo install --path .

# Resolve a handle to DID
atproto-identity-resolve ngerakines.me

# Get full DID document
atproto-identity-resolve --did-document ngerakines.me

Architecture#

The library is organized into several modules:

resolve: Core resolution logic for handles and DIDs
plc: PLC directory client for did:plc resolution
web: Web DID client for did:web resolution and URL conversion
model: Data structures for DID documents and AT Protocol entities
validation: Input validation for handles and DIDs
config: Configuration management and environment variable handling
errors: Structured error types following project conventions
key: Cryptographic key operations including signature validation and key identification for P-256 and K-256 curves

Error Handling#

All errors follow a structured format:

error-atproto-identity-<domain>-<number> <message>: <details>

Examples:

error-atproto-identity-resolve-1 Multiple DIDs resolved for method
error-atproto-identity-plc-1 HTTP request failed: https://plc.directory/did:plc:example Not Found
error-did-web-1 Invalid DID format: missing 'did:web:' prefix

Contributing#

Contributions are welcome! Please ensure that:

All tests pass: cargo test
Code is properly formatted: cargo fmt
No linting issues: cargo clippy
New functionality includes appropriate tests

License#

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments#

This library was extracted from the Smokesignal project, an open-source event and RSVP management and discovery application.

Clone this repository