fastn_id52/lib.rs
1//! # fastn-id52
2//!
3//! Entity identity and cryptographic key management for the fastn P2P network.
4//!
5//! This crate provides entity identity for fastn's peer-to-peer network. Each fastn
6//! instance is called an "entity" and is uniquely identified by an ID52 - a 52-character
7//! encoded Ed25519 public key.
8//!
9//! ## What is ID52?
10//!
11//! ID52 is the identity of an entity on the fastn peer-to-peer network. It's a
12//! 52-character string using BASE32_DNSSEC encoding that uniquely identifies each
13//! entity. The format is:
14//! - Exactly 52 characters long
15//! - Uses only lowercase letters and digits
16//! - DNS-compatible (can be used in subdomains)
17//! - URL-safe without special encoding
18//!
19//! ## Installation
20//!
21//! This crate can be used as a library or installed as a CLI tool:
22//!
23//! ```bash
24//! # As a library dependency
25//! cargo add fastn-id52
26//!
27//! # As a CLI tool
28//! cargo install fastn-id52
29//! ```
30//!
31//! ## CLI Usage
32//!
33//! The `fastn-id52` CLI tool generates entity identities:
34//!
35//! ```bash
36//! # Default: Generate and store in system keyring
37//! fastn-id52 generate
38//! # Output: ID52 printed to stdout, secret key stored in keyring
39//!
40//! # Save to file (less secure, requires explicit flag)
41//! fastn-id52 generate --file
42//! fastn-id52 generate --file my-entity.key
43//! # Output: Secret key saved to file, ID52 printed to stderr
44//!
45//! # Print to stdout
46//! fastn-id52 generate --file -
47//! fastn-id52 generate -f -
48//! # Output: Secret key (hex) printed to stdout, ID52 printed to stderr
49//!
50//! # Short output (only ID52, no descriptive messages)
51//! fastn-id52 generate --short
52//! fastn-id52 generate -f - -s
53//! # Output: Secret key stored in keyring, only ID52 printed (no messages)
54//! ```
55//!
56//! By default, secret keys are stored securely in the system keyring and can be
57//! viewed in your password manager. File storage requires explicit user consent.
58//!
59//! ## Quick Start (Library)
60//!
61//! ```
62//! use fastn_id52::SecretKey;
63//!
64//! // Generate a new entity identity
65//! let secret_key = SecretKey::generate();
66//! let public_key = secret_key.public_key();
67//!
68//! // Get the entity's ID52 identifier
69//! let entity_id52 = public_key.to_string();
70//! assert_eq!(entity_id52.len(), 52);
71//!
72//! // Sign and verify a message
73//! let message = b"Hello, fastn!";
74//! let signature = secret_key.sign(message);
75//! assert!(public_key.verify(message, &signature).is_ok());
76//! ```
77//!
78//! ## Key Types
79//!
80//! - [`SecretKey`]: Entity's private key for signing operations
81//! - [`PublicKey`]: Entity's public key with ID52 encoding
82//! - [`Signature`]: Ed25519 signature for entity authentication
83//!
84//! ## Error Types
85//!
86//! - [`ParseId52Error`]: Errors when parsing ID52 strings
87//! - [`InvalidKeyBytesError`]: Invalid key byte format
88//! - [`ParseSecretKeyError`]: Errors parsing secret key strings
89//! - [`InvalidSignatureBytesError`]: Invalid signature byte format
90//! - [`SignatureVerificationError`]: Signature verification failures
91//! - [`KeyringError`]: Errors when accessing the system keyring
92//!
93//! ## Security
94//!
95//! This crate uses `ed25519-dalek` for all cryptographic operations, which provides
96//! constant-time implementations to prevent timing attacks. Random key generation
97//! uses the operating system's secure random number generator.
98
99mod errors;
100mod keyring;
101mod keys;
102
103pub use errors::{
104 InvalidKeyBytesError, InvalidSignatureBytesError, ParseId52Error, ParseSecretKeyError,
105 SignatureVerificationError,
106};
107pub use keyring::KeyringError;
108pub use keys::{PublicKey, SecretKey, Signature};