atproto-record#

A Rust library for AT Protocol record signature operations, providing cryptographic signing and verification capabilities for AT Protocol records.

Overview#

This crate provides functionality for:

Record Signing: Create cryptographic signatures for AT Protocol records
Signature Verification: Verify existing signatures against records and public keys
Error Handling: Structured error types for signature operations
Multi-curve Support: Support for P-256 and K-256 elliptic curves via atproto-identity

Features#

Create signatures for AT Protocol records with proper $sig object handling
Required signature object validation (must include issuer and issued_at fields)
Verify record signatures against issuer public keys
IPLD DAG-CBOR serialization for consistent signature generation
Multibase encoding for signature representation
Integration with atproto-identity for cryptographic key operations
Repository and collection context support in signature objects
Comprehensive error handling with structured error types including creation and verification errors

Usage#

Creating Signatures#

use atproto_record::signature;
use atproto_identity::key::{identify_key, KeyType};
use serde_json::json;
use atproto_record::errors::VerificationError;

# async fn example() -> Result<(), VerificationError> {
// Prepare key data
let key_data = identify_key("did:key:example...").map_err(|e| {
    VerificationError::KeyOperationFailed(e)
})?;

// Create a record to sign
let record = json!({
    "$type": "app.bsky.feed.post",
    "text": "Hello AT Protocol!",
    "createdAt": "2024-01-01T00:00:00Z"
});

// Create signature object with required fields
let signature_object = json!({
    "issuer": "did:plc:signer123",
    "issued_at": "2024-01-01T00:00:00Z"
});

// Create signature
let signed_record = signature::create(
    &key_data,
    &record,
    "did:plc:user123",
    "app.bsky.feed.post",
    signature_object
).await?;
# Ok(())
# }

Verifying Signatures#

use atproto_record::signature;
use atproto_identity::key::identify_key;
use atproto_record::errors::VerificationError;

# async fn example() -> Result<(), VerificationError> {
// Get the issuer's public key
let issuer_key = identify_key("did:key:issuer...").map_err(|e| {
    VerificationError::KeyOperationFailed(e)
})?;

// Verify the signature
signature::verify(
    "did:plc:issuer123",
    &issuer_key,
    signed_record,
    "did:plc:user123",
    "app.bsky.feed.post"
).await?;
# Ok(())
# }

Command Line Tools#

The crate includes two command-line tools for AT Protocol record signature operations:

`atproto-record-sign`#

Creates cryptographic signatures for AT Protocol records with proper $sig object handling and embedded signature metadata. This tool reads JSON records, applies cryptographic signatures using DID keys, and outputs signed records ready for AT Protocol repository storage.

Features:

Flexible Input: Reads records from files or stdin
DID Key Support: Works with both P-256 and K-256 cryptographic keys
Signature Object Creation: Automatically creates required signature metadata with issuer and timestamp
Repository Context: Includes repository and collection context in signatures
IPLD Serialization: Uses DAG-CBOR serialization for consistent signature generation
Multibase Encoding: Outputs signatures in multibase format for AT Protocol compatibility

# Sign a record from a file with all required parameters
cargo run --bin atproto-record-sign did:key:zQ3sh... did:plc:issuer123 record.json repository=did:plc:user123 collection=app.bsky.feed.post

# Sign a record from stdin
echo '{"$type":"app.bsky.feed.post","text":"Hello AT Protocol!"}' | \
  cargo run --bin atproto-record-sign did:key:zQ3sh... did:plc:issuer123 -- \
  repository=did:plc:user123 collection=app.bsky.feed.post

# Example output: JSON record with embedded signatures array

Arguments:

<signing_key> - DID key string for signing (did🔑...)
<issuer_did> - DID of the signing entity
<record_file> - JSON file containing the record (optional, uses stdin if omitted)
repository=<did> - Repository DID where record will be stored
collection=<nsid> - Collection NSID (e.g., app.bsky.feed.post)

`atproto-record-verify`#

Verifies cryptographic signatures of AT Protocol records using embedded signature metadata. This tool validates that signed records contain authentic signatures from specified issuers, ensuring record integrity and authenticity.

Features:

Signature Validation: Verifies embedded signatures against public keys
Issuer Authentication: Confirms signatures are from specified DID issuers
Context Verification: Validates repository and collection context in signatures
Multi-Signature Support: Handles records with multiple signatures
IPLD Deserialization: Uses DAG-CBOR for signature verification consistency
Detailed Error Reporting: Provides specific feedback on verification failures

# Verify a signed record from a file
cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... signed_record.json \
  repository=did:plc:user123 collection=app.bsky.feed.post

# Verify a signed record from stdin
echo '{"signatures":[{"issuer":"did:plc:issuer123","signature":"u..."}],"$type":"app.bsky.feed.post","text":"Hello"}' | \
  cargo run --bin atproto-record-verify did:plc:issuer123 did:key:zQ3sh... -- \
  repository=did:plc:user123 collection=app.bsky.feed.post

# Successful verification returns exit code 0
# Failed verification returns exit code 1 with error details

Arguments:

<issuer_did> - DID of the expected signature issuer
<public_key> - DID key string for verification (did🔑...)
<record_file> - JSON file containing the signed record (optional, uses stdin if omitted)
repository=<did> - Repository DID context for verification
collection=<nsid> - Collection NSID context for verification

Exit Codes:

0 - Signature verification successful
1 - Signature verification failed or invalid arguments
2 - File I/O or parsing errors

Modules#

[signature] - Core signature creation and verification functions
[errors] - Structured error types for signature operations

Error Handling#

The crate uses structured error types defined in the errors module:

use atproto_record::errors::VerificationError;
use serde_json::json;

// Example error handling for signature creation
let signature_object = json!({ "missing": "required_fields" });

match signature::create(&key_data, &record, "repo", "collection", signature_object).await {
    Ok(signed_record) => println!("Signature created successfully!"),
    Err(VerificationError::SignatureObjectMissingField { field }) => {
        println!("Missing required field in signature object: {}", field);
    }
    Err(VerificationError::InvalidSignatureObjectType) => {
        println!("Signature object must be a JSON object");
    }
    Err(VerificationError::KeyOperationFailed(e)) => {
        println!("Cryptographic operation failed: {}", e);
    }
    Err(e) => println!("Other error: {}", e),
}

// Example error handling for signature verification
match signature::verify("did:plc:issuer", &key_data, record, "repo", "collection").await {
    Ok(()) => println!("Signature valid!"),
    Err(VerificationError::NoValidSignatureForIssuer { issuer }) => {
        println!("No valid signature found for issuer: {}", issuer);
    }
    Err(VerificationError::NoSignaturesField) => {
        println!("Record contains no signatures field");
    }
    Err(e) => println!("Verification failed: {}", e),
}

Dependencies#

This crate builds on:

atproto-identity - Cryptographic key operations and DID resolution
serde_ipld_dagcbor - IPLD DAG-CBOR serialization for signature content
multibase - Base encoding for signature representation
serde_json - JSON handling for AT Protocol records
anyhow - Error handling utilities
thiserror - Structured error type derivation

License#

Licensed under the MIT License.