Key management
Generation, persistence, recovery boundaries, and implementation-specific derivation.
Key material, identity documents, and authorization are separate objects. A seed can restore keys only according to the algorithm and binding used by that SDK. It does not restore a broker grant, an issued session, a revocation decision, or an authority anchor.
Local signing custody in SDK 0.7.2
OpenAgentWorkspace generates real Ed25519 signing keys, stores them privately and reopens the original identity. A separate receiver stores explicitly approved public keys and durable trust/challenge/replay/revocation. Public export never includes a private JWK. Keep both stores private, backed up, outside Git and on a single persistent host; do not synchronize or place them on ephemeral serverless storage. Unsafe filesystem state fails closed. Local identity is the complete current path.
These signing identities are independent of the older facade encryption-seed APIs below. Distributed services supply their own protected key custody, authoritative resolver/root policy and replay storage.
Versioned encryption-key facade behavior
| Implementation | Encryption-key derivation and boundary |
|---|---|
| TypeScript | Injected KeyCryptoBinding. Uses BLAKE3 context arsenal.agent.encryption_key. Deterministic X25519 restoration requires x25519_public_from_secret; without it the current fallback generates a new encryption keypair. |
| Python | Uses BLAKE3 when available; otherwise HKDF-SHA256. Preserve dependency configuration as part of restoration. |
| Other source implementations | Have independent derivation and dependency contracts. Their retired source snippets are not a cross-language restoration guarantee. |
Do not assume the same seed produces the same encryption identity across languages. Canonical ACT interoperability is a separate contract. Preserve the implementation, algorithm, dependency versions, and derivation parameters with your recovery procedure.
Seed files are not encrypted vaults
TypeScript and Python expose seed-file helpers. The file carries raw seed bytes. A requested owner-only file mode does not add encryption, secure deletion, an HSM, or protection against another process with the same account. Rewriting an existing file may retain its existing permissions; provision the file securely and check effective access.
Use a managed secret store or an encrypted key store for your deployment's custody requirements. Do not print the seed, place it in a URL, ship it to the browser bundle, or commit it with source. Keep recovery material separate from application logs and documentation exports.
Python restoration within one implementation
In openagentid-sdk@0.1.0, generate, save_seed and from_seed_file create and restore seed material. A matching signing public key does not establish matching encryption behavior across runtimes. The published Python optional BLAKE3 branch must also match the installed binding. Use the Python release boundary and qualify restoration with your actual dependency set before relying on it.
TypeScript binding prerequisites
setKeyCryptoBinding accepts Ed25519, X25519, and BLAKE3 functions. The published @openagentid/crypto-wasm@0.1.1 exports x25519_generate_keypair and x25519_diffie_hellman, but not x25519_public_from_secret. Therefore that direct binding alone does not provide deterministic encryption-key restoration through the TypeScript facade's fallback. Preserve existing encryption keys using your application's custody system until an appropriate complete binding is supplied and tested.
The optional ACT binding is separate from both local signing custody and encryption-key restoration. See TypeScript integration.
Rotation and recovery
Rotation, recovery, and authority changes require the relevant OAS/AEGIS protocol and storage integration. Changing a local seed does not itself rotate a published DID, update a lineage proof, revoke old capabilities, or migrate encrypted material. Plan those operations explicitly and verify old and new trust states before retiring a key.
See SDK key declarations and the published Python distribution. Memory-zeroization guarantees are implementation-specific; these docs do not promise that managed-runtime values never enter swap or remain inaccessible after use.