valinor-identity

Cryptographic identity management for the MudWorld ecosystem, providing Ed25519-based key generation, signing, verification, and principal ID derivation.

Purpose

valinor-identity solves the fundamental problem of cryptographic identity in distributed systems. It provides a minimal, auditable implementation for:

• Generating and persisting Ed25519 keypairs
• Signing messages and verifying signatures
• Deriving stable, human-readable principal IDs from public keys
• Generating unique identifiers with custom prefixes

When to Use This Crate

Use valinor-identity when you need to:

• Authenticate entities - Generate keypairs for users, services, or agents
• Sign and verify messages - Prove authorship or validate integrity
• Derive stable identifiers - Convert public keys into consistent, URL-safe principal IDs
• Generate unique IDs - Create prefixed identifiers (e.g., msg_, room_, user_)

Installation

Add to your Cargo.toml:

[dependencies]
valinor-identity = { path = "../valinor-identity" }

Or if published:

[dependencies]
valinor-identity = "0.1"

API Overview

Core Types

Key Functions

Usage Examples

Generate a New Identity

use valinor_identity::Identity;

let identity = Identity::generate();

// Get the principal ID (stable identifier derived from public key)
let principal = identity.principal_id();
println!("Principal: {principal}"); // e.g., "p_abc123..."

// Access raw public key bytes
let pubkey: [u8; 32] = identity.public_key_bytes();

Persist and Load Identity

use valinor_identity::Identity;
use std::path::Path;

// Generate and save
let identity = Identity::generate();
identity.save(Path::new("~/.config/mudworld/identity")).unwrap();

// Load later
let loaded = Identity::load(Path::new("~/.config/mudworld/identity")).unwrap();
assert_eq!(identity.public_key_bytes(), loaded.public_key_bytes());

Sign and Verify Messages

use valinor_identity::{Identity, verify_signature};

let identity = Identity::generate();
let message = b"authenticate this request";

// Sign
let signature = identity.sign(message);

// Verify (e.g., on server side with only the public key)
let pubkey = identity.public_key_bytes();
verify_signature(&pubkey, message, &signature.to_bytes()).unwrap();

Generate Prefixed IDs

use valinor_identity::generate_id;

let message_id = generate_id("msg_");  // e.g., "msg_V1StGXR8_Z5jdHi6B"
let room_id = generate_id("room_");    // e.g., "room_Uakgb_J5m9g-0JDMbcJqL"
let user_id = generate_id("u_");       // e.g., "u_FybRnyPW3Ie4dXe"

Derive Principal ID from Public Key

use valinor_identity::derive_principal_id;

let pubkey: [u8; 32] = /* from external source */;
let principal = derive_principal_id(&pubkey);
// Returns "p_" + URL-safe base64 of first 10 bytes of SHA-256 hash

Error Handling

use valinor_identity::{Identity, IdentityError};

match Identity::load(path) {
    Ok(id) => println!("Loaded: {}", id.principal_id()),
    Err(IdentityError::InvalidKeyFormat) => eprintln!("Corrupted or invalid key file"),
    Err(IdentityError::Io(e)) => eprintln!("File error: {e}"),
    Err(IdentityError::SignatureInvalid) => unreachable!(), // Not returned by load
}

File Format

Identity files are base64-encoded 64-byte keypairs (32-byte secret + 32-byte public). Example:

aW1hZ2luZSB0aGlzIGlzIGEgdmFsaWQgNjQgYnl0ZSBrZXlwYWlyIGVuY29kZWQgYXMgYmFzZTY0...

Security Considerations

• Private keys are stored in memory as SigningKey and zeroed on drop (via ed25519-dalek)
• Use filesystem permissions to protect identity files
• Principal IDs are one-way derivations; public keys cannot be recovered from them
• The crate uses OsRng for cryptographically secure random generation

Related Crates

License

MIT