refactor: restructure project into modular workspace architecture │

Split monolithic library into focused Cargo workspace with two specialized crates:
- atproto-identity: DID resolution, handle resolution, and identity management
- atproto-record: Record signature operations and cryptographic validation

CLAUDE.prompts.md

···
+# Useful Prompts
+
+## Find unecessary project dependencies
+
+Analyze all of the project dependencies and identify any that are not necessary or could be reduced. Think very very hard.
+
+## Review and ensure error correctness
+
+Review all of the errors defined in `path/to/errors.rs` 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.
+
+## Add missing documentation
+
+Using `cargo check`, add documentation to things that are missing documentation to satisfy compiler warnings.
+
+Document the `crates/atproto-record/src/bin/atproto-record-verify.rs` source file main method. It should include a high level overview of what the binary does. It should also include example usage. Think very hard.
+
+## Review and ensure README correctness
+
+In the `atproto-record` crate, update project documentation and README files to ensure they are accurate and reflect current source code. Think very very hard.
+
+## Module documentation
+
+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.
+
+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.
+
+## Check and clippy
+
+Using `cargo clippy`, satisfy warnings. Think very hard about how to do this.

Cargo.lock

···
 
 [[package]]
 name = "atproto-identity"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "anyhow",
  "ecdsa",
···
  "multibase",
  "p256",
  "reqwest",
+ "serde",
+ "serde_ipld_dagcbor",
+ "serde_json",
+ "thiserror 2.0.12",
+ "tokio",
+ "tracing",
+]
+
+[[package]]
+name = "atproto-record"
+version = "0.3.0"
+dependencies = [
+ "anyhow",
+ "atproto-identity",
+ "chrono",
+ "ecdsa",
+ "k256",
+ "multibase",
+ "p256",
  "serde",
  "serde_ipld_dagcbor",
  "serde_json",
···
 version = "0.2.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
+[[package]]
+name = "chrono"
+version = "0.4.41"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c469d952047f47f91b68d1cba3f10d63c11d73e4636f24f08daf0278abf01c4d"
+dependencies = [
+ "num-traits",
+]
 
 [[package]]
 name = "cid"
···
 dependencies = [
  "overload",
  "winapi",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
 ]
 
 [[package]]

Cargo.toml

···
-[package]
-name = "atproto-identity"
-version = "0.2.0"
+[workspace]
+members = [
+    "crates/atproto-record",
+    "crates/atproto-identity",
+]
+resolver = "3"
+
+[workspace.package]
 edition = "2021"
 rust-version = "1.83"
+repository = "https://tangled.sh/@smokesignal.events/atproto-identity-rs"
 authors = ["Nick Gerakines <[e-mail]>"]
-description = "An ATProtocol identity library"
-readme = "README.md"
-repository = "https://tangled.sh/@smokesignal.events/atproto-identity-rs"
 license = "MIT"
 keywords = ["atprotocol"]
 categories = ["command-line-utilities", "web-programming"]
-exclude = ["CLAUDE.md"]
 
-[[bin]]
-name = "atproto-identity-resolve"
-test = false
-bench = false
-doc = true
-
-[[bin]]
-name = "atproto-identity-sign"
-test = false
-bench = false
-doc = true
-
-[[bin]]
-name = "atproto-identity-validate"
-test = false
-bench = false
-doc = true
+[workspace.dependencies]
+atproto-identity = { version = "0.3.0", path = "crates/atproto-identity" }
+atproto-record = { version = "0.3.0", path = "crates/atproto-record" }
 
-[dependencies]
 anyhow = "1.0"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
···
 k256 = "0.13.4"
 p256 = "0.13.2"
 serde_ipld_dagcbor = "0.6.3"
+
+[workspace.lints.rust]
+unsafe_code = "forbid"

README.md

···
-# atproto-identity
-
-A Rust library for AT Protocol identity resolution and management.
-
-## Overview
-
-`atproto-identity` provides comprehensive support for resolving and managing identities in the AT Protocol ecosystem. This library handles multiple DID (Decentralized Identifier) methods including `did:plc` and `did:web`, as well as AT Protocol handle resolution via both DNS and HTTP methods.
-
-This project was extracted from the open-sourced [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project and is designed to be a standalone, reusable library for AT Protocol identity operations.
-
-## Features
-
-- **Handle Resolution**: Resolve AT Protocol handles to DIDs using DNS TXT records and HTTP well-known endpoints
-- **DID Document Retrieval**: Fetch and parse DID documents for `did:plc` and `did:web` identifiers
-- **Multiple Resolution Methods**: Supports both DNS and HTTP-based handle resolution with conflict detection
-- **Configurable DNS**: Custom DNS nameserver support with fallback to system defaults
-- **Cryptographic Key Operations**: Support for P-256 and K-256 key identification, signature validation, and signing
-- **Structured Logging**: Built-in tracing support for debugging and monitoring
-- **Type Safety**: Comprehensive error handling with structured error types
-
-## Supported DID Methods
-
-- **did-method-plc**: Public Ledger of Credentials DIDs via PLC directory
-- **did-method-web**: Web-based DIDs following the did:web specification with URL conversion utilities
-- **ATProtocol Handle Resolution**: AT Protocol handles (e.g., `ngerakines.me`) can be resolved to DIDs
-
-## Installation
-
-Add this to your `Cargo.toml`:
-
-```toml
-[dependencies]
-atproto-identity = "0.2.0"
-```
-
-## Usage
-
-### Basic Handle Resolution
-
-```rust
-use atproto_identity::resolve::{resolve_subject, create_resolver};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    let http_client = reqwest::Client::new();
-    let dns_resolver = create_resolver(&[]);
-    
-    let did = resolve_subject(&http_client, &dns_resolver, "ngerakines.me").await?;
-    println!("Resolved DID: {}", did);
-    
-    Ok(())
-}
-```
-
-### DID Document Retrieval
-
-```rust
-use atproto_identity::{plc, web};
-
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
-    let http_client = reqwest::Client::new();
-    
-    // Query PLC DID document
-    let plc_doc = plc::query(&http_client, "plc.directory", "did:plc:example123").await?;
-    
-    // Query Web DID document
-    let web_doc = web::query(&http_client, "did:web:example.com").await?;
-    
-    // Convert Web DID to URL (for custom processing)
-    let did_url = web::did_web_to_url("did:web:example.com")?;
-    println!("DID document URL: {}", did_url);
-    
-    Ok(())
-}
-```
-
-### Web DID URL Conversion
-
-The `web` module provides utilities for converting DID identifiers to their HTTPS document URLs:
-
-```rust
-use atproto_identity::web;
-
-fn main() -> anyhow::Result<()> {
-    // Convert simple hostname DID
-    let url = web::did_web_to_url("did:web:example.com")?;
-    // Returns: "https://example.com/.well-known/did.json"
-    
-    // Convert DID with path components  
-    let url = web::did_web_to_url("did:web:example.com:path:subpath")?;
-    // Returns: "https://example.com/path/subpath/did.json"
-    
-    Ok(())
-}
-```
-
-### Cryptographic Key Operations
-
-The `key` module provides utilities for working with cryptographic keys:
-
-```rust
-use atproto_identity::key::{identify_key, validate, KeyType};
-
-fn main() -> Result<(), Box<dyn std::error::Error>> {
-    // Identify a key from a DID key string
-    let key_data = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
-    
-    match key_data.0 {
-        KeyType::K256Public => println!("K-256 public key"),
-        KeyType::P256Public => println!("P-256 public key"),
-        KeyType::K256Private => println!("K-256 private key"),
-        KeyType::P256Private => println!("P-256 private key"),
-    }
-    
-    // Validate a signature (example with dummy data)
-    let content = b"hello world";
-    let signature = vec![0u8; 64]; // Replace with actual signature
-    validate(&key_data, &signature, content)?;
-    
-    Ok(())
-}
-```
-
-### Configuration
-
-The library supports various configuration options through environment variables:
-
-```bash
-# Custom PLC directory hostname
-export PLC_HOSTNAME=plc.directory
-
-# Custom DNS nameservers (semicolon-separated)
-export DNS_NAMESERVERS=8.8.8.8;1.1.1.1
-
-# Custom CA certificate bundles (semicolon-separated paths)
-export CERTIFICATE_BUNDLES=/path/to/cert1.pem;/path/to/cert2.pem
-
-# Custom User-Agent string
-export USER_AGENT="my-app/1.0"
-```
-
-## Command Line Tool
-
-The library includes a command-line tool for testing and resolution:
-
-```bash
-# Install the binary
-cargo install --path .
-
-# Resolve a handle to DID
-atproto-identity-resolve ngerakines.me
-
-# Get full DID document
-atproto-identity-resolve --did-document ngerakines.me
-```
-
-## Architecture
-
-The library is organized into several modules:
-
-- **resolve**: Core resolution logic for handles and DIDs
-- **plc**: PLC directory client for `did:plc` resolution
-- **web**: Web DID client for `did:web` resolution and URL conversion
-- **model**: Data structures for DID documents and AT Protocol entities
-- **validation**: Input validation for handles and DIDs
-- **config**: Configuration management and environment variable handling
-- **errors**: Structured error types following project conventions
-- **key**: Cryptographic key operations including signature validation and key identification for P-256 and K-256 curves
-
-## Error Handling
-
-All errors follow a structured format:
-
-```
-error-atproto-identity-<domain>-<number> <message>: <details>
-```
-
-Examples:
-- `error-atproto-identity-resolve-1 Multiple DIDs resolved for method`
-- `error-atproto-identity-plc-1 HTTP request failed: https://plc.directory/did:plc:example Not Found`
-- `error-did-web-1 Invalid DID format: missing 'did:web:' prefix`
-
-## Contributing
-
-Contributions are welcome! Please ensure that:
-
-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
-
-## 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-identity/Cargo.toml

···
+[package]
+name = "atproto-identity"
+version = "0.3.0"
+description = "An ATProtocol identity library"
+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
+
+[[bin]]
+name = "atproto-identity-resolve"
+test = false
+bench = false
+doc = true
+
+[[bin]]
+name = "atproto-identity-sign"
+test = false
+bench = false
+doc = true
+
+[[bin]]
+name = "atproto-identity-validate"
+test = false
+bench = false
+doc = true
+
+[dependencies]
+anyhow.workspace = true
+ecdsa.workspace = true
+hickory-resolver.workspace = true
+k256.workspace = true
+multibase.workspace = true
+p256.workspace = true
+reqwest.workspace = true
+serde_ipld_dagcbor.workspace = true
+serde_json.workspace = true
+serde.workspace = true
+thiserror.workspace = true
+tokio.workspace = true
+tracing.workspace = true
+
+[lints]
+workspace = true

crates/atproto-identity/README.md

···
+# atproto-identity
+
+A Rust library for AT Protocol identity resolution and management.
+
+## Overview
+
+`atproto-identity` provides comprehensive support for resolving and managing identities in the AT Protocol ecosystem. This library handles multiple DID (Decentralized Identifier) methods including `did:plc` and `did:web`, as well as AT Protocol handle resolution via both DNS and HTTP methods.
+
+This project was extracted from the open-sourced [Smokesignal](https://tangled.sh/@smokesignal.events/smokesignal) project and is designed to be a standalone, reusable library for AT Protocol identity operations.
+
+## Features
+
+- **Handle Resolution**: Resolve AT Protocol handles to DIDs using DNS TXT records and HTTP well-known endpoints
+- **DID Document Retrieval**: Fetch and parse DID documents for `did:plc` and `did:web` identifiers
+- **Multiple Resolution Methods**: Supports both DNS and HTTP-based handle resolution with conflict detection
+- **Configurable DNS**: Custom DNS nameserver support with fallback to system defaults
+- **Cryptographic Key Operations**: Support for P-256 and K-256 key identification, signature validation, and signing
+- **Structured Logging**: Built-in tracing support for debugging and monitoring
+- **Type Safety**: Comprehensive error handling with structured error types
+
+## Supported DID Methods
+
+- **did-method-plc**: Public Ledger of Credentials DIDs via PLC directory
+- **did-method-web**: Web-based DIDs following the did:web specification with URL conversion utilities
+- **ATProtocol Handle Resolution**: AT Protocol handles (e.g., `ngerakines.me`) can be resolved to DIDs
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+atproto-identity = "0.3.0"
+```
+
+## Usage
+
+### Basic Handle Resolution
+
+```rust
+use atproto_identity::resolve::{resolve_subject, create_resolver};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let http_client = reqwest::Client::new();
+    let dns_resolver = create_resolver(&[]);
+    
+    let did = resolve_subject(&http_client, &dns_resolver, "ngerakines.me").await?;
+    println!("Resolved DID: {}", did);
+    
+    Ok(())
+}
+```
+
+### DID Document Retrieval
+
+```rust
+use atproto_identity::{plc, web};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let http_client = reqwest::Client::new();
+    
+    // Query PLC DID document
+    let plc_doc = plc::query(&http_client, "plc.directory", "did:plc:example123").await?;
+    
+    // Query Web DID document
+    let web_doc = web::query(&http_client, "did:web:example.com").await?;
+    
+    // Convert Web DID to URL (for custom processing)
+    let did_url = web::did_web_to_url("did:web:example.com")?;
+    println!("DID document URL: {}", did_url);
+    
+    Ok(())
+}
+```
+
+### Web DID URL Conversion
+
+The `web` module provides utilities for converting DID identifiers to their HTTPS document URLs:
+
+```rust
+use atproto_identity::web;
+
+fn main() -> anyhow::Result<()> {
+    // Convert simple hostname DID
+    let url = web::did_web_to_url("did:web:example.com")?;
+    // Returns: "https://example.com/.well-known/did.json"
+    
+    // Convert DID with path components  
+    let url = web::did_web_to_url("did:web:example.com:path:subpath")?;
+    // Returns: "https://example.com/path/subpath/did.json"
+    
+    Ok(())
+}
+```
+
+### Cryptographic Key Operations
+
+The `key` module provides utilities for working with cryptographic keys:
+
+```rust
+use atproto_identity::key::{identify_key, validate, KeyType};
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Identify a key from a DID key string
+    let key_data = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
+    
+    match key_data.0 {
+        KeyType::K256Public => println!("K-256 public key"),
+        KeyType::P256Public => println!("P-256 public key"),
+        KeyType::K256Private => println!("K-256 private key"),
+        KeyType::P256Private => println!("P-256 private key"),
+    }
+    
+    // Validate a signature (example with dummy data)
+    let content = b"hello world";
+    let signature = vec![0u8; 64]; // Replace with actual signature
+    validate(&key_data, &signature, content)?;
+    
+    Ok(())
+}
+```
+
+### Configuration
+
+The library supports various configuration options through environment variables:
+
+```bash
+# Custom PLC directory hostname
+export PLC_HOSTNAME=plc.directory
+
+# Custom DNS nameservers (semicolon-separated)
+export DNS_NAMESERVERS=8.8.8.8;1.1.1.1
+
+# Custom CA certificate bundles (semicolon-separated paths)
+export CERTIFICATE_BUNDLES=/path/to/cert1.pem;/path/to/cert2.pem
+
+# Custom User-Agent string
+export USER_AGENT="my-app/1.0"
+```
+
+## Command Line Tool
+
+The library includes a command-line tool for testing and resolution:
+
+```bash
+# Install the binary
+cargo install --path .
+
+# Resolve a handle to DID
+atproto-identity-resolve ngerakines.me
+
+# Get full DID document
+atproto-identity-resolve --did-document ngerakines.me
+```
+
+## Architecture
+
+The library is organized into several modules:
+
+- **resolve**: Core resolution logic for handles and DIDs
+- **plc**: PLC directory client for `did:plc` resolution
+- **web**: Web DID client for `did:web` resolution and URL conversion
+- **model**: Data structures for DID documents and AT Protocol entities
+- **validation**: Input validation for handles and DIDs
+- **config**: Configuration management and environment variable handling
+- **errors**: Structured error types following project conventions
+- **key**: Cryptographic key operations including signature validation and key identification for P-256 and K-256 curves
+
+## Error Handling
+
+All errors follow a structured format:
+
+```
+error-atproto-identity-<domain>-<number> <message>: <details>
+```
+
+Examples:
+- `error-atproto-identity-resolve-1 Multiple DIDs resolved for method`
+- `error-atproto-identity-plc-1 HTTP request failed: https://plc.directory/did:plc:example Not Found`
+- `error-did-web-1 Invalid DID format: missing 'did:web:' prefix`
+
+## Contributing
+
+Contributions are welcome! Please ensure that:
+
+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
+
+## 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-record/Cargo.toml

···
+[package]
+name = "atproto-record"
+version = "0.3.0"
+description = "AT Protocol record signature operations - cryptographic signing and verification for AT Protocol records"
+
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+repository.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[[bin]]         
+name = "atproto-record-sign"
+test = false
+bench = false
+doc = true
+
+[[bin]]         
+name = "atproto-record-verify"
+test = false
+bench = false
+doc = true
+
+[dependencies]
+atproto-identity.workspace = true
+
+anyhow.workspace = true
+ecdsa.workspace = true
+k256.workspace = true
+multibase.workspace = true
+p256.workspace = true
+serde_ipld_dagcbor.workspace = true
+serde_json.workspace = true
+serde.workspace = true
+thiserror.workspace = true
+tracing.workspace = true
+
+tokio = {workspace = true}
+chrono = {version = "0.4.41", default-features = false, features = ["std", "now"]}
+
+[lints]
+workspace = true

crates/atproto-record/README.md

···
+# atproto-record
+
+A Rust library for AT Protocol record signature operations, providing cryptographic signing and verification capabilities for AT Protocol records.
+
+## Overview
+
+This crate provides functionality for:
+
+- **Record Signing**: Create cryptographic signatures for AT Protocol records
+- **Signature Verification**: Verify existing signatures against records and public keys
+- **Error Handling**: Structured error types for signature operations
+- **Multi-curve Support**: Support for P-256 and K-256 elliptic curves via `atproto-identity`
+
+## Features
+
+- Create signatures for AT Protocol records with proper `$sig` object handling
+- Required signature object validation (must include `issuer` and `issued_at` fields)
+- Verify record signatures against issuer public keys
+- IPLD DAG-CBOR serialization for consistent signature generation
+- Multibase encoding for signature representation
+- Integration with `atproto-identity` for cryptographic key operations
+- Repository and collection context support in signature objects
+- Comprehensive error handling with structured error types including creation and verification errors
+
+## Usage
+
+### Creating Signatures
+
+```rust
+use atproto_record::signature;
+use atproto_identity::key::{identify_key, KeyType};
+use serde_json::json;
+use atproto_record::errors::VerificationError;
+
+# async fn example() -> Result<(), VerificationError> {
+// Prepare key data
+let key_data = identify_key("did:key:example...").map_err(|e| {
+    VerificationError::KeyOperationFailed(e)
+})?;
+
+// Create a record to sign
+let record = json!({
+    "$type": "app.bsky.feed.post",
+    "text": "Hello AT Protocol!",
+    "createdAt": "2024-01-01T00:00:00Z"
+});
+
+// Create signature object with required fields
+let signature_object = json!({
+    "issuer": "did:plc:signer123",
+    "issued_at": "2024-01-01T00:00:00Z"
+});
+
+// Create signature
+let signed_record = signature::create(
+    &key_data,
+    &record,
+    "did:plc:user123",
+    "app.bsky.feed.post",
+    signature_object
+).await?;
+# Ok(())
+# }
+```
+
+### Verifying Signatures
+
+```rust
+use atproto_record::signature;
+use atproto_identity::key::identify_key;
+use atproto_record::errors::VerificationError;
+
+# async fn example() -> Result<(), VerificationError> {
+// Get the issuer's public key
+let issuer_key = identify_key("did:key:issuer...").map_err(|e| {
+    VerificationError::KeyOperationFailed(e)
+})?;
+
+// Verify the signature
+signature::verify(
+    "did:plc:issuer123",
+    &issuer_key,
+    signed_record,
+    "did:plc:user123",
+    "app.bsky.feed.post"
+).await?;
+# Ok(())
+# }
+```
+
+## Modules
+
+- [`signature`] - Core signature creation and verification functions
+- [`errors`] - Structured error types for signature operations
+
+## Error Handling
+
+The crate uses structured error types defined in the `errors` module:
+
+```rust
+use atproto_record::errors::VerificationError;
+use serde_json::json;
+
+// Example error handling for signature creation
+let signature_object = json!({ "missing": "required_fields" });
+
+match signature::create(&key_data, &record, "repo", "collection", signature_object).await {
+    Ok(signed_record) => println!("Signature created successfully!"),
+    Err(VerificationError::SignatureObjectMissingField { field }) => {
+        println!("Missing required field in signature object: {}", field);
+    }
+    Err(VerificationError::InvalidSignatureObjectType) => {
+        println!("Signature object must be a JSON object");
+    }
+    Err(VerificationError::KeyOperationFailed(e)) => {
+        println!("Cryptographic operation failed: {}", e);
+    }
+    Err(e) => println!("Other error: {}", e),
+}
+
+// Example error handling for signature verification
+match signature::verify("did:plc:issuer", &key_data, record, "repo", "collection").await {
+    Ok(()) => println!("Signature valid!"),
+    Err(VerificationError::NoValidSignatureForIssuer { issuer }) => {
+        println!("No valid signature found for issuer: {}", issuer);
+    }
+    Err(VerificationError::NoSignaturesField) => {
+        println!("Record contains no signatures field");
+    }
+    Err(e) => println!("Verification failed: {}", e),
+}
+```
+
+## Dependencies
+
+This crate builds on:
+
+- [`atproto-identity`](../atproto-identity) - Cryptographic key operations and DID resolution
+- `serde_ipld_dagcbor` - IPLD DAG-CBOR serialization for signature content
+- `multibase` - Base encoding for signature representation
+- `serde_json` - JSON handling for AT Protocol records
+- `anyhow` - Error handling utilities
+- `thiserror` - Structured error type derivation
+
+## License
+
+Licensed under the MIT License.

crates/atproto-record/src/bin/atproto-record-sign.rs

···
+use anyhow::{anyhow, Result};
+use atproto_identity::{
+    key::{identify_key, KeyType},
+    resolve::{parse_input, InputType},
+};
+use atproto_record::signature::create;
+use chrono::{SecondsFormat, Utc};
+use serde_json::json;
+use std::{collections::HashMap, env, fs};
+
+/// AT Protocol Record Signing Tool
+///
+/// This command-line tool provides cryptographic signing capabilities for AT Protocol records.
+/// It reads a JSON record from a file, applies a cryptographic signature using a DID key,
+/// and outputs the signed record with embedded signature metadata.
+///
+/// ## Overview
+///
+/// The tool performs the following operations:
+/// 1. **Command Line Parsing**: Extracts signing parameters from command line arguments
+/// 2. **Key Resolution**: Converts DID key strings to cryptographic key material
+/// 3. **Record Loading**: Reads and parses JSON records from disk files
+/// 4. **Signature Creation**: Generates cryptographic signatures using IPLD DAG-CBOR serialization
+/// 5. **Output Generation**: Produces signed records with embedded signature objects
+///
+/// ## Signature Process
+///
+/// The signing process follows AT Protocol conventions:
+/// - Creates a `$sig` object with repository and collection context
+/// - Serializes the record with `$sig` using IPLD DAG-CBOR format
+/// - Generates ECDSA signatures using P-256 or K-256 curves
+/// - Embeds signatures in a `signatures` array with issuer metadata
+/// - Encodes signatures using multibase (base64url)
+///
+/// ## Arguments
+///
+/// The tool accepts flexible argument ordering:
+/// - **DID Key** (`did:key:...`) - Cryptographic key for signing operations
+/// - **Issuer DID** (`did:plc:...` or `did:web:...`) - Identity of the signature issuer  
+/// - **Record File** (file path) - JSON file containing the record to sign
+/// - **Parameters** (`key=value`) - Repository, collection, and signature metadata
+///
+/// ## Required Parameters
+///
+/// - `repository=<DID>` - Repository context for the signature
+/// - `collection=<name>` - Collection type context for the signature
+///
+/// ## Optional Parameters
+///
+/// - `issued_at=<timestamp>` - RFC 3339 timestamp (defaults to current time)
+/// - Custom fields can be added to the signature object via `key=value` pairs
+///
+/// ## Examples
+///
+/// ### Basic Usage
+/// ```bash
+/// atproto-record-sign \
+///   did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
+///   ./post.json \
+///   did:plc:tgudj2fjm77pzkuawquqhsxm \
+///   repository=did:plc:4zutorghlchjxzgceklue4la \
+///   collection=app.bsky.feed.post
+/// ```
+///
+/// ### With Custom Timestamp
+/// ```bash
+/// atproto-record-sign \
+///   did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
+///   ./badge.json \
+///   did:plc:tgudj2fjm77pzkuawquqhsxm \
+///   repository=did:plc:4zutorghlchjxzgceklue4la \
+///   collection=community.lexicon.badge.award \
+///   issued_at=2025-05-16T14:00:02.000Z
+/// ```
+///
+/// ### Input Record Example (`post.json`)
+/// ```json
+/// {
+///   "$type": "app.bsky.feed.post",
+///   "text": "Hello AT Protocol!",
+///   "createdAt": "2024-01-01T00:00:00Z"
+/// }
+/// ```
+///
+/// ### Output Signed Record
+/// ```json
+/// {
+///   "$type": "app.bsky.feed.post",
+///   "text": "Hello AT Protocol!",
+///   "createdAt": "2024-01-01T00:00:00Z",
+///   "signatures": [
+///     {
+///       "issuer": "did:plc:tgudj2fjm77pzkuawquqhsxm",
+///       "issued_at": "2025-05-30T16:27:20.532Z",
+///       "signature": "uo36qFvSGV6QcFaxYYN9JCAGQNv2yVHK2LPN3lNp210v..."
+///     }
+///   ]
+/// }
+/// ```
+///
+/// ## Error Handling
+///
+/// The tool provides detailed error messages for:
+/// - Missing or invalid DID keys and issuer DIDs
+/// - File reading and JSON parsing failures  
+/// - Missing required parameters (repository, collection)
+/// - Cryptographic operation failures
+/// - Unsupported DID methods
+///
+/// ## Security Considerations
+///
+/// - Private keys are handled in-memory only and not persisted
+/// - Signatures are generated using industry-standard ECDSA algorithms
+/// - All cryptographic operations follow AT Protocol specifications
+/// - Input validation prevents malformed DID and parameter injection
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Check for help flags
+    let args: Vec<String> = env::args().skip(1).collect();
+    if args.is_empty() || args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        println!("AT Protocol Record Signing Tool");
+        println!();
+        println!("USAGE:");
+        println!("    atproto-record-sign <ISSUER_DID> <SIGNING_KEY> <RECORD_FILE> repository=<REPO> collection=<COLLECTION> [key=value...]");
+        println!();
+        println!("ARGUMENTS:");
+        println!("    <ISSUER_DID>    DID of the issuer (e.g., did:plc:...)");
+        println!("    <SIGNING_KEY>   DID key for signing (e.g., did:key:z42tv1...)");
+        println!("    <RECORD_FILE>   Path to JSON file containing the record to sign");
+        println!();
+        println!("REQUIRED PARAMETERS:");
+        println!("    repository=<REPO>       Repository DID context");
+        println!("    collection=<COLLECTION> Collection name context");
+        println!();
+        println!("OPTIONAL PARAMETERS:");
+        println!("    issued_at=<TIMESTAMP>   RFC 3339 timestamp (defaults to current time)");
+        println!("    [key=value...]          Additional fields for signature object");
+        println!();
+        println!("EXAMPLE:");
+        println!("    atproto-record-sign \\");
+        println!("      did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \\");
+        println!("      ./record.json \\");
+        println!("      did:plc:tgudj2fjm77pzkuawquqhsxm \\");
+        println!("      repository=did:plc:4zutorghlchjxzgceklue4la \\");
+        println!("      collection=community.lexicon.badge.award");
+        return Ok(());
+    }
+
+    let arguments = args.into_iter();
+
+    let mut collection: Option<String> = None;
+    let mut repository: Option<String> = None;
+    let mut record: Option<serde_json::Value> = None;
+    let mut issuer: Option<String> = None;
+    let mut key_data: Option<(KeyType, Vec<u8>)> = None;
+    let mut signature_extras: HashMap<String, String> = HashMap::default();
+
+    for argument in arguments {
+        if let Some((key, value)) = argument.split_once("=") {
+            match key {
+                "collection" => {
+                    collection = Some(value.to_string());
+                }
+                "repository" => {
+                    repository = Some(value.to_string());
+                }
+                _ => {
+                    signature_extras.insert(key.to_string(), value.to_string());
+                }
+            }
+        } else if argument.starts_with("did:key:") {
+            // Parse the did:key to extract key data for signing
+            key_data = Some(identify_key(&argument)?);
+        } else if argument.starts_with("did:") {
+            match parse_input(&argument) {
+                Ok(InputType::Plc(did)) | Ok(InputType::Web(did)) => {
+                    issuer = Some(did);
+                }
+                Ok(_) => return Err(anyhow!("Unsupported DID method: {}", argument)),
+                Err(e) => return Err(anyhow!("Failed to parse DID {}: {}", argument, e)),
+            }
+        } else {
+            // Assume it's a file path to read the record from
+            if record.is_none() {
+                let file_content = fs::read_to_string(&argument)
+                    .map_err(|e| anyhow!("Failed to read file {}: {}", argument, e))?;
+                record =
+                    Some(serde_json::from_str(&file_content).map_err(|e| {
+                        anyhow!("Failed to parse JSON from file {}: {}", argument, e)
+                    })?);
+            } else {
+                return Err(anyhow!("Unexpected argument: {}", argument));
+            }
+        }
+    }
+
+    let collection = collection.ok_or(anyhow!("missing collection value"))?;
+    let repository = repository.ok_or(anyhow!("missing repository value"))?;
+    let record = record.ok_or(anyhow!("missing record source value"))?;
+    let issuer = issuer.ok_or(anyhow!("missing issuer value"))?;
+    let key_data = key_data.ok_or(anyhow!("missing key data"))?;
+
+    // Write "issuer" key to signature_extras
+    signature_extras.insert("issuer".to_string(), issuer);
+
+    // If signature_extras does not contain "issued_at" key, create a RFC 3339 formatted timestamp
+    if !signature_extras.contains_key("issued_at") {
+        let timestamp = Utc::now().to_rfc3339_opts(SecondsFormat::Millis, true);
+        signature_extras.insert("issued_at".to_string(), timestamp);
+    }
+
+    let signature_object = json!(signature_extras);
+    let signed_record = create(
+        &key_data,
+        &record,
+        &repository,
+        &collection,
+        signature_object,
+    )
+    .await?;
+
+    let pretty_signed_record = serde_json::to_string_pretty(&signed_record);
+    println!("{}", pretty_signed_record.unwrap());
+
+    Ok(())
+}

crates/atproto-record/src/bin/atproto-record-verify.rs

···
+use anyhow::{anyhow, Result};
+use atproto_identity::{
+    key::{identify_key, KeyType},
+    resolve::{parse_input, InputType},
+};
+use atproto_record::signature::verify;
+use std::{env, fs};
+
+/// AT Protocol Record Verification Tool
+///
+/// This command-line tool provides cryptographic signature verification capabilities for AT Protocol records.
+/// It reads a signed JSON record from a file, validates the embedded cryptographic signatures using a public key,
+/// and reports whether the signature verification succeeds or fails.
+///
+/// ## Overview
+///
+/// The tool performs the following operations:
+/// 1. **Command Line Parsing**: Extracts verification parameters from command line arguments
+/// 2. **Key Resolution**: Converts DID key strings to cryptographic key material for verification
+/// 3. **Record Loading**: Reads and parses signed JSON records from disk files
+/// 4. **Signature Verification**: Validates cryptographic signatures using IPLD DAG-CBOR deserialization
+/// 5. **Result Reporting**: Outputs verification success or detailed failure information
+///
+/// ## Verification Process
+///
+/// The verification process follows AT Protocol conventions:
+/// - Extracts signatures from the `signatures` array in the record
+/// - Finds signatures matching the specified issuer DID
+/// - Reconstructs the `$sig` object with repository and collection context
+/// - Deserializes the record with `$sig` using IPLD DAG-CBOR format
+/// - Validates ECDSA signatures using P-256 or K-256 curves
+/// - Decodes signatures from multibase (base64url) encoding
+/// - Verifies cryptographic signatures against the public key
+///
+/// ## Arguments
+///
+/// The tool accepts flexible argument ordering:
+/// - **Issuer DID** (`did:plc:...` or `did:web:...`) - Identity of the expected signature issuer
+/// - **Verification Key** (`did:key:...`) - Public key for signature verification
+/// - **Record File** (file path) - JSON file containing the signed record to verify
+/// - **Parameters** (`key=value`) - Repository and collection context for verification
+///
+/// ## Required Parameters
+///
+/// - `repository=<DID>` - Repository context that was used during signing
+/// - `collection=<name>` - Collection type context that was used during signing
+///
+/// ## Examples
+///
+/// ### Basic Verification
+/// ```bash
+/// atproto-record-verify \
+///   did:plc:tgudj2fjm77pzkuawquqhsxm \
+///   did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
+///   ./signed_post.json \
+///   repository=did:plc:4zutorghlchjxzgceklue4la \
+///   collection=app.bsky.feed.post
+/// ```
+///
+/// ### Verifying Badge Awards
+/// ```bash
+/// atproto-record-verify \
+///   did:plc:tgudj2fjm77pzkuawquqhsxm \
+///   did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \
+///   ./signed_badge.json \
+///   repository=did:plc:4zutorghlchjxzgceklue4la \
+///   collection=community.lexicon.badge.award
+/// ```
+///
+/// ### Input Signed Record Example (`signed_post.json`)
+/// ```json
+/// {
+///   "$type": "app.bsky.feed.post",
+///   "text": "Hello AT Protocol!",
+///   "createdAt": "2024-01-01T00:00:00Z",
+///   "signatures": [
+///     {
+///       "issuer": "did:plc:tgudj2fjm77pzkuawquqhsxm",
+///       "issued_at": "2025-05-30T16:27:20.532Z",
+///       "signature": "uo36qFvSGV6QcFaxYYN9JCAGQNv2yVHK2LPN3lNp210v..."
+///     }
+///   ]
+/// }
+/// ```
+///
+/// ### Successful Verification Output
+/// ```
+/// OK
+/// ```
+///
+/// ### Failed Verification Output
+/// ```
+/// Error: Signature verification failed: error validating signature: ...
+/// ```
+///
+/// ## Verification Workflow
+///
+/// 1. **Parse Arguments**: Extract issuer DID, verification key, record file, and context parameters
+/// 2. **Load Record**: Read and parse the signed JSON record from the specified file
+/// 3. **Extract Signatures**: Find signature objects in the `signatures` array matching the issuer
+/// 4. **Reconstruct Context**: Recreate the `$sig` object with repository and collection context
+/// 5. **Serialize Content**: Convert the record with `$sig` to IPLD DAG-CBOR format
+/// 6. **Decode Signature**: Convert multibase-encoded signature to raw bytes
+/// 7. **Verify Cryptographically**: Validate the signature against the serialized content using the public key
+/// 8. **Report Result**: Output "OK" for valid signatures or detailed error messages for failures
+///
+/// ## Error Handling
+///
+/// The tool provides detailed error messages for:
+/// - Missing or invalid DID keys and issuer DIDs
+/// - File reading and JSON parsing failures
+/// - Missing required parameters (repository, collection)
+/// - Records without signature fields or matching issuer signatures
+/// - Signature decoding and deserialization failures
+/// - Cryptographic verification failures
+/// - Unsupported DID methods and malformed signatures
+///
+/// ## Security Considerations
+///
+/// - Public keys are used for verification only, no private key handling
+/// - Signature verification uses industry-standard ECDSA algorithms
+/// - All cryptographic operations follow AT Protocol specifications
+/// - Input validation prevents malformed DID and parameter injection
+/// - Failed verifications provide diagnostic information without exposing sensitive data
+///
+/// ## Integration with Signing Tool
+///
+/// This tool is designed to work with records produced by `atproto-record-sign`:
+/// 1. Use `atproto-record-sign` to create signed records with embedded signatures
+/// 2. Use `atproto-record-verify` to validate those signatures using the corresponding public key
+/// 3. The same repository and collection parameters must be used for both signing and verification
+/// 4. The verification key should correspond to the private key used for signing
+#[tokio::main]
+async fn main() -> Result<()> {
+    // Check for help flags
+    let args: Vec<String> = env::args().skip(1).collect();
+    if args.is_empty() || args.iter().any(|arg| arg == "--help" || arg == "-h") {
+        println!("AT Protocol Record Verifying Tool");
+        println!();
+        println!("USAGE:");
+        println!("    atproto-record-verify <ISSUER_DID> <KEY> <RECORD_FILE> repository=<REPO> collection=<COLLECTION> [key=value...]");
+        println!();
+        println!("ARGUMENTS:");
+        println!("    <ISSUER_DID>    DID of the issuer (e.g., did:plc:...)");
+        println!("    <KEY>           DID key for verifying (e.g., did:key:z42tv1...)");
+        println!("    <RECORD_FILE>   Path to JSON file containing the record to verify");
+        println!();
+        println!("REQUIRED PARAMETERS:");
+        println!("    repository=<REPO>       Repository DID context");
+        println!("    collection=<COLLECTION> Collection name context");
+        println!();
+        println!("EXAMPLE:");
+        println!("    atproto-record-verify \\");
+        println!("      did:plc:tgudj2fjm77pzkuawquqhsxm \\");
+        println!("      did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \\");
+        println!("      ./record.json \\");
+        println!("      repository=did:plc:4zutorghlchjxzgceklue4la \\");
+        println!("      collection=community.lexicon.badge.award");
+        return Ok(());
+    }
+
+    let arguments = args.into_iter();
+
+    let mut collection: Option<String> = None;
+    let mut repository: Option<String> = None;
+    let mut record: Option<serde_json::Value> = None;
+    let mut issuer: Option<String> = None;
+    let mut key_data: Option<(KeyType, Vec<u8>)> = None;
+
+    for argument in arguments {
+        if let Some((key, value)) = argument.split_once("=") {
+            match key {
+                "collection" => {
+                    collection = Some(value.to_string());
+                }
+                "repository" => {
+                    repository = Some(value.to_string());
+                }
+                _ => {}
+            }
+        } else if argument.starts_with("did:key:") {
+            // Parse the did:key to extract key data for verification
+            key_data = Some(identify_key(&argument)?);
+        } else if argument.starts_with("did:") {
+            match parse_input(&argument) {
+                Ok(InputType::Plc(did)) | Ok(InputType::Web(did)) => {
+                    issuer = Some(did);
+                }
+                Ok(_) => return Err(anyhow!("Unsupported DID method: {}", argument)),
+                Err(e) => return Err(anyhow!("Failed to parse DID {}: {}", argument, e)),
+            }
+        } else {
+            // Assume it's a file path to read the record from
+            if record.is_none() {
+                let file_content = fs::read_to_string(&argument)
+                    .map_err(|e| anyhow!("Failed to read file {}: {}", argument, e))?;
+                record =
+                    Some(serde_json::from_str(&file_content).map_err(|e| {
+                        anyhow!("Failed to parse JSON from file {}: {}", argument, e)
+                    })?);
+            } else {
+                return Err(anyhow!("Unexpected argument: {}", argument));
+            }
+        }
+    }
+
+    let collection = collection.ok_or(anyhow!("missing collection value"))?;
+    let repository = repository.ok_or(anyhow!("missing repository value"))?;
+    let record = record.ok_or(anyhow!("missing record source value"))?;
+    let issuer = issuer.ok_or(anyhow!("missing issuer value"))?;
+    let key_data = key_data.ok_or(anyhow!("missing key data"))?;
+
+    verify(&issuer, &key_data, record, &repository, &collection).await?;
+
+    println!("OK");
+
+    Ok(())
+}

crates/atproto-record/src/errors.rs

···
+use thiserror::Error;
+
+/// Represents errors that can occur during record signature verification operations.
+///
+/// These errors relate to various stages of the signature verification process
+/// for AT Protocol records, from parsing to cryptographic validation.
+#[derive(Debug, Error)]
+pub enum VerificationError {
+    /// Error when AT-URI parsing fails.
+    ///
+    /// This error occurs when the provided AT-URI is malformed or cannot
+    /// be parsed into its component parts (repository, collection, rkey).
+    #[error("error-atproto-record-verification-1 AT-URI parsing failed: {0}")]
+    AturiParsingFailed(#[from] anyhow::Error),
+
+    /// Error when no signatures field is found in the record.
+    ///
+    /// This error occurs when a record does not contain either a "signatures"
+    /// or "sigs" field, which is required for signature verification.
+    #[error("error-atproto-record-verification-2 No signatures field found in record")]
+    NoSignaturesField,
+
+    /// Error when issuer field is missing from a signature object.
+    ///
+    /// This error occurs when a signature object in the signatures array
+    /// does not contain the required "issuer" field.
+    #[error("error-atproto-record-verification-3 Missing issuer field in signature object")]
+    MissingIssuerField,
+
+    /// Error when signature field is missing from a signature object.
+    ///
+    /// This error occurs when a signature object in the signatures array
+    /// does not contain the required "signature" field.
+    #[error("error-atproto-record-verification-4 Missing signature field in signature object")]
+    MissingSignatureField,
+
+    /// Error when public key parsing fails.
+    ///
+    /// This error occurs when the decoded public key bytes cannot be
+    /// parsed into a valid P-256 public key structure.
+    #[error("error-atproto-record-verification-5 Public key parsing failed: {0}")]
+    PublicKeyParsingFailed(p256::elliptic_curve::Error),
+
+    /// Error when record serialization fails.
+    ///
+    /// This error occurs when the signed record cannot be serialized
+    /// to IPLD CBOR format for signature verification.
+    #[error("error-atproto-record-verification-6 Record serialization failed: {0}")]
+    RecordSerializationFailed(
+        #[from] serde_ipld_dagcbor::EncodeError<std::collections::TryReserveError>,
+    ),
+
+    /// Error when signature parsing fails.
+    ///
+    /// This error occurs when the decoded signature bytes cannot be
+    /// parsed into a valid P-256 ECDSA signature structure.
+    #[error("error-atproto-record-verification-7 Signature parsing failed: {0}")]
+    SignatureParsingFailed(p256::ecdsa::Error),
+
+    /// Error when signature verification fails.
+    ///
+    /// This error occurs when the cryptographic verification of the
+    /// signature against the signed record fails, indicating the
+    /// signature is invalid for the given data and public key.
+    #[error("error-atproto-record-verification-8 Signature verification failed: {0}")]
+    SignatureVerificationFailed(anyhow::Error),
+
+    /// Error when no valid signature is found for the specified issuer.
+    ///
+    /// This error occurs when none of the signatures in the record
+    /// belong to the specified issuer, or when all signatures from
+    /// the issuer fail verification.
+    #[error("error-atproto-record-verification-9 No valid signature found for issuer: {issuer}")]
+    NoValidSignatureForIssuer {
+        /// The issuer DID for which no valid signature was found
+        issuer: String,
+    },
+
+    /// Error when no valid signature is found in the record.
+    ///
+    /// This error occurs when a record contains no valid signatures
+    /// that can be verified, typically used as a fallback error.
+    #[error("error-atproto-record-verification-10 No valid signature")]
+    NoValidSignature,
+
+    /// Error when signature object is not a valid JSON object.
+    ///
+    /// This error occurs when the provided signature object parameter
+    /// is not a JSON object type, which is required for signature creation.
+    #[error("error-atproto-record-verification-11 Signature object must be a JSON object")]
+    InvalidSignatureObjectType,
+
+    /// Error when signature object is missing fields.
+    ///
+    /// This error occurs when the signature object is missing fields that are
+    /// necessary use during signature creation, such as 'issuer' or
+    /// 'issued_at'.
+    #[error("error-atproto-record-verification-12 Signature object missing field: {field}")]
+    SignatureObjectMissingField {
+        /// The name of the missing field
+        field: String,
+    },
+
+    /// Error when cryptographic key operations fail.
+    ///
+    /// This error occurs when key-related operations such as signing
+    /// or key parsing fail during signature creation or verification.
+    #[error("error-atproto-record-verification-13 Key operation failed: {0}")]
+    KeyOperationFailed(#[from] atproto_identity::errors::KeyError),
+}

crates/atproto-record/src/lib.rs

···
+//! # atproto-record
+//!
+//! A Rust library for AT Protocol record signature operations, providing cryptographic
+//! signing and verification capabilities for AT Protocol records.
+//!
+//! This crate handles the cryptographic aspects of AT Protocol record attestation,
+//! including signature creation and verification with proper `$sig` object handling
+//! and IPLD DAG-CBOR serialization.
+//!
+//! ## Core Modules
+//!
+//! - [`signature`] - Core signature creation and verification functions
+//! - [`errors`] - Structured error types for signature verification operations
+//!
+//! ## Key Features
+//!
+//! - **Record Signing**: Create cryptographic signatures for AT Protocol records
+//! - **Signature Verification**: Verify existing signatures against records and public keys
+//! - **Multi-curve Support**: Support for P-256 and K-256 elliptic curves via `atproto-identity`
+//! - **IPLD Integration**: Proper IPLD DAG-CBOR serialization for signature content
+//! - **Error Handling**: Comprehensive structured error types following project conventions
+//!
+//! ## Usage Examples
+//!
+//! ### Creating a Signature
+//!
+//! ```rust
+//! use atproto_record::signature;
+//! use atproto_record::errors::VerificationError;
+//! use serde_json::json;
+//! use atproto_identity::key::{KeyType};
+//! async fn example() -> Result<(), VerificationError> {
+//!   let key_data = (KeyType::P256Public, vec![]);
+//!
+//!   let record = json!({
+//!     "$type": "app.bsky.feed.post",
+//!     "text": "Hello AT Protocol!"
+//!   });
+//!
+//!   // Create signature object with required fields
+//!   let signature_object = json!({
+//!     "issuer": "did:plc:signer123",
+//!     "issued_at": "2024-01-01T00:00:00Z"
+//!   });
+//!
+//!   let signed_record = signature::create(
+//!     &key_data,
+//!     &record,
+//!     "did:plc:user123",
+//!     "app.bsky.feed.post",
+//!     signature_object
+//!   ).await?;
+//!   Ok(())
+//! }
+//! ```
+//!
+//! ### Verifying a Signature
+//!
+//! ```rust
+//! use atproto_record::signature;
+//! use atproto_record::errors::VerificationError;
+//! use atproto_identity::key::{KeyType};
+//! use serde_json::json;
+//! async fn example() -> Result<(), VerificationError> {
+//!   let issuer_key = (KeyType::P256Public, vec![]);
+//!   let signed_record = json!({
+//!     "signatures": [{
+//!       "issuer": "did:plc:issuer123",
+//!       "signature": "uExample_signature_data"
+//!     }]
+//!   });
+//!
+//!   signature::verify(
+//!     "did:plc:issuer123",
+//!     &issuer_key,
+//!     signed_record,
+//!     "did:plc:user123",
+//!     "app.bsky.feed.post"
+//!   ).await?;
+//!   Ok(())
+//! }
+//! ```
+//!
+//! ## Error Handling
+//!
+//! All signature operations return structured errors defined in the [`errors`] module:
+//!
+//! ```rust
+//! use atproto_record::errors::VerificationError;
+//! use atproto_record::signature::create;
+//! use serde_json::json;
+//!
+//! // Example: handling signature creation errors
+//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//!   let key_data = (atproto_identity::key::KeyType::P256Public, vec![]);
+//!   let record = json!({});
+//!   let invalid_signature_object = json!({ "missing": "required_fields" });
+//!
+//!   match create(&key_data, &record, "repo", "collection", invalid_signature_object).await {
+//!     Ok(_) => println!("Signature created successfully!"),
+//!     Err(VerificationError::SignatureObjectMissingField { field }) => {
+//!         println!("Missing required field: {}", field);
+//!     }
+//!     Err(VerificationError::InvalidSignatureObjectType) => {
+//!         println!("Signature object must be a JSON object");
+//!     }
+//!     Err(VerificationError::KeyOperationFailed(_)) => {
+//!         println!("Cryptographic operation failed");
+//!     }
+//!     Err(e) => println!("Other error: {}", e),
+//!   }
+//!   Ok(())
+//! }
+//! ```
+
+#![warn(missing_docs)]
+
+/// Structured error types for signature verification operations.
+///
+/// This module defines comprehensive error types that can occur during
+/// AT Protocol record signature verification, following the project's
+/// error naming conventions.
+pub mod errors;
+
+/// Core signature creation and verification functions.
+///
+/// This module provides the primary functionality for creating and verifying
+/// cryptographic signatures on AT Protocol records, with proper handling of
+/// signature objects and IPLD serialization.
+pub mod signature;

crates/atproto-record/src/signature.rs

···
+use anyhow::anyhow;
+use atproto_identity::key::{sign, validate, KeyType};
+use serde_json::json;
+
+use crate::errors::VerificationError;
+
+/// Signs an AT Protocol record.
+///
+/// This function generates a signature for the provided record using the specified
+/// key data and context information. The signature is embedded into the record
+/// following AT Protocol signature conventions.
+///
+/// # Parameters
+///
+/// * `key_data` - The cryptographic key information (key type and bytes)
+/// * `record` - The JSON record to be signed
+/// * `repository` - The repository DID context for the signature
+/// * `collection` - The collection name context for the signature  
+/// * `signature_object` - Optional additional fields for the signature object
+///
+/// # Returns
+///
+/// Returns the original record with a `signatures` field containing the new signature.
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - IPLD serialization fails
+/// - Cryptographic signing fails
+/// - JSON manipulation fails
+pub async fn create(
+    key_data: &(KeyType, Vec<u8>),
+    record: &serde_json::Value,
+    repository: &str,
+    collection: &str,
+    signature_object: serde_json::Value,
+) -> Result<serde_json::Value, VerificationError> {
+    if let Some(record_map) = signature_object.as_object() {
+        if !record_map.contains_key("issuer") {
+            return Err(VerificationError::SignatureObjectMissingField {
+                field: "issuer".to_string(),
+            });
+        }
+        if !record_map.contains_key("issued_at") {
+            return Err(VerificationError::SignatureObjectMissingField {
+                field: "issued_at".to_string(),
+            });
+        }
+    } else {
+        return Err(VerificationError::InvalidSignatureObjectType);
+    };
+
+    // Prepare the $sig object.
+    let mut sig = signature_object.clone();
+    if let Some(record_map) = sig.as_object_mut() {
+        record_map.insert("repository".to_string(), json!(repository));
+        record_map.insert("collection".to_string(), json!(collection));
+    }
+
+    // Create a copy of the record with the $sig object for signing.
+    let mut signing_record = record.clone();
+    if let Some(record_map) = signing_record.as_object_mut() {
+        record_map.remove("signatures");
+        record_map.remove("$sig");
+        record_map.insert("$sig".to_string(), sig);
+    }
+
+    // Create a signature.
+    let serialized_signing_record = serde_ipld_dagcbor::to_vec(&signing_record)?;
+
+    let signature = sign(key_data, &serialized_signing_record)?;
+    let encoded_signature = multibase::encode(multibase::Base::Base64Url, &signature);
+
+    // Compose the proof object
+    let mut proof = signature_object.clone();
+    if let Some(record_map) = proof.as_object_mut() {
+        record_map.remove("repository");
+        record_map.remove("collection");
+        record_map.insert("signature".to_string(), json!(encoded_signature));
+    }
+
+    // Add the signature to the original record
+    let mut signed_record = record.clone();
+
+    if let Some(record_map) = signed_record.as_object_mut() {
+        let mut signatures: Vec<serde_json::Value> = record
+            .get("signatures")
+            .and_then(|v| v.as_array().cloned())
+            .unwrap_or_default();
+
+        signatures.push(proof);
+
+        record_map.remove("$sig");
+        record_map.remove("signatures");
+
+        // Add the $sig field
+        record_map.insert("signatures".to_string(), json!(signatures));
+    }
+
+    Ok(signed_record)
+}
+
+/// Verifies a cryptographic signature on an AT Protocol record.
+///
+/// This function validates that the provided record contains a valid signature
+/// from the specified issuer using the provided public key. It reconstructs
+/// the signed content and verifies the cryptographic signature.
+///
+/// # Parameters
+///
+/// * `issuer` - The DID of the expected signature issuer
+/// * `key_data` - The public key information for verification
+/// * `record` - The signed JSON record to verify
+/// * `repository` - The repository DID context for verification
+/// * `collection` - The collection name context for verification
+///
+/// # Returns
+///
+/// Returns `Ok(())` if a valid signature from the issuer is found and verified.
+///
+/// # Errors
+///
+/// Returns a [`VerificationError`] if:
+/// - No signatures field is found in the record
+/// - No signature from the specified issuer is found
+/// - Signature decoding or parsing fails
+/// - Cryptographic verification fails
+/// - Record serialization fails
+pub async fn verify(
+    issuer: &str,
+    key_data: &(KeyType, Vec<u8>),
+    record: serde_json::Value,
+    repository: &str,
+    collection: &str,
+) -> Result<(), VerificationError> {
+    let signatures = record
+        .get("sigs")
+        .or_else(|| record.get("signatures"))
+        .and_then(|v| v.as_array())
+        .ok_or(VerificationError::NoSignaturesField)?;
+
+    for sig_obj in signatures {
+        // Extract the issuer from the signature object
+        let signature_issuer = sig_obj
+            .get("issuer")
+            .and_then(|v| v.as_str())
+            .ok_or(VerificationError::MissingIssuerField)?;
+
+        let signature_value = sig_obj
+            .get("signature")
+            .and_then(|v| v.as_str())
+            .ok_or(VerificationError::MissingSignatureField)?;
+
+        if issuer != signature_issuer {
+            continue;
+        }
+
+        let mut sig_variable = sig_obj.clone();
+
+        if let Some(sig_map) = sig_variable.as_object_mut() {
+            sig_map.remove("signature");
+            sig_map.insert("repository".to_string(), json!(repository));
+            sig_map.insert("collection".to_string(), json!(collection));
+        }
+
+        let mut signed_record = record.clone();
+        if let Some(record_map) = signed_record.as_object_mut() {
+            record_map.remove("signatures");
+            record_map.insert("$sig".to_string(), sig_variable);
+        }
+
+        let serialized_record = serde_ipld_dagcbor::to_vec(&signed_record)
+            .map_err(VerificationError::RecordSerializationFailed)?;
+
+        let (_, signature_bytes) = multibase::decode(signature_value).map_err(|e| {
+            VerificationError::SignatureVerificationFailed(anyhow!(
+                "error decoding signature: {}",
+                e
+            ))
+        })?;
+
+        validate(key_data, &signature_bytes, &serialized_record).map_err(|e| {
+            VerificationError::SignatureVerificationFailed(anyhow!(
+                "error validating signature: {}",
+                e
+            ))
+        })?;
+
+        return Ok(());
+    }
+
+    Err(VerificationError::NoValidSignatureForIssuer {
+        issuer: issuer.to_string(),
+    })
+}

src/lib.rs crates/atproto-identity/src/lib.rs

···
 //!
 
 #![warn(missing_docs)]
-#![warn(missing_doc_code_examples)]
 
 pub mod config;
 pub mod errors;