styrene-identity

Deterministic key hierarchy for Styrene mesh nodes. One root secret derives all protocol-specific keys — RNS, Yggdrasil, WireGuard, SSH, age, git signing, and per-agent delegation keys — via HKDF-SHA256 with domain separation.

Published on crates.io.

Quick start

[dependencies]
styrene-identity = "0.1"

Generate an identity

use styrene_identity::file_signer::{ClosurePassphraseProvider, FileSigner};
use styrene_identity::signer::IdentitySigner;

let provider = Box::new(ClosurePassphraseProvider::new(|| {
    Ok(b"my-passphrase".to_vec())
}));
let signer = FileSigner::new("~/.config/styrene/identity.key", provider);
signer.generate(b"my-passphrase").expect("generate identity");

Derive keys from a root secret

use styrene_identity::derive::{KeyDeriver, KeyPurpose};

let root_secret = [0x42u8; 32]; // in practice, from a signer
let deriver = KeyDeriver::new(&root_secret);

// Flat-purpose keys
let git_seed = deriver.derive(KeyPurpose::GitSigning);   // Ed25519 seed
let age_key  = deriver.derive(KeyPurpose::Age);           // X25519 private key
let ssh_seed = deriver.derive(KeyPurpose::SshHost);       // Ed25519 seed

// Parameterized keys (two-level HKDF — structurally collision-free)
let github_ssh = deriver.derive_ssh_user_key("github").unwrap();
let agent_key  = deriver.derive_agent_key("omegon-primary").unwrap();

// All keys are deterministic: same root → same keys, always.

Public key derivation

use styrene_identity::derive::{KeyDeriver, KeyPurpose};
use styrene_identity::pubkey::{ed25519_verifying_key, x25519_public_key};

let deriver = KeyDeriver::new(&[0x42u8; 32]);

let git_vk = ed25519_verifying_key(&deriver.derive(KeyPurpose::GitSigning));
let age_pk = x25519_public_key(&deriver.derive(KeyPurpose::Age));

Lifecycle management with IdentityVault

use styrene_identity::vault::IdentityVault;
use styrene_identity::file_signer::ClosurePassphraseProvider;

let provider = Box::new(ClosurePassphraseProvider::new(|| {
    Ok(b"my-passphrase".to_vec())
}));
let vault = IdentityVault::with_default_path(provider);

// Create — refuses to overwrite (O_EXCL, no TOCTOU race)
vault.init(b"my-passphrase").unwrap();

// Backup before risky operations
vault.backup("/tmp/identity.key.bak").unwrap();

// Check existence
assert!(vault.exists());

Derivation hierarchy

root_secret (32 bytes)
  │
  HKDF-Extract(salt="styrene-identity-v1", IKM=root_secret) = PRK
  │
  ├─ Expand(PRK, "styrene-rns-encryption-v1")      → RNS X25519
  ├─ Expand(PRK, "styrene-rns-signing-v1")          → RNS Ed25519
  ├─ Expand(PRK, "styrene-yggdrasil-v1")            → Yggdrasil Ed25519
  ├─ Expand(PRK, "styrene-wireguard-v1")            → WireGuard Curve25519
  ├─ Expand(PRK, "styrene-ssh-host-v1")             → SSH host Ed25519
  ├─ Expand(PRK, "styrene-age-v1")                  → age X25519
  ├─ Expand(PRK, "styrene-git-signing-v1")          → git signing Ed25519
  │
  ├─ SSH user keys (two-level HKDF)
  │   salt="styrene-identity-ssh-user-v1"
  │   ├─ "github"  → per-host SSH Ed25519
  │   └─ "work"    → per-host SSH Ed25519
  │
  └─ Agent signing keys (two-level HKDF)
      salt="styrene-identity-agent-v1"
      ├─ "omegon-primary"   → agent commit signing Ed25519
      └─ "omegon-cleave-0"  → worker commit signing Ed25519

Parameterized key families use two-level HKDF with distinct salts per family. Collisions between flat purposes, SSH user keys, and agent keys are structurally impossible — they derive from different IKM, different salts, and different HKDF trees.

Signer tiers

The IdentitySigner trait abstracts over four storage tiers. All tiers produce the same 32-byte root secret — they are different access paths to the same identity.

SignerChain tries signers in tier order (A→D), using the first available:

use styrene_identity::signer::SignerChain;

let chain = SignerChain::new_sorted(vec![
    Box::new(yubikey_signer),  // tried first
    Box::new(file_signer),     // fallback
]);
let root = chain.root_secret().await?;

Feature flags

Minimal dependency footprint — disable default-features and pick only what you need:

# Just the derivation hierarchy, no file I/O or crypto
styrene-identity = { version = "0.1", default-features = false }

# Derivation + public key helpers, no file signer
styrene-identity = { version = "0.1", default-features = false, features = ["signing"] }

# Full file-based identity (default)
styrene-identity = "0.1"

File format

The Tier D identity file (~/.config/styrene/identity.key) is 97 bytes:

STID [version:1] [salt:32] [nonce:12] [ciphertext:32+16]
 4B      1B          32B       12B          48B

• Encryption: argon2id (m=64MiB, t=3, p=1) → ChaCha20Poly1305
• Permissions: 0o600, set atomically at creation via O_EXCL
• Backward compat: legacy 92-byte headerless files (pre-v1) are still readable

Identity hash

The canonical identity hash is SHA-256 of the RNS signing Ed25519 public key, truncated to 16 bytes (32 hex chars). This is the mesh identity used by Signum, styrened, and cross-service attribution:

use styrene_identity::derive::{KeyDeriver, KeyPurpose};
use styrene_identity::pubkey::ed25519_verifying_key;
use sha2::{Digest, Sha256};

let deriver = KeyDeriver::new(&[0x42u8; 32]);
let seed = deriver.derive(KeyPurpose::RnsSigning);
let pubkey = ed25519_verifying_key(&seed);
let hash = Sha256::digest(pubkey.as_bytes());
let identity_hash = hex::encode(&hash[..16]); // 32 hex chars

Git commit signing

Derived keys work with git's SSH signing (gpg.format = ssh). Agent keys enable cryptographic distinction between human and agent commits:

All keys trace back to the same root — one identity, multiple signers.

Security properties

• Zeroize-on-drop for all secret material (RootSecret, KeyDeriver PRK, DerivedKeys, derived seeds)
• No private keys on disk — the SSH agent derives keys in memory per request
• Domain-separated HKDF — fixed salt prevents collision with any other HKDF usage
• Hardened KDF — argon2id params exceed OWASP minimums
• Atomic file creation — O_EXCL prevents overwrites with no TOCTOU race
• Credential injection — passphrases and PINs via traits, never environment variables

See SECURITY.md for the full threat model and accepted risks.

Test vectors

From a root secret of 0x42 repeated 32 times:

RnsEncryption = aefdbd63fb6746c2edb73bba3bcb34f61909077f65fe033c9372b55f6ace0c0c
GitSigning    = 6eb3d3ef12a2447f6de281d6f896eba20ad0b0add3bc6fce80499f36b7343842
SSH(github)   = 3c261af80e084a637fd20e0f7274a4106702894f0d23c47e855f6c9adce20d75
Agent(omegon) = 4dd66edcda091a5e3d15aa3fb8ec32d81e212d94760b61915b1d6f204b0672e2

These are pinned in the test suite. Any implementation of the derivation hierarchy must reproduce them.

Ecosystem usage

License

MIT