feature: attestation crate

CLAUDE.md

···
 - **Sign data**: `cargo run --features clap --bin atproto-identity-sign -- <did_key> <json_file>`
 - **Validate signatures**: `cargo run --features clap --bin atproto-identity-validate -- <did_key> <json_file> <signature>`
 
+#### Attestation Operations
+- **Sign records (inline)**: `cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- inline <source_record> <signing_key> <metadata_record>`
+- **Sign records (remote)**: `cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- remote <source_record> <repository_did> <metadata_record>`
+- **Verify records**: `cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- <record>` (verifies all signatures)
+- **Verify attestation**: `cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- <record> <attestation>` (verifies specific attestation)
+
 #### Record Operations
-- **Sign records**: `cargo run --features clap --bin atproto-record-sign -- <issuer_did> <signing_key> <record_input> repository=<repo> collection=<collection>`
-- **Verify records**: `cargo run --features clap --bin atproto-record-verify -- <issuer_did> <key> <record_input> repository=<repo> collection=<collection>`
 - **Generate CID**: `cat record.json | cargo run --features clap --bin atproto-record-cid` (reads JSON from stdin, outputs CID)
 
 #### Client Tools
···
 ## Architecture
 
 A comprehensive Rust workspace with multiple crates:
-- **atproto-identity**: Core identity management with 10 modules (resolve, plc, web, model, validation, config, errors, key, storage, storage_lru)
-- **atproto-record**: Record signature operations and validation  
+- **atproto-identity**: Core identity management with 11 modules (resolve, plc, web, model, validation, config, errors, key, storage_lru, traits, url)
+- **atproto-attestation**: CID-first attestation utilities for creating and verifying record signatures
+- **atproto-record**: Record utilities including TID generation, AT-URI parsing, and CID generation
 - **atproto-client**: HTTP client with OAuth and identity integration
 - **atproto-jetstream**: WebSocket event streaming with compression
 - **atproto-oauth**: OAuth workflow implementation with DPoP, PKCE, JWT, and storage abstractions
···
 ### Core Library Modules (atproto-identity)
 - **`src/lib.rs`**: Main library exports
 - **`src/resolve.rs`**: Core resolution logic for handles and DIDs, DNS/HTTP resolution
-- **`src/plc.rs`**: PLC directory client for did:plc resolution  
+- **`src/plc.rs`**: PLC directory client for did:plc resolution
 - **`src/web.rs`**: Web DID client for did:web resolution and URL conversion
 - **`src/model.rs`**: Data structures for DID documents and AT Protocol entities
 - **`src/validation.rs`**: Input validation for handles and DIDs
 - **`src/config.rs`**: Configuration management and environment variable handling
 - **`src/errors.rs`**: Structured error types following project conventions
 - **`src/key.rs`**: Cryptographic key operations including signature validation and key identification for P-256, P-384, and K-256 curves
-- **`src/storage.rs`**: Storage abstraction interface for DID document caching
 - **`src/storage_lru.rs`**: LRU-based storage implementation (requires `lru` feature)
+- **`src/traits.rs`**: Core trait definitions for identity resolution and key resolution
+- **`src/url.rs`**: URL utilities for AT Protocol services
 
 ### CLI Tools (require --features clap)
 
···
 - **`src/bin/atproto-identity-sign.rs`**: Create cryptographic signatures of JSON data
 - **`src/bin/atproto-identity-validate.rs`**: Validate cryptographic signatures
 
+#### Attestation Operations (atproto-attestation)
+- **`src/bin/atproto-attestation-sign.rs`**: Sign AT Protocol records with inline or remote attestations using CID-first specification
+- **`src/bin/atproto-attestation-verify.rs`**: Verify cryptographic signatures on AT Protocol records with attestation validation
+
 #### Record Operations (atproto-record)
-- **`src/bin/atproto-record-sign.rs`**: Sign AT Protocol records with cryptographic signatures
-- **`src/bin/atproto-record-verify.rs`**: Verify AT Protocol record signatures
 - **`src/bin/atproto-record-cid.rs`**: Generate CID (Content Identifier) for AT Protocol records using DAG-CBOR serialization
 
 #### Client Tools (atproto-client)

Cargo.lock

···
 checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
 
 [[package]]
+name = "atproto-attestation"
+version = "0.13.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "atproto-client",
+ "atproto-identity",
+ "atproto-record",
+ "base64",
+ "cid",
+ "clap",
+ "elliptic-curve",
+ "k256",
+ "multihash",
+ "p256",
+ "reqwest",
+ "serde",
+ "serde_ipld_dagcbor",
+ "serde_json",
+ "sha2",
+ "thiserror 2.0.12",
+ "tokio",
+]
+
+[[package]]
 name = "atproto-client"
 version = "0.13.0"
 dependencies = [
  "anyhow",
+ "async-trait",
  "atproto-identity",
  "atproto-oauth",
  "atproto-record",
···
  "thiserror 2.0.12",
  "tokio",
  "tracing",
+ "url",
  "urlencoding",
  "zeroize",
 ]
···
 version = "0.13.0"
 dependencies = [
  "anyhow",
+ "async-trait",
  "atproto-identity",
  "base64",
  "chrono",
  "cid",
  "clap",
  "multihash",
+ "rand 0.8.5",
  "serde",
  "serde_ipld_dagcbor",
  "serde_json",

Cargo.toml

···
     "crates/atproto-xrpcs-helloworld",
     "crates/atproto-xrpcs",
     "crates/atproto-lexicon",
+    "crates/atproto-attestation",
 ]
 resolver = "3"
 
···
 atproto-record = { version = "0.13.0", path = "crates/atproto-record" }
 atproto-xrpcs = { version = "0.13.0", path = "crates/atproto-xrpcs" }
 atproto-jetstream = { version = "0.13.0", path = "crates/atproto-jetstream" }
+atproto-attestation = { version = "0.13.0", path = "crates/atproto-attestation" }
 
 anyhow = "1.0"
 async-trait = "0.1.88"
···
 tokio-util = "0.7"
 tracing = { version = "0.1", features = ["async-await"] }
 ulid = "1.2.1"
+zstd = "0.13"
+url = "2.5"
 urlencoding = "2.1"
-zstd = "0.13"
 
 zeroize = { version = "1.8.1", features = ["zeroize_derive"] }
 

Dockerfile

···
 # Multi-stage build for atproto-identity-rs workspace
-# Builds and installs all 13 binaries from the workspace
+# Builds and installs all 15 binaries from the workspace
 
-# Build stage - use 1.89 to support resolver = "3" and edition = "2024"
+# Build stage - use 1.90 to support resolver = "3" and edition = "2024"
 FROM rust:1.90-slim-bookworm AS builder
 
 # Install system dependencies needed for building
···
 # Build all binaries in release mode
 # This will build all binaries defined in the workspace:
 # - atproto-identity: 4 binaries (resolve, key, sign, validate)
-# - atproto-record: 2 binaries (sign, verify)
+# - atproto-attestation: 2 binaries (attestation-sign, attestation-verify)
+# - atproto-record: 1 binary (record-cid)
 # - atproto-client: 3 binaries (auth, app-password, dpop)
 # - atproto-oauth: 1 binary (service-token)
 # - atproto-oauth-axum: 1 binary (oauth-tool)
···
 COPY --from=builder /usr/src/app/target/release/atproto-identity-key .
 COPY --from=builder /usr/src/app/target/release/atproto-identity-sign .
 COPY --from=builder /usr/src/app/target/release/atproto-identity-validate .
-COPY --from=builder /usr/src/app/target/release/atproto-record-sign .
-COPY --from=builder /usr/src/app/target/release/atproto-record-verify .
+COPY --from=builder /usr/src/app/target/release/atproto-attestation-sign .
+COPY --from=builder /usr/src/app/target/release/atproto-attestation-verify .
+COPY --from=builder /usr/src/app/target/release/atproto-record-cid .
 COPY --from=builder /usr/src/app/target/release/atproto-client-auth .
 COPY --from=builder /usr/src/app/target/release/atproto-client-app-password .
 COPY --from=builder /usr/src/app/target/release/atproto-client-dpop .
···
 
 # Default to the main resolution tool
 # Users can override with specific binary: docker run <image> atproto-identity-resolve --help
-# Or run other tools: 
+# Or run other tools:
 #   docker run <image> atproto-identity-key --help
-#   docker run <image> atproto-record-sign --help
+#   docker run <image> atproto-attestation-sign --help
+#   docker run <image> atproto-attestation-verify --help
+#   docker run <image> atproto-record-cid --help
 #   docker run <image> atproto-client-auth --help
 #   docker run <image> atproto-oauth-service-token --help
 #   docker run <image> atproto-oauth-tool --help
···
 LABEL org.opencontainers.image.licenses="MIT"
 
 # Document available binaries
-LABEL binaries="atproto-identity-resolve,atproto-identity-key,atproto-identity-sign,atproto-identity-validate,atproto-record-sign,atproto-record-verify,atproto-client-auth,atproto-client-app-password,atproto-client-dpop,atproto-oauth-service-token,atproto-oauth-tool,atproto-jetstream-consumer,atproto-xrpcs-helloworld,atproto-lexicon-resolve"
+LABEL binaries="atproto-identity-resolve,atproto-identity-key,atproto-identity-sign,atproto-identity-validate,atproto-attestation-sign,atproto-attestation-verify,atproto-record-cid,atproto-client-auth,atproto-client-app-password,atproto-client-dpop,atproto-oauth-service-token,atproto-oauth-tool,atproto-jetstream-consumer,atproto-xrpcs-helloworld,atproto-lexicon-resolve"

README.md

···
 ### Identity & Cryptography
 
 - **[`atproto-identity`](crates/atproto-identity/)** - Core identity management with multi-method DID resolution (plc, web, key), DNS/HTTP handle resolution, and P-256/P-384/K-256 cryptographic operations. *Includes 4 CLI tools.*
-- **[`atproto-record`](crates/atproto-record/)** - Cryptographic signature operations for AT Protocol records using IPLD DAG-CBOR serialization with AT-URI parsing support. *Includes 2 CLI tools.*
+- **[`atproto-attestation`](crates/atproto-attestation/)** - CID-first attestation utilities for creating and verifying cryptographic signatures on AT Protocol records, supporting both inline and remote attestation workflows. *Includes 2 CLI tools.*
+- **[`atproto-record`](crates/atproto-record/)** - Record utilities including TID generation, AT-URI parsing, datetime formatting, and CID generation using IPLD DAG-CBOR serialization. *Includes 1 CLI tool.*
 - **[`atproto-lexicon`](crates/atproto-lexicon/)** - Lexicon schema resolution and validation for AT Protocol, supporting recursive resolution, NSID validation, and DNS-based lexicon discovery. *Includes 1 CLI tool.*
 
 ### Authentication & Authorization  
···
 ```toml
 [dependencies]
 atproto-identity = "0.13.0"
+atproto-attestation = "0.13.0"
 atproto-record = "0.13.0"
 atproto-lexicon = "0.13.0"
 atproto-oauth = "0.13.0"
···
 ### Record Signing
 
 ```rust
-use atproto_identity::key::identify_key;
-use atproto_record::signature;
+use atproto_identity::key::{identify_key, to_public};
+use atproto_attestation::{create_inline_attestation, verify_all_signatures, VerificationStatus};
 use serde_json::json;
 
 #[tokio::main]
 async fn main() -> anyhow::Result<()> {
-    let signing_key = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
+    let private_key = identify_key("did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA")?;
+    let public_key = to_public(&private_key)?;
+    let key_reference = format!("{}", &public_key);
 
     let record = json!({
         "$type": "app.bsky.feed.post",
···
         "createdAt": "2024-01-01T00:00:00.000Z"
     });
 
-    let signature_object = json!({
+    let sig_metadata = json!({
+        "$type": "com.example.inlineSignature",
+        "key": &key_reference,
         "issuer": "did:plc:issuer123",
         "issuedAt": "2024-01-01T00:00:00.000Z"
     });
 
-    let signed_record = signature::create(
-        &signing_key,
-        &record,
-        "did:plc:user123",
-        "app.bsky.feed.post",
-        signature_object,
-    ).await?;
+    let signed_record =
+        create_inline_attestation(&record, &sig_metadata, &private_key)?;
+
+    let reports = verify_all_signatures(&signed_record, None).await?;
+    assert!(reports.iter().all(|report| matches!(report.status, VerificationStatus::Valid { .. })));
 
     Ok(())
 }
···
 cargo run --features clap --bin atproto-identity-sign -- did:key:... data.json
 cargo run --features clap --bin atproto-identity-validate -- did:key:... data.json signature
 
+# Attestation operations (atproto-attestation crate)
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- inline record.json did:key:... metadata.json
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- signed_record.json
+
 # Record operations (atproto-record crate)
-cargo run --features clap --bin atproto-record-sign -- did:key:... did:plc:issuer record.json repository=did:plc:user collection=app.bsky.feed.post
-cargo run --features clap --bin atproto-record-verify -- did:plc:issuer did:key:... signed_record.json repository=did:plc:user collection=app.bsky.feed.post
+cat record.json | cargo run --features clap --bin atproto-record-cid
 
 # Lexicon operations (atproto-lexicon crate)
 cargo run --features clap,hickory-dns --bin atproto-lexicon-resolve -- app.bsky.feed.post
···
 
 ## Acknowledgments
 
-Parts of this project were extracted from the [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source AT Protocol event and RSVP management application. This extraction enables broader community use and contribution to AT Protocol tooling in Rust.
+Parts of this project were extracted from the [smokesignal.events](https://tangled.sh/@smokesignal.events/smokesignal) project, an open-source AT Protocol event and RSVP management application. This extraction enables broader community use and contribution to AT Protocol tooling in Rust.

crates/atproto-attestation/Cargo.toml

···
+[package]
+name = "atproto-attestation"
+version = "0.13.0"
+description = "AT Protocol attestation utilities for creating and verifying record signatures"
+readme = "README.md"
+homepage = "https://tangled.sh/@smokesignal.events/atproto-identity-rs"
+documentation = "https://docs.rs/atproto-attestation"
+edition.workspace = true
+rust-version.workspace = true
+repository.workspace = true
+authors.workspace = true
+license.workspace = true
+keywords.workspace = true
+categories.workspace = true
+
+[[bin]]
+name = "atproto-attestation-sign"
+test = false
+bench = false
+doc = true
+required-features = ["clap", "tokio"]
+
+[[bin]]
+name = "atproto-attestation-verify"
+test = false
+bench = false
+doc = true
+required-features = ["clap", "tokio"]
+
+[dependencies]
+atproto-client.workspace = true
+atproto-identity.workspace = true
+atproto-record.workspace = true
+anyhow.workspace = true
+base64.workspace = true
+serde.workspace = true
+serde_json.workspace = true
+serde_ipld_dagcbor.workspace = true
+sha2.workspace = true
+thiserror.workspace = true
+
+cid = "0.11"
+elliptic-curve = { version = "0.13", default-features = false, features = ["std"] }
+k256 = { version = "0.13", default-features = false, features = ["ecdsa", "std"] }
+multihash = "0.19"
+p256 = { version = "0.13", default-features = false, features = ["ecdsa", "std"] }
+
+async-trait = { workspace = true, optional = true }
+clap = { workspace = true, optional = true }
+reqwest = { workspace = true, optional = true }
+tokio = { workspace = true, optional = true }
+
+[dev-dependencies]
+async-trait = "0.1"
+tokio = { workspace = true, features = ["macros", "rt"] }
+
+[features]
+default = []
+clap = ["dep:clap"]
+tokio = ["dep:tokio", "dep:reqwest", "dep:async-trait"]
+
+[lints]
+workspace = true

crates/atproto-attestation/README.md

···
+# atproto-attestation
+
+Utilities for preparing, signing, and verifying AT Protocol record attestations using the CID-first workflow.
+
+## Overview
+
+A Rust library implementing the CID-first attestation specification for AT Protocol records. This crate provides cryptographic signature creation and verification for records, supporting both inline attestations (signatures embedded directly in records) and remote attestations (separate proof records with strongRef references).
+
+The attestation workflow ensures deterministic signing payloads by:
+1. Preparing records with `$sig` metadata
+2. Generating content identifiers (CIDs) using DAG-CBOR serialization
+3. Signing CID bytes with elliptic curve cryptography
+4. Embedding or referencing signatures in records
+5. Verifying signatures against resolved public keys
+
+## Features
+
+- **Inline attestations**: Embed cryptographic signatures directly in record structures
+- **Remote attestations**: Create separate proof records with CID-based strongRef references
+- **CID-first workflow**: Deterministic signing based on content identifiers
+- **Multi-curve support**: Full support for P-256, P-384, and K-256 elliptic curves
+- **Signature normalization**: Automatic low-S normalization for ECDSA signatures
+- **Key resolution**: Resolve verification keys from DID documents or did:key identifiers
+- **Flexible verification**: Verify individual signatures or all signatures in a record
+- **Structured reporting**: Detailed verification reports with success/failure status
+
+## CLI Tools
+
+The following command-line tools are available when built with the `clap` and `tokio` features:
+
+- **`atproto-attestation-sign`**: Sign AT Protocol records with inline or remote attestations
+- **`atproto-attestation-verify`**: Verify cryptographic signatures on AT Protocol records
+
+## Library Usage
+
+### Creating Inline Attestations
+
+Inline attestations embed the signature bytes directly in the record:
+
+```rust
+use atproto_identity::key::{identify_key, to_public};
+use atproto_attestation::create_inline_attestation;
+use serde_json::json;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Parse the signing key from a did:key
+    let private_key = identify_key("did:key:zQ3sh...")?;
+    let public_key = to_public(&private_key)?;
+    let key_reference = format!("{}", &public_key);
+
+    // The record to sign
+    let record = json!({
+        "$type": "app.bsky.feed.post",
+        "text": "Hello world!",
+        "createdAt": "2024-01-01T00:00:00.000Z"
+    });
+
+    // Attestation metadata (required fields: $type, key)
+    let sig_metadata = json!({
+        "$type": "com.example.inlineSignature",
+        "key": &key_reference,
+        "issuer": "did:plc:issuer123",
+        "issuedAt": "2024-01-01T00:00:00.000Z"
+    });
+
+    // Create inline attestation
+    let signed_record = create_inline_attestation(&record, &sig_metadata, &private_key)?;
+
+    println!("{}", serde_json::to_string_pretty(&signed_record)?);
+
+    Ok(())
+}
+```
+
+The resulting record will have a `signatures` array:
+
+```json
+{
+  "$type": "app.bsky.feed.post",
+  "text": "Hello world!",
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "signatures": [
+    {
+      "$type": "com.example.inlineSignature",
+      "key": "did:key:zQ3sh...",
+      "issuer": "did:plc:issuer123",
+      "issuedAt": "2024-01-01T00:00:00.000Z",
+      "signature": {
+        "$bytes": "base64-encoded-signature-bytes"
+      }
+    }
+  ]
+}
+```
+
+### Creating Remote Attestations
+
+Remote attestations create a separate proof record that must be stored in a repository:
+
+```rust
+use atproto_attestation::{create_remote_attestation, create_remote_attestation_reference};
+use serde_json::json;
+
+let record = json!({
+    "$type": "app.bsky.feed.post",
+    "text": "Hello world!"
+});
+
+let metadata = json!({
+    "$type": "com.example.attestation",
+    "issuer": "did:plc:issuer123",
+    "purpose": "verification"
+});
+
+// Create the proof record (contains the CID)
+let proof_record = create_remote_attestation(&record, &metadata)?;
+
+// Create the source record with strongRef
+let repository_did = "did:plc:repo123";
+let attested_record = create_remote_attestation_reference(
+    &record,
+    &proof_record,
+    repository_did
+)?;
+
+// The proof_record should be stored in the repository
+// The attested_record contains the strongRef reference
+```
+
+### Verifying Signatures
+
+Verify signatures embedded in records:
+
+```rust
+use atproto_attestation::{verify_all_signatures, VerificationStatus};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Signed record with signatures array
+    let signed_record = /* ... */;
+
+    // Verify all signatures (remote attestations will be unverified)
+    let reports = verify_all_signatures(&signed_record, None).await?;
+
+    for report in reports {
+        match report.status {
+            VerificationStatus::Valid { cid } => {
+                println!("✓ Signature {} is valid (CID: {})", report.index, cid);
+            }
+            VerificationStatus::Invalid { error } => {
+                println!("✗ Signature {} is invalid: {}", report.index, error);
+            }
+            VerificationStatus::Unverified { reason } => {
+                println!("? Signature {} unverified: {}", report.index, reason);
+            }
+        }
+    }
+
+    Ok(())
+}
+```
+
+### Verifying with Custom Key Resolver
+
+For signatures that reference DID document keys (not did:key), provide a key resolver:
+
+```rust
+use atproto_attestation::verify_all_signatures;
+use atproto_identity::key::IdentityDocumentKeyResolver;
+use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+
+    // Create identity and key resolvers
+    let identity_resolver = Arc::new(InnerIdentityResolver {
+        http_client: http_client.clone(),
+        dns_resolver: Arc::new(dns_resolver),
+        plc_hostname: "plc.directory".to_string(),
+    });
+    let key_resolver = IdentityDocumentKeyResolver::new(identity_resolver);
+
+    let signed_record = /* ... */;
+
+    // Verify with key resolver for DID document keys
+    let reports = verify_all_signatures(&signed_record, Some(&key_resolver)).await?;
+
+    Ok(())
+}
+```
+
+### Verifying Remote Attestations
+
+To verify remote attestations (strongRef), use `verify_all_signatures_with_resolver` and provide a `RecordResolver` that can fetch proof records:
+
+```rust
+use atproto_attestation::verify_all_signatures_with_resolver;
+use atproto_client::record_resolver::RecordResolver;
+use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};
+use atproto_identity::traits::IdentityResolver;
+use std::sync::Arc;
+
+// Custom record resolver that resolves DIDs to find PDS endpoints
+struct MyRecordResolver {
+    http_client: reqwest::Client,
+    identity_resolver: InnerIdentityResolver,
+}
+
+#[async_trait::async_trait]
+impl RecordResolver for MyRecordResolver {
+    async fn resolve<T>(&self, aturi: &str) -> anyhow::Result<T>
+    where
+        T: serde::de::DeserializeOwned + Send,
+    {
+        // Parse AT-URI, resolve DID to PDS, fetch record
+        // See atproto-attestation-verify.rs for full implementation
+        todo!()
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+
+    let identity_resolver = InnerIdentityResolver {
+        http_client: http_client.clone(),
+        dns_resolver: Arc::new(dns_resolver),
+        plc_hostname: "plc.directory".to_string(),
+    };
+
+    let record_resolver = MyRecordResolver {
+        http_client,
+        identity_resolver,
+    };
+
+    let signed_record = /* ... */;
+
+    // Verify all signatures including remote attestations
+    let reports = verify_all_signatures_with_resolver(&signed_record, None, Some(&record_resolver)).await?;
+
+    Ok(())
+}
+```
+
+### Manual CID Generation
+
+For advanced use cases, manually generate CIDs:
+
+```rust
+use atproto_attestation::{prepare_signing_record, create_cid};
+use serde_json::json;
+
+let record = json!({
+    "$type": "app.bsky.feed.post",
+    "text": "Manual CID generation"
+});
+
+let metadata = json!({
+    "$type": "com.example.signature",
+    "key": "did:key:z..."
+});
+
+// Prepare the signing record (adds $sig, removes signatures)
+let signing_record = prepare_signing_record(&record, &metadata)?;
+
+// Generate the CID
+let cid = create_cid(&signing_record)?;
+println!("CID: {}", cid);
+```
+
+## Command Line Usage
+
+### Signing Records
+
+#### Inline Attestation
+
+```bash
+# Sign with inline attestation (signature embedded in record)
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- \
+  inline \
+  record.json \
+  did:key:zQ3shNzMp4oaaQ1gQRzCxMGXFrSW3NEM1M9T6KCY9eA7HhyEA \
+  metadata.json
+
+# Using JSON strings instead of files
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- \
+  inline \
+  '{"$type":"app.bsky.feed.post","text":"Hello!"}' \
+  did:key:zQ3sh... \
+  '{"$type":"com.example.sig","key":"did:key:zQ3sh..."}'
+
+# Read record from stdin
+cat record.json | cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- \
+  inline \
+  - \
+  did:key:zQ3sh... \
+  metadata.json
+```
+
+#### Remote Attestation
+
+```bash
+# Create remote attestation (generates proof record + strongRef)
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-sign -- \
+  remote \
+  record.json \
+  did:plc:repo123... \
+  metadata.json
+
+# This outputs TWO JSON objects:
+# 1. Proof record (store this in the repository)
+# 2. Source record with strongRef attestation
+```
+
+### Verifying Signatures
+
+#### Verify All Signatures in a Record
+
+```bash
+# Verify all signatures in a record from file
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- \
+  ./signed_record.json
+
+# Verify all signatures from AT-URI (fetches from PDS)
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- \
+  at://did:plc:abc123/app.bsky.feed.post/3k2k4j5h6g
+
+# Verify from stdin
+cat signed_record.json | cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- -
+
+# Verify from inline JSON
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- \
+  '{"$type":"app.bsky.feed.post","text":"Hello","signatures":[...]}'
+
+# Output shows each signature status:
+# ✓ Signature 0 valid (key: did:key:zQ3sh...pb3) [CID: bafyrei...]
+# ? Signature 1 unverified: Remote attestations require fetching the proof record via strongRef.
+#
+# Summary: 2 total, 1 valid
+```
+
+#### Verify Specific Attestation Against Record
+
+```bash
+# Verify a specific attestation record (both from files)
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- \
+  ./record.json \
+  ./attestation.json
+
+# Verify attestation from AT-URI against local record
+cargo run --package atproto-attestation --features clap,tokio --bin atproto-attestation-verify -- \
+  ./record.json \
+  at://did:plc:xyz/com.example.attestation/abc123
+
+# On success, outputs:
+# OK
+# CID: bafyrei...
+```
+
+## Attestation Specification
+
+This crate implements the CID-first attestation specification, which ensures:
+
+1. **Deterministic signing**: Records are serialized to DAG-CBOR with `$sig` metadata, producing consistent CIDs
+2. **Content addressing**: Signatures are over CID bytes, not the full record
+3. **Flexible metadata**: Custom fields in `$sig` are preserved and included in the CID calculation
+4. **Signature normalization**: ECDSA signatures are normalized to low-S form
+5. **Multiple attestations**: Records can have multiple signatures in the `signatures` array
+
+### Signature Structure
+
+Inline attestation entry:
+```json
+{
+  "$type": "com.example.signature",
+  "key": "did:key:z...",
+  "issuer": "did:plc:...",
+  "signature": {
+    "$bytes": "base64-signature"
+  }
+}
+```
+
+Remote attestation entry (strongRef):
+```json
+{
+  "$type": "com.atproto.repo.strongRef",
+  "uri": "at://did:plc:repo/com.example.attestation/tid",
+  "cid": "bafyrei..."
+}
+```
+
+## Error Handling
+
+The crate provides structured error types via `AttestationError`:
+
+- `RecordMustBeObject`: Input must be a JSON object
+- `MetadataMustBeObject`: Attestation metadata must be a JSON object
+- `SigMetadataMissing`: No `$sig` field found in prepared record
+- `SignatureCreationFailed`: Key signing operation failed
+- `SignatureValidationFailed`: Signature verification failed
+- `SignatureNotNormalized`: ECDSA signature not in low-S form
+- `KeyResolutionFailed`: Could not resolve verification key
+- `UnsupportedKeyType`: Key type not supported for signing/verification
+
+## Security Considerations
+
+- **Key management**: Private keys should be protected and never logged or transmitted
+- **Signature normalization**: All signatures are normalized to low-S form to prevent malleability
+- **CID verification**: Always verify signatures against the reconstructed CID, not the record content
+- **Key resolution**: Use trusted key resolvers to prevent key substitution attacks
+- **Timestamp validation**: Check `issuedAt` and `expiry` fields if present in metadata
+
+## License
+
+MIT License

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

···
+//! Command-line tool for signing AT Protocol records with inline or remote attestations.
+//!
+//! This tool creates cryptographic signatures for AT Protocol records using the CID-first
+//! attestation specification. It supports both inline attestations (embedding signatures
+//! directly in records) and remote attestations (creating separate proof records).
+//!
+//! ## Usage Patterns
+//!
+//! ### Remote Attestation
+//! ```bash
+//! atproto-attestation-sign remote <source_record> <repository_did> <metadata_record>
+//! ```
+//!
+//! ### Inline Attestation
+//! ```bash
+//! atproto-attestation-sign inline <source_record> <signing_key> <metadata_record>
+//! ```
+//!
+//! ## Arguments
+//!
+//! - `source_record`: JSON string or path to JSON file containing the record being attested
+//! - `repository_did`: (Remote mode) DID of the repository that will contain the remote attestation record
+//! - `signing_key`: (Inline mode) Private key string (did:key format) used to sign the attestation
+//! - `metadata_record`: JSON string or path to JSON file with attestation metadata used during CID creation
+//!
+//! ## Examples
+//!
+//! ```bash
+//! # Remote attestation - creates proof record and strongRef
+//! atproto-attestation-sign remote \
+//!   record.json \
+//!   did:plc:xyz123... \
+//!   metadata.json
+//!
+//! # Inline attestation - embeds signature in record
+//! atproto-attestation-sign inline \
+//!   record.json \
+//!   did:key:z42tv1pb3... \
+//!   '{"$type":"com.example.attestation","purpose":"demo"}'
+//!
+//! # Read from stdin
+//! cat record.json | atproto-attestation-sign inline \
+//!   - \
+//!   did:key:z42tv1pb3... \
+//!   metadata.json
+//! ```
+
+use anyhow::{Context, Result, anyhow};
+use atproto_attestation::{
+    create_inline_attestation, create_remote_attestation, create_remote_attestation_reference,
+};
+use atproto_identity::key::identify_key;
+use clap::{Parser, Subcommand};
+use serde_json::Value;
+use std::{
+    fs,
+    io::{self, Read},
+    path::Path,
+};
+
+/// Command-line tool for signing AT Protocol records with cryptographic attestations.
+///
+/// Creates inline or remote attestations following the CID-first specification.
+/// Inline attestations embed signatures directly in records, while remote attestations
+/// generate separate proof records with strongRef references.
+#[derive(Parser)]
+#[command(
+    name = "atproto-attestation-sign",
+    version,
+    about = "Sign AT Protocol records with cryptographic attestations",
+    long_about = "
+A command-line tool for signing AT Protocol records using the CID-first attestation
+specification. Supports both inline attestations (signatures embedded in the record)
+and remote attestations (separate proof records with CID references).
+
+MODES:
+  remote    Creates a separate proof record with strongRef reference
+            Syntax: remote <source_record> <repository_did> <metadata_record>
+
+  inline    Embeds signature bytes directly in the record
+            Syntax: inline <source_record> <signing_key> <metadata_record>
+
+ARGUMENTS:
+  source_record      JSON string or file path to the record being attested
+  repository_did     (Remote) DID of repository containing the attestation record
+  signing_key        (Inline) Private key in did:key format for signing
+  metadata_record    JSON string or file path with attestation metadata
+
+EXAMPLES:
+  # Remote attestation (creates proof record + strongRef):
+  atproto-attestation-sign remote \\
+    record.json \\
+    did:plc:xyz123abc... \\
+    metadata.json
+
+  # Inline attestation (embeds signature):
+  atproto-attestation-sign inline \\
+    record.json \\
+    did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \\
+    '{\"$type\":\"com.example.attestation\",\"purpose\":\"demo\"}'
+
+  # Read source record from stdin:
+  cat record.json | atproto-attestation-sign inline \\
+    - \\
+    did:key:z42tv1pb3... \\
+    metadata.json
+
+OUTPUT:
+  Remote mode outputs TWO JSON objects:
+    1. The proof record (to be stored in the repository)
+    2. The source record with strongRef attestation appended
+
+  Inline mode outputs ONE JSON object:
+    - The source record with inline attestation embedded
+"
+)]
+struct Args {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Create a remote attestation with separate proof record
+    ///
+    /// Generates a proof record containing the CID and returns both the proof
+    /// record (to be stored in the repository) and the source record with a
+    /// strongRef attestation reference.
+    #[command(visible_alias = "r")]
+    Remote {
+        /// Source record JSON string or file path (use '-' for stdin)
+        source_record: String,
+
+        /// Repository DID that will contain the remote attestation record
+        repository_did: String,
+
+        /// Attestation metadata JSON string or file path
+        metadata_record: String,
+    },
+
+    /// Create an inline attestation with embedded signature
+    ///
+    /// Signs the record with the provided private key and embeds the signature
+    /// directly in the record's attestation structure.
+    #[command(visible_alias = "i")]
+    Inline {
+        /// Source record JSON string or file path (use '-' for stdin)
+        source_record: String,
+
+        /// Private signing key in did:key format (e.g., did:key:z...)
+        signing_key: String,
+
+        /// Attestation metadata JSON string or file path
+        metadata_record: String,
+    },
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let args = Args::parse();
+
+    match args.command {
+        Commands::Remote {
+            source_record,
+            repository_did,
+            metadata_record,
+        } => handle_remote_attestation(&source_record, &repository_did, &metadata_record)?,
+
+        Commands::Inline {
+            source_record,
+            signing_key,
+            metadata_record,
+        } => handle_inline_attestation(&source_record, &signing_key, &metadata_record)?,
+    }
+
+    Ok(())
+}
+
+/// Handle remote attestation mode.
+///
+/// Creates a proof record and appends a strongRef to the source record.
+/// Outputs both the proof record and the updated source record.
+fn handle_remote_attestation(
+    source_record: &str,
+    repository_did: &str,
+    metadata_record: &str,
+) -> Result<()> {
+    // Load source record and metadata
+    let record_json = load_json_input(source_record)?;
+    let metadata_json = load_json_input(metadata_record)?;
+
+    // Validate inputs
+    if !record_json.is_object() {
+        return Err(anyhow!("Source record must be a JSON object"));
+    }
+
+    if !metadata_json.is_object() {
+        return Err(anyhow!("Metadata record must be a JSON object"));
+    }
+
+    // Validate repository DID
+    if !repository_did.starts_with("did:") {
+        return Err(anyhow!(
+            "Repository DID must start with 'did:' prefix, got: {}",
+            repository_did
+        ));
+    }
+
+    // Create the remote attestation proof record
+    let proof_record = create_remote_attestation(&record_json, &metadata_json)
+        .context("Failed to create remote attestation proof record")?;
+
+    // Create the source record with strongRef reference
+    let attested_record =
+        create_remote_attestation_reference(&record_json, &proof_record, repository_did)
+            .context("Failed to create remote attestation reference")?;
+
+    // Output both records
+    println!("=== Proof Record (store in repository) ===");
+    println!("{}", serde_json::to_string_pretty(&proof_record)?);
+    println!();
+    println!("=== Attested Record (with strongRef) ===");
+    println!("{}", serde_json::to_string_pretty(&attested_record)?);
+
+    Ok(())
+}
+
+/// Handle inline attestation mode.
+///
+/// Signs the record with the provided key and embeds the signature.
+/// Outputs the record with inline attestation.
+fn handle_inline_attestation(
+    source_record: &str,
+    signing_key: &str,
+    metadata_record: &str,
+) -> Result<()> {
+    // Load source record and metadata
+    let record_json = load_json_input(source_record)?;
+    let metadata_json = load_json_input(metadata_record)?;
+
+    // Validate inputs
+    if !record_json.is_object() {
+        return Err(anyhow!("Source record must be a JSON object"));
+    }
+
+    if !metadata_json.is_object() {
+        return Err(anyhow!("Metadata record must be a JSON object"));
+    }
+
+    // Parse the signing key
+    let key_data = identify_key(signing_key)
+        .with_context(|| format!("Failed to parse signing key: {}", signing_key))?;
+
+    // Create inline attestation
+    let signed_record = create_inline_attestation(&record_json, &metadata_json, &key_data)
+        .context("Failed to create inline attestation")?;
+
+    // Output the signed record
+    println!("{}", serde_json::to_string_pretty(&signed_record)?);
+
+    Ok(())
+}
+
+/// Load JSON input from various sources.
+///
+/// Accepts:
+/// - "-" for stdin
+/// - File paths (if the file exists)
+/// - Direct JSON strings
+///
+/// Returns the parsed JSON value or an error.
+fn load_json_input(argument: &str) -> Result<Value> {
+    // Handle stdin input
+    if argument == "-" {
+        let mut input = String::new();
+        io::stdin()
+            .read_to_string(&mut input)
+            .context("Failed to read from stdin")?;
+        return serde_json::from_str(&input).context("Failed to parse JSON from stdin");
+    }
+
+    // Try as file path first
+    let path = Path::new(argument);
+    if path.is_file() {
+        let file_content = fs::read_to_string(path)
+            .with_context(|| format!("Failed to read file: {}", argument))?;
+        return serde_json::from_str(&file_content)
+            .with_context(|| format!("Failed to parse JSON from file: {}", argument));
+    }
+
+    // Try as direct JSON string
+    serde_json::from_str(argument).with_context(|| {
+        format!(
+            "Argument is neither valid JSON nor a readable file: {}",
+            argument
+        )
+    })
+}

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

···
+//! Command-line tool for verifying cryptographic signatures on AT Protocol records.
+//!
+//! This tool validates attestation signatures on AT Protocol records by reconstructing
+//! the signed content and verifying ECDSA signatures against public keys embedded in the
+//! attestation metadata.
+//!
+//! ## Usage Patterns
+//!
+//! ### Verify all signatures in a record
+//! ```bash
+//! atproto-attestation-verify <record>
+//! ```
+//!
+//! ### Verify a specific attestation against a record
+//! ```bash
+//! atproto-attestation-verify <record> <attestation>
+//! ```
+//!
+//! ## Parameter Formats
+//!
+//! Both `record` and `attestation` parameters accept:
+//! - **JSON string**: Direct JSON payload (e.g., `'{"$type":"...","text":"..."}'`)
+//! - **File path**: Path to a JSON file (e.g., `./record.json`)
+//! - **AT-URI**: AT Protocol URI to fetch the record (e.g., `at://did:plc:abc/app.bsky.feed.post/123`)
+//!
+//! ## Examples
+//!
+//! ```bash
+//! # Verify all signatures in a record from file
+//! atproto-attestation-verify ./signed_post.json
+//!
+//! # Verify all signatures in a record from AT-URI
+//! atproto-attestation-verify at://did:plc:abc123/app.bsky.feed.post/3k2k4j5h6g
+//!
+//! # Verify specific attestation against a record (both from files)
+//! atproto-attestation-verify ./record.json ./attestation.json
+//!
+//! # Verify specific attestation (from AT-URI) against record (from file)
+//! atproto-attestation-verify ./record.json at://did:plc:xyz/com.example.attestation/abc123
+//!
+//! # Read record from stdin, verify all signatures
+//! cat signed.json | atproto-attestation-verify -
+//!
+//! # Verify inline JSON
+//! atproto-attestation-verify '{"$type":"app.bsky.feed.post","text":"Hello","signatures":[...]}'
+//! ```
+
+use anyhow::{Context, Result, anyhow};
+use atproto_attestation::{VerificationStatus, verify_all_signatures_with_resolver};
+use clap::Parser;
+use serde_json::Value;
+use std::{
+    fs,
+    io::{self, Read},
+    path::Path,
+};
+
+/// Command-line tool for verifying cryptographic signatures on AT Protocol records.
+///
+/// Validates attestation signatures by reconstructing signed content and checking
+/// ECDSA signatures against embedded public keys. Supports verifying all signatures
+/// in a record or validating a specific attestation record.
+#[derive(Parser)]
+#[command(
+    name = "atproto-attestation-verify",
+    version,
+    about = "Verify cryptographic signatures of AT Protocol records",
+    long_about = "
+A command-line tool for verifying cryptographic signatures of AT Protocol records.
+
+USAGE:
+  atproto-attestation-verify <record>                 Verify all signatures in record
+  atproto-attestation-verify <record> <attestation>   Verify specific attestation
+
+PARAMETER FORMATS:
+  Each parameter accepts JSON strings, file paths, or AT-URIs:
+  - JSON string:  '{\"$type\":\"...\",\"text\":\"...\"}'
+  - File path:    ./record.json
+  - AT-URI:       at://did:plc:abc/app.bsky.feed.post/123
+  - Stdin:        - (for record parameter only)
+
+EXAMPLES:
+  # Verify all signatures in a record:
+  atproto-attestation-verify ./signed_post.json
+  atproto-attestation-verify at://did:plc:abc/app.bsky.feed.post/123
+
+  # Verify specific attestation:
+  atproto-attestation-verify ./record.json ./attestation.json
+  atproto-attestation-verify ./record.json at://did:plc:xyz/com.example.attestation/abc
+
+  # Read from stdin:
+  cat signed.json | atproto-attestation-verify -
+
+OUTPUT:
+  Single record mode:   Reports each signature with ✓ (valid), ✗ (invalid), or ? (unverified)
+  Attestation mode:     Outputs 'OK' on success, error message on failure
+
+VERIFICATION:
+  - Inline signatures are verified by reconstructing $sig and validating against embedded keys
+  - Remote attestations (strongRef) are reported as unverified (require fetching proof record)
+  - Keys are resolved from did:key identifiers or require a key resolver for DID document keys
+"
+)]
+struct Args {
+    /// Record to verify - JSON string, file path, AT-URI, or '-' for stdin
+    record: String,
+
+    /// Optional attestation record to verify against the record - JSON string, file path, or AT-URI
+    attestation: Option<String>,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let args = Args::parse();
+
+    // Load the record
+    let record = load_input(&args.record, true)
+        .await
+        .context("Failed to load record")?;
+
+    if !record.is_object() {
+        return Err(anyhow!("Record must be a JSON object"));
+    }
+
+    // Determine verification mode
+    match args.attestation {
+        None => {
+            // Mode 1: Verify all signatures in the record
+            verify_all_mode(&record).await
+        }
+        Some(attestation_input) => {
+            // Mode 2: Verify specific attestation against record
+            let attestation = load_input(&attestation_input, false)
+                .await
+                .context("Failed to load attestation")?;
+
+            if !attestation.is_object() {
+                return Err(anyhow!("Attestation must be a JSON object"));
+            }
+
+            verify_attestation_mode(&record, &attestation).await
+        }
+    }
+}
+
+/// Mode 1: Verify all signatures contained in the record.
+///
+/// Reports each signature with status indicators:
+/// - ✓ Valid signature
+/// - ✗ Invalid signature
+/// - ? Unverified (e.g., remote attestations requiring proof record fetch)
+async fn verify_all_mode(record: &Value) -> Result<()> {
+    // Create an identity resolver for fetching remote attestations
+    use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};
+    use std::sync::Arc;
+
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+
+    let identity_resolver = InnerIdentityResolver {
+        http_client: http_client.clone(),
+        dns_resolver: Arc::new(dns_resolver),
+        plc_hostname: "plc.directory".to_string(),
+    };
+
+    // Create record resolver that can fetch remote attestation proof records
+    let record_resolver = RemoteAttestationResolver {
+        http_client,
+        identity_resolver,
+    };
+
+    let reports = verify_all_signatures_with_resolver(record, None, Some(&record_resolver))
+        .await
+        .context("Failed to verify signatures")?;
+
+    if reports.is_empty() {
+        return Err(anyhow!("No signatures found in record"));
+    }
+
+    let mut all_valid = true;
+    let mut has_errors = false;
+
+    for report in &reports {
+        match &report.status {
+            VerificationStatus::Valid { cid } => {
+                let key_info = report
+                    .key
+                    .as_deref()
+                    .map(|k| format!(" (key: {})", truncate_did(k)))
+                    .unwrap_or_default();
+                println!(
+                    "✓ Signature {} valid{} [CID: {}]",
+                    report.index, key_info, cid
+                );
+            }
+            VerificationStatus::Invalid { error } => {
+                println!("✗ Signature {} invalid: {}", report.index, error);
+                all_valid = false;
+                has_errors = true;
+            }
+            VerificationStatus::Unverified { reason } => {
+                println!("? Signature {} unverified: {}", report.index, reason);
+                all_valid = false;
+            }
+        }
+    }
+
+    println!();
+    println!(
+        "Summary: {} total, {} valid",
+        reports.len(),
+        reports
+            .iter()
+            .filter(|r| matches!(r.status, VerificationStatus::Valid { .. }))
+            .count()
+    );
+
+    if has_errors {
+        Err(anyhow!("One or more signatures are invalid"))
+    } else if !all_valid {
+        Err(anyhow!("One or more signatures could not be verified"))
+    } else {
+        Ok(())
+    }
+}
+
+/// Mode 2: Verify a specific attestation record against the provided record.
+///
+/// The attestation should be a standalone attestation object (e.g., from a remote proof record)
+/// that will be verified against the record's content.
+async fn verify_attestation_mode(record: &Value, attestation: &Value) -> Result<()> {
+    // The attestation should have a CID field that we can use to verify
+    let attestation_obj = attestation
+        .as_object()
+        .ok_or_else(|| anyhow!("Attestation must be a JSON object"))?;
+
+    // Get the CID from the attestation
+    let cid_str = attestation_obj
+        .get("cid")
+        .and_then(Value::as_str)
+        .ok_or_else(|| anyhow!("Attestation must contain a 'cid' field"))?;
+
+    // Prepare the signing record with the attestation metadata
+    let mut signing_metadata = attestation_obj.clone();
+    signing_metadata.remove("cid");
+    signing_metadata.remove("signature");
+
+    let signing_record =
+        atproto_attestation::prepare_signing_record(record, &Value::Object(signing_metadata))
+            .context("Failed to prepare signing record")?;
+
+    // Generate the CID from the signing record
+    let computed_cid =
+        atproto_attestation::create_cid(&signing_record).context("Failed to generate CID")?;
+
+    // Compare CIDs
+    if computed_cid.to_string() != cid_str {
+        return Err(anyhow!(
+            "CID mismatch: attestation claims {}, but computed {}",
+            cid_str,
+            computed_cid
+        ));
+    }
+
+    println!("OK");
+    println!("CID: {}", computed_cid);
+
+    Ok(())
+}
+
+/// Load input from various sources: JSON string, file path, AT-URI, or stdin.
+///
+/// The `allow_stdin` parameter controls whether "-" is interpreted as stdin.
+async fn load_input(input: &str, allow_stdin: bool) -> Result<Value> {
+    // Handle stdin
+    if input == "-" {
+        if !allow_stdin {
+            return Err(anyhow!(
+                "Stdin ('-') is only supported for the record parameter"
+            ));
+        }
+
+        let mut buffer = String::new();
+        io::stdin()
+            .read_to_string(&mut buffer)
+            .context("Failed to read from stdin")?;
+
+        return serde_json::from_str(&buffer).context("Failed to parse JSON from stdin");
+    }
+
+    // Check if it's an AT-URI
+    if input.starts_with("at://") {
+        return load_from_aturi(input)
+            .await
+            .with_context(|| format!("Failed to fetch record from AT-URI: {}", input));
+    }
+
+    // Try as file path
+    let path = Path::new(input);
+    if path.exists() && path.is_file() {
+        let content =
+            fs::read_to_string(path).with_context(|| format!("Failed to read file: {}", input))?;
+
+        return serde_json::from_str(&content)
+            .with_context(|| format!("Failed to parse JSON from file: {}", input));
+    }
+
+    // Try as direct JSON string
+    serde_json::from_str(input).with_context(|| {
+        format!(
+            "Input is not valid JSON, an existing file, or an AT-URI: {}",
+            input
+        )
+    })
+}
+
+/// Load a record from an AT-URI by fetching it from a PDS.
+///
+/// This requires resolving the DID to find the PDS endpoint, then fetching the record.
+async fn load_from_aturi(aturi: &str) -> Result<Value> {
+    use atproto_identity::resolve::{HickoryDnsResolver, InnerIdentityResolver};
+    use atproto_record::aturi::ATURI;
+    use std::str::FromStr;
+    use std::sync::Arc;
+
+    // Parse the AT-URI
+    let parsed = ATURI::from_str(aturi).map_err(|e| anyhow!("Invalid AT-URI: {}", e))?;
+
+    // Create resolver components
+    let http_client = reqwest::Client::new();
+    let dns_resolver = HickoryDnsResolver::create_resolver(&[]);
+
+    // Create identity resolver
+    let identity_resolver = InnerIdentityResolver {
+        http_client: http_client.clone(),
+        dns_resolver: Arc::new(dns_resolver),
+        plc_hostname: "plc.directory".to_string(),
+    };
+
+    // Resolve the DID to get the PDS endpoint
+    let document = identity_resolver
+        .resolve(&parsed.authority)
+        .await
+        .with_context(|| format!("Failed to resolve DID: {}", parsed.authority))?;
+
+    // Find the PDS endpoint
+    let pds_endpoint = document
+        .service
+        .iter()
+        .find(|s| s.r#type == "AtprotoPersonalDataServer")
+        .map(|s| s.service_endpoint.as_str())
+        .ok_or_else(|| anyhow!("No PDS endpoint found for DID: {}", parsed.authority))?;
+
+    // Fetch the record using the XRPC client
+    let response = atproto_client::com::atproto::repo::get_record(
+        &http_client,
+        &atproto_client::client::Auth::None,
+        pds_endpoint,
+        &parsed.authority,
+        &parsed.collection,
+        &parsed.record_key,
+        None,
+    )
+    .await
+    .with_context(|| format!("Failed to fetch record from PDS: {}", pds_endpoint))?;
+
+    match response {
+        atproto_client::com::atproto::repo::GetRecordResponse::Record { value, .. } => Ok(value),
+        atproto_client::com::atproto::repo::GetRecordResponse::Error(error) => {
+            Err(anyhow!("Failed to fetch record: {}", error.error_message()))
+        }
+    }
+}
+
+/// Truncate a DID or did:key for display purposes.
+fn truncate_did(did: &str) -> String {
+    if did.len() > 40 {
+        format!("{}...{}", &did[..20], &did[did.len() - 12..])
+    } else {
+        did.to_string()
+    }
+}
+
+/// Record resolver for remote attestations that resolves DIDs to find PDS endpoints.
+struct RemoteAttestationResolver {
+    http_client: reqwest::Client,
+    identity_resolver: atproto_identity::resolve::InnerIdentityResolver,
+}
+
+#[async_trait::async_trait]
+impl atproto_client::record_resolver::RecordResolver for RemoteAttestationResolver {
+    async fn resolve<T>(&self, aturi: &str) -> anyhow::Result<T>
+    where
+        T: serde::de::DeserializeOwned + Send,
+    {
+        use atproto_record::aturi::ATURI;
+        use std::str::FromStr;
+
+        // Parse the AT-URI
+        let parsed = ATURI::from_str(aturi).map_err(|e| anyhow!("Invalid AT-URI: {}", e))?;
+
+        // Resolve the DID to get the PDS endpoint
+        let document = self
+            .identity_resolver
+            .resolve(&parsed.authority)
+            .await
+            .with_context(|| format!("Failed to resolve DID: {}", parsed.authority))?;
+
+        // Find the PDS endpoint
+        let pds_endpoint = document
+            .service
+            .iter()
+            .find(|s| s.r#type == "AtprotoPersonalDataServer")
+            .map(|s| s.service_endpoint.as_str())
+            .ok_or_else(|| anyhow!("No PDS endpoint found for DID: {}", parsed.authority))?;
+
+        // Fetch the record using the XRPC client
+        let response = atproto_client::com::atproto::repo::get_record(
+            &self.http_client,
+            &atproto_client::client::Auth::None,
+            pds_endpoint,
+            &parsed.authority,
+            &parsed.collection,
+            &parsed.record_key,
+            None,
+        )
+        .await
+        .with_context(|| format!("Failed to fetch record from PDS: {}", pds_endpoint))?;
+
+        match response {
+            atproto_client::com::atproto::repo::GetRecordResponse::Record { value, .. } => {
+                serde_json::from_value(value)
+                    .map_err(|e| anyhow!("Failed to deserialize record: {}", e))
+            }
+            atproto_client::com::atproto::repo::GetRecordResponse::Error(error) => {
+                Err(anyhow!("Failed to fetch record: {}", error.error_message()))
+            }
+        }
+    }
+}

crates/atproto-attestation/src/errors.rs

···
+//! Errors that can occur during attestation preparation and verification.
+//!
+//! Covers CID construction, `$sig` metadata validation, inline attestation
+//! structure checks, and identity/key resolution failures.
+
+use thiserror::Error;
+
+/// Errors that can occur during attestation preparation and verification.
+#[derive(Debug, Error)]
+pub enum AttestationError {
+    /// Error when the record value is not a JSON object.
+    #[error("error-atproto-attestation-1 Record must be a JSON object")]
+    RecordMustBeObject,
+
+    /// Error when attestation metadata is not a JSON object.
+    #[error("error-atproto-attestation-2 Attestation metadata must be a JSON object")]
+    MetadataMustBeObject,
+
+    /// Error when attestation metadata is missing a required field.
+    #[error("error-atproto-attestation-3 Attestation metadata missing required field: {field}")]
+    MetadataMissingField {
+        /// Name of the missing field.
+        field: String,
+    },
+
+    /// Error when attestation metadata omits the `$type` discriminator.
+    #[error("error-atproto-attestation-4 Attestation metadata must include a string `$type` field")]
+    MetadataMissingSigType,
+
+    /// Error when the record does not contain a signatures array.
+    #[error("error-atproto-attestation-5 Signatures array not found on record")]
+    SignaturesArrayMissing,
+
+    /// Error when the signatures field exists but is not an array.
+    #[error("error-atproto-attestation-6 Signatures field must be an array")]
+    SignaturesFieldInvalid,
+
+    /// Error when attempting to verify a signature at an invalid index.
+    #[error("error-atproto-attestation-7 Signature index {index} out of bounds")]
+    SignatureIndexOutOfBounds {
+        /// Index that was requested.
+        index: usize,
+    },
+
+    /// Error when a signature object is missing a required field.
+    #[error("error-atproto-attestation-8 Signature object missing required field: {field}")]
+    SignatureMissingField {
+        /// Field name that was expected.
+        field: String,
+    },
+
+    /// Error when a signature object uses an invalid `$type` for inline attestations.
+    #[error(
+        "error-atproto-attestation-9 Inline attestation `$type` cannot be `com.atproto.repo.strongRef`"
+    )]
+    InlineAttestationTypeInvalid,
+
+    /// Error when a remote attestation entry does not use the strongRef type.
+    #[error(
+        "error-atproto-attestation-10 Remote attestation entries must use `com.atproto.repo.strongRef`"
+    )]
+    RemoteAttestationTypeInvalid,
+
+    /// Error when a remote attestation entry is missing a CID.
+    #[error(
+        "error-atproto-attestation-11 Remote attestation entries must include a string `cid` field"
+    )]
+    RemoteAttestationMissingCid,
+
+    /// Error when signature bytes are not provided using the `$bytes` wrapper.
+    #[error(
+        "error-atproto-attestation-12 Signature bytes must be encoded as `{{\"$bytes\": \"...\"}}`"
+    )]
+    SignatureBytesFormatInvalid,
+
+    /// Error when record serialization to DAG-CBOR fails.
+    #[error("error-atproto-attestation-13 Record serialization failed: {error}")]
+    RecordSerializationFailed {
+        /// Underlying serialization error.
+        #[from]
+        error: serde_ipld_dagcbor::EncodeError<std::collections::TryReserveError>,
+    },
+
+    /// Error when `$sig` metadata is missing from the record before CID creation.
+    #[error("error-atproto-attestation-14 `$sig` metadata must be present before generating a CID")]
+    SigMetadataMissing,
+
+    /// Error when `$sig` metadata is not an object.
+    #[error("error-atproto-attestation-15 `$sig` metadata must be a JSON object")]
+    SigMetadataNotObject,
+
+    /// Error when `$sig` metadata omits the `$type` discriminator.
+    #[error("error-atproto-attestation-16 `$sig` metadata must include a string `$type` field")]
+    SigMetadataMissingType,
+
+    /// Error when a key resolver is required but not provided.
+    #[error("error-atproto-attestation-17 Key resolver required to resolve key reference: {key}")]
+    KeyResolverRequired {
+        /// Key reference that required resolution.
+        key: String,
+    },
+
+    /// Error when key resolution using the provided resolver fails.
+    #[error("error-atproto-attestation-18 Failed to resolve key reference {key}: {error}")]
+    KeyResolutionFailed {
+        /// Key reference that was being resolved.
+        key: String,
+        /// Underlying resolution error.
+        #[source]
+        error: anyhow::Error,
+    },
+
+    /// Error when the key type is unsupported for inline attestations.
+    #[error("error-atproto-attestation-21 Unsupported key type for attestation: {key_type}")]
+    UnsupportedKeyType {
+        /// Unsupported key type.
+        key_type: atproto_identity::key::KeyType,
+    },
+
+    /// Error when signature decoding fails.
+    #[error("error-atproto-attestation-22 Signature decoding failed: {error}")]
+    SignatureDecodingFailed {
+        /// Underlying base64 decoding error.
+        #[from]
+        error: base64::DecodeError,
+    },
+
+    /// Error when signature length does not match the expected size.
+    #[error(
+        "error-atproto-attestation-23 Signature length invalid: expected {expected} bytes, found {actual}"
+    )]
+    SignatureLengthInvalid {
+        /// Expected signature length.
+        expected: usize,
+        /// Actual signature length.
+        actual: usize,
+    },
+
+    /// Error when signature is not normalized to low-S form.
+    #[error("error-atproto-attestation-24 Signature must be normalized to low-S form")]
+    SignatureNotNormalized,
+
+    /// Error when cryptographic verification fails.
+    #[error("error-atproto-attestation-25 Signature verification failed: {error}")]
+    SignatureValidationFailed {
+        /// Underlying key validation error.
+        #[source]
+        error: atproto_identity::errors::KeyError,
+    },
+
+    /// Error when multihash construction for CID generation fails.
+    #[error("error-atproto-attestation-26 Failed to construct CID multihash: {error}")]
+    MultihashWrapFailed {
+        /// Underlying multihash error.
+        #[source]
+        error: multihash::Error,
+    },
+
+    /// Error when signature creation fails during inline attestation.
+    #[error("error-atproto-attestation-27 Signature creation failed: {error}")]
+    SignatureCreationFailed {
+        /// Underlying signing error.
+        #[source]
+        error: atproto_identity::errors::KeyError,
+    },
+
+    /// Error when fetching a remote attestation proof record fails.
+    #[error("error-atproto-attestation-28 Failed to fetch remote attestation from {uri}: {error}")]
+    RemoteAttestationFetchFailed {
+        /// AT-URI that failed to resolve.
+        uri: String,
+        /// Underlying fetch error.
+        #[source]
+        error: anyhow::Error,
+    },
+
+    /// Error when the CID of a remote attestation proof record doesn't match expected.
+    #[error(
+        "error-atproto-attestation-29 Remote attestation CID mismatch: expected {expected}, got {actual}"
+    )]
+    RemoteAttestationCidMismatch {
+        /// Expected CID.
+        expected: String,
+        /// Actual CID.
+        actual: String,
+    },
+
+    /// Error when parsing a CID string fails.
+    #[error("error-atproto-attestation-30 Invalid CID format: {cid}")]
+    InvalidCid {
+        /// Invalid CID string.
+        cid: String,
+    },
+}

crates/atproto-attestation/src/lib.rs

···
+//! AT Protocol record attestation utilities based on the CID-first specification.
+//!
+//! This crate implements helpers for constructing deterministic signing payloads,
+//! creating inline and remote attestation references, and verifying signatures
+//! against DID verification methods. It follows the requirements documented in
+//! `bluesky-attestation-tee/documentation/spec/attestation.md`.
+//!
+//! The workflow for inline attestations is:
+//! 1. Prepare a signing record with [`prepare_signing_record`].
+//! 2. Generate the content identifier using [`create_cid`].
+//! 3. Sign the CID bytes externally and embed the attestation with
+//!    [`create_inline_attestation_reference`].
+//! 4. Verify signatures with [`verify_signature`] or [`verify_all_signatures`].
+//!
+//! Remote attestations follow the same `$sig` preparation process but store the
+//! generated CID in a proof record and reference it with
+//! [`create_remote_attestation_reference`].
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+pub mod errors;
+
+use atproto_record::tid::Tid;
+pub use errors::AttestationError;
+
+use atproto_identity::key::{KeyData, KeyResolver, KeyType, identify_key, sign, validate};
+use base64::{
+    Engine,
+    alphabet::STANDARD as STANDARD_ALPHABET,
+    engine::{
+        DecodePaddingMode,
+        general_purpose::{GeneralPurpose, GeneralPurposeConfig},
+    },
+};
+use cid::Cid;
+use elliptic_curve::scalar::IsHigh;
+use k256::ecdsa::Signature as K256Signature;
+use multihash::Multihash;
+use p256::ecdsa::Signature as P256Signature;
+use serde_json::{Map, Value, json};
+use sha2::{Digest, Sha256};
+
+// Base64 engine that accepts both padded and unpadded input for maximum compatibility
+// with various AT Protocol implementations. Uses standard encoding with padding for output,
+// but accepts any padding format for decoding.
+const BASE64: GeneralPurpose = GeneralPurpose::new(
+    &STANDARD_ALPHABET,
+    GeneralPurposeConfig::new()
+        .with_encode_padding(true)
+        .with_decode_padding_mode(DecodePaddingMode::Indifferent),
+);
+
+const STRONG_REF_TYPE: &str = "com.atproto.repo.strongRef";
+
+/// Resolver trait for retrieving remote attestation records by AT URI.
+///
+/// Kind of attestation represented within the `signatures` array.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum AttestationKind {
+    /// Inline attestation containing signature bytes.
+    Inline,
+    /// Remote attestation referencing a proof record via strongRef.
+    Remote,
+}
+
+/// Result of verifying a single attestation entry.
+#[derive(Debug)]
+pub enum VerificationStatus {
+    /// Signature is valid for the reconstructed signing payload.
+    Valid {
+        /// CID produced for the reconstructed record.
+        cid: Cid,
+    },
+    /// Signature verification or metadata validation failed.
+    Invalid {
+        /// Failure reason.
+        error: AttestationError,
+    },
+    /// Attestation cannot be verified locally (e.g., remote references).
+    Unverified {
+        /// Explanation for why verification was skipped.
+        reason: String,
+    },
+}
+
+/// Structured verification report for a single attestation entry.
+#[derive(Debug)]
+pub struct VerificationReport {
+    /// Zero-based index of the signature in the record's `signatures` array.
+    pub index: usize,
+    /// Detected attestation kind.
+    pub kind: AttestationKind,
+    /// `$type` discriminator from the attestation entry, if present.
+    pub signature_type: Option<String>,
+    /// Key reference for inline signatures (if available).
+    pub key: Option<String>,
+    /// Verification outcome.
+    pub status: VerificationStatus,
+}
+
+/// Create a deterministic CID for a record prepared with [`prepare_signing_record`].
+///
+/// The record **must** contain a `$sig` object with at least a `$type` string
+/// to scope the signature. The returned CID uses the blessed parameters:
+/// CIDv1, dag-cbor codec (0x71), and sha2-256 multihash.
+pub fn create_cid(record: &Value) -> Result<Cid, AttestationError> {
+    let record_object = record
+        .as_object()
+        .ok_or(AttestationError::RecordMustBeObject)?;
+
+    let sig_value = record_object
+        .get("$sig")
+        .ok_or(AttestationError::SigMetadataMissing)?;
+
+    let sig_object = sig_value
+        .as_object()
+        .ok_or(AttestationError::SigMetadataNotObject)?;
+
+    if !sig_object
+        .get("$type")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .is_some()
+    {
+        return Err(AttestationError::SigMetadataMissingType);
+    }
+
+    let dag_cbor_bytes = serde_ipld_dagcbor::to_vec(record)?;
+    let digest = Sha256::digest(&dag_cbor_bytes);
+    let multihash = Multihash::wrap(0x12, &digest)
+        .map_err(|error| AttestationError::MultihashWrapFailed { error })?;
+
+    Ok(Cid::new_v1(0x71, multihash))
+}
+
+fn create_plain_cid(record: &Value) -> Result<Cid, AttestationError> {
+    let dag_cbor_bytes = serde_ipld_dagcbor::to_vec(record)?;
+    let digest = Sha256::digest(&dag_cbor_bytes);
+    let multihash = Multihash::wrap(0x12, &digest)
+        .map_err(|error| AttestationError::MultihashWrapFailed { error })?;
+
+    Ok(Cid::new_v1(0x71, multihash))
+}
+
+/// Prepare a record for signing by removing attestation artifacts and adding `$sig`.
+///
+/// - Removes any existing `signatures`, `sigs`, and `$sig` fields.
+/// - Inserts the provided `attestation` metadata as the new `$sig` object.
+/// - Ensures the metadata contains a string `$type` discriminator.
+pub fn prepare_signing_record(
+    record: &Value,
+    attestation: &Value,
+) -> Result<Value, AttestationError> {
+    let mut prepared = record
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::RecordMustBeObject)?;
+
+    let mut sig_metadata = attestation
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::MetadataMustBeObject)?;
+
+    if !sig_metadata
+        .get("$type")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .is_some()
+    {
+        return Err(AttestationError::MetadataMissingSigType);
+    }
+
+    sig_metadata.remove("signature");
+    sig_metadata.remove("cid");
+
+    prepared.remove("signatures");
+    prepared.remove("sigs");
+    prepared.remove("$sig");
+    prepared.insert("$sig".to_string(), Value::Object(sig_metadata));
+
+    Ok(Value::Object(prepared))
+}
+
+/// Creates an inline attestation by signing the prepared record with the provided key.
+pub fn create_inline_attestation(
+    record: &Value,
+    attestation_metadata: &Value,
+    signing_key: &KeyData,
+) -> Result<Value, AttestationError> {
+    let signing_record = prepare_signing_record(record, attestation_metadata)?;
+    let cid = create_cid(&signing_record)?;
+
+    let raw_signature = sign(signing_key, &cid.to_bytes())
+        .map_err(|error| AttestationError::SignatureCreationFailed { error })?;
+    let signature_bytes = normalize_signature(raw_signature, signing_key.key_type())?;
+
+    let mut inline_object = attestation_metadata
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::MetadataMustBeObject)?;
+
+    inline_object.remove("signature");
+    inline_object.remove("cid");
+    inline_object.insert(
+        "signature".to_string(),
+        json!({"$bytes": BASE64.encode(signature_bytes)}),
+    );
+
+    create_inline_attestation_reference(record, &Value::Object(inline_object))
+}
+
+/// Creates a remote attestation by generating a proof record and strongRef entry.
+///
+/// Returns a tuple containing:
+/// - Remote proof record containing the CID for storage in a repository.
+pub fn create_remote_attestation(
+    record: &Value,
+    attestation_metadata: &Value,
+) -> Result<Value, AttestationError> {
+    let metadata = attestation_metadata
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::MetadataMustBeObject)?;
+
+    let metadata_value = Value::Object(metadata.clone());
+    let signing_record = prepare_signing_record(record, &metadata_value)?;
+    let cid = create_cid(&signing_record)?;
+
+    let mut remote_attestation = metadata.clone();
+    remote_attestation.insert("cid".to_string(), Value::String(cid.to_string()));
+
+    Ok(Value::Object(remote_attestation))
+}
+
+/// Normalize raw signature bytes to the required low-S form.
+///
+/// This helper ensures signatures produced by signing APIs comply with the
+/// specification requirements before embedding them in attestation objects.
+pub fn normalize_signature(
+    signature: Vec<u8>,
+    key_type: &KeyType,
+) -> Result<Vec<u8>, AttestationError> {
+    match key_type {
+        KeyType::P256Private | KeyType::P256Public => normalize_p256(signature),
+        KeyType::K256Private | KeyType::K256Public => normalize_k256(signature),
+        other => Err(AttestationError::UnsupportedKeyType {
+            key_type: other.clone(),
+        }),
+    }
+}
+
+/// Attach a remote attestation entry (strongRef) to the record.
+///
+/// The `attestation` value must be an object containing:
+/// - `$type`: `"com.atproto.repo.strongRef"`
+/// - `cid`: base32 CID string referencing the remote proof record
+/// - Optional `uri`: AT URI for the remote record
+pub fn create_remote_attestation_reference(
+    record: &Value,
+    attestation: &Value,
+    did: &str,
+) -> Result<Value, AttestationError> {
+    let mut result = record
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::RecordMustBeObject)?;
+
+    let attestation = attestation
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::MetadataMustBeObject)?;
+
+    let remote_object_type = attestation
+        .get("$type")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .ok_or(AttestationError::RemoteAttestationMissingCid)?;
+
+    let tid = Tid::new();
+
+    let attestion_cid = create_plain_cid(&serde_json::Value::Object(attestation.clone()))?;
+
+    let remote_object = json!({
+        "$type": STRONG_REF_TYPE,
+        "uri": format!("at://{did}/{remote_object_type}/{tid}"),
+        "cid": attestion_cid.to_string()
+    });
+
+    let mut signatures = extract_signatures_vec(&mut result)?;
+    signatures.push(remote_object);
+    result.insert("signatures".to_string(), Value::Array(signatures));
+
+    Ok(Value::Object(result))
+}
+
+/// Attach an inline attestation entry containing signature bytes.
+///
+/// The `attestation` value must be an object containing:
+/// - `$type`: union discriminator (must NOT be `com.atproto.repo.strongRef`)
+/// - `key`: verification method reference used to sign
+/// - `signature`: object with `$bytes` base64 signature
+/// Additional custom fields are preserved for `$sig` metadata.
+pub fn create_inline_attestation_reference(
+    record: &Value,
+    attestation: &Value,
+) -> Result<Value, AttestationError> {
+    let mut result = record
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::RecordMustBeObject)?;
+
+    let inline_object = attestation
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::MetadataMustBeObject)?;
+
+    let signature_type = inline_object
+        .get("$type")
+        .and_then(Value::as_str)
+        .ok_or_else(|| AttestationError::MetadataMissingField {
+            field: "$type".to_string(),
+        })?;
+
+    if signature_type == STRONG_REF_TYPE {
+        return Err(AttestationError::InlineAttestationTypeInvalid);
+    }
+
+    inline_object
+        .get("key")
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .ok_or_else(|| AttestationError::SignatureMissingField {
+            field: "key".to_string(),
+        })?;
+
+    let signature_bytes = inline_object
+        .get("signature")
+        .and_then(Value::as_object)
+        .and_then(|object| object.get("$bytes"))
+        .and_then(Value::as_str)
+        .filter(|value| !value.is_empty())
+        .ok_or(AttestationError::SignatureBytesFormatInvalid)?;
+
+    // Ensure the signature bytes decode cleanly to catch malformed input early.
+    let _ = BASE64
+        .decode(signature_bytes)
+        .map_err(|error| AttestationError::SignatureDecodingFailed { error })?;
+
+    let mut signatures = extract_signatures_vec(&mut result)?;
+    signatures.push(Value::Object(inline_object));
+    result.insert("signatures".to_string(), Value::Array(signatures));
+    result.remove("$sig");
+
+    Ok(Value::Object(result))
+}
+
+/// Verify a single attestation entry at the specified index without a record resolver.
+///
+/// Inline signatures are reconstructed into `$sig` metadata, a CID is generated,
+/// and the signature bytes are validated against the resolved public key.
+/// Remote attestations will be reported as unverified.
+///
+/// This is a convenience function for the common case where no record resolver is needed.
+/// For verifying remote attestations, use [`verify_signature_with_resolver`].
+pub async fn verify_signature(
+    record: &Value,
+    index: usize,
+    key_resolver: Option<&dyn KeyResolver>,
+) -> Result<VerificationReport, AttestationError> {
+    verify_signature_with_resolver::<atproto_client::record_resolver::HttpRecordResolver>(
+        record,
+        index,
+        key_resolver,
+        None,
+    )
+    .await
+}
+
+/// Verify a single attestation entry at the specified index with optional record resolver.
+///
+/// Inline signatures are reconstructed into `$sig` metadata, a CID is generated,
+/// and the signature bytes are validated against the resolved public key.
+/// Remote attestations can be verified if a `record_resolver` is provided to fetch
+/// the proof record via AT-URI. Without a record resolver, remote attestations are
+/// reported as unverified.
+pub async fn verify_signature_with_resolver<R>(
+    record: &Value,
+    index: usize,
+    key_resolver: Option<&dyn KeyResolver>,
+    record_resolver: Option<&R>,
+) -> Result<VerificationReport, AttestationError>
+where
+    R: atproto_client::record_resolver::RecordResolver,
+{
+    let signatures_array = extract_signatures_array(record)?;
+    let signature_entry = signatures_array
+        .get(index)
+        .ok_or(AttestationError::SignatureIndexOutOfBounds { index })?;
+
+    let signature_map =
+        signature_entry
+            .as_object()
+            .ok_or_else(|| AttestationError::SignatureMissingField {
+                field: "object".to_string(),
+            })?;
+
+    let signature_type = signature_map
+        .get("$type")
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned);
+
+    let report_kind = match signature_type.as_deref() {
+        Some(STRONG_REF_TYPE) => AttestationKind::Remote,
+        _ => AttestationKind::Inline,
+    };
+
+    let key_reference = signature_map
+        .get("key")
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned);
+
+    let status = match report_kind {
+        AttestationKind::Remote => {
+            match record_resolver {
+                Some(resolver) => {
+                    match verify_remote_attestation(record, signature_map, resolver).await {
+                        Ok(cid) => VerificationStatus::Valid { cid },
+                        Err(error) => VerificationStatus::Invalid { error },
+                    }
+                }
+                None => VerificationStatus::Unverified {
+                    reason: "Remote attestations require a record resolver to fetch the proof record via strongRef.".to_string(),
+                },
+            }
+        }
+        AttestationKind::Inline => {
+            match verify_inline_attestation(record, signature_map, key_resolver).await {
+                Ok(cid) => VerificationStatus::Valid { cid },
+                Err(error) => VerificationStatus::Invalid { error },
+            }
+        }
+    };
+
+    Ok(VerificationReport {
+        index,
+        kind: report_kind,
+        signature_type,
+        key: key_reference,
+        status,
+    })
+}
+
+/// Verify all attestation entries attached to the record without a record resolver.
+///
+/// Returns a report per signature. Structural issues with the record (for
+/// example, a missing `signatures` array) are returned as an error.
+///
+/// Remote attestations will be reported as unverified. For verifying remote
+/// attestations, use [`verify_all_signatures_with_resolver`].
+pub async fn verify_all_signatures(
+    record: &Value,
+    key_resolver: Option<&dyn KeyResolver>,
+) -> Result<Vec<VerificationReport>, AttestationError> {
+    verify_all_signatures_with_resolver::<atproto_client::record_resolver::HttpRecordResolver>(
+        record,
+        key_resolver,
+        None,
+    )
+    .await
+}
+
+/// Verify all attestation entries attached to the record with optional record resolver.
+///
+/// Returns a report per signature. Structural issues with the record (for
+/// example, a missing `signatures` array) are returned as an error.
+///
+/// If a `record_resolver` is provided, remote attestations will be fetched and verified.
+/// Otherwise, remote attestations will be reported as unverified.
+pub async fn verify_all_signatures_with_resolver<R>(
+    record: &Value,
+    key_resolver: Option<&dyn KeyResolver>,
+    record_resolver: Option<&R>,
+) -> Result<Vec<VerificationReport>, AttestationError>
+where
+    R: atproto_client::record_resolver::RecordResolver,
+{
+    let signatures_array = extract_signatures_array(record)?;
+    let mut reports = Vec::with_capacity(signatures_array.len());
+
+    for index in 0..signatures_array.len() {
+        reports.push(
+            verify_signature_with_resolver(record, index, key_resolver, record_resolver).await?,
+        );
+    }
+
+    Ok(reports)
+}
+
+async fn verify_remote_attestation<R>(
+    record: &Value,
+    signature_object: &Map<String, Value>,
+    record_resolver: &R,
+) -> Result<Cid, AttestationError>
+where
+    R: atproto_client::record_resolver::RecordResolver,
+{
+    // Extract the strongRef URI and CID
+    let uri = signature_object
+        .get("uri")
+        .and_then(Value::as_str)
+        .ok_or_else(|| AttestationError::SignatureMissingField {
+            field: "uri".to_string(),
+        })?;
+
+    let expected_cid_str = signature_object
+        .get("cid")
+        .and_then(Value::as_str)
+        .ok_or_else(|| AttestationError::SignatureMissingField {
+            field: "cid".to_string(),
+        })?;
+
+    // Fetch the proof record from the URI
+    let proof_record: Value = record_resolver.resolve(uri).await.map_err(|error| {
+        AttestationError::RemoteAttestationFetchFailed {
+            uri: uri.to_string(),
+            error,
+        }
+    })?;
+
+    // Verify the proof record CID matches
+    let proof_cid = create_plain_cid(&proof_record)?;
+    if proof_cid.to_string() != expected_cid_str {
+        return Err(AttestationError::RemoteAttestationCidMismatch {
+            expected: expected_cid_str.to_string(),
+            actual: proof_cid.to_string(),
+        });
+    }
+
+    // Extract the CID from the proof record
+    let attestation_cid_str = proof_record
+        .get("cid")
+        .and_then(Value::as_str)
+        .ok_or_else(|| AttestationError::SignatureMissingField {
+            field: "cid".to_string(),
+        })?;
+
+    // Parse the attestation CID
+    let attestation_cid =
+        attestation_cid_str
+            .parse::<Cid>()
+            .map_err(|_| AttestationError::InvalidCid {
+                cid: attestation_cid_str.to_string(),
+            })?;
+
+    // Prepare the signing record using the proof record as metadata (without the CID field)
+    let mut proof_metadata = proof_record
+        .as_object()
+        .cloned()
+        .ok_or(AttestationError::RecordMustBeObject)?;
+    proof_metadata.remove("cid");
+
+    let signing_record = prepare_signing_record(record, &Value::Object(proof_metadata))?;
+    let computed_cid = create_cid(&signing_record)?;
+
+    // Verify the CID matches
+    if computed_cid != attestation_cid {
+        return Err(AttestationError::RemoteAttestationCidMismatch {
+            expected: attestation_cid.to_string(),
+            actual: computed_cid.to_string(),
+        });
+    }
+
+    Ok(computed_cid)
+}
+
+async fn verify_inline_attestation(
+    record: &Value,
+    signature_object: &Map<String, Value>,
+    key_resolver: Option<&dyn KeyResolver>,
+) -> Result<Cid, AttestationError> {
+    let key_reference = signature_object
+        .get("key")
+        .and_then(Value::as_str)
+        .ok_or_else(|| AttestationError::SignatureMissingField {
+            field: "key".to_string(),
+        })?;
+
+    let key_data = resolve_key_reference(key_reference, key_resolver).await?;
+
+    let signature_bytes = signature_object
+        .get("signature")
+        .and_then(Value::as_object)
+        .and_then(|object| object.get("$bytes"))
+        .and_then(Value::as_str)
+        .ok_or(AttestationError::SignatureBytesFormatInvalid)?;
+
+    let signature_bytes = BASE64
+        .decode(signature_bytes)
+        .map_err(|error| AttestationError::SignatureDecodingFailed { error })?;
+
+    ensure_normalized_signature(&key_data, &signature_bytes)?;
+
+    let mut sig_metadata = signature_object.clone();
+    sig_metadata.remove("signature");
+
+    let signing_record = prepare_signing_record(record, &Value::Object(sig_metadata))?;
+    let cid = create_cid(&signing_record)?;
+    let cid_bytes = cid.to_bytes();
+
+    validate(&key_data, &signature_bytes, &cid_bytes)
+        .map_err(|error| AttestationError::SignatureValidationFailed { error })?;
+
+    Ok(cid)
+}
+
+async fn resolve_key_reference(
+    key_reference: &str,
+    key_resolver: Option<&dyn KeyResolver>,
+) -> Result<KeyData, AttestationError> {
+    if let Some(base) = key_reference.split('#').next() {
+        if let Ok(key_data) = identify_key(base) {
+            return Ok(key_data);
+        }
+    }
+
+    if let Ok(key_data) = identify_key(key_reference) {
+        return Ok(key_data);
+    }
+
+    let resolver = key_resolver.ok_or_else(|| AttestationError::KeyResolverRequired {
+        key: key_reference.to_string(),
+    })?;
+
+    resolver
+        .resolve(key_reference)
+        .await
+        .map_err(|error| AttestationError::KeyResolutionFailed {
+            key: key_reference.to_string(),
+            error,
+        })
+}
+
+fn normalize_p256(signature: Vec<u8>) -> Result<Vec<u8>, AttestationError> {
+    if signature.len() != 64 {
+        return Err(AttestationError::SignatureLengthInvalid {
+            expected: 64,
+            actual: signature.len(),
+        });
+    }
+
+    let parsed = P256Signature::from_slice(&signature).map_err(|_| {
+        AttestationError::SignatureLengthInvalid {
+            expected: 64,
+            actual: signature.len(),
+        }
+    })?;
+
+    let normalized = parsed.normalize_s().unwrap_or(parsed);
+
+    Ok(normalized.to_vec())
+}
+
+fn normalize_k256(signature: Vec<u8>) -> Result<Vec<u8>, AttestationError> {
+    if signature.len() != 64 {
+        return Err(AttestationError::SignatureLengthInvalid {
+            expected: 64,
+            actual: signature.len(),
+        });
+    }
+
+    let parsed = K256Signature::from_slice(&signature).map_err(|_| {
+        AttestationError::SignatureLengthInvalid {
+            expected: 64,
+            actual: signature.len(),
+        }
+    })?;
+
+    let normalized = parsed.normalize_s().unwrap_or(parsed);
+
+    Ok(normalized.to_vec())
+}
+
+fn ensure_normalized_signature(
+    key_data: &KeyData,
+    signature: &[u8],
+) -> Result<(), AttestationError> {
+    match key_data.key_type() {
+        KeyType::P256Private | KeyType::P256Public => {
+            if signature.len() != 64 {
+                return Err(AttestationError::SignatureLengthInvalid {
+                    expected: 64,
+                    actual: signature.len(),
+                });
+            }
+
+            let parsed = P256Signature::from_slice(signature).map_err(|_| {
+                AttestationError::SignatureLengthInvalid {
+                    expected: 64,
+                    actual: signature.len(),
+                }
+            })?;
+
+            if bool::from(parsed.s().is_high()) {
+                return Err(AttestationError::SignatureNotNormalized);
+            }
+        }
+        KeyType::K256Private | KeyType::K256Public => {
+            if signature.len() != 64 {
+                return Err(AttestationError::SignatureLengthInvalid {
+                    expected: 64,
+                    actual: signature.len(),
+                });
+            }
+
+            let parsed = K256Signature::from_slice(signature).map_err(|_| {
+                AttestationError::SignatureLengthInvalid {
+                    expected: 64,
+                    actual: signature.len(),
+                }
+            })?;
+
+            if bool::from(parsed.s().is_high()) {
+                return Err(AttestationError::SignatureNotNormalized);
+            }
+        }
+        other => {
+            return Err(AttestationError::UnsupportedKeyType {
+                key_type: other.clone(),
+            });
+        }
+    }
+
+    Ok(())
+}
+
+fn extract_signatures_array(record: &Value) -> Result<&Vec<Value>, AttestationError> {
+    let signatures = record.get("signatures");
+
+    match signatures {
+        Some(value) => value
+            .as_array()
+            .ok_or(AttestationError::SignaturesFieldInvalid),
+        None => Err(AttestationError::SignaturesArrayMissing),
+    }
+}
+
+fn extract_signatures_vec(record: &mut Map<String, Value>) -> Result<Vec<Value>, AttestationError> {
+    let existing = record.remove("signatures");
+
+    match existing {
+        Some(Value::Array(array)) => Ok(array),
+        Some(_) => Err(AttestationError::SignaturesFieldInvalid),
+        None => Ok(Vec::new()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use atproto_identity::key::{IdentityDocumentKeyResolver, KeyType, generate_key, to_public};
+    use atproto_identity::model::{Document, DocumentBuilder, VerificationMethod};
+    use atproto_identity::resolve::IdentityResolver;
+    use serde_json::json;
+    use std::sync::Arc;
+
+    struct StaticResolver {
+        document: Document,
+    }
+
+    #[async_trait::async_trait]
+    impl IdentityResolver for StaticResolver {
+        async fn resolve(&self, _subject: &str) -> anyhow::Result<Document> {
+            Ok(self.document.clone())
+        }
+    }
+
+    #[test]
+    fn prepare_signing_record_removes_signatures() -> Result<(), AttestationError> {
+        let record = json!({
+            "$type": "app.bsky.feed.post",
+            "text": "hello",
+            "signatures": [
+                {"$type": "example.sig", "signature": {"$bytes": "dGVzdA=="}, "key": "did:key:zabc"}
+            ]
+        });
+
+        let metadata = json!({
+            "$type": "com.example.inlineSignature",
+            "key": "did:key:zabc",
+            "purpose": "demo",
+            "signature": {"$bytes": "trim"},
+            "cid": "bafyignored"
+        });
+
+        let prepared = prepare_signing_record(&record, &metadata)?;
+        let object = prepared.as_object().unwrap();
+        assert!(object.get("signatures").is_none());
+        assert!(object.get("sigs").is_none());
+        assert!(object.get("$sig").is_some());
+
+        let sig_object = object.get("$sig").unwrap().as_object().unwrap();
+        assert_eq!(
+            sig_object.get("$type").and_then(Value::as_str),
+            Some("com.example.inlineSignature")
+        );
+        assert_eq!(
+            sig_object.get("purpose").and_then(Value::as_str),
+            Some("demo")
+        );
+        assert!(sig_object.get("signature").is_none());
+        assert!(sig_object.get("cid").is_none());
+
+        Ok(())
+    }
+
+    #[test]
+    fn create_cid_produces_expected_codec_and_length() -> Result<(), AttestationError> {
+        let prepared = json!({
+            "$type": "app.example.record",
+            "text": "cid demo",
+            "$sig": {
+                "$type": "com.example.inlineSignature",
+                "key": "did:key:zabc"
+            }
+        });
+
+        let cid = create_cid(&prepared)?;
+        assert_eq!(cid.codec(), 0x71);
+        assert_eq!(cid.hash().code(), 0x12);
+        assert_eq!(cid.hash().digest().len(), 32);
+        assert_eq!(cid.to_bytes().len(), 36);
+
+        Ok(())
+    }
+
+    #[test]
+    fn create_inline_attestation_appends_signature() -> Result<(), AttestationError> {
+        let record = json!({
+            "$type": "app.example.record",
+            "body": "Important content"
+        });
+
+        let inline = json!({
+            "$type": "com.example.inlineSignature",
+            "key": "did:key:zabc",
+            "signature": {"$bytes": "ZHVtbXk="}
+        });
+
+        let updated = create_inline_attestation_reference(&record, &inline)?;
+        let signatures = updated
+            .get("signatures")
+            .and_then(Value::as_array)
+            .expect("signatures array should exist");
+        assert_eq!(signatures.len(), 1);
+        assert_eq!(
+            signatures[0].get("$type").and_then(Value::as_str),
+            Some("com.example.inlineSignature")
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn create_remote_attestation_produces_reference_and_proof()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let record = json!({
+            "$type": "app.example.record",
+            "body": "remote attestation"
+        });
+
+        let metadata = json!({
+            "$type": "com.example.inlineSignature"
+        });
+
+        let proof_record = create_remote_attestation(&record, &metadata)?;
+
+        let proof_object = proof_record
+            .as_object()
+            .expect("reference should be an object");
+        assert_eq!(
+            proof_object.get("$type").and_then(Value::as_str),
+            Some("com.example.inlineSignature")
+        );
+        assert!(
+            proof_object.get("cid").and_then(Value::as_str).is_some(),
+            "proof must contain a cid"
+        );
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn verify_inline_signature_with_did_key() -> Result<(), Box<dyn std::error::Error>> {
+        let private_key = generate_key(KeyType::K256Private)?;
+        let public_key = to_public(&private_key)?;
+        let key_reference = format!("{}", &public_key);
+
+        let base_record = json!({
+            "$type": "app.example.record",
+            "body": "Sign me"
+        });
+
+        let sig_metadata = json!({
+            "$type": "com.example.inlineSignature",
+            "key": key_reference,
+            "purpose": "unit-test"
+        });
+
+        let signed = create_inline_attestation(&base_record, &sig_metadata, &private_key)?;
+
+        let report = verify_signature(&signed, 0, None).await?;
+        match report.status {
+            VerificationStatus::Valid { .. } => {}
+            other => panic!("expected valid signature, got {:?}", other),
+        }
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn verify_inline_signature_with_resolver() -> Result<(), Box<dyn std::error::Error>> {
+        let private_key = generate_key(KeyType::P256Private)?;
+        let public_key = to_public(&private_key)?;
+        let key_multibase = format!("{}", &public_key);
+        let key_reference = "did:plc:resolvertest#atproto".to_string();
+
+        let document = DocumentBuilder::new()
+            .id("did:plc:resolvertest")
+            .add_verification_method(VerificationMethod::Multikey {
+                id: key_reference.clone(),
+                controller: "did:plc:resolvertest".to_string(),
+                public_key_multibase: key_multibase
+                    .strip_prefix("did:key:")
+                    .unwrap_or(&key_multibase)
+                    .to_string(),
+                extra: std::collections::HashMap::new(),
+            })
+            .build()
+            .unwrap();
+
+        let identity_resolver = Arc::new(StaticResolver { document });
+        let key_resolver = IdentityDocumentKeyResolver::new(identity_resolver.clone());
+
+        let base_record = json!({
+            "$type": "app.example.record",
+            "body": "resolver test"
+        });
+
+        let sig_metadata = json!({
+            "$type": "com.example.inlineSignature",
+            "key": key_reference,
+            "scope": "resolver"
+        });
+
+        let signed = create_inline_attestation(&base_record, &sig_metadata, &private_key)?;
+
+        let report = verify_signature(&signed, 0, Some(&key_resolver)).await?;
+        match report.status {
+            VerificationStatus::Valid { .. } => {}
+            other => panic!("expected valid signature, got {:?}", other),
+        }
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn verify_all_signatures_reports_remote() -> Result<(), Box<dyn std::error::Error>> {
+        let record = json!({
+            "$type": "app.example.record",
+            "signatures": [
+                {
+                    "$type": STRONG_REF_TYPE,
+                    "cid": "bafyreid473y2gjzvzgjwdj3vpbk2bdzodf5hvbgxncjc62xmy3zsmb3pxq",
+                    "uri": "at://did:plc:example/com.example.attestation/abc123"
+                }
+            ]
+        });
+
+        let reports = verify_all_signatures(&record, None).await?;
+        assert_eq!(reports.len(), 1);
+        match &reports[0].status {
+            VerificationStatus::Unverified { reason } => {
+                assert!(reason.contains("Remote attestations"));
+            }
+            other => panic!("expected unverified status, got {:?}", other),
+        }
+
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn verify_detects_tampering() -> Result<(), Box<dyn std::error::Error>> {
+        let private_key = generate_key(KeyType::K256Private)?;
+        let public_key = to_public(&private_key)?;
+        let key_reference = format!("{}", &public_key);
+
+        let base_record = json!({
+            "$type": "app.example.record",
+            "body": "original"
+        });
+
+        let sig_metadata = json!({
+            "$type": "com.example.inlineSignature",
+            "key": key_reference
+        });
+
+        let mut signed = create_inline_attestation(&base_record, &sig_metadata, &private_key)?;
+        if let Some(object) = signed.as_object_mut() {
+            object.insert("body".to_string(), json!("tampered"));
+        }
+
+        let report = verify_signature(&signed, 0, None).await?;
+        match report.status {
+            VerificationStatus::Invalid { .. } => {}
+            other => panic!("expected invalid signature, got {:?}", other),
+        }
+
+        Ok(())
+    }
+}

crates/atproto-client/Cargo.toml

···
 
 [dependencies]
 atproto-identity.workspace = true
-atproto-record.workspace = true
 atproto-oauth.workspace = true
+atproto-record.workspace = true
 
 anyhow.workspace = true
 reqwest-chain.workspace = true
···
 tokio.workspace = true
 tracing.workspace = true
 urlencoding = "2.1.3"
+async-trait.workspace = true
 bytes = "1.10.1"
 clap = { workspace = true, optional = true }
 rpassword = { workspace = true, optional = true }

crates/atproto-client/src/com_atproto_identity.rs

···
 use std::collections::HashMap;
 
 use anyhow::Result;
-use atproto_identity::url::URLBuilder;
+use atproto_identity::url::build_url;
 use serde::{Deserialize, de::DeserializeOwned};
 
 use crate::{
···
     base_url: &str,
     handle: String,
 ) -> Result<ResolveHandleResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.identity.resolveHandle");
-
-    url_builder.param("handle", &handle);
-
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.identity.resolveHandle",
+        [("handle", handle.as_str())],
+    )?
+    .to_string();
 
     match auth {
         Auth::None => get_json(http_client, &url)

crates/atproto-client/src/com_atproto_repo.rs

···
 //! OAuth access tokens and private keys for proof generation.
 
 use std::collections::HashMap;
+use std::iter;
 
 use anyhow::Result;
-use atproto_identity::url::URLBuilder;
+use atproto_identity::url::build_url;
 use bytes::Bytes;
 use serde::{Deserialize, Serialize, de::DeserializeOwned};
 
···
     did: &str,
     cid: &str,
 ) -> Result<Bytes> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.sync.getBlob");
-
-    url_builder.param("did", did);
-    url_builder.param("cid", cid);
-
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.sync.getBlob",
+        [("did", did), ("cid", cid)],
+    )?
+    .to_string();
 
     get_bytes(http_client, &url).await
 }
···
     rkey: &str,
     cid: Option<&str>,
 ) -> Result<GetRecordResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.repo.getRecord");
-
-    url_builder.param("repo", repo);
-    url_builder.param("collection", collection);
-    url_builder.param("rkey", rkey);
-
+    let mut params = vec![("repo", repo), ("collection", collection), ("rkey", rkey)];
     if let Some(cid) = cid {
-        url_builder.param("cid", cid);
+        params.push(("cid", cid));
     }
 
-    let url = url_builder.build();
+    let url = build_url(base_url, "/xrpc/com.atproto.repo.getRecord", params)?.to_string();
 
     match auth {
         Auth::None => get_json(http_client, &url)
···
     collection: String,
     params: ListRecordsParams,
 ) -> Result<ListRecordsResponse<T>> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.repo.listRecords");
+    let mut url = build_url(
+        base_url,
+        "/xrpc/com.atproto.repo.listRecords",
+        iter::empty::<(&str, &str)>(),
+    )?;
+    {
+        let mut pairs = url.query_pairs_mut();
+        pairs.append_pair("repo", &repo);
+        pairs.append_pair("collection", &collection);
 
-    // Add query parameters
-    url_builder.param("repo", &repo);
-    url_builder.param("collection", &collection);
+        if let Some(limit) = params.limit {
+            pairs.append_pair("limit", &limit.to_string());
+        }
 
-    if let Some(limit) = params.limit {
-        url_builder.param("limit", &limit.to_string());
-    }
+        if let Some(cursor) = params.cursor {
+            pairs.append_pair("cursor", &cursor);
+        }
 
-    if let Some(cursor) = params.cursor {
-        url_builder.param("cursor", &cursor);
+        if let Some(reverse) = params.reverse {
+            pairs.append_pair("reverse", &reverse.to_string());
+        }
     }
 
-    if let Some(reverse) = params.reverse {
-        url_builder.param("reverse", &reverse.to_string());
-    }
-
-    let url = url_builder.build();
+    let url = url.to_string();
 
     match auth {
         Auth::None => get_json(http_client, &url)
···
     base_url: &str,
     record: CreateRecordRequest<T>,
 ) -> Result<CreateRecordResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.repo.createRecord");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.repo.createRecord",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     let value = serde_json::to_value(record)?;
 
···
     base_url: &str,
     record: PutRecordRequest<T>,
 ) -> Result<PutRecordResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.repo.putRecord");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.repo.putRecord",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     let value = serde_json::to_value(record)?;
 
···
     base_url: &str,
     record: DeleteRecordRequest,
 ) -> Result<DeleteRecordResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.repo.deleteRecord");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.repo.deleteRecord",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     let value = serde_json::to_value(record)?;
 

crates/atproto-client/src/com_atproto_server.rs

···
 //! an access JWT token from an authenticated session.
 
 use anyhow::Result;
-use atproto_identity::url::URLBuilder;
+use atproto_identity::url::build_url;
 use serde::{Deserialize, Serialize};
+use std::iter;
 
 use crate::{
     client::{Auth, post_json},
···
     password: &str,
     auth_factor_token: Option<&str>,
 ) -> Result<AppPasswordSession> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.server.createSession");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.server.createSession",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     let request = CreateSessionRequest {
         identifier: identifier.to_string(),
···
     base_url: &str,
     refresh_token: &str,
 ) -> Result<RefreshSessionResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.server.refreshSession");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.server.refreshSession",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     // Create a new client with the refresh token in Authorization header
     let mut headers = reqwest::header::HeaderMap::new();
···
     access_token: &str,
     name: &str,
 ) -> Result<AppPasswordResponse> {
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.server.createAppPassword");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.server.createAppPassword",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     let request_body = serde_json::json!({
         "name": name
···
         }
     };
 
-    let mut url_builder = URLBuilder::new(base_url);
-    url_builder.path("/xrpc/com.atproto.server.deleteSession");
-    let url = url_builder.build();
+    let url = build_url(
+        base_url,
+        "/xrpc/com.atproto.server.deleteSession",
+        iter::empty::<(&str, &str)>(),
+    )?
+    .to_string();
 
     // Create headers with the Bearer token
     let mut headers = reqwest::header::HeaderMap::new();

crates/atproto-client/src/lib.rs

···
 
 pub mod client;
 pub mod errors;
+pub mod record_resolver;
+
+pub use record_resolver::{HttpRecordResolver, RecordResolver};
 
 mod com_atproto_identity;
 mod com_atproto_repo;

crates/atproto-client/src/record_resolver.rs

···
+//! Helpers for resolving AT Protocol records referenced by URI.
+
+use std::str::FromStr;
+
+use anyhow::{Result, anyhow, bail};
+use async_trait::async_trait;
+use atproto_record::aturi::ATURI;
+
+use crate::{
+    client::Auth,
+    com::atproto::repo::{GetRecordResponse, get_record},
+};
+
+/// Trait for resolving AT Protocol records by `at://` URI.
+///
+/// Implementations perform the network lookup and deserialize the response into
+/// the requested type.
+#[async_trait]
+pub trait RecordResolver: Send + Sync {
+    /// Resolve an AT URI to a typed record.
+    async fn resolve<T>(&self, aturi: &str) -> Result<T>
+    where
+        T: serde::de::DeserializeOwned + Send;
+}
+
+/// Resolver that fetches records using public XRPC endpoints.
+#[derive(Clone)]
+pub struct HttpRecordResolver {
+    http_client: reqwest::Client,
+    base_url: String,
+}
+
+impl HttpRecordResolver {
+    /// Create a new resolver using the provided HTTP client and PDS base URL.
+    pub fn new(http_client: reqwest::Client, base_url: impl Into<String>) -> Self {
+        Self {
+            http_client,
+            base_url: base_url.into(),
+        }
+    }
+}
+
+#[async_trait]
+impl RecordResolver for HttpRecordResolver {
+    async fn resolve<T>(&self, aturi: &str) -> Result<T>
+    where
+        T: serde::de::DeserializeOwned + Send,
+    {
+        let parsed = ATURI::from_str(aturi).map_err(|error| anyhow!(error))?;
+        let auth = Auth::None;
+
+        let response = get_record(
+            &self.http_client,
+            &auth,
+            &self.base_url,
+            &parsed.authority,
+            &parsed.collection,
+            &parsed.record_key,
+            None,
+        )
+        .await?;
+
+        match response {
+            GetRecordResponse::Record { value, .. } => {
+                serde_json::from_value(value).map_err(|error| anyhow!(error))
+            }
+            GetRecordResponse::Error(error) => {
+                let message = error.error_message();
+                if message.is_empty() {
+                    bail!("Record resolution failed without additional error details");
+                }
+
+                bail!(message);
+            }
+        }
+    }
+}

crates/atproto-identity/Cargo.toml

···
 thiserror.workspace = true
 tokio.workspace = true
 tracing.workspace = true
+url.workspace = true
 urlencoding.workspace = true
 zeroize = { workspace = true, optional = true }
 

crates/atproto-identity/src/key.rs

···
 //! }
 //! ```
 
-use anyhow::Result;
+use anyhow::{Context, Result, anyhow};
 use ecdsa::signature::Signer;
 use elliptic_curve::JwkEcKey;
 use elliptic_curve::sec1::ToEncodedPoint;
 
+use crate::model::VerificationMethod;
+use crate::traits::IdentityResolver;
+
+pub use crate::traits::KeyResolver;
+use std::sync::Arc;
+
 use crate::errors::KeyError;
 
 #[cfg(feature = "zeroize")]
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 /// Cryptographic key types supported for AT Protocol identity.
-#[derive(Clone, PartialEq)]
-#[cfg_attr(debug_assertions, derive(Debug))]
+#[derive(Clone, PartialEq, Debug)]
 #[cfg_attr(feature = "zeroize", derive(Zeroize, ZeroizeOnDrop))]
 pub enum KeyType {
     /// A p256 (P-256 / secp256r1 / ES256) public key.
···
         // Add DID key prefix
         write!(f, "did:key:{}", multibase_encoded)
     }
-}
-
-/// 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.
···
                 .map_err(|error| KeyError::ECDSAError { error })?;
             Ok(signature.to_vec())
         }
+    }
+}
+
+/// Key resolver implementation that fetches DID documents using an [`IdentityResolver`].
+#[derive(Clone)]
+pub struct IdentityDocumentKeyResolver {
+    identity_resolver: Arc<dyn IdentityResolver>,
+}
+
+impl IdentityDocumentKeyResolver {
+    /// Creates a new key resolver backed by an [`IdentityResolver`].
+    pub fn new(identity_resolver: Arc<dyn IdentityResolver>) -> Self {
+        Self { identity_resolver }
+    }
+}
+
+#[async_trait::async_trait]
+impl KeyResolver for IdentityDocumentKeyResolver {
+    async fn resolve(&self, key: &str) -> Result<KeyData> {
+        if let Some(did_key) = key.split('#').next() {
+            if let Ok(key_data) = identify_key(did_key) {
+                return Ok(key_data);
+            }
+        } else if let Ok(key_data) = identify_key(key) {
+            return Ok(key_data);
+        }
+
+        let (did, fragment) = key
+            .split_once('#')
+            .context("Key reference must contain a DID fragment (e.g., did:example#key)")?;
+
+        if did.is_empty() || fragment.is_empty() {
+            return Err(anyhow!(
+                "Key reference must include both DID and fragment (received `{key}`)"
+            ));
+        }
+
+        let document = self.identity_resolver.resolve(did).await?;
+        let fragment_with_hash = format!("#{fragment}");
+
+        let public_key_multibase = document
+            .verification_method
+            .iter()
+            .find_map(|method| match method {
+                VerificationMethod::Multikey {
+                    id,
+                    public_key_multibase,
+                    ..
+                } if id == key || *id == fragment_with_hash => Some(public_key_multibase.clone()),
+                _ => None,
+            })
+            .context(format!(
+                "Verification method `{key}` not found in DID document `{did}`"
+            ))?;
+
+        let full_key = if public_key_multibase.starts_with("did:key:") {
+            public_key_multibase
+        } else {
+            format!("did:key:{}", public_key_multibase)
+        };
+
+        identify_key(&full_key).context("Failed to parse key data from verification method")
     }
 }
 

crates/atproto-identity/src/lib.rs

···
 pub mod model;
 pub mod plc;
 pub mod resolve;
-pub mod storage;
 #[cfg(feature = "lru")]
 pub mod storage_lru;
+pub mod traits;
 pub mod url;
 pub mod validation;
 pub mod web;

crates/atproto-identity/src/resolve.rs

···
 use crate::validation::{is_valid_did_method_plc, is_valid_handle};
 use crate::web::query as web_query;
 
-/// Trait for AT Protocol identity resolution.
-///
-/// Implementations must be thread-safe (Send + Sync) and usable in async environments.
-/// This trait provides the core functionality for resolving AT Protocol subjects
-/// (handles or DIDs) to their corresponding DID documents.
-#[async_trait::async_trait]
-pub trait IdentityResolver: Send + Sync {
-    /// Resolves an AT Protocol subject to its DID document.
-    ///
-    /// Takes a handle or DID, resolves it to a canonical DID, then retrieves
-    /// the corresponding DID document from the appropriate source (PLC directory or web).
-    ///
-    /// # Arguments
-    /// * `subject` - The AT Protocol handle or DID to resolve
-    ///
-    /// # Returns
-    /// * `Ok(Document)` - The resolved DID document
-    /// * `Err(anyhow::Error)` - Resolution error with detailed context
-    async fn resolve(&self, subject: &str) -> Result<Document>;
-}
-
-/// Trait for DNS resolution operations.
-/// Provides async DNS TXT record lookups for handle resolution.
-#[async_trait::async_trait]
-pub trait DnsResolver: Send + Sync {
-    /// Resolves TXT records for a given domain name.
-    /// Returns a vector of strings representing the TXT record values.
-    async fn resolve_txt(&self, domain: &str) -> Result<Vec<String>, ResolveError>;
-}
+pub use crate::traits::{DnsResolver, IdentityResolver};
 
 /// Hickory DNS implementation of the DnsResolver trait.
 /// Wraps hickory_resolver::TokioResolver for TXT record resolution.
···
         is_valid_handle(trimmed)
             .map(InputType::Handle)
             .ok_or(ResolveError::InvalidInput)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::key::{
+        IdentityDocumentKeyResolver, KeyResolver, KeyType, generate_key, identify_key, to_public,
+    };
+    use crate::model::{DocumentBuilder, VerificationMethod};
+    use std::collections::HashMap;
+
+    struct StubIdentityResolver {
+        expected: String,
+        document: Document,
+    }
+
+    #[async_trait::async_trait]
+    impl IdentityResolver for StubIdentityResolver {
+        async fn resolve(&self, subject: &str) -> Result<Document> {
+            if !self.expected.is_empty() {
+                assert_eq!(self.expected, subject);
+            }
+            Ok(self.document.clone())
+        }
+    }
+
+    #[tokio::test]
+    async fn resolves_direct_did_key() -> Result<()> {
+        let private_key = generate_key(KeyType::K256Private)?;
+        let public_key = to_public(&private_key)?;
+        let key_reference = format!("{}", &public_key);
+
+        let resolver = IdentityDocumentKeyResolver::new(Arc::new(StubIdentityResolver {
+            expected: String::new(),
+            document: Document::builder()
+                .id("did:plc:placeholder")
+                .build()
+                .unwrap(),
+        }));
+
+        let key_data = resolver.resolve(&key_reference).await?;
+        assert_eq!(key_data.bytes(), public_key.bytes());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn resolves_literal_did_key_reference() -> Result<()> {
+        let resolver = IdentityDocumentKeyResolver::new(Arc::new(StubIdentityResolver {
+            expected: String::new(),
+            document: Document::builder()
+                .id("did:example:unused".to_string())
+                .build()
+                .unwrap(),
+        }));
+
+        let sample = "did:key:zDnaezRmyM3NKx9NCphGiDFNBEMyR2sTZhhMGTseXCU2iXn53";
+        let expected = identify_key(sample)?;
+        let resolved = resolver.resolve(sample).await?;
+        assert_eq!(resolved.bytes(), expected.bytes());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn resolves_via_identity_document() -> Result<()> {
+        let private_key = generate_key(KeyType::P256Private)?;
+        let public_key = to_public(&private_key)?;
+        let public_key_multibase = format!("{}", &public_key)
+            .strip_prefix("did:key:")
+            .unwrap()
+            .to_string();
+
+        let did = "did:web:example.com";
+        let method_id = format!("{did}#atproto");
+
+        let document = DocumentBuilder::new()
+            .id(did.to_string())
+            .add_verification_method(VerificationMethod::Multikey {
+                id: method_id.clone(),
+                controller: did.to_string(),
+                public_key_multibase,
+                extra: HashMap::new(),
+            })
+            .build()
+            .unwrap();
+
+        let resolver = IdentityDocumentKeyResolver::new(Arc::new(StubIdentityResolver {
+            expected: did.to_string(),
+            document,
+        }));
+
+        let key_data = resolver.resolve(&method_id).await?;
+        assert_eq!(key_data.bytes(), public_key.bytes());
+        Ok(())
     }
 }
 

crates/atproto-identity/src/storage.rs

···
-//! DID document storage abstraction.
-//!
-//! Storage trait for DID document CRUD operations supporting multiple
-//! backends (database, file system, memory) with consistent interface.
-
-use anyhow::Result;
-
-use crate::model::Document;
-
-/// Trait for implementing DID document CRUD operations across different storage backends.
-///
-/// This trait provides an abstraction layer for storing and retrieving DID documents,
-/// allowing different implementations for various storage systems such as databases, file systems,
-/// in-memory stores, or cloud storage services.
-///
-/// All methods return `anyhow::Result` to allow implementations to use their own error types
-/// while providing a consistent interface for callers. Implementations should handle their
-/// specific error conditions and convert them to appropriate error messages.
-///
-/// ## Thread Safety
-///
-/// This trait requires implementations to be thread-safe (`Send + Sync`), meaning:
-/// - `Send`: The storage implementation can be moved between threads
-/// - `Sync`: The storage implementation can be safely accessed from multiple threads simultaneously
-///
-/// This is essential for async applications where the storage might be accessed from different
-/// async tasks running on different threads. Implementations should use appropriate
-/// synchronization primitives (like `Arc<Mutex<>>`, `RwLock`, or database connection pools)
-/// to ensure thread safety.
-///
-/// ## Usage
-///
-/// Implementors of this trait can provide storage for AT Protocol DID documents in any backend:
-///
-/// ```rust,ignore
-/// use atproto_identity::storage::DidDocumentStorage;
-/// use atproto_identity::model::Document;
-/// use anyhow::Result;
-/// use std::sync::Arc;
-/// use tokio::sync::RwLock;
-/// use std::collections::HashMap;
-///
-/// // Thread-safe in-memory storage using Arc<RwLock<>>
-/// #[derive(Clone)]
-/// struct InMemoryStorage {
-///     data: Arc<RwLock<HashMap<String, Document>>>, // DID -> Document mapping
-/// }
-///
-/// #[async_trait::async_trait]
-/// impl DidDocumentStorage for InMemoryStorage {
-///     async fn get_document_by_did(&self, did: &str) -> Result<Option<Document>> {
-///         let data = self.data.read().await;
-///         Ok(data.get(did).cloned())
-///     }
-///     
-///     async fn store_document(&self, document: Document) -> Result<()> {
-///         let mut data = self.data.write().await;
-///         data.insert(document.id.clone(), document);
-///         Ok(())
-///     }
-///     
-///     async fn delete_document_by_did(&self, did: &str) -> Result<()> {
-///         let mut data = self.data.write().await;
-///         data.remove(did);
-///         Ok(())
-///     }
-/// }
-///
-/// // Database storage with thread-safe connection pool
-/// struct DatabaseStorage {
-///     pool: sqlx::Pool<sqlx::Postgres>, // Thread-safe connection pool
-/// }
-///
-/// #[async_trait::async_trait]
-/// impl DidDocumentStorage for DatabaseStorage {
-///     async fn get_document_by_did(&self, did: &str) -> Result<Option<Document>> {
-///         // Database connection pools are thread-safe
-///         let row: Option<(serde_json::Value,)> = sqlx::query_as(
-///             "SELECT document FROM did_documents WHERE did = $1"
-///         )
-///         .bind(did)
-///         .fetch_optional(&self.pool)
-///         .await?;
-///         
-///         if let Some((doc_json,)) = row {
-///             let document: Document = serde_json::from_value(doc_json)?;
-///             Ok(Some(document))
-///         } else {
-///             Ok(None)
-///         }
-///     }
-///     
-///     async fn store_document(&self, document: Document) -> Result<()> {
-///         let doc_json = serde_json::to_value(&document)?;
-///         sqlx::query("INSERT INTO did_documents (did, document) VALUES ($1, $2) ON CONFLICT (did) DO UPDATE SET document = $2")
-///             .bind(&document.id)
-///             .bind(doc_json)
-///             .execute(&self.pool)
-///             .await?;
-///         Ok(())
-///     }
-///     
-///     async fn delete_document_by_did(&self, did: &str) -> Result<()> {
-///         sqlx::query("DELETE FROM did_documents WHERE did = $1")
-///             .bind(did)
-///             .execute(&self.pool)
-///             .await?;
-///         Ok(())
-///     }
-/// }
-/// ```
-#[async_trait::async_trait]
-pub trait DidDocumentStorage: Send + Sync {
-    /// Retrieves a DID document associated with the given DID.
-    ///
-    /// This method looks up the complete DID document that is currently stored for the provided
-    /// DID (Decentralized Identifier). The document contains services, verification methods,
-    /// and other identity information for the DID.
-    ///
-    /// # Arguments
-    /// * `did` - The DID (Decentralized Identifier) to look up. Should be in the format
-    ///          `did:method:identifier` (e.g., "did:plc:bv6ggog3tya2z3vxsub7hnal")
-    ///
-    /// # Returns
-    /// * `Ok(Some(document))` - If a document is found for the given DID
-    /// * `Ok(None)` - If no document is currently stored for the DID
-    /// * `Err(error)` - If an error occurs during retrieval (storage failure, invalid DID format, etc.)
-    ///
-    /// # Examples
-    ///
-    /// ```rust,ignore
-    /// let storage = MyStorage::new();
-    /// let document = storage.get_document_by_did("did:plc:bv6ggog3tya2z3vxsub7hnal").await?;
-    /// match document {
-    ///     Some(doc) => {
-    ///         println!("Found document for DID: {}", doc.id);
-    ///         if let Some(handle) = doc.handles() {
-    ///             println!("Primary handle: {}", handle);
-    ///         }
-    ///     },
-    ///     None => println!("No document found for this DID"),
-    /// }
-    /// ```
-    async fn get_document_by_did(&self, did: &str) -> Result<Option<Document>>;
-
-    /// Stores or updates a DID document.
-    ///
-    /// This method creates a new DID document entry or updates an existing one.
-    /// In the AT Protocol ecosystem, this operation typically occurs when a DID document
-    /// is resolved from the network, updated by the identity owner, or cached for performance.
-    ///
-    /// Implementations should ensure that:
-    /// - The document's DID (`document.id`) is used as the key for storage
-    /// - The operation is atomic (either fully succeeds or fully fails)
-    /// - Any existing document for the same DID is properly replaced
-    /// - The complete document structure is preserved
-    ///
-    /// # Arguments
-    /// * `document` - The complete DID document to store. The document's `id` field
-    ///               will be used as the storage key.
-    ///
-    /// # Returns
-    /// * `Ok(())` - If the document was successfully stored or updated
-    /// * `Err(error)` - If an error occurs during the operation (storage failure,
-    ///                 serialization failure, constraint violation, etc.)
-    ///
-    /// # Examples
-    ///
-    /// ```rust,ignore
-    /// let storage = MyStorage::new();
-    /// let document = Document {
-    ///     id: "did:plc:bv6ggog3tya2z3vxsub7hnal".to_string(),
-    ///     also_known_as: vec!["at://alice.bsky.social".to_string()],
-    ///     service: vec![/* services */],
-    ///     verification_method: vec![/* verification methods */],
-    ///     extra: HashMap::new(),
-    /// };
-    /// storage.store_document(document).await?;
-    /// println!("Document successfully stored");
-    /// ```
-    async fn store_document(&self, document: Document) -> Result<()>;
-
-    /// Deletes a DID document by its DID.
-    ///
-    /// This method removes a DID document from storage using the DID as the identifier.
-    /// This operation is typically used when cleaning up expired cache entries, removing
-    /// invalid documents, or when an identity is deactivated.
-    ///
-    /// Implementations should:
-    /// - Handle the case where the DID doesn't exist gracefully (return Ok(()))
-    /// - Ensure the deletion is atomic
-    /// - Clean up any related data or indexes
-    /// - Preserve referential integrity if applicable
-    ///
-    /// # Arguments
-    /// * `did` - The DID identifying the document to delete.
-    ///          Should be in the format `did:method:identifier`
-    ///          (e.g., "did:plc:bv6ggog3tya2z3vxsub7hnal")
-    ///
-    /// # Returns
-    /// * `Ok(())` - If the document was successfully deleted or didn't exist
-    /// * `Err(error)` - If an error occurs during deletion (storage failure, etc.)
-    ///
-    /// # Examples
-    ///
-    /// ```rust,ignore
-    /// let storage = MyStorage::new();
-    /// storage.delete_document_by_did("did:plc:bv6ggog3tya2z3vxsub7hnal").await?;
-    /// println!("Document deleted");
-    /// ```
-    async fn delete_document_by_did(&self, did: &str) -> Result<()>;
-}

crates/atproto-identity/src/storage_lru.rs

···
 
 use crate::errors::StorageError;
 use crate::model::Document;
-use crate::storage::DidDocumentStorage;
+use crate::traits::DidDocumentStorage;
 
 /// An LRU-based implementation of `DidDocumentStorage` that maintains a fixed-size cache of DID documents.
 ///
···
 ///
 /// ```rust
 /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-/// use atproto_identity::storage::DidDocumentStorage;
+/// use atproto_identity::traits::DidDocumentStorage;
 /// use atproto_identity::model::Document;
 /// use std::num::NonZeroUsize;
 /// use std::collections::HashMap;
···
     ///
     /// ```rust
     /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-    /// use atproto_identity::storage::DidDocumentStorage;
+    /// use atproto_identity::traits::DidDocumentStorage;
     /// use atproto_identity::model::Document;
     /// use std::num::NonZeroUsize;
     /// use std::collections::HashMap;
···
     ///
     /// ```rust
     /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-    /// use atproto_identity::storage::DidDocumentStorage;
+    /// use atproto_identity::traits::DidDocumentStorage;
     /// use atproto_identity::model::Document;
     /// use std::num::NonZeroUsize;
     /// use std::collections::HashMap;
···
     ///
     /// ```rust
     /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-    /// use atproto_identity::storage::DidDocumentStorage;
+    /// use atproto_identity::traits::DidDocumentStorage;
     /// use atproto_identity::model::Document;
     /// use std::num::NonZeroUsize;
     /// use std::collections::HashMap;
···
     ///
     /// ```rust
     /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-    /// use atproto_identity::storage::DidDocumentStorage;
+    /// use atproto_identity::traits::DidDocumentStorage;
     /// use atproto_identity::model::Document;
     /// use std::num::NonZeroUsize;
     /// use std::collections::HashMap;
···
     ///
     /// ```rust
     /// use atproto_identity::storage_lru::LruDidDocumentStorage;
-    /// use atproto_identity::storage::DidDocumentStorage;
+    /// use atproto_identity::traits::DidDocumentStorage;
     /// use atproto_identity::model::Document;
     /// use std::num::NonZeroUsize;
     /// use std::collections::HashMap;
···
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::traits::DidDocumentStorage;
     use std::collections::HashMap;
     use std::num::NonZeroUsize;
 

crates/atproto-identity/src/traits.rs

···
+//! Shared trait definitions for AT Protocol identity operations.
+//!
+//! This module centralizes async traits used across the identity crate so they can
+//! be implemented without introducing circular module dependencies.
+
+use anyhow::Result;
+use async_trait::async_trait;
+
+use crate::errors::ResolveError;
+use crate::key::KeyData;
+use crate::model::Document;
+
+/// Trait for AT Protocol identity resolution.
+///
+/// Implementations must resolve handles or DIDs to canonical DID documents.
+#[async_trait]
+pub trait IdentityResolver: Send + Sync {
+    /// Resolves an AT Protocol subject to its DID document.
+    async fn resolve(&self, subject: &str) -> Result<Document>;
+}
+
+/// Trait for DNS resolution operations used during handle lookups.
+#[async_trait]
+pub trait DnsResolver: Send + Sync {
+    /// Resolves TXT records for a given domain name.
+    async fn resolve_txt(&self, domain: &str) -> Result<Vec<String>, ResolveError>;
+}
+
+/// Trait for retrieving private keys by identifier.
+#[async_trait]
+/// Trait for resolving key references (e.g., DID verification methods) to [`KeyData`].
+#[async_trait]
+pub trait KeyResolver: Send + Sync {
+    /// Resolves a key reference string into key material.
+    async fn resolve(&self, key: &str) -> Result<KeyData>;
+}
+
+/// Trait for DID document storage backends.
+#[async_trait]
+pub trait DidDocumentStorage: Send + Sync {
+    /// Retrieves a DID document if present.
+    async fn get_document_by_did(&self, did: &str) -> Result<Option<Document>>;
+
+    /// Stores or updates a DID document.
+    async fn store_document(&self, document: Document) -> Result<()>;
+
+    /// Deletes a DID document by DID.
+    async fn delete_document_by_did(&self, did: &str) -> Result<()>;
+}

crates/atproto-identity/src/url.rs

···
-//! URL construction utilities for HTTP endpoints.
+//! URL construction utilities leveraging the `url` crate.
 //!
-//! Build well-formed HTTP request URLs with parameter encoding
-//! and query string generation.
-
-/// A single query parameter as a key-value pair.
-pub type QueryParam<'a> = (&'a str, &'a str);
-/// A collection of query parameters.
-pub type QueryParams<'a> = Vec<QueryParam<'a>>;
-
-/// Builds a query string from a collection of query parameters.
-///
-/// # Arguments
-///
-/// * `query` - Collection of key-value pairs to build into a query string
-///
-/// # Returns
-///
-/// A formatted query string with URL-encoded parameters
-pub fn build_querystring(query: QueryParams) -> String {
-    query.iter().fold(String::new(), |acc, &tuple| {
-        acc + tuple.0 + "=" + tuple.1 + "&"
-    })
-}
+//! Provides helpers for building URLs and appending query parameters
+//! without manual string concatenation.
 
-/// Builder for constructing URLs with host, path, and query parameters.
-pub struct URLBuilder {
-    host: String,
-    path: String,
-    params: Vec<(String, String)>,
-}
+use url::{ParseError, Url};
 
-/// Convenience function to build a URL with optional parameters.
-///
-/// # Arguments
-///
-/// * `host` - The hostname (will be prefixed with https:// if needed)
-/// * `path` - The URL path
-/// * `params` - Vector of optional key-value pairs for query parameters
-///
-/// # Returns
-///
-/// A fully constructed URL string
-pub fn build_url(host: &str, path: &str, params: Vec<Option<(&str, &str)>>) -> String {
-    let mut url_builder = URLBuilder::new(host);
-    url_builder.path(path);
+/// Builds a URL from the provided components.
+/// Returns `Result<Url, ParseError>` to surface parsing errors.
+pub fn build_url<K, V, I>(host: &str, path: &str, params: I) -> Result<Url, ParseError>
+where
+    I: IntoIterator<Item = (K, V)>,
+    K: AsRef<str>,
+    V: AsRef<str>,
+{
+    let mut base = if host.starts_with("http://") || host.starts_with("https://") {
+        Url::parse(host)?
+    } else {
+        Url::parse(&format!("https://{}", host))?
+    };
 
-    for (key, value) in params.iter().filter_map(|x| *x) {
-        url_builder.param(key, value);
+    if !base.path().ends_with('/') {
+        let mut new_path = base.path().to_string();
+        if !new_path.ends_with('/') {
+            new_path.push('/');
+        }
+        if new_path.is_empty() {
+            new_path.push('/');
+        }
+        base.set_path(&new_path);
     }
 
-    url_builder.build()
-}
-
-impl URLBuilder {
-    /// Creates a new URLBuilder with the specified host.
-    ///
-    /// # Arguments
-    ///
-    /// * `host` - The hostname (will be prefixed with https:// if needed and trailing slash removed)
-    ///
-    /// # Returns
-    ///
-    /// A new URLBuilder instance
-    pub fn new(host: &str) -> URLBuilder {
-        let host = if host.starts_with("https://") {
-            host.to_string()
-        } else {
-            format!("https://{}", host)
-        };
-
-        let host = if let Some(trimmed) = host.strip_suffix('/') {
-            trimmed.to_string()
-        } else {
-            host
-        };
-
-        URLBuilder {
-            host: host.to_string(),
-            params: vec![],
-            path: "/".to_string(),
+    let mut url = base.join(path.trim_start_matches('/'))?;
+    {
+        let mut pairs = url.query_pairs_mut();
+        for (key, value) in params {
+            pairs.append_pair(key.as_ref(), value.as_ref());
         }
     }
+    Ok(url)
+}
 
-    /// Adds a query parameter to the URL.
-    ///
-    /// # Arguments
-    ///
-    /// * `key` - The parameter key
-    /// * `value` - The parameter value (will be URL-encoded)
-    ///
-    /// # Returns
-    ///
-    /// A mutable reference to self for method chaining
-    pub fn param(&mut self, key: &str, value: &str) -> &mut Self {
-        self.params
-            .push((key.to_owned(), urlencoding::encode(value).to_string()));
-        self
-    }
+#[cfg(test)]
+mod tests {
+    use super::*;
 
-    /// Sets the URL path.
-    ///
-    /// # Arguments
-    ///
-    /// * `path` - The URL path
-    ///
-    /// # Returns
-    ///
-    /// A mutable reference to self for method chaining
-    pub fn path(&mut self, path: &str) -> &mut Self {
-        path.clone_into(&mut self.path);
-        self
-    }
+    #[test]
+    fn builds_url_with_params() {
+        let url = build_url(
+            "example.com/api",
+            "resource",
+            [("id", "123"), ("status", "active")],
+        )
+        .expect("url build failed");
 
-    /// Constructs the final URL string.
-    ///
-    /// # Returns
-    ///
-    /// The complete URL with host, path, and query parameters
-    pub fn build(self) -> String {
-        let mut url_params = String::new();
-
-        if !self.params.is_empty() {
-            url_params.push('?');
-
-            let qs_args = self.params.iter().map(|(k, v)| (&**k, &**v)).collect();
-            url_params.push_str(build_querystring(qs_args).as_str());
-        }
-
-        format!("{}{}{}", self.host, self.path, url_params)
+        assert_eq!(
+            url.as_str(),
+            "https://example.com/api/resource?id=123&status=active"
+        );
     }
 }

crates/atproto-oauth-aip/src/workflow.rs

···
 //! and protocol violations.
 
 use anyhow::Result;
-use atproto_identity::url::URLBuilder;
+use atproto_identity::url::build_url;
 use atproto_oauth::{
     jwk::WrappedJsonWebKey,
     workflow::{OAuthRequest, OAuthRequestState, ParResponse, TokenResponse},
 };
 use serde::Deserialize;
+use std::iter;
 
 use crate::errors::OAuthWorkflowError;
 
···
     access_token_type: &Option<&str>,
     subject: &Option<&str>,
 ) -> Result<ATProtocolSession> {
-    let mut url_builder = URLBuilder::new(protected_resource_base);
-    url_builder.path("/api/atprotocol/session");
+    let mut url = build_url(
+        protected_resource_base,
+        "/api/atprotocol/session",
+        iter::empty::<(&str, &str)>(),
+    )?;
+    {
+        let mut pairs = url.query_pairs_mut();
+        if let Some(value) = access_token_type {
+            pairs.append_pair("access_token_type", value);
+        }
 
-    if let Some(value) = access_token_type {
-        url_builder.param("access_token_type", value);
-    }
-
-    if let Some(value) = subject {
-        url_builder.param("sub", value);
+        if let Some(value) = subject {
+            pairs.append_pair("sub", value);
+        }
     }
 
-    let url = url_builder.build();
+    let url: String = url.into();
 
     let response = http_client
-        .get(url)
+        .get(&url)
         .bearer_auth(access_token)
         .send()
         .await

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

···
 use async_trait::async_trait;
 use atproto_identity::{
     config::{CertificateBundles, DnsNameservers, default_env, optional_env, require_env, version},
-    key::{KeyData, KeyProvider, KeyType, generate_key, identify_key, to_public},
-    storage::DidDocumentStorage,
+    key::{KeyData, KeyResolver, KeyType, generate_key, identify_key, to_public},
     storage_lru::LruDidDocumentStorage,
+    traits::DidDocumentStorage,
 };
 
 #[cfg(feature = "hickory-dns")]
···
 };
 
 #[derive(Clone)]
-pub struct SimpleKeyProvider {
+pub struct SimpleKeyResolver {
     keys: HashMap<String, KeyData>,
 }
 
-impl Default for SimpleKeyProvider {
+impl Default for SimpleKeyResolver {
     fn default() -> Self {
         Self::new()
     }
 }
 
-impl SimpleKeyProvider {
+impl SimpleKeyResolver {
     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())
+impl KeyResolver for SimpleKeyResolver {
+    async fn resolve(&self, key_id: &str) -> anyhow::Result<KeyData> {
+        self.keys
+            .get(key_id)
+            .cloned()
+            .ok_or_else(|| anyhow::anyhow!("Key not found: {}", key_id))
     }
 }
 
···
     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>,
+    pub key_resolver: Arc<dyn KeyResolver + Send + Sync>,
 }
 
 #[derive(Clone, FromRef)]
···
     }
 }
 
-impl FromRef<WebContext> for Arc<dyn KeyProvider> {
+impl FromRef<WebContext> for Arc<dyn KeyResolver> {
     fn from_ref(context: &WebContext) -> Self {
-        context.0.key_provider.clone()
+        context.0.key_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 {
+        key_resolver: Arc::new(SimpleKeyResolver {
             keys: signing_key_storage,
         }),
     }));

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

···
 
 use anyhow::Result;
 use atproto_identity::{
-    key::{KeyProvider, identify_key},
-    storage::DidDocumentStorage,
+    key::{KeyResolver, identify_key},
+    traits::DidDocumentStorage,
 };
 use atproto_oauth::{
     resources::pds_resources,
···
     client: HttpClient,
     oauth_request_storage: State<Arc<dyn OAuthRequestStorage>>,
     did_document_storage: State<Arc<dyn DidDocumentStorage>>,
-    key_provider: State<Arc<dyn KeyProvider>>,
+    key_resolver: State<Arc<dyn KeyResolver>>,
     Form(callback_form): Form<OAuthCallbackForm>,
 ) -> Result<impl IntoResponse, OAuthCallbackError> {
     let oauth_request = oauth_request_storage
···
         });
     }
 
-    let private_signing_key_data = key_provider
-        .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_signing_key_data = key_resolver
+        .resolve(&oauth_request.signing_public_key)
+        .await
+        .map_err(|_| OAuthCallbackError::NoSigningKeyFound)?;
 
     let private_dpop_key_data = identify_key(&oauth_request.dpop_private_key)?;
 

crates/atproto-oauth/src/dpop.rs

···
 /// * `false` if no DPoP error is found or the header format is invalid
 ///
 /// # Examples
-/// ```
+/// ```no_run
 /// use atproto_oauth::dpop::is_dpop_error;
 ///
 /// // Valid DPoP error: invalid_dpop_proof
···
 /// - HTTP method or URI don't match expected values
 ///
 /// # Examples
-/// ```
+/// ```no_run
 /// use atproto_oauth::dpop::{validate_dpop_jwt, DpopValidationConfig};
 ///
 /// let dpop_jwt = "eyJhbGciOiJFUzI1NiIsImp3ayI6eyJhbGciOiJFUzI1NiIsImNydiI6IlAtMjU2Iiwia2lkIjoiZGlkOmtleTp6RG5hZVpVeEFhZDJUbkRYTjFaZWprcFV4TWVvMW9mNzF6NGVackxLRFRtaEQzOEQ3Iiwia3R5IjoiRUMiLCJ1c2UiOiJzaWciLCJ4IjoiaG56dDlSSGppUDBvMFJJTEZacEdjX0phenJUb1pHUzF1d0d5R3JleUNNbyIsInkiOiJzaXJhU2FGU09md3FrYTZRdnR3aUJhM0FKUi14eEhQaWVWZkFhZEhQQ0JRIn0sInR5cCI6ImRwb3Arand0In0.eyJqdGkiOiI2NDM0ZmFlNC00ZTYxLTQ1NDEtOTNlZC1kMzQ5ZjRiMTQ1NjEiLCJodG0iOiJQT1NUIiwiaHR1IjoiaHR0cHM6Ly9haXBkZXYudHVubi5kZXYvb2F1dGgvdG9rZW4iLCJpYXQiOjE3NDk3NjQ1MTl9.GkoB00Y-68djRHLhO5-PayNV8PWcQI1pwZaAUL3Hzppj-ga6SKMyGpPwY4kcGdHM7lvvisNkzvd7RjEmdDtnjQ";

crates/atproto-record/Cargo.toml

···
 keywords.workspace = true
 categories.workspace = true
 
-[[bin]]         
-name = "atproto-record-sign"
-test = false
-bench = false
-doc = true
-required-features = ["clap", "tokio"]
-
-[[bin]]
-name = "atproto-record-verify"
-test = false
-bench = false
-doc = true
-required-features = ["clap", "tokio"]
-
 [[bin]]
 name = "atproto-record-cid"
 test = false
···
 
 anyhow.workspace = true
 base64.workspace = true
+rand.workspace = true
 serde_ipld_dagcbor.workspace = true
 serde_json.workspace = true
 serde.workspace = true
···
 cid = "0.11"
 multihash = "0.19"
 sha2 = { workspace = true }
+
+[dev-dependencies]
+async-trait = "0.1"
+tokio = { workspace = true, features = ["macros", "rt"] }
 
 [features]
 default = ["hickory-dns"]

crates/atproto-record/README.md

···
 # atproto-record
 
-Cryptographic signature operations and utilities for AT Protocol records.
+Utilities for working with AT Protocol records.
 
 ## Overview
 
-A comprehensive Rust library for working with AT Protocol records, providing cryptographic signature creation and verification, AT-URI parsing, and datetime utilities. Built on IPLD DAG-CBOR serialization with support for P-256, P-384, and K-256 elliptic curve cryptography.
+A Rust library for working with AT Protocol records, providing AT-URI parsing, TID generation, datetime formatting, and CID generation. Built on IPLD DAG-CBOR serialization for deterministic content addressing.
 
 ## Features
 
-- **Record signing**: Create cryptographic signatures on AT Protocol records following community.lexicon.attestation.signature specification
-- **Signature verification**: Verify record signatures against public keys with issuer validation
 - **AT-URI parsing**: Parse and validate AT Protocol URIs (at://authority/collection/record_key) with robust error handling
-- **IPLD serialization**: DAG-CBOR serialization ensuring deterministic and verifiable record encoding
-- **Multi-curve support**: Full support for P-256, P-384, and K-256 elliptic curve signatures
+- **TID generation**: Timestamp-based identifiers for AT Protocol records with microsecond precision
+- **CID generation**: Content Identifier generation using DAG-CBOR serialization and SHA-256 hashing
 - **DateTime utilities**: RFC 3339 datetime serialization with millisecond precision for consistent timestamp handling
+- **Typed records**: Type-safe record handling with lexicon type validation
+- **Bytes handling**: Base64 encoding/decoding for binary data in AT Protocol records
 - **Structured errors**: Type-safe error handling following project conventions with detailed error messages
 
 ## CLI Tools
 
-The following command-line tools are available when built with the `clap` feature:
+The following command-line tool is available when built with the `clap` feature:
 
-- **`atproto-record-sign`**: Sign AT Protocol records with private keys, supporting flexible argument ordering
-- **`atproto-record-verify`**: Verify AT Protocol record signatures by validating cryptographic signatures against issuer DIDs and public keys
+- **`atproto-record-cid`**: Generate CID (Content Identifier) for AT Protocol records from JSON input
 
 ## Library Usage
 
-### Creating Signatures
+### Generating CIDs
 
 ```rust
-use atproto_record::signature;
-use atproto_identity::key::identify_key;
 use serde_json::json;
-
-// Parse the signing key from a did:key
-let key_data = identify_key("did:key:zQ3sh...")?;
-
-// The record to sign
-let record = json!({"$type": "app.bsky.feed.post", "text": "Hello world!"});
+use cid::Cid;
+use sha2::{Digest, Sha256};
+use multihash::Multihash;
 
-// Signature metadata (issuer is required, other fields are optional)
-let signature_object = json!({
-    "issuer": "did:plc:issuer"
-    // Optional: "issuedAt", "purpose", "expiry", etc.
+// Serialize a record to DAG-CBOR and generate its CID
+let record = json!({
+    "$type": "app.bsky.feed.post",
+    "text": "Hello world!",
+    "createdAt": "2024-01-01T00:00:00.000Z"
 });
 
-// Create the signed record with embedded signatures array
-let signed_record = signature::create(
-    &key_data,
-    &record,
-    "did:plc:repository",
-    "app.bsky.feed.post",
-    signature_object
-).await?;
+let dag_cbor_bytes = serde_ipld_dagcbor::to_vec(&record)?;
+let hash = Sha256::digest(&dag_cbor_bytes);
+let multihash = Multihash::wrap(0x12, &hash)?;
+let cid = Cid::new_v1(0x71, multihash);
+
+println!("Record CID: {}", cid);
 ```
 
-### Verifying Signatures
+### Generating TIDs
 
 ```rust
-use atproto_record::signature;
-use atproto_identity::key::identify_key;
+use atproto_record::tid::Tid;
 
-// Parse the public key for verification
-let issuer_key = identify_key("did:key:zQ3sh...")?;
+// Generate a new timestamp-based identifier
+let tid = Tid::new();
+println!("TID: {}", tid); // e.g., "3l2k4j5h6g7f8d9s"
 
-// Verify the signature (throws error if invalid)
-signature::verify(
-    "did:plc:issuer",      // Expected issuer DID
-    &issuer_key,           // Public key for verification
-    signed_record,         // The signed record
-    "did:plc:repository",  // Repository context
-    "app.bsky.feed.post"   // Collection context
-).await?;
+// TIDs are sortable by creation time
+let tid1 = Tid::new();
+std::thread::sleep(std::time::Duration::from_millis(1));
+let tid2 = Tid::new();
+assert!(tid1 < tid2);
 ```
 
 ### AT-URI Parsing
···
 
 ## Command Line Usage
 
-All CLI tools require the `clap` feature:
+The CLI tool requires the `clap` feature:
 
 ```bash
 # Build with CLI support
 cargo build --features clap --bins
 
-# Sign a record
-cargo run --features clap --bin atproto-record-sign -- \
-  did:key:zQ3sh...                    # Signing key (did:key format)
-  did:plc:issuer                      # Issuer DID
-  record.json                          # Record file (or use -- for stdin)
-  repository=did:plc:repo              # Repository context
-  collection=app.bsky.feed.post        # Collection type
+# Generate CID from JSON file
+cat record.json | cargo run --features clap --bin atproto-record-cid
 
-# Sign with custom fields (e.g., issuedAt, purpose, expiry)
-cargo run --features clap --bin atproto-record-sign -- \
-  did:key:zQ3sh... did:plc:issuer record.json \
-  repository=did:plc:repo collection=app.bsky.feed.post \
-  issuedAt="2024-01-01T00:00:00.000Z" purpose="attestation"
+# Generate CID from inline JSON
+echo '{"$type":"app.bsky.feed.post","text":"Hello!"}' | cargo run --features clap --bin atproto-record-cid
 
-# Verify a signature
-cargo run --features clap --bin atproto-record-verify -- \
-  did:plc:issuer                      # Expected issuer DID
-  did:key:zQ3sh...                    # Verification key
-  signed.json                          # Signed record file
-  repository=did:plc:repo              # Repository context (must match signing)
-  collection=app.bsky.feed.post        # Collection type (must match signing)
+# Example with a complete AT Protocol record
+cat <<EOF | cargo run --features clap --bin atproto-record-cid
+{
+  "$type": "app.bsky.feed.post",
+  "text": "Hello AT Protocol!",
+  "createdAt": "2024-01-01T00:00:00.000Z"
+}
+EOF
+```
 
-# Read from stdin
-echo '{"text":"Hello"}' | cargo run --features clap --bin atproto-record-sign -- \
-  did:key:zQ3sh... did:plc:issuer -- \
-  repository=did:plc:repo collection=app.bsky.feed.post
+The tool outputs the CID in base32 format:
+```
+bafyreibjzlvhtyxnhbvvzl3gj4qmg2ufl2jbhh5qr3gvvxlm7ksf3qwxqq
 ```
 
 ## License
 
-MIT License
+MIT License

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

···
-//! Command-line tool for signing AT Protocol records with cryptographic signatures.
-//!
-//! This tool creates cryptographic signatures on AT Protocol records using ECDSA
-//! signatures with IPLD DAG-CBOR serialization. It supports flexible argument
-//! ordering and customizable signature metadata.
-
-use anyhow::Result;
-use atproto_identity::{
-    key::{KeyData, identify_key},
-    resolve::{InputType, parse_input},
-};
-use atproto_record::errors::CliError;
-use atproto_record::signature::create;
-use clap::Parser;
-use serde_json::json;
-use std::{
-    collections::HashMap,
-    fs,
-    io::{self, Read},
-};
-
-/// AT Protocol Record Signing CLI
-#[derive(Parser)]
-#[command(
-    name = "atproto-record-sign",
-    version,
-    about = "Sign AT Protocol records with cryptographic signatures",
-    long_about = "
-A command-line tool for signing AT Protocol records using DID keys. Reads a JSON
-record from a file or stdin, applies a cryptographic signature, and outputs the
-signed record with embedded signature metadata.
-
-The tool accepts flexible argument ordering with DID keys, issuer DIDs, record
-inputs, and key=value parameters for repository, collection, and custom metadata.
-
-REQUIRED PARAMETERS:
-  repository=<DID>        Repository context for the signature
-  collection=<name>       Collection type context for the signature
-
-OPTIONAL PARAMETERS:
-  Any additional key=value pairs are included in the signature metadata
-  (e.g., issuedAt=<timestamp>, purpose=<string>, expiry=<timestamp>)
-
-EXAMPLES:
-  # Basic usage:
-  atproto-record-sign \\
-    did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \\
-    ./post.json \\
-    did:plc:tgudj2fjm77pzkuawquqhsxm \\
-    repository=did:plc:4zutorghlchjxzgceklue4la \\
-    collection=app.bsky.feed.post
-
-  # With custom metadata:
-  atproto-record-sign \\
-    did:key:z42tv1pb3... ./post.json did:plc:issuer... \\
-    repository=did:plc:repo... collection=app.bsky.feed.post \\
-    issuedAt=\"2024-01-01T00:00:00.000Z\" purpose=\"attestation\"
-
-  # Reading from stdin:
-  echo '{\"text\":\"Hello!\"}' | atproto-record-sign \\
-    did:key:z42tv1pb3... -- did:plc:issuer... \\
-    repository=did:plc:repo... collection=app.bsky.feed.post
-
-SIGNATURE PROCESS:
-  - Creates $sig object with repository, collection, and custom metadata
-  - Serializes record using IPLD DAG-CBOR format
-  - Generates ECDSA signatures using P-256, P-384, or K-256 curves
-  - Embeds signatures with issuer and any provided metadata
-"
-)]
-struct Args {
-    /// All arguments - flexible parsing handles DID keys, issuer DIDs, files, and key=value pairs
-    args: Vec<String>,
-}
-#[tokio::main]
-async fn main() -> Result<()> {
-    let args = Args::parse();
-
-    let arguments = args.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<KeyData> = 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(CliError::UnsupportedDidMethod {
-                        method: argument.clone(),
-                    }
-                    .into());
-                }
-                Err(_) => {
-                    return Err(CliError::DidParseFailed {
-                        did: argument.clone(),
-                    }
-                    .into());
-                }
-            }
-        } else if argument == "--" {
-            // Read record from stdin
-            if record.is_none() {
-                let mut stdin_content = String::new();
-                io::stdin()
-                    .read_to_string(&mut stdin_content)
-                    .map_err(|_| CliError::StdinReadFailed)?;
-                record = Some(
-                    serde_json::from_str(&stdin_content)
-                        .map_err(|_| CliError::StdinJsonParseFailed)?,
-                );
-            } else {
-                return Err(CliError::UnexpectedArgument {
-                    argument: argument.clone(),
-                }
-                .into());
-            }
-        } 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(|_| CliError::FileReadFailed {
-                        path: argument.clone(),
-                    })?;
-                record = Some(serde_json::from_str(&file_content).map_err(|_| {
-                    CliError::FileJsonParseFailed {
-                        path: argument.clone(),
-                    }
-                })?);
-            } else {
-                return Err(CliError::UnexpectedArgument {
-                    argument: argument.clone(),
-                }
-                .into());
-            }
-        }
-    }
-
-    let collection = collection.ok_or(CliError::MissingRequiredValue {
-        name: "collection".to_string(),
-    })?;
-    let repository = repository.ok_or(CliError::MissingRequiredValue {
-        name: "repository".to_string(),
-    })?;
-    let record = record.ok_or(CliError::MissingRequiredValue {
-        name: "record".to_string(),
-    })?;
-    let issuer = issuer.ok_or(CliError::MissingRequiredValue {
-        name: "issuer".to_string(),
-    })?;
-    let key_data = key_data.ok_or(CliError::MissingRequiredValue {
-        name: "signing_key".to_string(),
-    })?;
-
-    // Write "issuer" key to signature_extras
-    signature_extras.insert("issuer".to_string(), issuer);
-
-    let signature_object = json!(signature_extras);
-    let signed_record = create(
-        &key_data,
-        &record,
-        &repository,
-        &collection,
-        signature_object,
-    )?;
-
-    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

···
-//! Command-line tool for verifying cryptographic signatures on AT Protocol records.
-//!
-//! This tool validates signatures on AT Protocol records by reconstructing the
-//! signed content and verifying ECDSA signatures against public keys. It ensures
-//! that records have valid signatures from specified issuers.
-
-use anyhow::Result;
-use atproto_identity::{
-    key::{KeyData, identify_key},
-    resolve::{InputType, parse_input},
-};
-use atproto_record::errors::CliError;
-use atproto_record::signature::verify;
-use clap::Parser;
-use std::{
-    fs,
-    io::{self, Read},
-};
-
-/// AT Protocol Record Verification CLI
-#[derive(Parser)]
-#[command(
-    name = "atproto-record-verify",
-    version,
-    about = "Verify cryptographic signatures of AT Protocol records",
-    long_about = "
-A command-line tool for verifying cryptographic signatures of AT Protocol records.
-Reads a signed JSON record from a file or stdin, validates the embedded signatures
-using a public key, and reports verification success or failure.
-
-The tool accepts flexible argument ordering with issuer DIDs, verification keys,
-record inputs, and key=value parameters for repository and collection context.
-
-REQUIRED PARAMETERS:
-  repository=<DID>        Repository context used during signing
-  collection=<name>       Collection type context used during signing
-
-EXAMPLES:
-  # Basic verification:
-  atproto-record-verify \\
-    did:plc:tgudj2fjm77pzkuawquqhsxm \\
-    did:key:z42tv1pb3Dzog28Q1udyieg1YJP3x1Un5vraE1bttXeCDSpW \\
-    ./signed_post.json \\
-    repository=did:plc:4zutorghlchjxzgceklue4la \\
-    collection=app.bsky.feed.post
-
-  # Verify from stdin:
-  echo '{\"signatures\":[...]}' | atproto-record-verify \\
-    did:plc:issuer... did:key:z42tv1pb3... -- \\
-    repository=did:plc:repo... collection=app.bsky.feed.post
-
-VERIFICATION PROCESS:
-  - Extracts signatures from the signatures array
-  - Finds signatures matching the specified issuer DID  
-  - Reconstructs $sig object with repository and collection context
-  - Validates ECDSA signatures using P-256 or K-256 curves
-"
-)]
-struct Args {
-    /// All arguments - flexible parsing handles issuer DIDs, verification keys, files, and key=value pairs
-    args: Vec<String>,
-}
-#[tokio::main]
-async fn main() -> Result<()> {
-    let args = Args::parse();
-
-    let arguments = args.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<KeyData> = 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(CliError::UnsupportedDidMethod {
-                        method: argument.clone(),
-                    }
-                    .into());
-                }
-                Err(_) => {
-                    return Err(CliError::DidParseFailed {
-                        did: argument.clone(),
-                    }
-                    .into());
-                }
-            }
-        } else if argument == "--" {
-            // Read record from stdin
-            if record.is_none() {
-                let mut stdin_content = String::new();
-                io::stdin()
-                    .read_to_string(&mut stdin_content)
-                    .map_err(|_| CliError::StdinReadFailed)?;
-                record = Some(
-                    serde_json::from_str(&stdin_content)
-                        .map_err(|_| CliError::StdinJsonParseFailed)?,
-                );
-            } else {
-                return Err(CliError::UnexpectedArgument {
-                    argument: argument.clone(),
-                }
-                .into());
-            }
-        } 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(|_| CliError::FileReadFailed {
-                        path: argument.clone(),
-                    })?;
-                record = Some(serde_json::from_str(&file_content).map_err(|_| {
-                    CliError::FileJsonParseFailed {
-                        path: argument.clone(),
-                    }
-                })?);
-            } else {
-                return Err(CliError::UnexpectedArgument {
-                    argument: argument.clone(),
-                }
-                .into());
-            }
-        }
-    }
-
-    let collection = collection.ok_or(CliError::MissingRequiredValue {
-        name: "collection".to_string(),
-    })?;
-    let repository = repository.ok_or(CliError::MissingRequiredValue {
-        name: "repository".to_string(),
-    })?;
-    let record = record.ok_or(CliError::MissingRequiredValue {
-        name: "record".to_string(),
-    })?;
-    let issuer = issuer.ok_or(CliError::MissingRequiredValue {
-        name: "issuer".to_string(),
-    })?;
-    let key_data = key_data.ok_or(CliError::MissingRequiredValue {
-        name: "key".to_string(),
-    })?;
-
-    verify(&issuer, &key_data, record, &repository, &collection)?;
-
-    println!("OK");
-
-    Ok(())
-}

crates/atproto-record/src/errors.rs

···
 //! Errors occurring during AT-URI parsing and validation.
 //! Error codes: aturi-1 through aturi-9
 //!
+//! ### `TidError` (Domain: tid)
+//! Errors occurring during TID (Timestamp Identifier) parsing and decoding.
+//! Error codes: tid-1 through tid-3
+//!
 //! ### `CliError` (Domain: cli)
 //! Command-line interface specific errors for file I/O, argument parsing, and DID validation.
-//! Error codes: cli-1 through cli-8
+//! Error codes: cli-1 through cli-10
 //!
 //! ## Error Format
 //!
···
     /// record key component, which is not valid.
     #[error("error-atproto-record-aturi-9 Record key component cannot be empty")]
     EmptyRecordKey,
+}
+
+/// Errors that can occur during TID (Timestamp Identifier) operations.
+///
+/// This enum covers all validation failures when parsing and decoding TIDs,
+/// including format violations, invalid characters, and encoding errors.
+#[derive(Debug, Error)]
+pub enum TidError {
+    /// Error when TID string length is invalid.
+    ///
+    /// This error occurs when a TID string is not exactly 13 characters long,
+    /// which is required by the TID specification.
+    #[error("error-atproto-record-tid-1 Invalid TID length: expected {expected}, got {actual}")]
+    InvalidLength {
+        /// Expected length (always 13)
+        expected: usize,
+        /// Actual length of the provided string
+        actual: usize,
+    },
+
+    /// Error when TID contains an invalid character.
+    ///
+    /// This error occurs when a TID string contains a character outside the
+    /// base32-sortable character set (234567abcdefghijklmnopqrstuvwxyz).
+    #[error("error-atproto-record-tid-2 Invalid character '{character}' at position {position}")]
+    InvalidCharacter {
+        /// The invalid character
+        character: char,
+        /// Position in the string (0-indexed)
+        position: usize,
+    },
+
+    /// Error when TID format is invalid.
+    ///
+    /// This error occurs when the TID violates structural requirements,
+    /// such as having the top bit set (which must always be 0).
+    #[error("error-atproto-record-tid-3 Invalid TID format: {reason}")]
+    InvalidFormat {
+        /// Reason for the format violation
+        reason: String,
+    },
 }
 
 /// Errors specific to command-line interface operations.

crates/atproto-record/src/lib.rs

···
 //! ## Example Usage
 //!
 //! ```ignore
-//! use atproto_record::signature;
-//! use atproto_identity::key::identify_key;
+//! use atproto_record::attestation;
+//! use atproto_identity::key::{identify_key, sign, to_public};
+//! use base64::engine::general_purpose::STANDARD;
 //! use serde_json::json;
 //!
-//! // Sign a record
-//! let key_data = identify_key("did:key:...")?;
-//! let record = json!({"$type": "app.bsky.feed.post", "text": "Hello!"});
-//! let sig_obj = json!({"issuer": "did:plc:..."});
+//! let private_key = identify_key("did:key:zPrivate...")?;
+//! let public_key = to_public(&private_key)?;
+//! let key_reference = format!("{}", &public_key);
 //!
-//! let signed = signature::create(&key_data, &record, "did:plc:repo",
-//!                                "app.bsky.feed.post", sig_obj).await?;
+//! let record = json!({
+//!     "$type": "app.example.record",
+//!     "text": "Hello from attestation helpers!"
+//! });
+//!
+//! let sig_metadata = json!({
+//!     "$type": "com.example.inlineSignature",
+//!     "key": &key_reference,
+//!     "purpose": "demo"
+//! });
+//!
+//! let signing_record = attestation::prepare_signing_record(&record, &sig_metadata)?;
+//! let cid = attestation::create_cid(&signing_record)?;
+//! let signature_bytes = sign(&private_key, &cid.to_bytes())?;
+//!
+//! let inline_attestation = json!({
+//!     "$type": "com.example.inlineSignature",
+//!    "key": key_reference,
+//!     "purpose": "demo",
+//!     "signature": {"$bytes": STANDARD.encode(signature_bytes)}
+//! });
 //!
-//! // Verify a signature
-//! signature::verify("did:plc:issuer", &key_data, signed,
-//!                   "did:plc:repo", "app.bsky.feed.post").await?;
+//! let signed = attestation::create_inline_attestation_reference(&record, &inline_attestation)?;
+//! let reports = tokio_test::block_on(async {
+//!     attestation::verify_all_signatures(&signed, None).await
+//! })?;
+//! assert!(matches!(reports[0].status, attestation::VerificationStatus::Valid { .. }));
 //! ```
 
 #![forbid(unsafe_code)]
···
 /// and CLI operations. All errors follow the project's standardized format:
 /// `error-atproto-record-{domain}-{number} {message}: {details}`
 pub mod errors;
-
-/// Core signature creation and verification.
-///
-/// Provides functions for creating and verifying cryptographic signatures on
-/// AT Protocol records using IPLD DAG-CBOR serialization. Supports the
-/// community.lexicon.attestation.signature specification with proper $sig
-/// object handling and multiple signature support.
-pub mod signature;
 
 /// AT-URI parsing and validation.
 ///
···
 /// in many AT Protocol lexicon structures. The wrapper can automatically add type
 /// fields during serialization and validate them during deserialization.
 pub mod typed;
+
+/// Timestamp Identifier (TID) generation and parsing.
+///
+/// TIDs are sortable, distributed identifiers combining microsecond timestamps
+/// with random clock identifiers. They provide a collision-resistant, monotonically
+/// increasing identifier scheme for AT Protocol records encoded as 13-character
+/// base32-sortable strings.
+pub mod tid;

crates/atproto-record/src/signature.rs

···
-//! AT Protocol record signature creation and verification.
-//!
-//! This module provides comprehensive functionality for creating and verifying
-//! cryptographic signatures on AT Protocol records following the
-//! community.lexicon.attestation.signature specification.
-//!
-//! ## Signature Process
-//!
-//! 1. **Signing**: Records are augmented with a `$sig` object containing issuer,
-//!    timestamp, and context information, then serialized using IPLD DAG-CBOR
-//!    for deterministic encoding before signing with ECDSA.
-//!
-//! 2. **Storage**: Signatures are stored in a `signatures` array within the record,
-//!    allowing multiple signatures from different issuers.
-//!
-//! 3. **Verification**: The original signed content is reconstructed by replacing
-//!    the signatures array with the appropriate `$sig` object, then verified
-//!    using the issuer's public key.
-//!
-//! ## Supported Curves
-//!
-//! - P-256 (NIST P-256 / secp256r1)
-//! - P-384 (NIST P-384 / secp384r1)  
-//! - K-256 (secp256k1)
-//!
-//! ## Example
-//!
-//! ```ignore
-//! use atproto_record::signature::{create, verify};
-//! use atproto_identity::key::identify_key;
-//! use serde_json::json;
-//!
-//! // Create a signature
-//! let key = identify_key("did:key:...")?;
-//! let record = json!({"text": "Hello!"});
-//! let sig_obj = json!({
-//!     "issuer": "did:plc:issuer"
-//!     // Optional: any additional fields like "issuedAt", "purpose", etc.
-//! });
-//!
-//! let signed = create(&key, &record, "did:plc:repo",
-//!                     "app.bsky.feed.post", sig_obj)?;
-//!
-//! // Verify the signature
-//! verify("did:plc:issuer", &key, signed,
-//!        "did:plc:repo", "app.bsky.feed.post")?;
-//! ```
-
-use atproto_identity::key::{KeyData, sign, validate};
-use base64::{Engine, engine::general_purpose::STANDARD};
-use serde_json::json;
-
-use crate::errors::VerificationError;
-
-/// Creates a cryptographic signature for an AT Protocol record.
-///
-/// This function generates a signature following the community.lexicon.attestation.signature
-/// specification. The record is augmented with a `$sig` object containing context information,
-/// serialized using IPLD DAG-CBOR, signed with the provided key, and the signature is added
-/// to a `signatures` array in the returned record.
-///
-/// # Parameters
-///
-/// * `key_data` - The signing key (private key) wrapped in KeyData
-/// * `record` - The JSON record to be signed (will not be modified)
-/// * `repository` - The repository DID where this record will be stored
-/// * `collection` - The collection type (NSID) for this record
-/// * `signature_object` - Metadata for the signature, must include:
-///   - `issuer`: The DID of the entity creating the signature (required)
-///   - Additional custom fields are preserved in the signature (optional)
-///
-/// # Returns
-///
-/// Returns a new record containing:
-/// - All original record fields
-/// - A `signatures` array with the new signature appended
-/// - No `$sig` field (only used during signing)
-///
-/// # Errors
-///
-/// Returns [`VerificationError`] if:
-/// - Required field `issuer` is missing from signature_object
-/// - IPLD DAG-CBOR serialization fails
-/// - Cryptographic signing operation fails
-/// - JSON structure manipulation fails
-pub fn create(
-    key_data: &KeyData,
-    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(),
-            });
-        }
-    } 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));
-        record_map.insert(
-            "$type".to_string(),
-            json!("community.lexicon.attestation.signature"),
-        );
-    }
-
-    // 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: Vec<u8> = sign(key_data, &serialized_signing_record)?;
-    let encoded_signature = STANDARD.encode(&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!({"$bytes": json!(encoded_signature)}),
-        );
-        record_map.insert(
-            "$type".to_string(),
-            json!("community.lexicon.attestation.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 signatures by reconstructing the original signed content
-/// (record with `$sig` object) and verifying the ECDSA signature against it.
-/// It searches through all signatures in the record to find one matching the
-/// specified issuer, then verifies it with the provided public key.
-///
-/// # Parameters
-///
-/// * `issuer` - The DID of the expected signature issuer to verify
-/// * `key_data` - The public key for signature verification
-/// * `record` - The signed record containing a `signatures` or `sigs` array
-/// * `repository` - The repository DID used during signing (must match)
-/// * `collection` - The collection type used during signing (must match)
-///
-/// # Returns
-///
-/// Returns `Ok(())` if a valid signature from the specified issuer is found
-/// and successfully verified against the reconstructed signed content.
-///
-/// # Errors
-///
-/// Returns [`VerificationError`] if:
-/// - No `signatures` or `sigs` field exists in the record
-/// - No signature from the specified issuer is found
-/// - The issuer's signature is malformed or missing required fields
-/// - The signature is not in the expected `{"$bytes": "..."}` format
-/// - Base64 decoding of the signature fails
-/// - IPLD DAG-CBOR serialization of reconstructed content fails
-/// - Cryptographic verification fails (invalid signature)
-///
-/// # Note
-///
-/// This function supports both `signatures` and `sigs` field names for
-/// backward compatibility with different AT Protocol implementations.
-pub fn verify(
-    issuer: &str,
-    key_data: &KeyData,
-    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_object())
-            .and_then(|obj| obj.get("$bytes"))
-            .and_then(|b| b.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.remove("sigs");
-            record_map.insert("$sig".to_string(), sig_variable);
-        }
-
-        let serialized_record = serde_ipld_dagcbor::to_vec(&signed_record)
-            .map_err(|error| VerificationError::RecordSerializationFailed { error })?;
-
-        let signature_bytes = STANDARD
-            .decode(signature_value)
-            .map_err(|error| VerificationError::SignatureDecodingFailed { error })?;
-
-        validate(key_data, &signature_bytes, &serialized_record)
-            .map_err(|error| VerificationError::CryptographicValidationFailed { error })?;
-
-        return Ok(());
-    }
-
-    Err(VerificationError::NoValidSignatureForIssuer {
-        issuer: issuer.to_string(),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use atproto_identity::key::{KeyType, generate_key, to_public};
-    use serde_json::json;
-
-    #[test]
-    fn test_create_sign_and_verify_record_p256() -> Result<(), Box<dyn std::error::Error>> {
-        // Step 1: Generate a P-256 key pair
-        let private_key = generate_key(KeyType::P256Private)?;
-        let public_key = to_public(&private_key)?;
-
-        // Step 2: Create a sample record
-        let record = json!({
-            "text": "Hello AT Protocol!",
-            "createdAt": "2025-01-19T10:00:00Z",
-            "langs": ["en"]
-        });
-
-        // Step 3: Define signature metadata
-        let issuer_did = "did:plc:test123";
-        let repository = "did:plc:repo456";
-        let collection = "app.bsky.feed.post";
-
-        let signature_object = json!({
-            "issuer": issuer_did,
-            "issuedAt": "2025-01-19T10:00:00Z",
-            "purpose": "attestation"
-        });
-
-        // Step 4: Sign the record
-        let signed_record = create(
-            &private_key,
-            &record,
-            repository,
-            collection,
-            signature_object.clone(),
-        )?;
-
-        // Verify that the signed record contains signatures array
-        assert!(signed_record.get("signatures").is_some());
-        let signatures = signed_record
-            .get("signatures")
-            .and_then(|v| v.as_array())
-            .expect("signatures should be an array");
-        assert_eq!(signatures.len(), 1);
-
-        // Verify signature object structure
-        let sig = &signatures[0];
-        assert_eq!(sig.get("issuer").and_then(|v| v.as_str()), Some(issuer_did));
-        assert!(sig.get("signature").is_some());
-        assert_eq!(
-            sig.get("$type").and_then(|v| v.as_str()),
-            Some("community.lexicon.attestation.signature")
-        );
-
-        // Step 5: Verify the signature
-        verify(
-            issuer_did,
-            &public_key,
-            signed_record.clone(),
-            repository,
-            collection,
-        )?;
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_create_sign_and_verify_record_k256() -> Result<(), Box<dyn std::error::Error>> {
-        // Test with K-256 curve
-        let private_key = generate_key(KeyType::K256Private)?;
-        let public_key = to_public(&private_key)?;
-
-        let record = json!({
-            "subject": "at://did:plc:example/app.bsky.feed.post/123",
-            "likedAt": "2025-01-19T10:00:00Z"
-        });
-
-        let issuer_did = "did:plc:issuer789";
-        let repository = "did:plc:repo789";
-        let collection = "app.bsky.feed.like";
-
-        let signature_object = json!({
-            "issuer": issuer_did,
-            "issuedAt": "2025-01-19T10:00:00Z"
-        });
-
-        let signed_record = create(
-            &private_key,
-            &record,
-            repository,
-            collection,
-            signature_object,
-        )?;
-
-        verify(
-            issuer_did,
-            &public_key,
-            signed_record,
-            repository,
-            collection,
-        )?;
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_create_sign_and_verify_record_p384() -> Result<(), Box<dyn std::error::Error>> {
-        // Test with P-384 curve
-        let private_key = generate_key(KeyType::P384Private)?;
-        let public_key = to_public(&private_key)?;
-
-        let record = json!({
-            "displayName": "Test User",
-            "description": "Testing P-384 signatures"
-        });
-
-        let issuer_did = "did:web:example.com";
-        let repository = "did:plc:profile123";
-        let collection = "app.bsky.actor.profile";
-
-        let signature_object = json!({
-            "issuer": issuer_did,
-            "issuedAt": "2025-01-19T10:00:00Z",
-            "expiresAt": "2025-01-20T10:00:00Z",
-            "customField": "custom value"
-        });
-
-        let signed_record = create(
-            &private_key,
-            &record,
-            repository,
-            collection,
-            signature_object.clone(),
-        )?;
-
-        // Verify custom fields are preserved in signature
-        let signatures = signed_record
-            .get("signatures")
-            .and_then(|v| v.as_array())
-            .expect("signatures should exist");
-        let sig = &signatures[0];
-        assert_eq!(
-            sig.get("customField").and_then(|v| v.as_str()),
-            Some("custom value")
-        );
-
-        verify(
-            issuer_did,
-            &public_key,
-            signed_record,
-            repository,
-            collection,
-        )?;
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_multiple_signatures() -> Result<(), Box<dyn std::error::Error>> {
-        // Create a record with multiple signatures from different issuers
-        let private_key1 = generate_key(KeyType::P256Private)?;
-        let public_key1 = to_public(&private_key1)?;
-
-        let private_key2 = generate_key(KeyType::K256Private)?;
-        let public_key2 = to_public(&private_key2)?;
-
-        let record = json!({
-            "text": "Multi-signed content",
-            "important": true
-        });
-
-        let repository = "did:plc:repo_multi";
-        let collection = "app.example.document";
-
-        // First signature
-        let issuer1 = "did:plc:issuer1";
-        let sig_obj1 = json!({
-            "issuer": issuer1,
-            "issuedAt": "2025-01-19T09:00:00Z",
-            "role": "author"
-        });
-
-        let signed_once = create(&private_key1, &record, repository, collection, sig_obj1)?;
-
-        // Second signature on already signed record
-        let issuer2 = "did:plc:issuer2";
-        let sig_obj2 = json!({
-            "issuer": issuer2,
-            "issuedAt": "2025-01-19T10:00:00Z",
-            "role": "reviewer"
-        });
-
-        let signed_twice = create(
-            &private_key2,
-            &signed_once,
-            repository,
-            collection,
-            sig_obj2,
-        )?;
-
-        // Verify we have two signatures
-        let signatures = signed_twice
-            .get("signatures")
-            .and_then(|v| v.as_array())
-            .expect("signatures should exist");
-        assert_eq!(signatures.len(), 2);
-
-        // Verify both signatures independently
-        verify(
-            issuer1,
-            &public_key1,
-            signed_twice.clone(),
-            repository,
-            collection,
-        )?;
-        verify(
-            issuer2,
-            &public_key2,
-            signed_twice.clone(),
-            repository,
-            collection,
-        )?;
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_verify_wrong_issuer_fails() -> Result<(), Box<dyn std::error::Error>> {
-        let private_key = generate_key(KeyType::P256Private)?;
-        let public_key = to_public(&private_key)?;
-
-        let record = json!({"test": "data"});
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-
-        let sig_obj = json!({
-            "issuer": "did:plc:correct_issuer"
-        });
-
-        let signed = create(&private_key, &record, repository, collection, sig_obj)?;
-
-        // Try to verify with wrong issuer
-        let result = verify(
-            "did:plc:wrong_issuer",
-            &public_key,
-            signed,
-            repository,
-            collection,
-        );
-
-        assert!(result.is_err());
-        assert!(matches!(
-            result.unwrap_err(),
-            VerificationError::NoValidSignatureForIssuer { .. }
-        ));
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_verify_wrong_key_fails() -> Result<(), Box<dyn std::error::Error>> {
-        let private_key = generate_key(KeyType::P256Private)?;
-        let wrong_private_key = generate_key(KeyType::P256Private)?;
-        let wrong_public_key = to_public(&wrong_private_key)?;
-
-        let record = json!({"test": "data"});
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-        let issuer = "did:plc:issuer";
-
-        let sig_obj = json!({ "issuer": issuer });
-
-        let signed = create(&private_key, &record, repository, collection, sig_obj)?;
-
-        // Try to verify with wrong key
-        let result = verify(issuer, &wrong_public_key, signed, repository, collection);
-
-        assert!(result.is_err());
-        assert!(matches!(
-            result.unwrap_err(),
-            VerificationError::CryptographicValidationFailed { .. }
-        ));
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_verify_tampered_record_fails() -> Result<(), Box<dyn std::error::Error>> {
-        let private_key = generate_key(KeyType::P256Private)?;
-        let public_key = to_public(&private_key)?;
-
-        let record = json!({"text": "original"});
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-        let issuer = "did:plc:issuer";
-
-        let sig_obj = json!({ "issuer": issuer });
-
-        let mut signed = create(&private_key, &record, repository, collection, sig_obj)?;
-
-        // Tamper with the record content
-        if let Some(obj) = signed.as_object_mut() {
-            obj.insert("text".to_string(), json!("tampered"));
-        }
-
-        // Verification should fail
-        let result = verify(issuer, &public_key, signed, repository, collection);
-
-        assert!(result.is_err());
-        assert!(matches!(
-            result.unwrap_err(),
-            VerificationError::CryptographicValidationFailed { .. }
-        ));
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_create_missing_issuer_fails() -> Result<(), Box<dyn std::error::Error>> {
-        let private_key = generate_key(KeyType::P256Private)?;
-
-        let record = json!({"test": "data"});
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-
-        // Signature object without issuer field
-        let sig_obj = json!({
-            "issuedAt": "2025-01-19T10:00:00Z"
-        });
-
-        let result = create(&private_key, &record, repository, collection, sig_obj);
-
-        assert!(result.is_err());
-        assert!(matches!(
-            result.unwrap_err(),
-            VerificationError::SignatureObjectMissingField { field } if field == "issuer"
-        ));
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_verify_supports_sigs_field() -> Result<(), Box<dyn std::error::Error>> {
-        // Test backward compatibility with "sigs" field name
-        let private_key = generate_key(KeyType::P256Private)?;
-        let public_key = to_public(&private_key)?;
-
-        let record = json!({"test": "data"});
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-        let issuer = "did:plc:issuer";
-
-        let sig_obj = json!({ "issuer": issuer });
-
-        let mut signed = create(&private_key, &record, repository, collection, sig_obj)?;
-
-        // Rename "signatures" to "sigs"
-        if let Some(obj) = signed.as_object_mut()
-            && let Some(signatures) = obj.remove("signatures")
-        {
-            obj.insert("sigs".to_string(), signatures);
-        }
-
-        // Should still verify successfully
-        verify(issuer, &public_key, signed, repository, collection)?;
-
-        Ok(())
-    }
-
-    #[test]
-    fn test_signature_preserves_original_record() -> Result<(), Box<dyn std::error::Error>> {
-        let private_key = generate_key(KeyType::P256Private)?;
-
-        let original_record = json!({
-            "text": "Original content",
-            "metadata": {
-                "author": "Test",
-                "version": 1
-            },
-            "tags": ["test", "sample"]
-        });
-
-        let repository = "did:plc:repo";
-        let collection = "app.test";
-
-        let sig_obj = json!({
-            "issuer": "did:plc:issuer"
-        });
-
-        let signed = create(
-            &private_key,
-            &original_record,
-            repository,
-            collection,
-            sig_obj,
-        )?;
-
-        // All original fields should be preserved
-        assert_eq!(signed.get("text"), original_record.get("text"));
-        assert_eq!(signed.get("metadata"), original_record.get("metadata"));
-        assert_eq!(signed.get("tags"), original_record.get("tags"));
-
-        // Plus the new signatures field
-        assert!(signed.get("signatures").is_some());
-
-        Ok(())
-    }
-}

crates/atproto-record/src/tid.rs

···
+//! Timestamp Identifier (TID) generation and parsing.
+//!
+//! TIDs are 64-bit integers encoded as 13-character base32-sortable strings, combining
+//! a microsecond timestamp with a random clock identifier for collision resistance.
+//! They provide a sortable, distributed identifier scheme for AT Protocol records.
+//!
+//! ## Format
+//!
+//! - **Length**: Always 13 ASCII characters
+//! - **Encoding**: Base32-sortable character set (`234567abcdefghijklmnopqrstuvwxyz`)
+//! - **Structure**: 64-bit big-endian integer with:
+//!   - Bit 0 (top): Always 0
+//!   - Bits 1-53: Microseconds since UNIX epoch
+//!   - Bits 54-63: Random 10-bit clock identifier
+//!
+//! ## Example
+//!
+//! ```
+//! use atproto_record::tid::Tid;
+//!
+//! // Generate a new TID
+//! let tid = Tid::new();
+//! let tid_str = tid.to_string();
+//! assert_eq!(tid_str.len(), 13);
+//!
+//! // Parse a TID string
+//! let parsed = tid_str.parse::<Tid>().unwrap();
+//! assert_eq!(tid, parsed);
+//!
+//! // TIDs are sortable by timestamp
+//! let tid1 = Tid::new();
+//! std::thread::sleep(std::time::Duration::from_micros(10));
+//! let tid2 = Tid::new();
+//! assert!(tid1 < tid2);
+//! ```
+
+use std::fmt;
+use std::str::FromStr;
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use crate::errors::TidError;
+
+/// Base32-sortable character set for TID encoding.
+///
+/// This character set maintains lexicographic sort order when encoded TIDs
+/// are compared as strings, ensuring timestamp ordering is preserved.
+const BASE32_SORTABLE: &[u8; 32] = b"234567abcdefghijklmnopqrstuvwxyz";
+
+/// Reverse lookup table for base32-sortable decoding.
+///
+/// Maps ASCII character values to their corresponding 5-bit values.
+/// Invalid characters are marked with 0xFF.
+const BASE32_DECODE: [u8; 256] = {
+    let mut table = [0xFF; 256];
+    table[b'2' as usize] = 0;
+    table[b'3' as usize] = 1;
+    table[b'4' as usize] = 2;
+    table[b'5' as usize] = 3;
+    table[b'6' as usize] = 4;
+    table[b'7' as usize] = 5;
+    table[b'a' as usize] = 6;
+    table[b'b' as usize] = 7;
+    table[b'c' as usize] = 8;
+    table[b'd' as usize] = 9;
+    table[b'e' as usize] = 10;
+    table[b'f' as usize] = 11;
+    table[b'g' as usize] = 12;
+    table[b'h' as usize] = 13;
+    table[b'i' as usize] = 14;
+    table[b'j' as usize] = 15;
+    table[b'k' as usize] = 16;
+    table[b'l' as usize] = 17;
+    table[b'm' as usize] = 18;
+    table[b'n' as usize] = 19;
+    table[b'o' as usize] = 20;
+    table[b'p' as usize] = 21;
+    table[b'q' as usize] = 22;
+    table[b'r' as usize] = 23;
+    table[b's' as usize] = 24;
+    table[b't' as usize] = 25;
+    table[b'u' as usize] = 26;
+    table[b'v' as usize] = 27;
+    table[b'w' as usize] = 28;
+    table[b'x' as usize] = 29;
+    table[b'y' as usize] = 30;
+    table[b'z' as usize] = 31;
+    table
+};
+
+/// Timestamp Identifier (TID) for AT Protocol records.
+///
+/// A TID combines a microsecond-precision timestamp with a random clock identifier
+/// to create a sortable, collision-resistant identifier. TIDs are represented as
+/// 13-character base32-sortable strings.
+///
+/// ## Monotonicity
+///
+/// The TID generator ensures monotonically increasing values even when the system
+/// clock moves backwards or multiple TIDs are generated within the same microsecond.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Tid(u64);
+
+/// Thread-local state for monotonic TID generation.
+///
+/// Tracks the last generated timestamp and clock identifier to ensure
+/// monotonically increasing TID values.
+static LAST_TID: Mutex<Option<(u64, u16)>> = Mutex::new(None);
+
+impl Tid {
+    /// The length of a TID string in characters.
+    pub const LENGTH: usize = 13;
+
+    /// Maximum valid timestamp value (53 bits).
+    const MAX_TIMESTAMP: u64 = (1u64 << 53) - 1;
+
+    /// Bitmask for extracting the 10-bit clock identifier.
+    const CLOCK_ID_MASK: u64 = 0x3FF;
+
+    /// Creates a new TID with the current timestamp and a random clock identifier.
+    ///
+    /// This function ensures monotonically increasing TID values by tracking the
+    /// last generated TID and incrementing the clock identifier when necessary.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atproto_record::tid::Tid;
+    ///
+    /// let tid = Tid::new();
+    /// println!("Generated TID: {}", tid);
+    /// ```
+    pub fn new() -> Self {
+        Self::new_with_time(Self::current_timestamp_micros())
+    }
+
+    /// Creates a new TID with a specific timestamp (for testing).
+    ///
+    /// # Arguments
+    ///
+    /// * `timestamp_micros` - Microseconds since UNIX epoch
+    ///
+    /// # Panics
+    ///
+    /// Panics if the timestamp exceeds 53 bits (year 2255+).
+    pub fn new_with_time(timestamp_micros: u64) -> Self {
+        assert!(
+            timestamp_micros <= Self::MAX_TIMESTAMP,
+            "Timestamp exceeds 53-bit maximum"
+        );
+
+        let mut last = LAST_TID.lock().unwrap();
+
+        let clock_id = if let Some((last_timestamp, last_clock)) = *last {
+            if timestamp_micros > last_timestamp {
+                // New timestamp, generate random clock ID
+                Self::random_clock_id()
+            } else if timestamp_micros == last_timestamp {
+                // Same timestamp, increment clock ID
+                if last_clock == Self::CLOCK_ID_MASK as u16 {
+                    // Clock ID overflow, use random
+                    Self::random_clock_id()
+                } else {
+                    last_clock + 1
+                }
+            } else {
+                // Clock moved backwards, use last timestamp + 1
+                let adjusted_timestamp = last_timestamp + 1;
+                let adjusted_clock = Self::random_clock_id();
+                *last = Some((adjusted_timestamp, adjusted_clock));
+                return Self::from_parts(adjusted_timestamp, adjusted_clock);
+            }
+        } else {
+            // First TID, generate random clock ID
+            Self::random_clock_id()
+        };
+
+        *last = Some((timestamp_micros, clock_id));
+        Self::from_parts(timestamp_micros, clock_id)
+    }
+
+    /// Creates a TID from timestamp and clock identifier components.
+    ///
+    /// # Arguments
+    ///
+    /// * `timestamp_micros` - Microseconds since UNIX epoch (53 bits max)
+    /// * `clock_id` - Random clock identifier (10 bits max)
+    ///
+    /// # Panics
+    ///
+    /// Panics if timestamp exceeds 53 bits or clock_id exceeds 10 bits.
+    pub fn from_parts(timestamp_micros: u64, clock_id: u16) -> Self {
+        assert!(
+            timestamp_micros <= Self::MAX_TIMESTAMP,
+            "Timestamp exceeds 53-bit maximum"
+        );
+        assert!(
+            clock_id <= Self::CLOCK_ID_MASK as u16,
+            "Clock ID exceeds 10-bit maximum"
+        );
+
+        // Combine: top bit 0, 53 bits timestamp, 10 bits clock ID
+        let value = (timestamp_micros << 10) | (clock_id as u64);
+        Tid(value)
+    }
+
+    /// Returns the timestamp component in microseconds since UNIX epoch.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atproto_record::tid::Tid;
+    ///
+    /// let tid = Tid::new();
+    /// let timestamp = tid.timestamp_micros();
+    /// println!("Timestamp: {} μs", timestamp);
+    /// ```
+    pub fn timestamp_micros(&self) -> u64 {
+        self.0 >> 10
+    }
+
+    /// Returns the clock identifier component (10 bits).
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atproto_record::tid::Tid;
+    ///
+    /// let tid = Tid::new();
+    /// let clock_id = tid.clock_id();
+    /// println!("Clock ID: {}", clock_id);
+    /// ```
+    pub fn clock_id(&self) -> u16 {
+        (self.0 & Self::CLOCK_ID_MASK) as u16
+    }
+
+    /// Returns the raw 64-bit integer value.
+    pub fn as_u64(&self) -> u64 {
+        self.0
+    }
+
+    /// Encodes the TID as a 13-character base32-sortable string.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atproto_record::tid::Tid;
+    ///
+    /// let tid = Tid::new();
+    /// let encoded = tid.encode();
+    /// assert_eq!(encoded.len(), 13);
+    /// ```
+    pub fn encode(&self) -> String {
+        let mut chars = [0u8; Self::LENGTH];
+        let mut value = self.0;
+
+        // Encode from right to left (least significant to most significant)
+        for i in (0..Self::LENGTH).rev() {
+            chars[i] = BASE32_SORTABLE[(value & 0x1F) as usize];
+            value >>= 5;
+        }
+
+        // BASE32_SORTABLE only contains valid UTF-8 ASCII characters
+        String::from_utf8(chars.to_vec()).expect("base32-sortable encoding is always valid UTF-8")
+    }
+
+    /// Decodes a base32-sortable string into a TID.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`TidError::InvalidLength`] if the string is not exactly 13 characters.
+    /// Returns [`TidError::InvalidCharacter`] if the string contains invalid characters.
+    /// Returns [`TidError::InvalidFormat`] if the decoded value has the top bit set.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use atproto_record::tid::Tid;
+    ///
+    /// let tid_str = "3jzfcijpj2z2a";
+    /// let tid = Tid::decode(tid_str).unwrap();
+    /// assert_eq!(tid.to_string(), tid_str);
+    /// ```
+    pub fn decode(s: &str) -> Result<Self, TidError> {
+        if s.len() != Self::LENGTH {
+            return Err(TidError::InvalidLength {
+                expected: Self::LENGTH,
+                actual: s.len(),
+            });
+        }
+
+        let bytes = s.as_bytes();
+        let mut value: u64 = 0;
+
+        for (i, &byte) in bytes.iter().enumerate() {
+            let decoded = BASE32_DECODE[byte as usize];
+            if decoded == 0xFF {
+                return Err(TidError::InvalidCharacter {
+                    character: byte as char,
+                    position: i,
+                });
+            }
+            value = (value << 5) | (decoded as u64);
+        }
+
+        // Verify top bit is 0
+        if value & (1u64 << 63) != 0 {
+            return Err(TidError::InvalidFormat {
+                reason: "Top bit must be 0".to_string(),
+            });
+        }
+
+        Ok(Tid(value))
+    }
+
+    /// Gets the current timestamp in microseconds since UNIX epoch.
+    fn current_timestamp_micros() -> u64 {
+        SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("System time before UNIX epoch")
+            .as_micros() as u64
+    }
+
+    /// Generates a random 10-bit clock identifier.
+    fn random_clock_id() -> u16 {
+        use rand::RngCore;
+        let mut rng = rand::thread_rng();
+        (rng.next_u32() as u16) & (Self::CLOCK_ID_MASK as u16)
+    }
+}
+
+impl Default for Tid {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl fmt::Display for Tid {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.encode())
+    }
+}
+
+impl FromStr for Tid {
+    type Err = TidError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::decode(s)
+    }
+}
+
+impl serde::Serialize for Tid {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        serializer.serialize_str(&self.encode())
+    }
+}
+
+impl<'de> serde::Deserialize<'de> for Tid {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let s = String::deserialize(deserializer)?;
+        Self::decode(&s).map_err(serde::de::Error::custom)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_tid_encode_decode() {
+        let tid = Tid::new();
+        let encoded = tid.encode();
+        assert_eq!(encoded.len(), Tid::LENGTH);
+
+        let decoded = Tid::decode(&encoded).unwrap();
+        assert_eq!(tid, decoded);
+    }
+
+    #[test]
+    fn test_tid_from_parts() {
+        let timestamp = 1234567890123456u64;
+        let clock_id = 42u16;
+        let tid = Tid::from_parts(timestamp, clock_id);
+
+        assert_eq!(tid.timestamp_micros(), timestamp);
+        assert_eq!(tid.clock_id(), clock_id);
+    }
+
+    #[test]
+    fn test_tid_monotonic() {
+        let tid1 = Tid::new();
+        std::thread::sleep(std::time::Duration::from_micros(10));
+        let tid2 = Tid::new();
+
+        assert!(tid1 < tid2);
+    }
+
+    #[test]
+    fn test_tid_same_timestamp() {
+        let timestamp = 1234567890123456u64;
+        let tid1 = Tid::new_with_time(timestamp);
+        let tid2 = Tid::new_with_time(timestamp);
+
+        // Should have different clock IDs or incremented clock ID
+        assert!(tid1 < tid2 || tid1.clock_id() + 1 == tid2.clock_id());
+    }
+
+    #[test]
+    fn test_tid_string_roundtrip() {
+        let tid = Tid::new();
+        let s = tid.to_string();
+        let parsed: Tid = s.parse().unwrap();
+        assert_eq!(tid, parsed);
+    }
+
+    #[test]
+    fn test_tid_serde() {
+        let tid = Tid::new();
+        let json = serde_json::to_string(&tid).unwrap();
+        let parsed: Tid = serde_json::from_str(&json).unwrap();
+        assert_eq!(tid, parsed);
+    }
+
+    #[test]
+    fn test_tid_valid_examples() {
+        // Examples from the specification
+        let examples = ["3jzfcijpj2z2a", "7777777777777", "2222222222222"];
+
+        for example in &examples {
+            let tid = Tid::decode(example).unwrap();
+            assert_eq!(&tid.encode(), example);
+        }
+    }
+
+    #[test]
+    fn test_tid_invalid_length() {
+        let result = Tid::decode("123");
+        assert!(matches!(result, Err(TidError::InvalidLength { .. })));
+    }
+
+    #[test]
+    fn test_tid_invalid_character() {
+        let result = Tid::decode("123456789012!");
+        assert!(matches!(result, Err(TidError::InvalidCharacter { .. })));
+    }
+
+    #[test]
+    fn test_tid_first_char_range() {
+        // First character must be in valid range per spec
+        let tid = Tid::new();
+        let encoded = tid.encode();
+        let first_char = encoded.chars().next().unwrap();
+
+        // First char must be 234567abcdefghij (values 0-15 in base32-sortable)
+        assert!("234567abcdefghij".contains(first_char));
+    }
+
+    #[test]
+    fn test_tid_sortability() {
+        // TIDs with increasing timestamps should sort correctly as strings
+        let tid1 = Tid::from_parts(1000000, 0);
+        let tid2 = Tid::from_parts(2000000, 0);
+        let tid3 = Tid::from_parts(3000000, 0);
+
+        let s1 = tid1.to_string();
+        let s2 = tid2.to_string();
+        let s3 = tid3.to_string();
+
+        assert!(s1 < s2);
+        assert!(s2 < s3);
+        assert!(s1 < s3);
+    }
+
+    #[test]
+    fn test_tid_clock_backward() {
+        // Simulate clock moving backwards
+        let timestamp1 = 2000000u64;
+        let tid1 = Tid::new_with_time(timestamp1);
+
+        let timestamp2 = 1000000u64; // Earlier timestamp
+        let tid2 = Tid::new_with_time(timestamp2);
+
+        // TID should still be monotonically increasing
+        assert!(tid2 > tid1);
+    }
+}

crates/atproto-xrpcs-helloworld/src/main.rs

···
 use atproto_identity::resolve::SharedIdentityResolver;
 use atproto_identity::{
     config::{CertificateBundles, DnsNameservers, default_env, optional_env, require_env, version},
-    key::{KeyData, KeyProvider, identify_key, to_public},
+    key::{KeyData, KeyResolver, identify_key, to_public},
     resolve::{HickoryDnsResolver, IdentityResolver, InnerIdentityResolver},
-    storage::DidDocumentStorage,
     storage_lru::LruDidDocumentStorage,
+    traits::DidDocumentStorage,
 };
 use atproto_xrpcs::authorization::ResolvingAuthorization;
 use axum::{
···
 use std::{collections::HashMap, num::NonZeroUsize, ops::Deref, sync::Arc};
 
 #[derive(Clone)]
-pub struct SimpleKeyProvider {
+pub struct SimpleKeyResolver {
     keys: HashMap<String, KeyData>,
 }
 
-impl Default for SimpleKeyProvider {
+impl Default for SimpleKeyResolver {
     fn default() -> Self {
         Self::new()
     }
 }
 
-impl SimpleKeyProvider {
+impl SimpleKeyResolver {
     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())
+impl KeyResolver for SimpleKeyResolver {
+    async fn resolve(&self, key: &str) -> anyhow::Result<KeyData> {
+        if let Some(key_data) = self.keys.get(key) {
+            Ok(key_data.clone())
+        } else {
+            identify_key(key).map_err(Into::into)
+        }
     }
 }
 
···
 pub struct InnerWebContext {
     pub http_client: reqwest::Client,
     pub document_storage: Arc<dyn DidDocumentStorage>,
-    pub key_provider: Arc<dyn KeyProvider>,
+    pub key_resolver: Arc<dyn KeyResolver>,
     pub service_document: ServiceDocument,
     pub service_did: ServiceDID,
     pub identity_resolver: Arc<dyn IdentityResolver>,
···
     }
 }
 
-impl FromRef<WebContext> for Arc<dyn KeyProvider> {
+impl FromRef<WebContext> for Arc<dyn KeyResolver> {
     fn from_ref(context: &WebContext) -> Self {
-        context.0.key_provider.clone()
+        context.0.key_resolver.clone()
     }
 }
 
···
     let web_context = WebContext(Arc::new(InnerWebContext {
         http_client: http_client.clone(),
         document_storage: Arc::new(LruDidDocumentStorage::new(NonZeroUsize::new(255).unwrap())),
-        key_provider: Arc::new(SimpleKeyProvider {
+        key_resolver: Arc::new(SimpleKeyResolver {
             keys: signing_key_storage,
         }),
         service_document,

crates/atproto-xrpcs/src/authorization.rs

···
 use anyhow::Result;
 use atproto_identity::key::identify_key;
 use atproto_identity::resolve::IdentityResolver;
-use atproto_identity::storage::DidDocumentStorage;
+use atproto_identity::traits::DidDocumentStorage;
 use atproto_oauth::jwt::{Claims, Header};
 use axum::extract::{FromRef, OptionalFromRequestParts};
 use axum::http::request::Parts;
···
 mod tests {
     use super::*;
     use atproto_identity::model::{Document, VerificationMethod};
-    use atproto_identity::storage::DidDocumentStorage;
+    use atproto_identity::traits::DidDocumentStorage;
     use axum::extract::FromRef;
     use axum::http::{Method, Request};
     use std::collections::HashMap;