Crate styrene_identity 

Deterministic key hierarchy for Styrene mesh nodes.

One 32-byte root secret derives all protocol-specific keys — RNS, Yggdrasil, WireGuard, SSH, age, git signing, and per-agent delegation — via HKDF-SHA256 with domain separation.

Usage

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 (7 protocols)
let git_seed = deriver.derive(KeyPurpose::GitSigning);
let age_key  = deriver.derive(KeyPurpose::Age);

// 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();

Signer tiers

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

Tier	Backend	Feature
A	YubiKey FIDO2 hmac-secret	yubikey
B	Platform secure element	— (planned)
C	Credential manager (Bitwarden, Keychain)	— (planned)
D	Encrypted file (argon2id + ChaCha20Poly1305)	file-signer (default)

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

Feature flags

Feature	Default	Enables
file-signer	yes	FileSigner, IdentityVault
signing	via file-signer	pubkey module (ed25519, x25519)
yubikey	no	YubiKeySigner (FIDO2 hmac-secret)
ssh-agent	no	StyreneAgent (SSH agent protocol)

Derivation hierarchy

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

Linkability warning

All keys derived from one root are cryptographically linked. This is by design for attribution and recovery, but it means derived keys cannot provide anonymity or unlinkability. If you need an identity that cannot be traced to your primary identity, use ephemeral() or a separate identity file. See docs/unlinkability.md for the full model.

use styrene_identity::signer::RootSecret;

// Anonymous: independent CSPRNG root, no link to any persistent identity
let anon = RootSecret::ephemeral();

Security

• All secret material is zeroized on drop (RootSecret, KeyDeriver, DerivedKeys)
• Passphrases and PINs are provided via traits, never environment variables
• File creation uses O_EXCL (no TOCTOU race)
• argon2id params exceed OWASP minimums (m=64MiB, t=3, p=1)

Re-exports

pub use derive::derive_key;

pub use derive::derive_keys;

pub use derive::validate_label;

pub use derive::DeriveError;

pub use derive::DerivedKeys;

pub use derive::KeyDeriver;

pub use derive::KeyPurpose;

pub use discover::discover;

pub use discover::DiscoveredIdentity;

pub use export::AllPublicKeys;

pub use identity::identity_hash;

pub use identity::identity_pubkey;

pub use identity::identity_sign;

pub use identity::identity_verify;

pub use identity::IdentityInfo;Deprecated

pub use identity::PublicIdentity;

pub use identity::SignedAttestation;

pub use identity::IDENTITY_HASH_BYTES;

pub use signer::IdentitySigner;

pub use signer::SignerChain;

pub use signer::SignerError;

pub use signer::SignerTier;

Modules

derive

HKDF key derivation hierarchy — derives protocol-specific keys from root secret.

discover

Identity auto-discovery — probes the machine for an existing Styrene identity.

export

Batch public key export — all derived public keys in one call.

file_signer

Tier D: EncryptedFile signer — argon2id + ChaCha20Poly1305.

format

Protocol-specific key formatting.

identity

Canonical identity hash and info — the unique fingerprint for a Styrene identity.

pubkey

Public key derivation and signing from HKDF-derived seeds.

signer

IdentitySigner trait — abstract signing interface across hardware tiers.

vault

Identity vault — safe lifecycle management for Styrene identities.