Identity System
Register named agent identities, derive unique keypairs using HKDF, and look up public identities for verification.
import { Invariance, deriveAgentKeypair } from '@invariance/sdk';
Overview
The identity system allows you to register named agents in the form "owner/agent-name". Each identity has a unique Ed25519 public key derived from the owner's master key using HKDF-SHA256.
Key derivation happens client-side — only the public key is sent to the server. The same master key deterministically produces the same agent keypair every time. Public identities can be looked up by anyone for signature verification.
Architecture
Identity derivation uses HKDF-SHA256 from @noble/hashes. The identity string is the HKDF info parameter, and the owner's private key is the input key material.
Important Notes
Same owner key + identity string always produces the same keypair. You can "recover" keys by re-deriving.
If the master private key is compromised, ALL derived agent keys are compromised.
Quick Example
const inv = Invariance.init({ apiKey: 'dev_...', privateKey: masterKey });
await inv.registerAgent('acme', 'compliance-agent');
const identity = await inv.lookupIdentity('acme', 'compliance-agent');
console.log(identity.public_key);
const { privateKey, publicKey } = inv.deriveAgentKeypair('acme/compliance-agent');
Type Definitions
AgentIdentity
interface AgentIdentity {
org: string;
name: string;
fullIdentity: string;
}
Parsed components of an agent identity string.
API Reference
registerAgent
Register a named agent identity. Derives the keypair locally and sends only the public key.
async registerAgent(owner: string, name: string): Promise<AgentIdentityResult>
Parameters
ownerstringOwner handle or org name
namestringAgent name (unique within the owner)
ReturnsPromise<{ owner, name, public_key, agent_id, created_at }>
lookupIdentity
Look up a public agent identity. No authentication required.
async lookupIdentity(owner: string, name: string): Promise<IdentityResult>
Parameters
ownerstringOwner handle
namestringAgent name
ReturnsPromise<{ owner, name, public_key, created_at }>
deriveAgentKeypair
Derive an Ed25519 keypair for a named identity using HKDF-SHA256.
deriveAgentKeypair(identity: string): { privateKey: string; publicKey: string }
Parameters
identitystringFull identity string, e.g. "acme/compliance-agent"
Returns{ privateKey: string; publicKey: string }
Invariance.parseIdentity
Parse an identity string into its components.
static parseIdentity(identity: string): AgentIdentity
Parameters
identitystringIdentity string in "org/name" format
ReturnsAgentIdentity
Walkthrough
Setting up agent identities for an organization
Generate a master keypair
Create a master keypair that will be used to derive all agent keys.
import { Invariance } from '@invariance/sdk';
const { privateKey: masterKey, publicKey: masterPublic } = Invariance.generateKeypair();
// Store masterKey securely — all agent keys derive from it
Initialize and register agents
Register named agent identities with the backend. Only the public key is sent.
const inv = Invariance.init({
apiKey: process.env.INVARIANCE_KEY!,
privateKey: masterKey,
});
await inv.registerAgent('acme', 'compliance-agent');
await inv.registerAgent('acme', 'trading-agent');
await inv.registerAgent('acme', 'research-agent');
Derive keypairs for each agent
Deterministically derive unique Ed25519 keypairs from the master key.
const compliance = inv.deriveAgentKeypair('acme/compliance-agent');
const trading = inv.deriveAgentKeypair('acme/trading-agent');
// Same master key + identity always produces the same keypair
console.log(compliance.publicKey); // deterministic
Look up public identities
Any party can look up agent public keys for verification.
const identity = await inv.lookupIdentity('acme', 'compliance-agent');
console.log(identity.public_key); // matches compliance.publicKey
// Use the public key to verify receipts signed by this agent
Use Cases
- Register named agents for an organization
- Look up agent public keys to verify receipt signatures independently
- Derive deterministic keypairs without storing individual keys
- Enable cross-organization agent verification through public identity lookup