smokesignal.events
A library for ATProtocol identities.
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7This 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.
8
9## Common Commands
10
11- **Build**: `cargo build`
12- **Run tests**: `cargo test`
13- **Run specific test**: `cargo test test_name`
14- **Check code**: `cargo check`
15- **Format code**: `cargo fmt`
16- **Lint**: `cargo clippy`
17- **Run CLI tool**: `cargo run --bin atproto-identity-resolve -- <handle_or_did>`
18- **Run CLI with DID document**: `cargo run --bin atproto-identity-resolve -- --did-document <handle_or_did>`
19
20## Architecture
21
22A comprehensive Rust library with:
23- Modular architecture with 8 core modules (resolve, plc, web, model, validation, config, errors, key)
24- Complete CLI tool for identity resolution (`atproto-identity-resolve`)
25- Rust edition 2024 with modern async/await patterns
26- Comprehensive error handling with structured error types
27- Multiple external dependencies for HTTP, DNS, JSON, and cryptographic operations
28- Full test coverage with unit tests for all modules
29
30## Error Handling
31
32All error strings must use this format:
33
34 error-atproto-identity-<domain>-<number> <message>: <details>
35
36Example errors:
37
38* error-atproto-identity-resolve-1 Multiple DIDs resolved for method
39* error-atproto-identity-plc-1 HTTP request failed: https://google.com/ Not Found
40* error-atproto-identity-key-1 Error decoding key: invalid
41
42Errors should be represented as enums using the `thiserror` library when possible using `src/errors.rs` as a reference and example.
43
44Avoid creating new errors with the `anyhow!(...)` macro.
45
46When 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:
47
48```
49If let Err(err) = result {
50 tracing::error!(error = ?error, "Helpful contextual log line.");
51}
52```
53
54## Result
55
56Functions 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`.
57
58## Logging
59
60Use tracing for structured logging.
61
62All calls to `tracing::error`, `tracing::warn`, `tracing::info`, `tracing::debug`, and `tracing::trace` should be fully qualified.
63
64Do not use the `println!` macro in library code.
65
66Async calls should be instrumented using the `.instrument()` that references the `use tracing::Instrument;` trait.
67
68## Module Structure
69
70- **`src/lib.rs`**: Main library exports
71- **`src/resolve.rs`**: Core resolution logic for handles and DIDs, DNS/HTTP resolution
72- **`src/plc.rs`**: PLC directory client for did:plc resolution
73- **`src/web.rs`**: Web DID client for did:web resolution and URL conversion
74- **`src/model.rs`**: Data structures for DID documents and AT Protocol entities
75- **`src/validation.rs`**: Input validation for handles and DIDs
76- **`src/config.rs`**: Configuration management and environment variable handling
77- **`src/errors.rs`**: Structured error types following project conventions
78- **`src/key.rs`**: Cryptographic key operations including signature validation and key identification for P-256 and K-256 curves
79- **`src/bin/atproto-identity-resolve.rs`**: CLI tool for identity resolution
80
81## Documentation
82
83All public and exported types, methods, and variables must be documented.
84
85All source files must have high level module documentation.
86
87Documentation must be brief and specific.