1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
//! # atproto-record
//!
//! A Rust library for AT Protocol record signature operations, providing cryptographic
//! signing and verification capabilities for AT Protocol records.
//!
//! This crate handles the cryptographic aspects of AT Protocol record attestation,
//! including signature creation and verification with proper `$sig` object handling
//! and IPLD DAG-CBOR serialization.
//!
//! ## Core Modules
//!
//! - [`signature`] - Core signature creation and verification functions
//! - [`errors`] - Structured error types for signature verification operations
//!
//! ## Key Features
//!
//! - **Record Signing**: Create cryptographic signatures for AT Protocol records
//! - **Signature Verification**: Verify existing signatures against records and public keys
//! - **Multi-curve Support**: Support for P-256 and K-256 elliptic curves via `atproto-identity`
//! - **IPLD Integration**: Proper IPLD DAG-CBOR serialization for signature content
//! - **Error Handling**: Comprehensive structured error types following project conventions
//!
//! ## Usage Examples
//!
//! ### Creating a Signature
//!
//! ```rust
//! use atproto_record::signature;
//! use atproto_record::errors::VerificationError;
//! use serde_json::json;
//! use atproto_identity::key::{KeyData, KeyType};
//! async fn example() -> Result<(), VerificationError> {
//! let key_data = KeyData::new(KeyType::P256Public, vec![]);
//!
//! let record = json!({
//! "$type": "app.bsky.feed.post",
//! "text": "Hello AT Protocol!"
//! });
//!
//! // Create signature object with required fields
//! let signature_object = json!({
//! "issuer": "did:plc:signer123",
//! "issued_at": "2024-01-01T00:00:00Z"
//! });
//!
//! let signed_record = signature::create(
//! &key_data,
//! &record,
//! "did:plc:user123",
//! "app.bsky.feed.post",
//! signature_object
//! ).await?;
//! Ok(())
//! }
//! ```
//!
//! ### Verifying a Signature
//!
//! ```rust
//! use atproto_record::signature;
//! use atproto_record::errors::VerificationError;
//! use atproto_identity::key::{KeyData, KeyType};
//! use serde_json::json;
//! async fn example() -> Result<(), VerificationError> {
//! let issuer_key = KeyData::new(KeyType::P256Public, vec![]);
//! let signed_record = json!({
//! "signatures": [{
//! "issuer": "did:plc:issuer123",
//! "signature": "uExample_signature_data"
//! }]
//! });
//!
//! signature::verify(
//! "did:plc:issuer123",
//! &issuer_key,
//! signed_record,
//! "did:plc:user123",
//! "app.bsky.feed.post"
//! ).await?;
//! Ok(())
//! }
//! ```
//!
//! ## Error Handling
//!
//! All signature operations return structured errors defined in the [`errors`] module:
//!
//! ```rust
//! use atproto_record::errors::VerificationError;
//! use atproto_record::signature::create;
//! use serde_json::json;
//!
//! // Example: handling signature creation errors
//! async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let key_data = atproto_identity::key::KeyData::new(atproto_identity::key::KeyType::P256Public, vec![]);
//! let record = json!({});
//! let invalid_signature_object = json!({ "missing": "required_fields" });
//!
//! match create(&key_data, &record, "repo", "collection", invalid_signature_object).await {
//! Ok(_) => println!("Signature created successfully!"),
//! Err(VerificationError::SignatureObjectMissingField { field }) => {
//! println!("Missing required field: {}", field);
//! }
//! Err(VerificationError::InvalidSignatureObjectType) => {
//! println!("Signature object must be a JSON object");
//! }
//! Err(VerificationError::KeyOperationFailed { .. }) => {
//! println!("Cryptographic operation failed");
//! }
//! Err(e) => println!("Other error: {}", e),
//! }
//! Ok(())
//! }
//! ```
/// Structured error types for signature verification operations.
///
/// This module defines comprehensive error types that can occur during
/// AT Protocol record signature verification, following the project's
/// error naming conventions.
/// Core signature creation and verification functions.
///
/// This module provides the primary functionality for creating and verifying
/// cryptographic signatures on AT Protocol records, with proper handling of
/// signature objects and IPLD serialization.