feature: added atproto-oauth-axum crate

Signed-off-by: Nick Gerakines <[e-mail]>

CLAUDE.prompts.md

···
 
 ## Review and ensure error correctness
 
-Review all of the errors in the `atproto-client` crate and ensure their names, messages, documentation, and usage are correct. Each error must have a globally unique identifier and error numbers must be ordered consistently. Think very very hard.
+Review all of the errors in the `atproto-oauth-axum` crate and ensure their names, messages, documentation, and usage are correct. Each error must have a globally unique identifier and error numbers must be ordered consistently. Think very very hard.
 
 Review all of the errors and identify any that are unused. Think very very hard.
 
···
 
 Write high level module documentation in the `path/to/file.rs` source file. Documentation should brief and specific. Think very hard about how to do this.
 
-Update the high level module documentation in each of the source files in the `atproto-identity`, `atproto-record`, `atproto-oauth`, `atproto-client` crates. Documentation should brief and specific. Think very hard about how to do this.
+Update the high level module documentation in each of the source files in the `atproto-identity`, `atproto-record`, `atproto-oauth`, `atproto-client`, and `atproto-oauth-axum` crates. Documentation should brief and specific. Think very hard about how to do this.
 
-Update the `README.md` files in the `atproto-identity`, `atproto-record`, `atproto-oauth`, and `atproto-client` crates. Each `README.md` file should include a high level overview of what the crate provides and include a summary of each binary produced by the crate. Think very hard.
+Update the `README.md` files in the `atproto-identity`, `atproto-record`, `atproto-oauth`, `atproto-oauth-axum`, and `atproto-client` crates. Each `README.md` file should include a high level overview of what the crate provides and include a summary of each binary produced by the crate. Think very hard.
 
 Write a project `README.md` file that describes the project as a library that supports ATProtocol identity record signing and verifying. Note that parts of this was extracted from the open sourced https://tangled.sh/@smokesignal.events/smokesignal project. This project is open source under the MIT license.
 
-The `REAADME.md` file should provide a high level overview of both the `atproto-identity` and `atproto-record` crates. It should also concisely reference the available binaries and provide a minimal example of how to use them.
+The `README.md` file should provide a high level overview of all of the project crates. It should also concisely reference the available binaries and provide a minimal example of how to use them.
 
 Write a `README.md` file for the `atproto-oauth` crate. Use `crates/atproto-identity/README.md` and `crates/atproto-record/README.md` as references. Think really hard.
 

Cargo.lock

···
 dependencies = [
  "anyhow",
  "async-trait",
+ "axum",
  "ecdsa",
  "elliptic-curve",
  "hickory-resolver",
+ "http",
  "k256",
  "lru",
  "multibase",
···
  "anyhow",
  "async-trait",
  "atproto-identity",
+ "axum",
  "base64",
  "chrono",
  "ecdsa",
  "elliptic-curve",
+ "http",
  "k256",
  "lru",
  "multibase",
···
 ]
 
 [[package]]
+name = "atproto-oauth-axum"
+version = "0.3.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "atproto-identity",
+ "atproto-oauth",
+ "atproto-record",
+ "axum",
+ "chrono",
+ "elliptic-curve",
+ "hickory-resolver",
+ "http",
+ "rand 0.8.5",
+ "reqwest",
+ "reqwest-chain",
+ "reqwest-middleware",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.12",
+ "tokio",
+ "tracing",
+ "urlencoding",
+]
+
+[[package]]
 name = "atproto-record"
 version = "0.3.0"
 dependencies = [
···
 checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26"
 
 [[package]]
+name = "axum"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "021e862c184ae977658b36c4500f7feac3221ca5da43e3f25bd04ab6c79a29b5"
+dependencies = [
+ "axum-core",
+ "axum-macros",
+ "bytes",
+ "form_urlencoded",
+ "futures-util",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "itoa",
+ "matchit",
+ "memchr",
+ "mime",
+ "percent-encoding",
+ "pin-project-lite",
+ "rustversion",
+ "serde",
+ "serde_json",
+ "serde_path_to_error",
+ "serde_urlencoded",
+ "sync_wrapper",
+ "tokio",
+ "tower",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-core"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68464cd0412f486726fb3373129ef5d2993f90c34bc2bc1c1e9943b2f4fc7ca6"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "mime",
+ "pin-project-lite",
+ "rustversion",
+ "sync_wrapper",
+ "tower-layer",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "axum-macros"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "604fde5e028fea851ce1d8570bbdc034bec850d157f7569d10f347d06808c05c"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
 name = "backtrace"
 version = "0.3.75"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
 checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
 
 [[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
 name = "hyper"
 version = "1.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
  "http",
  "http-body",
  "httparse",
+ "httpdate",
  "itoa",
  "pin-project-lite",
  "smallvec",
···
 ]
 
 [[package]]
+name = "matchit"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
+
+[[package]]
 name = "memchr"
 version = "2.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
 ]
 
 [[package]]
+name = "serde_path_to_error"
+version = "0.1.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59fab13f937fa393d08645bf3a84bdfe86e296747b506ada67bb15f10f218b2a"
+dependencies = [
+ "itoa",
+ "serde",
+]
+
+[[package]]
 name = "serde_urlencoded"
 version = "0.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
···
  "tokio",
  "tower-layer",
  "tower-service",
+ "tracing",
 ]
 
 [[package]]
···
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "784e0ac535deb450455cbfa28a6f0df145ea1bb7ae51b821cf5e7927fdcfbdd0"
 dependencies = [
+ "log",
  "pin-project-lite",
  "tracing-attributes",
  "tracing-core",

Cargo.toml

···
     "crates/atproto-record",
     "crates/atproto-identity",
     "crates/atproto-oauth",
-    "crates/atproto-client",
+    "crates/atproto-client", "crates/atproto-oauth-axum",
 ]
 resolver = "3"
 

README.md

···
 # AT Protocol Identity & Record Library
 
-A comprehensive Rust library for AT Protocol identity management and record signing/verification. This library provides full functionality for DID resolution, handle resolution, identity document management, and cryptographic record operations across multiple DID methods.
+A comprehensive Rust library for AT Protocol identity management, record signing, verification, and OAuth operations. This library provides full functionality for DID resolution, handle resolution, identity document management, cryptographic record operations, and OAuth 2.0 flows across multiple DID methods.
 
-Parts of this library were extracted from the open-sourced [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project.
+This project was extracted from the open-sourced [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project and is released under the MIT license.
+
+## Project Overview
+
+This workspace provides a complete toolkit for AT Protocol operations including identity resolution, record signing/verification, OAuth 2.0 flows, HTTP client operations, and web server integration. The library is designed to be modular, secure, and fully compliant with AT Protocol specifications.
 
 ## Crates
 
-This workspace contains two main crates:
+This workspace contains five specialized crates:
 
-### `atproto-identity`
-
-A comprehensive AT Protocol identity management library providing:
+### [`atproto-identity`](crates/atproto-identity/) 
+**Core identity management and cryptographic operations**
 
 - **DID Resolution**: Support for `did:plc`, `did:web`, and `did:key` methods
-- **Handle Resolution**: DNS-based handle resolution with validation
+- **Handle Resolution**: DNS and HTTP-based handle resolution with validation  
 - **Identity Documents**: Complete DID document parsing and management
-- **Cryptographic Operations**: P-256 and K-256 elliptic curve support
+- **Cryptographic Operations**: P-256 and K-256 elliptic curve support with signing/verification
+- **Key Management**: DID key identification, conversion, and JWK generation
 - **Validation**: Input validation for handles and DIDs
-- **Configuration**: Environment-based configuration management
+- **Configuration**: Environment-based configuration with DNS and certificate customization
 
-### `atproto-record`
+### [`atproto-record`](crates/atproto-record/)
+**AT Protocol record signature operations**
 
-AT Protocol record signature operations library providing:
-
-- **Record Signing**: Create cryptographic signatures for AT Protocol records
+- **Record Signing**: Create cryptographic signatures for AT Protocol records with proper `$sig` object handling
 - **Signature Verification**: Verify existing signatures against records and public keys
-- **IPLD Integration**: Proper IPLD DAG-CBOR serialization for signature content
-- **Multi-curve Support**: Support for P-256 and K-256 elliptic curves
+- **IPLD Integration**: Proper IPLD DAG-CBOR serialization for consistent signature generation
+- **Multi-curve Support**: Support for P-256 and K-256 elliptic curves via `atproto-identity`
+- **Repository Context**: Include repository and collection context in signatures
 
-## CLI Tools
+### [`atproto-oauth`](crates/atproto-oauth/)
+**Complete OAuth 2.0 operations with AT Protocol extensions**
 
-The library includes several command-line utilities:
+- **JWT Operations**: Complete JSON Web Token minting, verification, and validation with ES256/ES256K support
+- **JWK Management**: JSON Web Key generation and management for P-256 and K-256 curves
+- **PKCE Implementation**: RFC 7636 Proof Key for Code Exchange for secure OAuth flows
+- **DPoP Support**: RFC 9449 Demonstration of Proof-of-Possession with automatic retry middleware
+- **OAuth Resource Discovery**: RFC 8414 OAuth 2.0 authorization server and protected resource metadata discovery
+- **AT Protocol Validation**: Comprehensive validation of OAuth servers against AT Protocol requirements
+
+### [`atproto-client`](crates/atproto-client/)
+**HTTP client library for AT Protocol services**
+
+- **HTTP Client Operations**: Authenticated and unauthenticated HTTP GET/POST requests with JSON support
+- **DPoP Authentication**: RFC 9449 Demonstration of Proof-of-Possession with automatic retry middleware
+- **Repository Operations**: Complete CRUD operations for AT Protocol repository records  
+- **URL Building**: Flexible URL construction with parameter encoding and query string generation
+- **OAuth Integration**: Seamless integration with `atproto-oauth` for DPoP authentication
+
+### [`atproto-oauth-axum`](crates/atproto-oauth-axum/)
+**Axum web handlers for OAuth 2.0 authorization server endpoints**
+
+- **Complete OAuth Server Handlers**: Ready-to-use Axum handlers for all required OAuth 2.0 endpoints
+- **Client Metadata Endpoint**: RFC 7591 compliant client metadata for dynamic client registration  
+- **JWKS Endpoint**: JSON Web Key Set serving for JWT signature verification
+- **Authorization Callback Handler**: Complete OAuth callback processing with token exchange
+- **OAuth Login CLI Tool**: Full-featured command-line tool for testing and development OAuth flows
 
-### atproto-identity
+## Command Line Tools
 
-- `atproto-identity-resolve` - Resolve DIDs and handles to identity documents
-- `atproto-identity-sign` - Sign identity-related operations
-- `atproto-identity-validate` - Validate DID and handle formats
+The library includes 7 command-line utilities across the crates:
+
+### Identity Operations (`atproto-identity`)
+- **`atproto-identity-resolve`** - Resolve AT Protocol handles and DIDs to identity documents
+- **`atproto-identity-sign`** - Sign JSON data with DID keys using IPLD DAG-CBOR serialization
+- **`atproto-identity-validate`** - Verify cryptographic signatures of JSON data
+- **`atproto-identity-key`** - Generate and manage cryptographic keys (P-256/K-256)
 
-### atproto-record
+### Record Operations (`atproto-record`) 
+- **`atproto-record-sign`** - Sign AT Protocol records with embedded signature metadata
+- **`atproto-record-verify`** - Verify AT Protocol record signatures with issuer authentication
 
-- `atproto-record-sign` - Sign AT Protocol records from files or stdin
-- `atproto-record-verify` - Verify AT Protocol record signatures from files or stdin
+### OAuth Operations (`atproto-oauth-axum`)
+- **`atproto-oauth-login`** - Complete OAuth client flow with local server and token acquisition
 
 ## Quick Start
 
···
 ```toml
 [dependencies]
 atproto-identity = "0.3.0"
-atproto-record = "0.3.0"
+atproto-record = "0.3.0" 
+atproto-oauth = "0.3.0"
+atproto-client = "0.3.0"
+atproto-oauth-axum = "0.3.0"
 ```
 
 ### Basic Identity Resolution
 
 ```rust
-use atproto_identity::resolve::resolve_handle;
+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(&[]);
+    
     // Resolve a handle to a DID
-    let did = resolve_handle("alice.bsky.social").await?;
+    let did = resolve_subject(&http_client, &dns_resolver, "alice.bsky.social").await?;
     println!("Resolved DID: {}", did);
     
     Ok(())
···
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
     // Parse DID key for signing operations
-    let signing_key = identify_key("did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW")?;
+    let signing_key = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
     
     // Create a record to sign
     let record = json!({
···
     
     // Create signature object with issuer and timestamp
     let signature_object = json!({
-        "issuer": "did:plc:tgudj2fjm77pzkuawquqhsxm",
-        "issued_at": "2024-01-01T00:00:00.000Z"
+        "issuer": "did:plc:issuer123",
+        "issuedAt": "2024-01-01T00:00:00.000Z"
     });
     
     // Sign the record
     let signed_record = signature::create(
         &signing_key,
         &record,
-        "did:plc:4zutorghlchjxzgceklue4la", // repository
-        "app.bsky.feed.post",              // collection
+        "did:plc:user123",     // repository
+        "app.bsky.feed.post",  // collection
         signature_object,
     ).await?;
     
     // Verify the signature
     signature::verify(
-        "did:plc:tgudj2fjm77pzkuawquqhsxm", // issuer
-        &signing_key,                       // verification key
-        signed_record,                      // signed record
-        "did:plc:4zutorghlchjxzgceklue4la", // repository
-        "app.bsky.feed.post",               // collection
+        "did:plc:issuer123",   // issuer
+        &signing_key,          // verification key
+        signed_record,         // signed record
+        "did:plc:user123",     // repository
+        "app.bsky.feed.post",  // collection
     ).await?;
     
     println!("Signature verification successful");
···
 }
 ```
 
-### CLI Usage Examples
+### OAuth Operations
+
+```rust
+use atproto_oauth::jwt::{mint, Header, Claims, JoseClaims};
+use atproto_oauth::pkce;
+use atproto_identity::key::identify_key;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let key_data = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
+    
+    // Generate PKCE parameters
+    let (code_verifier, code_challenge) = pkce::generate();
+    println!("PKCE Challenge: {}", code_challenge);
+    
+    // Create and sign JWT
+    let header = Header::default();
+    let claims = Claims::new(JoseClaims {
+        issuer: Some("did:plc:issuer123".to_string()),
+        subject: Some("did:plc:subject456".to_string()),
+        audience: Some("https://pds.example.com".to_string()),
+        ..Default::default()
+    });
+    
+    let token = mint(&key_data, &header, &claims)?;
+    println!("JWT: {}", token);
+    
+    Ok(())
+}
+```
+
+## CLI Usage Examples
 
 ```bash
-# Resolve a handle or DID
-cargo run --bin atproto-identity-resolve -- alice.bsky.social
+# Resolve a handle or DID to identity document
+cargo run --bin atproto-identity-resolve alice.bsky.social
 
-# Get full DID document
-cargo run --bin atproto-identity-resolve -- --did-document did:plc:abc123
+# Get full DID document with verification methods
+cargo run --bin atproto-identity-resolve --did-document did:plc:user123
 
-# Sign a record from file
-cargo run --bin atproto-record-sign -- \
-  did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
-  ./record.json \
-  did:plc:tgudj2fjm77pzkuawquqhsxm \
-  repository=did:plc:4zutorghlchjxzgceklue4la \
-  collection=app.bsky.feed.post
+# Generate a new P-256 private key
+cargo run --bin atproto-identity-key generate p256
 
-# Sign a record from stdin
-echo '{"$type":"app.bsky.feed.post","text":"Hello!"}' | \
-cargo run --bin atproto-record-sign -- \
-  did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
-  -- \
-  did:plc:tgudj2fjm77pzkuawquqhsxm \
-  repository=did:plc:4zutorghlchjxzgceklue4la \
+# Sign a record from file with all required context
+cargo run --bin atproto-record-sign \
+  did:key:zQ3shNzMp4oaaQ1... \
+  did:plc:issuer123 \
+  record.json \
+  repository=did:plc:user123 \
   collection=app.bsky.feed.post
 
-# Verify a signature from file
-cargo run --bin atproto-record-verify -- \
-  did:plc:tgudj2fjm77pzkuawquqhsxm \
-  did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
-  ./signed_record.json \
-  repository=did:plc:4zutorghlchjxzgceklue4la \
+# Verify a signed record
+cargo run --bin atproto-record-verify \
+  did:plc:issuer123 \
+  did:key:zQ3shNzMp4oaaQ1... \
+  signed_record.json \
+  repository=did:plc:user123 \
   collection=app.bsky.feed.post
 
-# Verify a signature from stdin
-echo '{"signatures":[...],"text":"Hello!"}' | \
-cargo run --bin atproto-record-verify -- \
-  did:plc:tgudj2fjm77pzkuawquqhsxm \
-  did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
-  -- \
-  repository=did:plc:4zutorghlchjxzgceklue4la \
-  collection=app.bsky.feed.post
+# Start OAuth login flow (requires EXTERNAL_BASE environment variable)  
+EXTERNAL_BASE=localhost:8080 cargo run --bin atproto-oauth-login login \
+  did:key:zQ3shNzMp4oaaQ1... \
+  alice.bsky.social
+```
+
+## Features
+
+- **Async/Await**: Built with modern Rust async patterns using Tokio
+- **Error Handling**: Comprehensive structured error types using `thiserror` with standardized error codes
+- **Security**: Forbids unsafe code, follows security best practices, and implements all required OAuth security extensions
+- **Standards Compliance**: Full AT Protocol, RFC 7636 (PKCE), RFC 9449 (DPoP), and RFC 8414 (OAuth Discovery) compliance
+- **Logging**: Structured logging with `tracing` for debugging and monitoring
+- **Multi-platform**: Works on all major platforms with configurable DNS and HTTP settings
+- **Modular Design**: Clean separation of concerns allowing selective usage of components
+
+## Architecture
+
+The library follows a layered architecture with clear separation of concerns:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Application Layer                       │
+│                 (CLI Tools & Web Handlers)                  │
+├─────────────────────────────────────────────────────────────┤
+│                    Protocol Layer                           │
+│              (atproto-client, atproto-record)               │
+├─────────────────────────────────────────────────────────────┤
+│                     OAuth Layer                             │
+│             (atproto-oauth, atproto-oauth-axum)             │
+├─────────────────────────────────────────────────────────────┤
+│                   Foundation Layer                          │
+│              (atproto-identity - Core Services)             │
+└─────────────────────────────────────────────────────────────┘
 ```
 
+- **Foundation Layer**: Core identity, cryptographic, and DID operations
+- **OAuth Layer**: Complete OAuth 2.0 flows with AT Protocol extensions
+- **Protocol Layer**: Higher-level AT Protocol operations (records, client)
+- **Application Layer**: Ready-to-use tools and web framework integration
+
 ## Development
 
-### Building
+### Building the Project
 
 ```bash
+# Build all crates
 cargo build
+
+# Build specific crate
+cargo build -p atproto-identity
+
+# Build with all features
+cargo build --all-features
 ```
 
 ### Running Tests
 
 ```bash
+# Run all tests
 cargo test
+
+# Run tests for specific crate  
+cargo test -p atproto-oauth
+
+# Run with output
+cargo test -- --nocapture
 ```
 
 ### Code Quality
···
 # Format code
 cargo fmt
 
-# Lint
+# Lint code
 cargo clippy
 
 # Check without building
 cargo check
+
+# Run all quality checks
+cargo fmt && cargo clippy && cargo test
 ```
 
-## Features
+### Documentation
 
-- **Async/Await**: Built with modern Rust async patterns using Tokio
-- **Error Handling**: Comprehensive structured error types using `thiserror`
-- **Logging**: Structured logging with `tracing`
-- **Security**: Forbids unsafe code and follows security best practices
-- **Standards Compliance**: Full AT Protocol specification compliance
-- **Multi-platform**: Works on all major platforms
-
-## Architecture
-
-The library follows a modular architecture with clear separation of concerns:
+```bash
+# Generate documentation
+cargo doc --open
 
-- **Identity Management**: Handle DID resolution, validation, and document management
-- **Cryptographic Operations**: Secure key operations and signature handling
-- **Network Operations**: HTTP and DNS resolution with proper error handling
-- **Data Models**: Comprehensive type definitions for AT Protocol entities
-- **CLI Tools**: Ready-to-use command-line utilities
+# Generate documentation for all crates
+cargo doc --workspace --open
+```
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ## Contributing
 
-Contributions are welcome! This project follows standard Rust conventions and includes comprehensive testing and documentation requirements.
+Contributions are welcome! Please ensure that:
 
-## Repository
+1. All tests pass: `cargo test`
+2. Code is properly formatted: `cargo fmt`
+3. No linting issues: `cargo clippy`
+4. New functionality includes appropriate tests and documentation
+5. Error handling follows the project's structured error format
 
-https://tangled.sh/@smokesignal.events/atproto-identity-rs
+## Acknowledgments
+
+This library was extracted from the [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source event and RSVP management and discovery application. We thank the Smokesignal contributors for their foundational work on AT Protocol identity management and record operations.

crates/atproto-client/README.md

···
 ```rust
 use atproto_client::com::atproto::repo::{
     get_record, list_records, create_record, put_record,
-    CreateRecordRequest, PutRecordRequest
+    CreateRecordRequest, PutRecordRequest, ListRecordsParams
 };
 use atproto_client::client::DPoPAuth;
 use atproto_identity::key::identify_key;
···
         None // Optional CID for specific version
     ).await?;
     
-    // List records in a collection
+    // List records in a collection with parameters
     let list_response = list_records::<serde_json::Value>(
         &http_client,
         &dpop_auth,
         pds_url,
         "did:plc:user123".to_string(),
         "app.bsky.feed.post".to_string(),
-        Some(50),     // limit
-        None,         // cursor for pagination
-        Some(false)   // reverse order
+        ListRecordsParams::new()
+            .limit(50)
+            .reverse(false)
     ).await?;
     
     // Create a new record
···
 
 ### Request/Response Types
 
+- **`ListRecordsParams`**: Builder-style parameters for listing records with pagination
 - **`CreateRecordRequest<T>`**: Strongly-typed request for creating new records
 - **`PutRecordRequest<T>`**: Strongly-typed request for updating records
 - **`GetRecordResponse`**: Response containing record data, URI, and CID

crates/atproto-client/src/com_atproto_repo.rs

···
 use serde::{de::DeserializeOwned, Deserialize, Serialize};
 
 use crate::{
-    client::{get_dpop_json, post_dpop_json, DPoPAuth},
+    client::{get_dpop_json, get_json, post_dpop_json, DPoPAuth},
     errors::SimpleError,
     url::URLBuilder,
 };
···
     Error(SimpleError),
 }
 
-/// Request to create a new record in an AT Protocol repository.
-#[derive(Debug, Serialize, Deserialize, Clone)]
-#[serde(bound = "T: Serialize + DeserializeOwned")]
-pub struct CreateRecordRequest<T: DeserializeOwned> {
-    /// Repository identifier (DID)
-    pub repo: String,
-    /// Collection NSID (e.g., "app.bsky.feed.post")
-    pub collection: String,
-
-    /// Optional record key; if None, server will generate one
-    #[serde(skip_serializing_if = "Option::is_none", default, rename = "rkey")]
-    pub record_key: Option<String>,
-
-    /// Whether to validate the record against its schema
-    pub validate: bool,
-
-    /// The record content to create
-    pub record: T,
-
-    /// Optional commit CID to swap (for atomic updates)
-    #[serde(
-        skip_serializing_if = "Option::is_none",
-        default,
-        rename = "swapCommit"
-    )]
-    pub swap_commit: Option<String>,
-}
-
-/// Request to update an existing record in an AT Protocol repository.
-#[derive(Debug, Serialize, Deserialize, Clone)]
-#[serde(bound = "T: Serialize + DeserializeOwned")]
-pub struct PutRecordRequest<T: DeserializeOwned> {
-    /// Repository identifier (DID)
-    pub repo: String,
-    /// Collection NSID (e.g., "app.bsky.feed.post")
-    pub collection: String,
-
-    /// Record key to update
-    #[serde(rename = "rkey")]
-    pub record_key: String,
-
-    /// Whether to validate the record against its schema
-    pub validate: bool,
-
-    /// The new record content
-    pub record: T,
-
-    /// Optional commit CID to swap (for atomic updates)
-    #[serde(
-        skip_serializing_if = "Option::is_none",
-        default,
-        rename = "swapCommit"
-    )]
-    pub swap_commit: Option<String>,
-
-    /// Optional record CID to swap (for conditional updates)
-    #[serde(
-        skip_serializing_if = "Option::is_none",
-        default,
-        rename = "swapRecord"
-    )]
-    pub swap_record: Option<String>,
-}
-
-/// Response from creating a record in an AT Protocol repository.
-#[derive(Debug, Deserialize, Clone)]
-#[serde(untagged)]
-pub enum CreateRecordResponse {
-    /// Successfully created record reference
-    StrongRef {
-        /// AT-URI of the created record
-        uri: String,
-        /// Content identifier (CID) of the created record
-        cid: String,
-
-        /// Additional fields not part of the standard response
-        #[serde(flatten)]
-        extra: HashMap<String, serde_json::Value>,
-    },
-    /// Error response from the server
-    Error(SimpleError),
-}
-
-/// Response from updating a record in an AT Protocol repository.
-#[derive(Debug, Serialize, Deserialize, Clone)]
-#[serde(untagged)]
-pub enum PutRecordResponse {
-    /// Successfully updated record reference
-    StrongRef {
-        /// AT-URI of the updated record
-        uri: String,
-        /// Content identifier (CID) of the updated record
-        cid: String,
-
-        /// Additional fields not part of the standard response
-        #[serde(flatten)]
-        extra: HashMap<String, serde_json::Value>,
-    },
-    /// Error response from the server
-    Error(SimpleError),
-}
-
 /// Retrieves a record from an AT Protocol repository.
 ///
 /// # Arguments
···
 /// The record data or an error response
 pub async fn get_record(
     http_client: &reqwest::Client,
-    dpop_auth: &DPoPAuth,
+    dpop_auth: Option<&DPoPAuth>,
     base_url: &str,
     repo: &str,
     collection: &str,
···
 
     tracing::info!(?url, "get_record");
 
-    get_dpop_json(http_client, dpop_auth, &url)
-        .await
-        .and_then(|value| serde_json::from_value(value).map_err(|err| err.into()))
+    if let Some(dpop_auth) = dpop_auth {
+        get_dpop_json(http_client, dpop_auth, &url)
+            .await
+            .and_then(|value| serde_json::from_value(value).map_err(|err| err.into()))
+    } else {
+        get_json(http_client, &url)
+            .await
+            .and_then(|value| serde_json::from_value(value).map_err(|err| err.into()))
+    }
 }
 
 /// A single record in a list records response.
···
     pub records: Vec<ListRecord<T>>,
 }
 
+/// Parameters for listing records from a repository collection.
+#[derive(Default)]
+pub struct ListRecordsParams {
+    /// Maximum number of records to return
+    pub limit: Option<u32>,
+    /// Pagination cursor from previous request
+    pub cursor: Option<String>,
+    /// Whether to return records in reverse chronological order
+    pub reverse: Option<bool>,
+}
+
+impl ListRecordsParams {
+    /// Creates new list records parameters with default values.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Sets the maximum number of records to return.
+    pub fn limit(mut self, limit: u32) -> Self {
+        self.limit = Some(limit);
+        self
+    }
+
+    /// Sets the pagination cursor.
+    pub fn cursor(mut self, cursor: String) -> Self {
+        self.cursor = Some(cursor);
+        self
+    }
+
+    /// Sets reverse chronological ordering.
+    pub fn reverse(mut self, reverse: bool) -> Self {
+        self.reverse = Some(reverse);
+        self
+    }
+}
+
 /// Lists records from an AT Protocol repository collection.
 ///
 /// # Arguments
···
 /// * `base_url` - Base URL of the AT Protocol server
 /// * `repo` - Repository identifier (DID)
 /// * `collection` - Collection NSID to list from
-/// * `limit` - Maximum number of records to return
-/// * `cursor` - Pagination cursor from previous request
-/// * `reverse` - Whether to return records in reverse chronological order
+/// * `params` - Optional parameters for listing (limit, cursor, reverse)
 ///
 /// # Returns
 ///
···
     base_url: &str,
     repo: String,
     collection: String,
-    limit: Option<u32>,
-    cursor: Option<String>,
-    reverse: Option<bool>,
+    params: ListRecordsParams,
 ) -> Result<ListRecordsResponse<T>> {
     let mut url_builder = URLBuilder::new(base_url);
     url_builder.path("/xrpc/com.atproto.repo.listRecords");
···
     url_builder.param("repo", &repo);
     url_builder.param("collection", &collection);
 
-    if let Some(limit) = limit {
+    if let Some(limit) = params.limit {
         url_builder.param("limit", &limit.to_string());
     }
 
-    if let Some(cursor) = cursor {
+    if let Some(cursor) = params.cursor {
         url_builder.param("cursor", &cursor);
     }
 
-    if let Some(reverse) = reverse {
+    if let Some(reverse) = params.reverse {
         url_builder.param("reverse", &reverse.to_string());
     }
 
···
         .and_then(|value| serde_json::from_value(value).map_err(|err| err.into()))
 }
 
+/// Request to create a new record in an AT Protocol repository.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(bound = "T: Serialize + DeserializeOwned")]
+pub struct CreateRecordRequest<T: DeserializeOwned> {
+    /// Repository identifier (DID)
+    pub repo: String,
+    /// Collection NSID (e.g., "app.bsky.feed.post")
+    pub collection: String,
+
+    /// Optional record key; if None, server will generate one
+    #[serde(skip_serializing_if = "Option::is_none", default, rename = "rkey")]
+    pub record_key: Option<String>,
+
+    /// Whether to validate the record against its schema
+    pub validate: bool,
+
+    /// The record content to create
+    pub record: T,
+
+    /// Optional commit CID to swap (for atomic updates)
+    #[serde(
+        skip_serializing_if = "Option::is_none",
+        default,
+        rename = "swapCommit"
+    )]
+    pub swap_commit: Option<String>,
+}
+
+/// Response from creating a record in an AT Protocol repository.
+#[derive(Debug, Deserialize, Clone)]
+#[serde(untagged)]
+pub enum CreateRecordResponse {
+    /// Successfully created record reference
+    StrongRef {
+        /// AT-URI of the created record
+        uri: String,
+        /// Content identifier (CID) of the created record
+        cid: String,
+
+        /// Additional fields not part of the standard response
+        #[serde(flatten)]
+        extra: HashMap<String, serde_json::Value>,
+    },
+    /// Error response from the server
+    Error(SimpleError),
+}
+
 /// Creates a new record in an AT Protocol repository.
 ///
 /// # Arguments
···
     post_dpop_json(http_client, dpop_auth, &url, value)
         .await
         .and_then(|value| serde_json::from_value(value).map_err(|err| err.into()))
+}
+
+/// Request to update an existing record in an AT Protocol repository.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(bound = "T: Serialize + DeserializeOwned")]
+pub struct PutRecordRequest<T: DeserializeOwned> {
+    /// Repository identifier (DID)
+    pub repo: String,
+    /// Collection NSID (e.g., "app.bsky.feed.post")
+    pub collection: String,
+
+    /// Record key to update
+    #[serde(rename = "rkey")]
+    pub record_key: String,
+
+    /// Whether to validate the record against its schema
+    pub validate: bool,
+
+    /// The new record content
+    pub record: T,
+
+    /// Optional commit CID to swap (for atomic updates)
+    #[serde(
+        skip_serializing_if = "Option::is_none",
+        default,
+        rename = "swapCommit"
+    )]
+    pub swap_commit: Option<String>,
+
+    /// Optional record CID to swap (for conditional updates)
+    #[serde(
+        skip_serializing_if = "Option::is_none",
+        default,
+        rename = "swapRecord"
+    )]
+    pub swap_record: Option<String>,
+}
+
+/// Response from updating a record in an AT Protocol repository.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+#[serde(untagged)]
+pub enum PutRecordResponse {
+    /// Successfully updated record reference
+    StrongRef {
+        /// AT-URI of the updated record
+        uri: String,
+        /// Content identifier (CID) of the updated record
+        cid: String,
+
+        /// Additional fields not part of the standard response
+        #[serde(flatten)]
+        extra: HashMap<String, serde_json::Value>,
+    },
+    /// Error response from the server
+    Error(SimpleError),
 }
 
 /// Updates an existing record in an AT Protocol repository.

crates/atproto-identity/Cargo.toml

···
 async-trait = "0.1.88"
 lru = { workspace = true, optional = true }
 
+axum = { version = "0.8", optional = true }
+http = { version = "1.0.0", optional = true }
+
 [features]
+default = ["lru", "axum"]
 lru = ["dep:lru"]
+axum = ["dep:axum", "dep:http"]
 
 [lints]
 workspace = true

crates/atproto-identity/README.md

···
 
 ## Command Line Tools
 
-The library includes several command-line tools for AT Protocol identity operations:
+The library includes four command-line tools for AT Protocol identity operations:
 
 ### `atproto-identity-resolve`
-Resolves AT Protocol handles and DIDs to their canonical DID identifiers and optionally retrieves full DID documents. Supports both did:plc and did:web methods with configurable DNS and HTTP settings.
+
+Resolves AT Protocol handles and DIDs to their canonical DID identifiers and optionally retrieves full DID documents. This tool supports both `did:plc` and `did:web` methods with configurable DNS and HTTP settings for comprehensive identity resolution.
+
+**Features:**
+- **Handle Resolution**: Converts AT Protocol handles (e.g., `alice.bsky.social`) to DIDs
+- **DID Document Retrieval**: Fetches complete DID documents with verification methods
+- **Multi-Method Support**: Handles both PLC directory and Web DID resolution
+- **DNS Configuration**: Supports custom DNS nameservers and certificate bundles
+- **Output Options**: Choose between DID-only output or full document retrieval
 
 ```bash
-# Resolve a handle to DID
-cargo run --bin atproto-identity-resolve ngerakines.me
+# Resolve a handle to its DID
+cargo run --bin atproto-identity-resolve alice.bsky.social
 
-# Get full DID document
-cargo run --bin atproto-identity-resolve --did-document ngerakines.me
+# Resolve a DID and get full DID document
+cargo run --bin atproto-identity-resolve --did-document did:plc:user123
+
+# Resolve with custom configuration
+PLC_HOSTNAME=plc.directory DNS_NAMESERVERS="8.8.8.8;1.1.1.1" \
+  cargo run --bin atproto-identity-resolve --did-document alice.bsky.social
 ```
 
 ### `atproto-identity-sign`
-Creates cryptographic signatures of JSON data using AT Protocol DID keys. Takes a JSON file, serializes it using IPLD DAG-CBOR format, and produces a multibase-encoded signature.
+
+Creates cryptographic signatures of JSON data using AT Protocol DID keys. This tool reads JSON files, serializes them using IPLD DAG-CBOR format for consistency, and produces multibase-encoded signatures suitable for AT Protocol operations.
+
+**Features:**
+- **DID Key Support**: Works with both P-256 and K-256 private keys
+- **JSON Processing**: Handles arbitrary JSON data structures
+- **IPLD Serialization**: Uses DAG-CBOR for deterministic serialization
+- **Multibase Output**: Produces signatures in multibase format
+- **File Input**: Reads JSON data from specified files
 
 ```bash
-# Sign a JSON file with a DID key
-cargo run --bin atproto-identity-sign did:key:zQ3sh... record.json
+# Sign a JSON file with a DID private key
+cargo run --bin atproto-identity-sign did:key:zQ3shNzMp4oaaQ1... data.json
+
+# Example output: multibase-encoded signature string
+# uEiB5vJz8aZhpx3bY2nKfRzPpLmQwA8Z9qXhNvYtF2gH7...
 ```
 
 ### `atproto-identity-validate`
-Verifies cryptographic signatures of JSON data using AT Protocol DID keys. Takes a JSON file, a multibase-encoded signature, and a DID key, then validates the signature.
+
+Verifies cryptographic signatures of JSON data using AT Protocol DID keys. This tool validates that signatures were created by the holder of a specific private key, ensuring data integrity and authenticity for AT Protocol operations.
+
+**Features:**
+- **Signature Verification**: Validates multibase-encoded signatures
+- **DID Key Support**: Works with P-256 and K-256 public keys
+- **IPLD Deserialization**: Uses DAG-CBOR for consistent verification
+- **File Processing**: Reads JSON data and signatures from files
+- **Exit Code Reporting**: Returns appropriate exit codes for success/failure
 
 ```bash
 # Validate a signature against a JSON file
-cargo run --bin atproto-identity-validate did:key:zQ3sh... record.json uEiB...
+cargo run --bin atproto-identity-validate did:key:zQ3shNzMp4oaaQ1... data.json uEiB5vJz8aZ...
+
+# Successful validation returns exit code 0
+# Failed validation returns exit code 1
 ```
 
+**Arguments:**
+- `<public_key>` - DID key string for verification (did:key:...)
+- `<data_file>` - JSON file containing the original data
+- `<signature>` - Multibase-encoded signature to verify
+
 ### `atproto-identity-key`
-Provides cryptographic key management capabilities including key generation for both P-256 and K-256 elliptic curves.
+
+Provides comprehensive cryptographic key management capabilities for AT Protocol operations, including key generation and inspection for both P-256 and K-256 elliptic curves.
+
+**Features:**
+- **Key Generation**: Creates new private keys for both curve types
+- **Secure Random**: Uses cryptographically secure random number generation
+- **DID Key Format**: Outputs keys in standard DID key format
+- **Multiple Algorithms**: Supports both P-256 (secp256r1) and K-256 (secp256k1) curves
+- **Development Ready**: Generated keys ready for use in AT Protocol operations
 
 ```bash
-# Generate a new P-256 private key
+# Generate a new P-256 private key (recommended for most AT Protocol use)
 cargo run --bin atproto-identity-key generate p256
 
-# Generate a new K-256 private key
+# Generate a new K-256 private key (Bitcoin-style curve)
 cargo run --bin atproto-identity-key generate k256
+
+# Example output format:
+# did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA
 ```
+
+**Key Types:**
+- **P-256**: NIST P-256 curve (secp256r1) - Recommended for new applications
+- **K-256**: secp256k1 curve (same as Bitcoin) - For Bitcoin-compatible operations
+
+**Security Note:** Generated keys are output to stdout and should be stored securely. Never commit private keys to version control or share them publicly.
 
 ## Architecture
 

crates/atproto-identity/src/axum/mod.rs

···
+//! Axum web framework integration for AT Protocol identity management.
+//!
+//! Provides request extractors and state management for integrating AT Protocol
+//! identity operations with Axum web applications.
+
+pub mod state;

crates/atproto-identity/src/axum/state.rs

···
+//! Axum request extractors for AT Protocol identity services.
+//!
+//! Provides extractors that automatically inject DID document storage and key providers
+//! into Axum request handlers from application state.
+
+use axum::extract::{FromRef, FromRequestParts};
+use http::request::Parts;
+use std::convert::Infallible;
+use std::sync::Arc;
+
+use crate::{key::KeyProvider, storage::DidDocumentStorage};
+
+/// Axum request extractor for DID document storage.
+///
+/// Automatically extracts a DID document storage implementation from the application state.
+#[derive(Clone)]
+pub struct DidDocumentStorageExtractor(pub Arc<dyn DidDocumentStorage + Send + Sync>);
+
+impl<S> FromRequestParts<S> for DidDocumentStorageExtractor
+where
+    Arc<dyn DidDocumentStorage + Send + Sync>: FromRef<S>,
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let storage = Arc::<dyn DidDocumentStorage + Send + Sync>::from_ref(state);
+        Ok(DidDocumentStorageExtractor(storage))
+    }
+}
+
+/// Axum request extractor for key provider services.
+///
+/// Automatically extracts a key provider implementation from the application state.
+#[derive(Clone)]
+pub struct KeyProviderExtractor(pub Arc<dyn KeyProvider + Send + Sync>);
+
+impl<S> FromRequestParts<S> for KeyProviderExtractor
+where
+    Arc<dyn KeyProvider + Send + Sync>: FromRef<S>,
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let key_provider = Arc::<dyn KeyProvider + Send + Sync>::from_ref(state);
+        Ok(KeyProviderExtractor(key_provider))
+    }
+}

crates/atproto-identity/src/errors.rs

···
 //! - **`ConfigError`** (config-1 to config-3): Configuration and environment variable related errors
 //! - **`ResolveError`** (resolve-1 to resolve-7): Handle and DID resolution errors including DNS/HTTP failures and conflicts
 //! - **`PLCDIDError`** (plc-1 to plc-2): PLC directory communication and document parsing errors
-//! - **`KeyError`** (key-1 to key-9): Cryptographic key operations including generation, parsing, signing, and validation
+//! - **`KeyError`** (key-1 to key-13): Cryptographic key operations including generation, parsing, signing, and validation
 //! - **`StorageError`** (storage-1 to storage-3): Storage operations including cache lock failures and data access errors
 //!
 //! ## Error Format
···
 #[derive(Debug, Error)]
 pub enum ResolveError {
     /// Occurs when multiple different DIDs are found via DNS TXT record lookup
-    #[error("error-atproto-identity-resolve-1 Multiple DIDs resolved for handle: expected single DID")]
+    #[error(
+        "error-atproto-identity-resolve-1 Multiple DIDs resolved for handle: expected single DID"
+    )]
     MultipleDIDsFound,
 
     /// Occurs when no DIDs are found via either DNS or HTTP resolution methods
···
     },
 
     /// Occurs when HTTP response from .well-known/atproto-did doesn't start with "did:"
-    #[error("error-atproto-identity-resolve-6 Invalid HTTP resolution response: expected DID format")]
+    #[error(
+        "error-atproto-identity-resolve-6 Invalid HTTP resolution response: expected DID format"
+    )]
     InvalidHTTPResolutionResponse,
 
     /// Occurs when input cannot be parsed as a valid handle or DID
···
     /// Occurs when attempting to generate a public key directly
     #[error("error-atproto-identity-key-9 Public key generation not supported: generate private key instead")]
     PublicKeyGenerationNotSupported,
+
+    /// Occurs when the decoded key data is too short to identify the key type
+    #[error("error-atproto-identity-key-10 Unidentified key type: key data too short")]
+    UnidentifiedKeyType,
+
+    /// Occurs when the multibase key type prefix is not recognized
+    #[error("error-atproto-identity-key-11 Invalid multibase key type: {prefix:?}")]
+    InvalidMultibaseKeyType {
+        /// The unrecognized key type prefix
+        prefix: Vec<u8>,
+    },
+
+    /// Occurs when JWK format conversion is not supported for the key type
+    #[error("error-atproto-identity-key-12 JWK format conversion not supported for key type: {key_type}")]
+    JWKConversionNotSupported {
+        /// The key type that doesn't support JWK conversion
+        key_type: String,
+    },
+
+    /// Occurs when JWK format conversion fails for supported key types
+    #[error("error-atproto-identity-key-13 JWK format conversion failed: {error}")]
+    JWKConversionFailed {
+        /// The underlying conversion error
+        error: String,
+    },
 }
 
 /// Error types that can occur when working with storage operations

crates/atproto-identity/src/key.rs

···
 //! }
 //! ```
 
-use anyhow::{anyhow, Result};
+use anyhow::Result;
 use ecdsa::signature::Signer;
 use elliptic_curve::JwkEcKey;
 
···
     }
 }
 
+/// Trait for providing cryptographic keys by identifier.
+///
+/// This trait defines the interface for key providers that can retrieve private keys
+/// by their identifier. Implementations must be thread-safe to support concurrent access.
+#[async_trait::async_trait]
+pub trait KeyProvider: Send + Sync {
+    /// Retrieves a private key by its identifier.
+    ///
+    /// # Arguments
+    /// * `key_id` - The identifier of the key to retrieve
+    ///
+    /// # Returns
+    /// * `Ok(Some(KeyData))` - If the key was found and successfully retrieved
+    /// * `Ok(None)` - If no key exists for the given identifier
+    /// * `Err(anyhow::Error)` - If an error occurred during key retrieval
+    async fn get_private_key_by_id(&self, key_id: &str) -> Result<Option<KeyData>>;
+}
+
 /// DID key method prefix.
 const DID_METHOD_KEY_PREFIX: &str = "did:key:";
 
···
         multibase::decode(stripped_key).map_err(|error| KeyError::DecodeError { error })?;
 
     if decoded_multibase_key.len() < 3 {
-        return Err(KeyError::InvalidKey {
-            error: anyhow!("unidentified key type"),
-        });
+        return Err(KeyError::UnidentifiedKeyType);
     }
 
     // These values were verified using the following method:
···
             decoded_multibase_key[2..].to_vec(),
         )),
 
-        _ => Err(KeyError::InvalidKey {
-            error: anyhow!(
-                "invalid multibase key type: {:?}",
-                &decoded_multibase_key[..2]
-            ),
+        _ => Err(KeyError::InvalidMultibaseKeyType {
+            prefix: decoded_multibase_key[..2].to_vec(),
         }),
     }
 }
···
         match *self.key_type() {
             KeyType::P256Public => {
                 let public_key = p256::PublicKey::from_sec1_bytes(self.bytes()).map_err(|e| {
-                    KeyError::InvalidKey {
-                        error: anyhow!("Failed to parse P256 public key: {}", e),
+                    KeyError::JWKConversionFailed {
+                        error: format!("Failed to parse P256 public key: {}", e),
                     }
                 })?;
                 Ok(public_key.to_jwk())
···
                     .map_err(|error| KeyError::SecretKeyError { error })?;
                 Ok(secret_key.to_jwk())
             }
-            KeyType::K256Public => Err(KeyError::InvalidKey {
-                error: anyhow!("K256 keys do not support JWK format conversion"),
+            KeyType::K256Public => Err(KeyError::JWKConversionNotSupported {
+                key_type: "K256Public".to_string(),
             }),
-            KeyType::K256Private => Err(KeyError::InvalidKey {
-                error: anyhow!("K256 keys do not support JWK format conversion"),
+            KeyType::K256Private => Err(KeyError::JWKConversionNotSupported {
+                key_type: "K256Private".to_string(),
             }),
         }
     }
···
         // Test invalid key type prefix
         assert!(matches!(
             identify_key("z4vLVqpQveB3w8G6MQsLVseJ1Z2E1JyQzUj6WgRYNNwB9jdE"),
-            Err(KeyError::InvalidKey { .. })
+            Err(KeyError::InvalidMultibaseKeyType { .. })
         ));
     }
 
···
         assert!(private_jwk.is_err());
         assert!(matches!(
             private_jwk.unwrap_err(),
-            KeyError::InvalidKey { .. }
+            KeyError::JWKConversionNotSupported { .. }
         ));
 
         let public_jwk: Result<elliptic_curve::JwkEcKey, _> = (&public_key_data).try_into();
         assert!(public_jwk.is_err());
         assert!(matches!(
             public_jwk.unwrap_err(),
-            KeyError::InvalidKey { .. }
+            KeyError::JWKConversionNotSupported { .. }
         ));
 
         Ok(())

crates/atproto-identity/src/lib.rs

···
 pub mod storage_lru;
 pub mod validation;
 pub mod web;
+
+#[cfg(feature = "axum")]
+pub mod axum;

crates/atproto-oauth-axum/Cargo.toml

···
+[package]
+name = "atproto-oauth-axum"
+version = "0.3.0"
+readme = "README.md"
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[dependencies]
+atproto-identity.workspace = true
+atproto-record.workspace = true
+atproto-oauth.workspace = true
+
+anyhow.workspace = true
+async-trait.workspace = true
+chrono.workspace = true
+elliptic-curve.workspace = true
+hickory-resolver.workspace = true
+rand.workspace = true
+reqwest-chain.workspace = true
+reqwest-middleware.workspace = true
+reqwest.workspace = true
+serde_json.workspace = true
+serde.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+urlencoding = "2.1.3"
+axum = { version = "0.8", features = ["macros"] }
+http = "1.0.0"
+
+[lints]
+workspace = true

crates/atproto-oauth-axum/README.md

···
+# atproto-oauth-axum
+
+A Rust library providing complete Axum web handlers for AT Protocol OAuth 2.0 authorization server endpoints, including client metadata, JWKS, authorization callback handling, and a comprehensive command-line OAuth login tool.
+
+## Overview
+
+`atproto-oauth-axum` provides ready-to-use Axum web handlers that implement the complete AT Protocol OAuth 2.0 authorization server specification. This library handles OAuth client metadata discovery, JSON Web Key Set (JWKS) endpoints, authorization callback processing, and includes a full-featured command-line tool for OAuth login flows.
+
+This project was extracted from the open-sourced [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project and is designed to be a standalone, reusable library for AT Protocol OAuth server implementations.
+
+## Features
+
+- **Complete OAuth Server Handlers**: Ready-to-use Axum handlers for all required OAuth 2.0 endpoints
+- **Client Metadata Endpoint**: RFC 7591 compliant client metadata for dynamic client registration
+- **JWKS Endpoint**: JSON Web Key Set serving for JWT signature verification
+- **Authorization Callback Handler**: Complete OAuth callback processing with token exchange
+- **OAuth Login CLI Tool**: Full-featured command-line tool for testing and development OAuth flows
+- **Axum Integration**: Native Axum state management and request extractors
+- **Error Handling**: Comprehensive structured error types with proper HTTP responses
+- **AT Protocol Compliance**: Implements all AT Protocol-specific OAuth requirements
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+atproto-oauth-axum = "0.3.0"
+```
+
+## Usage
+
+### Basic Axum Server Setup
+
+```rust
+use atproto_oauth_axum::{
+    handle_complete::handle_oauth_callback,
+    handle_jwks::handle_oauth_jwks,
+    handler_metadata::handle_oauth_metadata,
+    state::OAuthClientConfig,
+};
+use axum::{routing::get, Router};
+use atproto_identity::key::identify_key;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Set up OAuth client configuration
+    let oauth_config = OAuthClientConfig {
+        client_uri: "https://your-app.com".to_string(),
+        client_id: "https://your-app.com/oauth/client-metadata.json".to_string(),
+        redirect_uris: "https://your-app.com/oauth/callback".to_string(),
+        jwks_uri: "https://your-app.com/.well-known/jwks.json".to_string(),
+        signing_keys: vec![
+            identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?
+        ],
+    };
+
+    // Create Axum router with OAuth handlers
+    let app = Router::new()
+        .route("/oauth/client-metadata.json", get(handle_oauth_metadata))
+        .route("/.well-known/jwks.json", get(handle_oauth_jwks))
+        .route("/oauth/callback", get(handle_oauth_callback))
+        .with_state(oauth_config);
+
+    // Start the server
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
+    axum::serve(listener, app).await?;
+
+    Ok(())
+}
+```
+
+### OAuth Client Metadata Handler
+
+```rust
+use atproto_oauth_axum::{handler_metadata::handle_oauth_metadata, state::OAuthClientConfig};
+use axum::{routing::get, Router};
+
+// The metadata handler automatically generates RFC 7591 compliant client metadata
+let app = Router::new()
+    .route("/oauth/client-metadata.json", get(handle_oauth_metadata))
+    .with_state(oauth_config);
+
+// Returns JSON like:
+// {
+//   "client_id": "https://your-app.com/oauth/client-metadata.json",
+//   "client_uri": "https://your-app.com",
+//   "dpop_bound_access_tokens": true,
+//   "application_type": "web",
+//   "redirect_uris": ["https://your-app.com/oauth/callback"],
+//   "grant_types": ["authorization_code", "refresh_token"],
+//   "response_types": ["code"],
+//   "scope": "atproto transition:generic",
+//   "token_endpoint_auth_method": "private_key_jwt",
+//   "jwks_uri": "https://your-app.com/.well-known/jwks.json"
+// }
+```
+
+### JWKS Endpoint Handler
+
+```rust
+use atproto_oauth_axum::{handle_jwks::handle_oauth_jwks, state::OAuthClientConfig};
+use axum::{routing::get, Router};
+
+// The JWKS handler automatically converts your signing keys to JWK format
+let app = Router::new()
+    .route("/.well-known/jwks.json", get(handle_oauth_jwks))
+    .with_state(oauth_config);
+
+// Returns JSON Web Key Set with your public keys for signature verification
+```
+
+### OAuth Callback Handler
+
+```rust
+use atproto_oauth_axum::{
+    handle_complete::handle_oauth_callback,
+    state::{OAuthClientConfig, HttpClient},
+};
+use atproto_identity::axum::state::{DidDocumentStorageExtractor, KeyProviderExtractor};
+use atproto_oauth::axum::state::OAuthRequestStorageExtractor;
+use axum::{routing::get, Router};
+
+// The callback handler processes OAuth authorization callbacks
+// It automatically:
+// - Validates OAuth state parameters
+// - Exchanges authorization codes for tokens
+// - Validates DPoP proofs
+// - Returns complete OAuth response with tokens
+
+let app = Router::new()
+    .route("/oauth/callback", get(handle_oauth_callback))
+    .with_state(web_context); // Includes all required state
+```
+
+### Integration with Other Libraries
+
+```rust
+use atproto_oauth_axum::state::{OAuthClientConfig, HttpClient};
+use atproto_identity::{
+    axum::state::{DidDocumentStorageExtractor, KeyProviderExtractor},
+    storage_lru::LruDidDocumentStorage,
+    key::KeyProvider,
+};
+use atproto_oauth::{
+    axum::state::OAuthRequestStorageExtractor,
+    storage_lru::LruOAuthRequestStorage,
+};
+use std::{num::NonZeroUsize, sync::Arc};
+
+// Set up storage and state for full OAuth server
+let did_storage = Arc::new(LruDidDocumentStorage::new(NonZeroUsize::new(256).unwrap()));
+let oauth_storage = Arc::new(LruOAuthRequestStorage::new(NonZeroUsize::new(256).unwrap()));
+let key_provider = Arc::new(your_key_provider_impl);
+
+// The handlers automatically extract these from your application state
+```
+
+## Command Line Tools
+
+The crate includes a comprehensive command-line tool for OAuth operations:
+
+### `atproto-oauth-login`
+
+A complete OAuth login CLI tool that implements the full AT Protocol OAuth client flow. This tool sets up a local web server to handle OAuth callbacks and guides users through the complete authorization process from subject resolution to token acquisition.
+
+**Features:**
+- **Subject Resolution**: Automatically resolves AT Protocol handles or DIDs to their identity documents
+- **DID Document Retrieval**: Fetches and validates DID documents from PLC directory or Web DID endpoints
+- **PDS Discovery**: Discovers Personal Data Server (PDS) endpoints from DID documents
+- **Authorization Server Discovery**: Retrieves OAuth authorization server metadata from PDS resources
+- **PKCE Implementation**: Generates secure PKCE parameters for authorization code flows
+- **DPoP Key Generation**: Creates DPoP keys for bound access tokens
+- **Local OAuth Server**: Runs temporary web server to handle authorization callbacks
+- **Complete Token Exchange**: Handles full OAuth flow from authorization to token acquisition
+
+```bash
+# Start OAuth login flow for a handle
+cargo run --bin atproto-oauth-login login did:key:zQ3sh... alice.bsky.social
+
+# Start OAuth login flow for a DID
+cargo run --bin atproto-oauth-login login did:key:zQ3sh... did:plc:user123
+
+# The tool will:
+# 1. Resolve the subject to a DID
+# 2. Fetch the DID document
+# 3. Discover the PDS endpoint
+# 4. Get OAuth authorization server configuration
+# 5. Generate PKCE and DPoP parameters
+# 6. Start a local server on http://localhost:8080
+# 7. Display the authorization URL to visit
+# 8. Handle the OAuth callback
+# 9. Exchange authorization code for tokens
+# 10. Display the complete OAuth response including access tokens and DPoP key
+
+# Example output:
+# OAuth server started on http://0.0.0.0:8080
+# 🔐 OAuth Authorization URL:
+# https://auth.bsky.social/oauth/authorize?client_id=https://localhost:8080/oauth/client-metadata.json&request_uri=urn:ietf:params:oauth:request_uri:abc123
+# 
+# Please visit this URL in your browser to complete the OAuth flow.
+# The callback will be handled at: https://localhost:8080/oauth/callback
+```
+
+**Server Endpoints:**
+The tool automatically sets up these endpoints during the OAuth flow:
+- `GET /oauth/client-metadata.json` - OAuth client metadata
+- `GET /.well-known/jwks.json` - JSON Web Key Set
+- `GET /oauth/callback` - Authorization callback handler
+
+**Environment Variables:**
+```bash
+# Required: Your application's external base URL
+export EXTERNAL_BASE=your-app.com
+
+# Optional: Custom PLC directory
+export PLC_HOSTNAME=plc.directory
+
+# Optional: Custom DNS nameservers
+export DNS_NAMESERVERS=8.8.8.8;1.1.1.1
+
+# Optional: Custom CA certificates
+export CERTIFICATE_BUNDLES=/path/to/cert.pem
+
+# Optional: Custom User-Agent
+export USER_AGENT="my-oauth-client/1.0"
+```
+
+**Security Features:**
+- Cryptographically secure PKCE code verifier generation
+- DPoP proof-of-possession for bound access tokens
+- State parameter validation for CSRF protection
+- Automatic nonce handling for DPoP challenges
+- Private key security with no key storage
+
+## Modules
+
+- **[`handle_complete`]** - OAuth authorization callback handler with token exchange
+- **[`handler_metadata`]** - OAuth client metadata endpoint (RFC 7591)
+- **[`handle_jwks`]** - JSON Web Key Set endpoint for signature verification
+- **[`handle_init`]** - OAuth authorization initiation (reserved for future use)
+- **[`state`]** - Axum state management and request extractors
+- **[`errors`]** - Structured error types for OAuth operations
+
+## Error Handling
+
+The crate uses comprehensive structured error types:
+
+```rust
+use atproto_oauth_axum::errors::{OAuthCallbackError, OAuthLoginError};
+
+// OAuth callback handler errors
+match callback_result {
+    Err(OAuthCallbackError::NoOAuthRequestFound) => {
+        println!("OAuth state not found - possible CSRF attack");
+    },
+    Err(OAuthCallbackError::InvalidIssuer { expected, actual }) => {
+        println!("Issuer mismatch: expected {}, got {}", expected, actual);
+    },
+    Err(OAuthCallbackError::NoDIDDocumentFound) => {
+        println!("DID document not found for OAuth request");
+    },
+    Ok(response) => println!("OAuth callback successful"),
+}
+
+// OAuth login CLI errors
+match login_result {
+    Err(OAuthLoginError::SubjectResolutionFailed { error }) => {
+        println!("Failed to resolve subject: {}", error);
+    },
+    Err(OAuthLoginError::NoPDSEndpointFound) => {
+        println!("No PDS endpoint found in DID document");
+    },
+    Err(OAuthLoginError::OAuthInitFailed { error }) => {
+        println!("OAuth initialization failed: {}", error);
+    },
+    Ok(()) => println!("OAuth login completed successfully"),
+}
+```
+
+### Error Format
+
+All errors follow the standardized format:
+
+```
+error-atproto-oauth-axum-<domain>-<number> <message>: <details>
+```
+
+Example error codes:
+- `error-atproto-oauth-axum-callback-1` through `error-atproto-oauth-axum-callback-7` - OAuth callback errors
+- `error-atproto-oauth-axum-login-1` through `error-atproto-oauth-axum-login-11` - OAuth login CLI errors
+
+## AT Protocol Compliance
+
+This library implements all AT Protocol OAuth requirements:
+
+### OAuth Server Requirements
+- Support for `authorization_code` and `refresh_token` grant types
+- PKCE with `S256` code challenge method
+- DPoP bound access tokens
+- `private_key_jwt` token endpoint authentication
+- `ES256` signing algorithm support
+- Required OAuth scopes (`atproto`, `transition:generic`)
+
+### Client Requirements
+- Dynamic client registration metadata
+- JWKS endpoint for public key discovery
+- Proper redirect URI validation
+- State parameter CSRF protection
+
+## Dependencies
+
+This crate builds on:
+
+- [`atproto-identity`](../atproto-identity) - Identity resolution and cryptographic operations
+- [`atproto-oauth`](../atproto-oauth) - Core OAuth 2.0 operations and security extensions
+- `axum` - Web framework for HTTP handlers
+- `reqwest` - HTTP client for OAuth server communication
+- `tokio` - Async runtime for web server operations
+- `serde_json` - JSON serialization for OAuth responses
+- `chrono` - Date and time handling for OAuth flows
+- `anyhow` - Error handling utilities
+- `thiserror` - Structured error type derivation
+
+## Development and Testing
+
+This crate is ideal for:
+
+- **OAuth Server Development**: Complete Axum handlers for AT Protocol OAuth servers
+- **OAuth Client Testing**: CLI tool for testing OAuth flows against AT Protocol services
+- **Integration Testing**: Ready-to-use handlers for OAuth endpoint testing
+- **Development Workflows**: Local OAuth server for development and debugging
+
+## Contributing
+
+Contributions are welcome! Please ensure that:
+
+1. All tests pass: `cargo test`
+2. Code is properly formatted: `cargo fmt`
+3. No linting issues: `cargo clippy`
+4. New functionality includes appropriate tests and documentation
+5. Error handling follows the project's structured error format
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+
+## Acknowledgments
+
+This library was extracted from the [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source event and RSVP management and discovery application.

crates/atproto-oauth-axum/src/bin/atproto-oauth-login.rs

···
+use anyhow::Result;
+use async_trait::async_trait;
+use atproto_identity::{
+    config::{default_env, optional_env, require_env, version, CertificateBundles, DnsNameservers},
+    key::{generate_key, identify_key, to_public, KeyData, KeyProvider, KeyType},
+    plc,
+    resolve::{create_resolver, resolve_subject},
+    storage::DidDocumentStorage,
+    storage_lru::LruDidDocumentStorage,
+    web,
+};
+use atproto_oauth::{
+    pkce,
+    resources::pds_resources,
+    storage::OAuthRequestStorage,
+    storage_lru::LruOAuthRequestStorage,
+    workflow::{oauth_init, OAuthClient, OAuthRequest, OAuthRequestState},
+};
+use atproto_oauth_axum::errors::OAuthLoginError;
+use atproto_oauth_axum::{handle_complete::handle_oauth_callback, handle_jwks::handle_oauth_jwks};
+use atproto_oauth_axum::{handler_metadata::handle_oauth_metadata, state::OAuthClientConfig};
+use axum::{extract::FromRef, routing::get, Router};
+use chrono::{Duration, Utc};
+use hickory_resolver::TokioResolver;
+use rand::distributions::{Alphanumeric, DistString};
+use std::{collections::HashMap, env, num::NonZeroUsize, ops::Deref, sync::Arc};
+
+#[derive(Clone)]
+pub struct SimpleKeyProvider {
+    keys: HashMap<String, KeyData>,
+}
+
+impl Default for SimpleKeyProvider {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl SimpleKeyProvider {
+    pub fn new() -> Self {
+        Self {
+            keys: HashMap::new(),
+        }
+    }
+}
+
+#[async_trait]
+impl KeyProvider for SimpleKeyProvider {
+    async fn get_private_key_by_id(&self, key_id: &str) -> anyhow::Result<Option<KeyData>> {
+        Ok(self.keys.get(key_id).cloned())
+    }
+}
+
+pub struct InnerWebContext {
+    pub http_client: reqwest::Client,
+    pub dns_resolver: TokioResolver,
+    pub oauth_client_config: OAuthClientConfig,
+    pub oauth_storage: Arc<dyn OAuthRequestStorage + Send + Sync>,
+    pub document_storage: Arc<dyn DidDocumentStorage + Send + Sync>,
+    pub key_provider: Arc<dyn KeyProvider + Send + Sync>,
+}
+
+#[derive(Clone, FromRef)]
+pub struct WebContext(pub Arc<InnerWebContext>);
+
+impl Deref for WebContext {
+    type Target = InnerWebContext;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl FromRef<WebContext> for OAuthClientConfig {
+    fn from_ref(context: &WebContext) -> Self {
+        context.0.oauth_client_config.clone()
+    }
+}
+
+impl FromRef<WebContext> for reqwest::Client {
+    fn from_ref(context: &WebContext) -> Self {
+        context.0.http_client.clone()
+    }
+}
+
+impl FromRef<WebContext> for Arc<dyn OAuthRequestStorage + Send + Sync> {
+    fn from_ref(context: &WebContext) -> Self {
+        context.0.oauth_storage.clone()
+    }
+}
+
+impl FromRef<WebContext> for Arc<dyn DidDocumentStorage + Send + Sync> {
+    fn from_ref(context: &WebContext) -> Self {
+        context.0.document_storage.clone()
+    }
+}
+
+impl FromRef<WebContext> for Arc<dyn KeyProvider + Send + Sync> {
+    fn from_ref(context: &WebContext) -> Self {
+        context.0.key_provider.clone()
+    }
+}
+
+fn print_usage() {
+    println!("AT Protocol OAuth Login Tool");
+    println!();
+    println!("Usage:");
+    println!("  atproto-oauth-login login <private_signing_key> <subject>");
+    println!("  atproto-oauth-login refresh <private_signing_key> <subject> <private_dpop_key> <refresh_token>");
+    println!();
+    println!("Commands:");
+    println!("  login    Start OAuth login flow");
+    println!("  refresh  Refresh OAuth tokens");
+    println!();
+    println!("Arguments:");
+    println!("  private_signing_key   Private key for signing");
+    println!("  subject              OAuth subject identifier");
+    println!("  private_dpop_key     Private DPoP key (refresh only)");
+    println!("  refresh_token        Refresh token (refresh only)");
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Parse command line arguments
+    let args: Vec<String> = env::args().skip(1).collect();
+
+    if args.is_empty() || args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        print_usage();
+        return Ok(());
+    }
+
+    let (subcommand, private_signing_key, subject, private_dpop_key, refresh_token) =
+        match args.len() {
+            3 if args[0] == "login" => ("login", args[1].clone(), args[2].clone(), None, None),
+            5 if args[0] == "refresh" => (
+                "refresh",
+                args[1].clone(),
+                args[2].clone(),
+                Some(args[3].clone()),
+                Some(args[4].clone()),
+            ),
+            _ => {
+                eprintln!("Error: Invalid arguments");
+                print_usage();
+                std::process::exit(1);
+            }
+        };
+
+    // Log the selected command
+    println!(
+        "Starting OAuth {} flow for subject: {}",
+        subcommand, subject
+    );
+    if let Some(ref dpop_key) = private_dpop_key {
+        println!("Using DPoP key: {}", dpop_key);
+    }
+    if let Some(ref token) = refresh_token {
+        println!(
+            "Using refresh token: {}...",
+            &token[..std::cmp::min(8, token.len())]
+        );
+    }
+
+    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-identity-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()?;
+
+    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()?;
+
+    let dns_resolver = create_resolver(dns_nameservers.as_ref());
+
+    let external_base = require_env("EXTERNAL_BASE")?;
+
+    // Load signing keys for JWK generation
+    let mut signing_keys = Vec::new();
+    if subcommand == "login" {
+        // For login command, include the provided signing key in the JWKS
+        match identify_key(&private_signing_key) {
+            Ok(key_data) => {
+                signing_keys.push(key_data);
+            }
+            Err(e) => tracing::warn!(error = ?e, "Failed to parse signing key for JWKS"),
+        }
+    }
+
+    let oauth_client_config = OAuthClientConfig {
+        client_uri: format!("https://{}", &external_base),
+        jwks_uri: format!("https://{}/.well-known/jwks.json", &external_base),
+        redirect_uris: format!("https://{}/oauth/callback", &external_base),
+        client_id: format!("https://{}/oauth/client-metadata.json", &external_base),
+        signing_keys: signing_keys
+            .iter()
+            .filter_map(|value| to_public(value).ok())
+            .collect(),
+    };
+
+    let mut signing_key_storage = HashMap::new();
+
+    for signing_key in &signing_keys {
+        let public_signing_key_data = to_public(signing_key)?;
+
+        let public_signing_key = public_signing_key_data.to_string();
+        signing_key_storage.insert(public_signing_key, signing_key.clone());
+    }
+
+    let web_context = WebContext(Arc::new(InnerWebContext {
+        http_client: http_client.clone(),
+        dns_resolver: dns_resolver.clone(),
+        oauth_client_config: oauth_client_config.clone(),
+        oauth_storage: Arc::new(LruOAuthRequestStorage::new(NonZeroUsize::new(256).unwrap())),
+        document_storage: Arc::new(LruDidDocumentStorage::new(NonZeroUsize::new(255).unwrap())),
+        key_provider: Arc::new(SimpleKeyProvider {
+            keys: signing_key_storage,
+        }),
+    }));
+
+    let router = Router::new()
+        .route("/oauth/client-metadata.json", get(handle_oauth_metadata))
+        .route("/.well-known/jwks.json", get(handle_oauth_jwks))
+        .route("/oauth/callback", get(handle_oauth_callback))
+        .with_state(web_context.clone());
+
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await?;
+
+    // Start the web server in the background
+    let server_handle = tokio::spawn(async move {
+        if let Err(e) = axum::serve(listener, router).await {
+            eprintln!("Server error: {}", e);
+        }
+    });
+
+    println!("OAuth server started on http://0.0.0.0:8080");
+
+    // Handle the login command
+    if subcommand == "login" {
+        handle_login_command(
+            &http_client,
+            &dns_resolver,
+            &private_signing_key,
+            &subject,
+            &external_base,
+            &web_context.document_storage,
+            &web_context.oauth_storage,
+        )
+        .await?;
+
+        println!("\nServer is running to handle the OAuth callback...");
+        println!("Press Ctrl+C to stop the server when done.");
+    }
+
+    // Keep the server running
+    server_handle.await.unwrap();
+
+    Ok(())
+}
+
+async fn handle_login_command(
+    http_client: &reqwest::Client,
+    dns_resolver: &TokioResolver,
+    private_signing_key: &str,
+    subject: &str,
+    external_base: &str,
+    did_document_storage: &Arc<dyn DidDocumentStorage + Send + Sync>,
+    oauth_request_storage: &Arc<dyn OAuthRequestStorage + Send + Sync>,
+) -> Result<()> {
+    println!("Resolving subject: {}", subject);
+
+    // Resolve the subject to a DID
+    let did = resolve_subject(http_client, dns_resolver, subject)
+        .await
+        .map_err(|e| OAuthLoginError::SubjectResolutionFailed { error: e.into() })?;
+
+    println!("Resolved DID: {}", did);
+
+    // Get the DID document based on DID type
+    let document = if did.starts_with("did:plc:") {
+        plc::query(http_client, "plc.directory", &did)
+            .await
+            .map_err(|e| OAuthLoginError::PLCQueryFailed { error: e.into() })?
+    } else if did.starts_with("did:web:") {
+        web::query(http_client, &did)
+            .await
+            .map_err(|e| OAuthLoginError::WebDIDQueryFailed { error: e.into() })?
+    } else {
+        return Err(OAuthLoginError::UnsupportedDIDMethod { did }.into());
+    };
+
+    did_document_storage
+        .store_document(document.clone())
+        .await?;
+
+    println!("Retrieved DID document for: {}", document.id);
+
+    // Get PDS endpoint from the DID document
+    let pds_endpoints = document.pds_endpoints();
+    let pds_endpoint = pds_endpoints
+        .first()
+        .ok_or(OAuthLoginError::NoPDSEndpointFound)?;
+
+    println!("Using PDS endpoint: {}", pds_endpoint);
+
+    // Get authorization server configuration
+    let (_, authorization_server) = pds_resources(http_client, pds_endpoint)
+        .await
+        .map_err(|e| OAuthLoginError::PDSResourcesFailed { error: e.into() })?;
+
+    println!("Authorization server: {}", authorization_server.issuer);
+
+    // Generate OAuth security parameters
+    let (pkce_verifier, code_challenge) = pkce::generate();
+    let state = Alphanumeric.sample_string(&mut rand::thread_rng(), 32);
+    let nonce = Alphanumeric.sample_string(&mut rand::thread_rng(), 32);
+
+    // Generate DPoP key
+    let dpop_key = generate_key(KeyType::P256Private)
+        .map_err(|e| OAuthLoginError::DPoPKeyGenerationFailed { error: e.into() })?;
+
+    // Parse the private signing key
+    let signing_key = identify_key(private_signing_key)
+        .map_err(|e| OAuthLoginError::InvalidPrivateSigningKey { error: e.into() })?;
+
+    // Create OAuth client configuration
+    let oauth_client = OAuthClient {
+        redirect_uri: format!("https://{}/oauth/callback", external_base),
+        client_id: format!("https://{}/oauth/client-metadata.json", external_base),
+        private_signing_key_data: signing_key.clone(),
+    };
+
+    // Create OAuth request state
+    let oauth_request_state = OAuthRequestState {
+        state: state.clone(),
+        nonce: nonce.clone(),
+        code_challenge,
+    };
+
+    println!("Initiating OAuth flow...");
+
+    // Initiate OAuth flow
+    let par_response = oauth_init(
+        http_client,
+        &oauth_client,
+        &dpop_key,
+        subject,
+        &authorization_server,
+        &oauth_request_state,
+    )
+    .await
+    .map_err(|e| OAuthLoginError::OAuthInitFailed { error: e.into() })?;
+
+    // Store OAuth request state for callback handling
+    let public_signing_key = to_public(&signing_key)
+        .map_err(|e| OAuthLoginError::PublicKeyDerivationFailed { error: e.into() })?;
+
+    let now = Utc::now();
+    let oauth_request = OAuthRequest {
+        oauth_state: state.clone(),
+        issuer: authorization_server.issuer.clone(),
+        did: did.clone(),
+        nonce: nonce.clone(),
+        pkce_verifier,
+        signing_public_key: public_signing_key.to_string(),
+        dpop_private_key: dpop_key.to_string(),
+        created_at: now,
+        expires_at: now + Duration::hours(1),
+    };
+
+    oauth_request_storage
+        .insert_oauth_request(oauth_request)
+        .await
+        .map_err(|e| OAuthLoginError::OAuthRequestStorageFailed { error: e })?;
+
+    // Compose the authorization URL
+    let auth_url = format!(
+        "{}?client_id={}&request_uri={}",
+        authorization_server.authorization_endpoint,
+        oauth_client.client_id,
+        par_response.request_uri
+    );
+
+    println!("\n🔐 OAuth Authorization URL:");
+    println!("{}\n", auth_url);
+    println!("Please visit this URL in your browser to complete the OAuth flow.");
+    println!(
+        "The callback will be handled at: https://{}/oauth/callback",
+        external_base
+    );
+    println!("OAuth state: {}", state);
+
+    Ok(())
+}

crates/atproto-oauth-axum/src/errors.rs

···
+//! # Structured Error Types for OAuth Axum Handlers
+//!
+//! Comprehensive error handling for AT Protocol OAuth Axum web handlers using structured error types
+//! with the `thiserror` library. All errors follow the project convention of prefixed error codes
+//! with descriptive messages.
+//!
+//! ## Error Categories
+//!
+//! - **`OAuthCallbackError`** (callback-1 to callback-7): OAuth callback handler errors
+//! - **`OAuthLoginError`** (login-1 to login-11): OAuth login CLI tool errors
+//!
+//! ## Error Format
+//!
+//! All errors use the standardized format: `error-atproto-oauth-axum-{domain}-{number} {message}: {details}`
+
+use thiserror::Error;
+
+/// Error types that can occur during OAuth callback handling.
+///
+/// These errors represent failures in the OAuth authorization callback flow
+/// including request validation and token exchange operations.
+#[derive(Debug, Error)]
+pub enum OAuthCallbackError {
+    /// Occurs when no OAuth request is found for the provided state parameter
+    #[error("error-atproto-oauth-axum-callback-1 No OAuth request found for state")]
+    NoOAuthRequestFound,
+
+    /// Occurs when the issuer in the callback doesn't match the stored OAuth request
+    #[error(
+        "error-atproto-oauth-axum-callback-2 Invalid issuer: expected {expected}, got {actual}"
+    )]
+    InvalidIssuer {
+        /// The expected issuer from the stored OAuth request
+        expected: String,
+        /// The actual issuer from the callback
+        actual: String,
+    },
+
+    /// Occurs when no DID document is found for the OAuth request
+    #[error("error-atproto-oauth-axum-callback-3 No DID document found for OAuth request")]
+    NoDIDDocumentFound,
+
+    /// Occurs when no signing key is found for the OAuth request
+    #[error("error-atproto-oauth-axum-callback-4 No signing key found for OAuth request")]
+    NoSigningKeyFound,
+
+    /// Occurs when an underlying operation fails with an anyhow error
+    #[error("error-atproto-oauth-axum-callback-5 Operation failed: {error}")]
+    OperationFailed {
+        /// The underlying anyhow error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when key operations fail
+    #[error("error-atproto-oauth-axum-callback-6 Key operation failed: {error}")]
+    KeyOperationFailed {
+        /// The underlying key error
+        error: atproto_identity::errors::KeyError,
+    },
+
+    /// Occurs when OAuth client operations fail
+    #[error("error-atproto-oauth-axum-callback-7 OAuth client operation failed: {error}")]
+    OAuthClientOperationFailed {
+        /// The underlying OAuth client error
+        error: atproto_oauth::errors::OAuthClientError,
+    },
+}
+
+impl From<anyhow::Error> for OAuthCallbackError {
+    fn from(error: anyhow::Error) -> Self {
+        OAuthCallbackError::OperationFailed { error }
+    }
+}
+
+impl From<atproto_identity::errors::KeyError> for OAuthCallbackError {
+    fn from(error: atproto_identity::errors::KeyError) -> Self {
+        OAuthCallbackError::KeyOperationFailed { error }
+    }
+}
+
+impl From<atproto_oauth::errors::OAuthClientError> for OAuthCallbackError {
+    fn from(error: atproto_oauth::errors::OAuthClientError) -> Self {
+        OAuthCallbackError::OAuthClientOperationFailed { error }
+    }
+}
+
+/// Error types that can occur during OAuth login CLI operations.
+///
+/// These errors represent failures in the OAuth login command-line tool
+/// including subject resolution, DID operations, and OAuth flow initiation.
+#[derive(Debug, Error)]
+pub enum OAuthLoginError {
+    /// Occurs when subject resolution fails
+    #[error("error-atproto-oauth-axum-login-1 Failed to resolve subject: {error}")]
+    SubjectResolutionFailed {
+        /// The underlying resolution error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when PLC directory query fails
+    #[error("error-atproto-oauth-axum-login-2 Failed to query PLC directory: {error}")]
+    PLCQueryFailed {
+        /// The underlying PLC error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when web DID query fails
+    #[error("error-atproto-oauth-axum-login-3 Failed to query web DID: {error}")]
+    WebDIDQueryFailed {
+        /// The underlying web DID error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when an unsupported DID method is encountered
+    #[error("error-atproto-oauth-axum-login-4 Unsupported DID method: {did}")]
+    UnsupportedDIDMethod {
+        /// The unsupported DID identifier
+        did: String,
+    },
+
+    /// Occurs when no PDS endpoint is found in the DID document
+    #[error("error-atproto-oauth-axum-login-5 No PDS endpoint found in DID document")]
+    NoPDSEndpointFound,
+
+    /// Occurs when PDS resources retrieval fails
+    #[error("error-atproto-oauth-axum-login-6 Failed to get PDS resources: {error}")]
+    PDSResourcesFailed {
+        /// The underlying PDS resources error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when DPoP key generation fails
+    #[error("error-atproto-oauth-axum-login-7 Failed to generate DPoP key: {error}")]
+    DPoPKeyGenerationFailed {
+        /// The underlying key generation error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when private signing key parsing fails
+    #[error("error-atproto-oauth-axum-login-8 Invalid private signing key: {error}")]
+    InvalidPrivateSigningKey {
+        /// The underlying key parsing error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when OAuth initialization fails
+    #[error("error-atproto-oauth-axum-login-9 OAuth init failed: {error}")]
+    OAuthInitFailed {
+        /// The underlying OAuth initialization error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when public key derivation fails
+    #[error("error-atproto-oauth-axum-login-10 Failed to derive public key: {error}")]
+    PublicKeyDerivationFailed {
+        /// The underlying key derivation error
+        error: anyhow::Error,
+    },
+
+    /// Occurs when OAuth request storage fails
+    #[error("error-atproto-oauth-axum-login-11 Failed to store OAuth request: {error}")]
+    OAuthRequestStorageFailed {
+        /// The underlying storage error
+        error: anyhow::Error,
+    },
+}

crates/atproto-oauth-axum/src/handle_complete.rs

···
+//! OAuth authorization callback handler.
+//!
+//! Handles the OAuth authorization callback by exchanging authorization codes for tokens,
+//! validating OAuth state, and completing the OAuth flow with proper error handling.
+
+use anyhow::Result;
+use atproto_identity::{
+    axum::state::{DidDocumentStorageExtractor, KeyProviderExtractor},
+    key::identify_key,
+};
+use atproto_oauth::{
+    axum::state::OAuthRequestStorageExtractor,
+    workflow::{oauth_complete, OAuthClient},
+};
+use axum::{
+    response::{IntoResponse, Response},
+    Form,
+};
+use http::StatusCode;
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    errors::OAuthCallbackError,
+    state::{HttpClient, OAuthClientConfig},
+};
+
+/// OAuth authorization callback form data.
+///
+/// Contains the parameters sent by the authorization server during the OAuth callback.
+#[derive(Deserialize, Serialize)]
+pub struct OAuthCallbackForm {
+    /// OAuth state parameter for CSRF protection
+    pub state: String,
+    /// Authorization server issuer identifier
+    pub iss: String,
+    /// Authorization code from the authorization server
+    pub code: String,
+}
+
+impl IntoResponse for OAuthCallbackError {
+    fn into_response(self) -> Response {
+        tracing::error!(error = ?self, "OAuth callback error");
+        (
+            StatusCode::INTERNAL_SERVER_ERROR,
+            format!("OAuth callback failed: {}", self),
+        )
+            .into_response()
+    }
+}
+
+/// Handles OAuth authorization callback requests.
+///
+/// Processes the authorization callback by validating the OAuth state, exchanging
+/// the authorization code for tokens, and returning the complete OAuth response.
+pub async fn handle_oauth_callback(
+    oauth_client_config: OAuthClientConfig,
+    client: HttpClient,
+    oauth_request_storage: OAuthRequestStorageExtractor,
+    did_document_storage: DidDocumentStorageExtractor,
+    key_provider: KeyProviderExtractor,
+    Form(callback_form): Form<OAuthCallbackForm>,
+) -> Result<impl IntoResponse, OAuthCallbackError> {
+    let oauth_request = oauth_request_storage
+        .0
+        .get_oauth_request_by_state(&callback_form.state)
+        .await?;
+
+    let oauth_request = oauth_request.ok_or(OAuthCallbackError::NoOAuthRequestFound)?;
+
+    if oauth_request.issuer != callback_form.iss {
+        return Err(OAuthCallbackError::InvalidIssuer {
+            expected: oauth_request.issuer.clone(),
+            actual: callback_form.iss.clone(),
+        });
+    }
+
+    let document = did_document_storage
+        .0
+        .get_document_by_did(&oauth_request.did)
+        .await?;
+
+    let document = document.ok_or(OAuthCallbackError::NoDIDDocumentFound)?;
+
+    let private_signing_key_data = key_provider
+        .0
+        .get_private_key_by_id(&oauth_request.signing_public_key)
+        .await?;
+
+    let private_signing_key_data =
+        private_signing_key_data.ok_or(OAuthCallbackError::NoSigningKeyFound)?;
+
+    let private_dpop_key_data = identify_key(&oauth_request.dpop_private_key)?;
+
+    let oauth_client = OAuthClient {
+        redirect_uri: oauth_client_config.redirect_uris,
+        client_id: oauth_client_config.client_id,
+        private_signing_key_data,
+    };
+
+    let token_response = oauth_complete(
+        &client,
+        &oauth_client,
+        &private_dpop_key_data,
+        &callback_form.code,
+        &oauth_request,
+        &document,
+    )
+    .await?;
+
+    // Format the response with OAuth tokens and DPoP key information
+    let response_body = format!(
+        "OAuth Callback Completed Successfully\n\
+            =====================================\n\
+            DID: {}\n\
+            Issuer: {}\n\
+            Access Token: {}\n\
+            Refresh Token: {}\n\
+            Token Type: {}\n\
+            Expires In: {} seconds\n\
+            Scope: {}\n\
+            Subject: {}\n\
+            Private DPoP Key: {}\n",
+        oauth_request.did,
+        oauth_request.issuer,
+        token_response.access_token,
+        token_response.refresh_token,
+        token_response.token_type,
+        token_response.expires_in,
+        token_response.scope,
+        token_response.sub,
+        private_dpop_key_data
+    );
+
+    Ok((
+        StatusCode::OK,
+        [("Content-Type", "text/plain")],
+        response_body,
+    )
+        .into_response())
+}

crates/atproto-oauth-axum/src/handle_init.rs

···
+//! OAuth authorization initiation handler (placeholder).
+//!
+//! Reserved module for OAuth authorization initiation endpoints.
+//! Currently unused but available for future implementation.

crates/atproto-oauth-axum/src/handle_jwks.rs

···
+//! OAuth JSON Web Key Set (JWKS) endpoint handler.
+//!
+//! Serves the JWKS endpoint for OAuth client public keys, enabling authorization servers
+//! to verify JWT signatures from the OAuth client during authentication flows.
+
+use atproto_oauth::jwk::{generate, WrappedJsonWebKey};
+use axum::{response::IntoResponse, Json};
+use serde::Serialize;
+
+use crate::state::OAuthClientConfig;
+
+/// JSON Web Key Set response structure.
+///
+/// Contains a collection of public keys for JWT signature verification.
+#[derive(Serialize)]
+pub struct WrappedJsonWebKeySet {
+    /// Array of JSON Web Keys
+    pub keys: Vec<WrappedJsonWebKey>,
+}
+
+/// Handles requests for the OAuth JWKS (JSON Web Key Set) endpoint.
+///
+/// Returns the public keys used by this OAuth client for JWT signature verification.
+pub async fn handle_oauth_jwks(oauth_client_config: OAuthClientConfig) -> impl IntoResponse {
+    let mut jwks = Vec::new();
+    for key_data in &oauth_client_config.signing_keys {
+        if let Ok(jwk) = generate(key_data) {
+            jwks.push(jwk);
+        }
+    }
+    Json(WrappedJsonWebKeySet { keys: jwks })
+}

crates/atproto-oauth-axum/src/handler_metadata.rs

···
+//! OAuth client metadata endpoint handler.
+//!
+//! Serves OAuth 2.0 client metadata according to RFC 7591, providing client configuration
+//! information required for dynamic client registration and authorization server discovery.
+
+use axum::{response::IntoResponse, Json};
+use serde::Serialize;
+
+use crate::state::OAuthClientConfig;
+
+#[derive(Serialize)]
+struct AuthMetadata {
+    client_id: String,
+    dpop_bound_access_tokens: bool,
+    application_type: &'static str,
+    redirect_uris: Vec<String>,
+    client_uri: String,
+    grant_types: Vec<&'static str>,
+    response_types: Vec<&'static str>,
+    scope: &'static str,
+    client_name: &'static str,
+    token_endpoint_auth_method: &'static str,
+    jwks_uri: String,
+    subject_type: &'static str,
+    token_endpoint_auth_signing_alg: &'static str,
+}
+
+/// Handles requests for OAuth client metadata.
+///
+/// Returns RFC 7591 compliant client metadata for dynamic client registration.
+pub async fn handle_oauth_metadata(oauth_client_config: OAuthClientConfig) -> impl IntoResponse {
+    let resp = AuthMetadata {
+        application_type: "web",
+        client_id: oauth_client_config.client_id.clone(),
+        client_name: "Smoke Signal",
+        client_uri: oauth_client_config.client_uri.clone(),
+        dpop_bound_access_tokens: true,
+        grant_types: vec!["authorization_code", "refresh_token"],
+        jwks_uri: oauth_client_config.jwks_uri.clone(),
+        redirect_uris: vec![oauth_client_config.redirect_uris.clone()],
+        response_types: vec!["code"],
+        scope: "atproto transition:generic",
+        token_endpoint_auth_method: "private_key_jwt",
+        token_endpoint_auth_signing_alg: "ES256",
+        subject_type: "public",
+    };
+    Json(resp)
+}

crates/atproto-oauth-axum/src/lib.rs

···
+//! AT Protocol OAuth Axum web handlers.
+//!
+//! Complete Axum web handlers for implementing AT Protocol OAuth 2.0 authorization server
+//! endpoints including client metadata, JWKS, and authorization callback handling.
+
+#![warn(missing_docs)]
+
+pub mod errors;
+pub mod handle_complete;
+pub mod handle_init;
+pub mod handle_jwks;
+pub mod handler_metadata;
+pub mod state;

crates/atproto-oauth-axum/src/state.rs

···
+//! Axum state management for OAuth client configuration.
+//!
+//! Provides request extractors and HTTP client wrappers for injecting OAuth client
+//! configuration and HTTP clients into Axum request handlers.
+
+use atproto_identity::key::KeyData;
+use axum::extract::{FromRef, FromRequestParts};
+use http::request::Parts;
+use std::convert::Infallible;
+
+/// OAuth client configuration for Axum handlers.
+///
+/// Contains the essential configuration needed for OAuth client operations.
+#[derive(Clone)]
+pub struct OAuthClientConfig {
+    /// OAuth client URI
+    pub client_uri: String,
+    /// OAuth client identifier
+    pub client_id: String,
+    /// Allowed OAuth redirect URIs
+    pub redirect_uris: String,
+    /// JSON Web Key Set URI for public keys
+    pub jwks_uri: String,
+    /// Signing keys for JWT operations
+    pub signing_keys: Vec<KeyData>,
+}
+
+impl<S> FromRequestParts<S> for OAuthClientConfig
+where
+    OAuthClientConfig: FromRef<S>,
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let oauth_client_config = OAuthClientConfig::from_ref(state);
+        Ok(oauth_client_config)
+    }
+}
+
+/// HTTP client wrapper for dependency injection.
+///
+/// Wraps a reqwest::Client for use in Axum extractors.
+#[derive(Clone)]
+pub struct HttpClient(pub reqwest::Client);
+
+impl std::ops::Deref for HttpClient {
+    type Target = reqwest::Client;
+
+    fn deref(&self) -> &Self::Target {
+        &self.0
+    }
+}
+
+impl<S> FromRequestParts<S> for HttpClient
+where
+    reqwest::Client: FromRef<S>,
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let client = reqwest::Client::from_ref(state);
+        Ok(HttpClient(client))
+    }
+}

crates/atproto-oauth/Cargo.toml

···
 tracing.workspace = true
 ulid.workspace = true
 
+axum = { version = "0.8", optional = true }
+http = { version = "1.0.0", optional = true }
+
 [features]
+default = ["lru", "axum"]
 lru = ["dep:lru"]
+axum = ["dep:axum", "dep:http"]
 
 [lints]
 workspace = true

crates/atproto-oauth/src/axum/mod.rs

···
+//! Axum web framework integration for AT Protocol OAuth operations.
+//!
+//! Provides request extractors and state management for integrating AT Protocol
+//! OAuth workflows with Axum web applications.
+
+pub mod state;

crates/atproto-oauth/src/axum/state.rs

···
+//! Axum request extractors for AT Protocol OAuth services.
+//!
+//! Provides extractors that automatically inject OAuth request storage
+//! into Axum request handlers from application state.
+
+use axum::extract::{FromRef, FromRequestParts};
+use http::request::Parts;
+use std::{convert::Infallible, sync::Arc};
+
+use crate::storage::OAuthRequestStorage;
+
+/// Axum request extractor for OAuth request storage.
+///
+/// Automatically extracts an OAuth request storage implementation from the application state.
+#[derive(Clone)]
+pub struct OAuthRequestStorageExtractor(pub Arc<dyn OAuthRequestStorage + Send + Sync>);
+
+impl<S> FromRequestParts<S> for OAuthRequestStorageExtractor
+where
+    Arc<dyn OAuthRequestStorage + Send + Sync>: FromRef<S>,
+    S: Send + Sync,
+{
+    type Rejection = Infallible;
+
+    async fn from_request_parts(_parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+        let storage = Arc::<dyn OAuthRequestStorage + Send + Sync>::from_ref(state);
+        Ok(OAuthRequestStorageExtractor(storage))
+    }
+}

crates/atproto-oauth/src/lib.rs

···
 pub mod storage_lru;
 /// OAuth workflow implementation for AT Protocol authorization flows.
 pub mod workflow;
+
+#[cfg(feature = "axum")]
+pub mod axum;

crates/atproto-record/README.md

···
 
 ## Command Line Tools
 
-The crate includes command-line tools for AT Protocol record signature operations:
+The crate includes two command-line tools for AT Protocol record signature operations:
 
 ### `atproto-record-sign`
-Creates cryptographic signatures for AT Protocol records. Reads a JSON record from a file or stdin, applies a cryptographic signature using a DID key, and outputs the signed record with embedded signature metadata. Supports flexible argument ordering and uses IPLD DAG-CBOR serialization for consistent signature generation.
+
+Creates cryptographic signatures for AT Protocol records with proper `$sig` object handling and embedded signature metadata. This tool reads JSON records, applies cryptographic signatures using DID keys, and outputs signed records ready for AT Protocol repository storage.
+
+**Features:**
+- **Flexible Input**: Reads records from files or stdin
+- **DID Key Support**: Works with both P-256 and K-256 cryptographic keys
+- **Signature Object Creation**: Automatically creates required signature metadata with issuer and timestamp
+- **Repository Context**: Includes repository and collection context in signatures
+- **IPLD Serialization**: Uses DAG-CBOR serialization for consistent signature generation
+- **Multibase Encoding**: Outputs signatures in multibase format for AT Protocol compatibility
 
 ```bash
-# Sign a record from a file
+# Sign a record from a file with all required parameters
 cargo run --bin atproto-record-sign did:key:zQ3sh... did:plc:issuer123 record.json repository=did:plc:user123 collection=app.bsky.feed.post
 
 # Sign a record from stdin
-echo '{"$type":"app.bsky.feed.post","text":"Hello"}' | cargo run --bin atproto-record-sign did:key:zQ3sh... did:plc:issuer123 -- repository=did:plc:user123 collection=app.bsky.feed.post
+echo '{"$type":"app.bsky.feed.post","text":"Hello AT Protocol!"}' | \
+  cargo run --bin atproto-record-sign did:key:zQ3sh... did:plc:issuer123 -- \
+  repository=did:plc:user123 collection=app.bsky.feed.post
+
+# Example output: JSON record with embedded signatures array
 ```
 
+**Arguments:**
+- `<signing_key>` - DID key string for signing (did:key:...)
+- `<issuer_did>` - DID of the signing entity
+- `<record_file>` - JSON file containing the record (optional, uses stdin if omitted)
+- `repository=<did>` - Repository DID where record will be stored
+- `collection=<nsid>` - Collection NSID (e.g., app.bsky.feed.post)
+
 ### `atproto-record-verify`
-Verifies cryptographic signatures of AT Protocol records. Reads a signed JSON record from a file or stdin, validates the embedded cryptographic signatures using a public key, and reports whether the signature verification succeeds or fails. Uses IPLD DAG-CBOR deserialization for verification.
+
+Verifies cryptographic signatures of AT Protocol records using embedded signature metadata. This tool validates that signed records contain authentic signatures from specified issuers, ensuring record integrity and authenticity.
+
+**Features:**
+- **Signature Validation**: Verifies embedded signatures against public keys
+- **Issuer Authentication**: Confirms signatures are from specified DID issuers
+- **Context Verification**: Validates repository and collection context in signatures
+- **Multi-Signature Support**: Handles records with multiple signatures
+- **IPLD Deserialization**: Uses DAG-CBOR for signature verification consistency
+- **Detailed Error Reporting**: Provides specific feedback on verification failures
 
 ```bash
 # Verify a signed record from a file
-cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... signed_record.json repository=did:plc:user123 collection=app.bsky.feed.post
+cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... signed_record.json \
+  repository=did:plc:user123 collection=app.bsky.feed.post
 
 # Verify a signed record from stdin
-echo '{"signatures":[...],"$type":"app.bsky.feed.post","text":"Hello"}' | cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... -- repository=did:plc:user123 collection=app.bsky.feed.post
+echo '{"signatures":[{"issuer":"did:plc:issuer123","signature":"u..."}],"$type":"app.bsky.feed.post","text":"Hello"}' | \
+  cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... -- \
+  repository=did:plc:user123 collection=app.bsky.feed.post
+
+# Successful verification returns exit code 0
+# Failed verification returns exit code 1 with error details
 ```
+
+**Arguments:**
+- `<issuer_did>` - DID of the expected signature issuer
+- `<public_key>` - DID key string for verification (did:key:...)
+- `<record_file>` - JSON file containing the signed record (optional, uses stdin if omitted)
+- `repository=<did>` - Repository DID context for verification
+- `collection=<nsid>` - Collection NSID context for verification
+
+**Exit Codes:**
+- `0` - Signature verification successful
+- `1` - Signature verification failed or invalid arguments
+- `2` - File I/O or parsing errors
 
 ## Modules
 

crates/atproto-record/src/errors.rs

···
 //!
 //! ## Error Categories
 //!
-//! - **`VerificationError`** (verification-1 to verification-9): Record signature verification and creation errors
+//! - **`VerificationError`** (verification-1 to verification-11): Record signature verification and creation errors
 //! - **`AturiError`** (aturi-1 to aturi-9): AT-URI parsing and validation errors
 //!
 //! ## Error Format
···
     KeyOperationFailed {
         /// The underlying key operation error
         #[from]
+        error: atproto_identity::errors::KeyError,
+    },
+
+    /// Error when signature decoding fails.
+    ///
+    /// This error occurs when the multibase-encoded signature cannot
+    /// be decoded, typically due to invalid encoding format.
+    #[error("error-atproto-record-verification-10 Signature decoding failed: {error}")]
+    SignatureDecodingFailed {
+        /// The underlying multibase decoding error
+        error: multibase::Error,
+    },
+
+    /// Error when cryptographic signature validation fails.
+    ///
+    /// This error occurs when the cryptographic validation of the signature
+    /// fails, indicating either an invalid signature or mismatched key/data.
+    #[error("error-atproto-record-verification-11 Cryptographic validation failed: {error}")]
+    CryptographicValidationFailed {
+        /// The underlying validation error
         error: atproto_identity::errors::KeyError,
     },
 }

crates/atproto-record/src/signature.rs

···
 //! elliptic curve digital signatures. Implements the AT Protocol signature format with proper
 //! `$sig` object handling and IPLD DAG-CBOR serialization for secure record attestation.
 
-use anyhow::anyhow;
 use atproto_identity::key::{sign, validate, KeyData};
 use serde_json::json;
 
···
         let serialized_record = serde_ipld_dagcbor::to_vec(&signed_record)
             .map_err(|error| VerificationError::RecordSerializationFailed { error })?;
 
-        let (_, signature_bytes) = multibase::decode(signature_value).map_err(|e| {
-            VerificationError::SignatureVerificationFailed {
-                error: anyhow!("error decoding signature: {}", e),
-            }
-        })?;
+        let (_, signature_bytes) = multibase::decode(signature_value)
+            .map_err(|error| VerificationError::SignatureDecodingFailed { error })?;
 
-        validate(key_data, &signature_bytes, &serialized_record).map_err(|e| {
-            VerificationError::SignatureVerificationFailed {
-                error: anyhow!("error validating signature: {}", e),
-            }
-        })?;
+        validate(key_data, &signature_bytes, &serialized_record)
+            .map_err(|error| VerificationError::CryptographicValidationFailed { error })?;
 
         return Ok(());
     }