Key Management

​

The five-minute version

import { keys } from '@openagentid/sdk';

const agent = await keys.generate();            // fresh identity
await keys.saveSeed(agent, 'agent.seed');       // owner-only (0600)
const restored = await keys.fromSeedFile('agent.seed');
// or: keys.fromEnv('AGENT_SEED_HEX')

from openagent_sdk import keys

agent = keys.generate()
keys.save_seed(agent, "agent.seed")             # owner-only (0600)
restored = keys.from_seed_file("agent.seed")

let keys = openagent_sdk::keys::generate()?;
openagent_sdk::keys::save_seed(&keys, "agent.seed")?;
let restored = openagent_sdk::keys::from_seed_file("agent.seed")?;

• Ed25519 signing keypair — the seed is the signing key (Ed25519 signing keys are 32-byte seeds). Signs challenges, lineage proofs, and ACT-related material.
• X25519 encryption keypair — derived via BLAKE3 context-separated derivation (arsenal.agent.encryption_key), the same derivation across the Rust, TypeScript, and Python SDKs, so a seed moved between SDKs restores the same keys.

​

The lifecycle, shelf by shelf

​

Generation

• CSPRNG seed generation (32 bytes of entropy)
• Ed25519 key pair derivation from seed
• Multibase encoding of public key (z prefix + base58btc)
• DID identifier construction from the multibase public key

​

Derivation

• HKDF-Extract: derive PRK from parent key + salt
• HKDF-Expand: derive child key material from PRK + info
• Ed25519 key pair generation from derived material
• Path recording for audit and reconstruction

​

Storage

• KEK derivation via Argon2id (memory: 256MB, iterations: 3)
• AES-256-GCM encryption of the private key with a random nonce
• BLAKE3 integrity hash over the sealed envelope
• Storage in the configured key store (file, OS keychain, HSM)

​

Usage

• Decrypt the private key from the sealed envelope
• JCS canonicalization of the payload
• Ed25519 signature computation (constant-time)
• Immediate zeroing of the decrypted key

​

Rotation

1. Generate the new Ed25519 key pair
2. Create a rotation proof signed by the old key
3. Update the DID Document with the new verification method
4. Publish the rotation proof and updated document
5. Archive the old key with a revocation timestamp

​

Recovery

• Social recovery — collect t-of-n guardian signatures from pre-designated guardians
• FROST recovery — reconstruct from threshold key shares (MHR entities)
• HSM recovery — present a hardware attestation certificate

​

Derivation path conventions

​

The rules that matter most

1. Persist the seed, not the keys. One 32-byte secret restores the whole identity; everything else derives.
2. Keys never appear in wire artifacts. Public keys and DIDs travel; private keys do not, ever. A token, document, or log containing private key material is an incident.
3. Zero intermediate material. PRKs, decrypted keys, and passphrases are zeroed at the point of last use, not at cleanup time.
4. Custody is the killer feature. An agent that can restore its own identity from a seed — across SDKs, across machines, across restarts — is what every other agent framework is missing. Build on it.

​

Next

• ACT tokens — what those keys sign
• Lineage — how derivation paths become provable ancestry
• AEGIS verification — how signatures are evaluated