CLAUDE.md#

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview#

This is atproto-identity, a comprehensive Rust library for AT Protocol identity management. The project provides full functionality for DID resolution, handle resolution, and identity document management across multiple DID methods.

Common Commands#

• Build: cargo build
• Run tests: cargo test
• Run specific test: cargo test test_name
• Check code: cargo check
• Format code: cargo fmt
• Lint: cargo clippy
• Run CLI tool: cargo run --bin atproto-identity-resolve -- <handle_or_did>
• Run CLI with DID document: cargo run --bin atproto-identity-resolve -- --did-document <handle_or_did>

Architecture#

A comprehensive Rust library with:

• Modular architecture with 8 core modules (resolve, plc, web, model, validation, config, errors, key)
• Complete CLI tool for identity resolution (atproto-identity-resolve)
• Rust edition 2024 with modern async/await patterns
• Comprehensive error handling with structured error types
• Multiple external dependencies for HTTP, DNS, JSON, and cryptographic operations
• Full test coverage with unit tests for all modules

Error Handling#

All error strings must use this format:

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

Example errors:

• error-atproto-identity-resolve-1 Multiple DIDs resolved for method
• error-atproto-identity-plc-1 HTTP request failed: https://google.com/ Not Found
• error-atproto-identity-key-1 Error decoding key: invalid

Errors should be represented as enums using the thiserror library when possible using src/errors.rs as a reference and example.

Avoid creating new errors with the anyhow!(...) macro.

When a function call would return anyhow::Error, use the following pattern to log the error in addition to any code specific handling that must occur

If let Err(err) = result {
    tracing::error!(error = ?error, "Helpful contextual log line.");
}

Result#

Functions that return a Result type should use anyhow::Result where second Error component of is one of the error types defined in src/errors.rs.

Logging#

Use tracing for structured logging.

Async calls should be instrumented using the .instrument() that references the use tracing::Instrument; trait.

Module Structure#

• src/lib.rs: Main library exports
• src/resolve.rs: Core resolution logic for handles and DIDs, DNS/HTTP resolution
• src/plc.rs: PLC directory client for did:plc resolution
• src/web.rs: Web DID client for did:web resolution and URL conversion
• src/model.rs: Data structures for DID documents and AT Protocol entities
• src/validation.rs: Input validation for handles and DIDs
• src/config.rs: Configuration management and environment variable handling
• src/errors.rs: Structured error types following project conventions
• src/key.rs: Cryptographic key operations including signature validation and key identification for P-256 and K-256 curves
• src/bin/atproto-identity-resolve.rs: CLI tool for identity resolution

Documentation#

All public and exported types, methods, and variables must be documented.

All source files must have high level module documentation.

Documentation must be brief and specific.