smokesignal.events / atproto-identity-rs
A library for ATProtocol identities.
fork atom
atproto-identity-rs / CLAUDE.md
at main 10 kB view raw view code

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
  • Build with CLI tools: cargo build --features clap,hickory-dns --bins
  • Run tests: cargo test
  • Run specific test: cargo test test_name
  • Check code: cargo check
  • Format code: cargo fmt
  • Lint: cargo clippy

CLI Tools (require --features clap)#

All CLI tools now use clap for consistent command-line argument processing. Use --help with any tool for detailed usage information.

Identity Management#

  • Resolve identities: cargo run --features clap,hickory-dns --bin atproto-identity-resolve -- <handle_or_did>
  • Resolve with DID document: cargo run --features clap,hickory-dns --bin atproto-identity-resolve -- --did-document <handle_or_did>
  • Generate keys: cargo run --features clap --bin atproto-identity-key -- generate p256 (supports p256, p384, k256)
  • Sign data: cargo run --features clap --bin atproto-identity-sign -- <did_key> <json_file>
  • Validate signatures: cargo run --features clap --bin atproto-identity-validate -- <did_key> <json_file> <signature>

Attestation Operations#

  • Sign records (inline): cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- inline <source_record> <signing_key> <metadata_record>
  • Sign records (remote): cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- remote <source_record> <repository_did> <metadata_record>
  • Verify records: cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- <record> (verifies all signatures)
  • Verify attestation: cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- <record> <attestation> (verifies specific attestation)

Record Operations#

  • Generate CID: cat record.json | cargo run --features clap --bin atproto-record-cid (reads JSON from stdin, outputs CID)

Client Tools#

  • App password auth: cargo run --features clap --bin atproto-client-app-password -- <subject> <access_token> <xrpc_path>
  • Session auth: cargo run --features clap --bin atproto-client-auth -- login <identifier> <password>
  • DPoP client: cargo run --features clap --bin atproto-client-dpop -- <subject> <private_dpop_key> <access_token> <xrpc_path>

Streaming and OAuth#

  • Jetstream consumer: cargo run --features clap --bin atproto-jetstream-consumer -- <hostname> <zstd_dictionary>
  • OAuth tool: cargo run --features clap --bin atproto-oauth-tool -- login <private_signing_key> <subject>
  • XRPCS service: cargo run --features clap --bin atproto-xrpcs-helloworld

Architecture#

A comprehensive Rust workspace with multiple crates:

  • atproto-identity: Core identity management with 11 modules (resolve, plc, web, model, validation, config, errors, key, storage_lru, traits, url)
  • atproto-attestation: CID-first attestation utilities for creating and verifying record signatures
  • atproto-record: Record utilities including TID generation, AT-URI parsing, and CID generation
  • atproto-client: HTTP client with OAuth and identity integration
  • atproto-jetstream: WebSocket event streaming with compression
  • atproto-oauth: OAuth workflow implementation with DPoP, PKCE, JWT, and storage abstractions
  • atproto-oauth-aip: AT Protocol OAuth AIP (Identity Provider) implementation with PAR support
  • atproto-oauth-axum: Axum web framework integration for OAuth
  • atproto-xrpcs: XRPC service framework
  • atproto-xrpcs-helloworld: Complete example XRPC service

Features:

  • 13 CLI tools with consistent clap-based command-line interfaces (optional via clap feature)
  • Rust edition 2024 with modern async/await patterns
  • Comprehensive error handling with structured error types
  • Full test coverage with unit tests across all modules
  • Modern dependencies for HTTP, DNS, JSON, cryptographic operations, and WebSocket streaming
  • Storage abstractions with LRU caching support (enabled by default via lru feature)
  • DNS resolution with Hickory DNS support (enabled by default via hickory-dns feature)
  • Secure memory handling (optional via zeroize feature)

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.

All calls to tracing::error, tracing::warn, tracing::info, tracing::debug, and tracing::trace should be fully qualified.

Do not use the println! macro in library code.

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

Command-Line Interface Pattern#

All CLI tools use the clap library with derive macros for consistent command-line argument processing:

  • Optional dependency: clap is an optional dependency in each crate via clap = { workspace = true, optional = true }
  • Feature-gated: All binaries require the clap feature via required-features = ["clap"]
  • Derive pattern: Use #[derive(Parser)] and #[derive(Subcommand)] for command structures
  • Comprehensive help: Include detailed help documentation in clap attributes
  • Consistent structure: Use structured arguments with proper types rather than manual parsing

Example command structure:

#[derive(Parser)]
#[command(
    name = "tool-name",
    version,
    about = "Brief description",
    long_about = "Detailed description with examples"
)]
struct Args {
    /// Argument description
    positional_arg: String,
    
    /// Optional flag description
    #[arg(long)]
    optional_flag: bool,
}

Module Structure#

Core Library Modules (atproto-identity)#

  • 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, P-384, and K-256 curves
  • src/storage_lru.rs: LRU-based storage implementation (requires lru feature)
  • src/traits.rs: Core trait definitions for identity resolution and key resolution
  • src/url.rs: URL utilities for AT Protocol services

CLI Tools (require --features clap)#

Identity Management (atproto-identity)#

  • src/bin/atproto-identity-resolve.rs: Resolve AT Protocol handles and DIDs to canonical identifiers
  • src/bin/atproto-identity-key.rs: Generate and manage cryptographic keys (P-256, P-384, K-256)
  • src/bin/atproto-identity-sign.rs: Create cryptographic signatures of JSON data
  • src/bin/atproto-identity-validate.rs: Validate cryptographic signatures

Attestation Operations (atproto-attestation)#

  • src/bin/atproto-attestation-sign.rs: Sign AT Protocol records with inline or remote attestations using CID-first specification
  • src/bin/atproto-attestation-verify.rs: Verify cryptographic signatures on AT Protocol records with attestation validation

Record Operations (atproto-record)#

  • src/bin/atproto-record-cid.rs: Generate CID (Content Identifier) for AT Protocol records using DAG-CBOR serialization

Client Tools (atproto-client)#

  • src/bin/atproto-client-app-password.rs: Make XRPC calls using app password authentication
  • src/bin/atproto-client-auth.rs: Create and refresh authentication sessions
  • src/bin/atproto-client-dpop.rs: Make XRPC calls using DPoP (Demonstration of Proof-of-Possession) authentication

Streaming and Services#

  • crates/atproto-jetstream/src/bin/atproto-jetstream-consumer.rs: Consume AT Protocol events via WebSocket streaming
  • crates/atproto-oauth/src/bin/atproto-oauth-service-token.rs: OAuth service token management tool for AT Protocol authentication workflows
  • crates/atproto-oauth-axum/src/bin/atproto-oauth-tool.rs: OAuth authentication workflow management
  • crates/atproto-xrpcs-helloworld/src/main.rs: Complete example XRPC service with DID web functionality

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.