@lawrenceliang-btc/atel-sdk 0.8.7

package/dist/handshake/index.js

@@ -0,0 +1,287 @@
+/**
+ * Module: Handshake Protocol
+ *
+ * Mutual identity verification + encrypted session establishment.
+ * Uses challenge-response with Ed25519 signatures and X25519 key exchange.
+ *
+ * Flow:
+ *   A → B: handshake_init  {did_a, pubkey_a, enc_pubkey_a, challenge_a}
+ *   B → A: handshake_ack   {did_b, pubkey_b, enc_pubkey_b, challenge_b, sign(challenge_a)}
+ *   A → B: handshake_confirm {sign(challenge_b)}
+ *   ✅ Encrypted session established (X25519 shared secret derived)
+ */
+import { randomUUID, randomBytes } from 'node:crypto';
+import { verify, sign as didSign, parseDID } from '../identity/index.js';
+import { createMessage, verifyMessage, } from '../envelope/index.js';
+import { generateEncryptionKeyPair, deriveSharedKey, EncryptionManager, } from '../crypto/index.js';
+// ─── Custom Errors ───────────────────────────────────────────────
+export class HandshakeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandshakeError';
+    }
+}
+// ─── Wallet Proof Helpers ─────────────────────────────────────────
+/** Create a signed wallet bundle proving DID ownership of wallet addresses */
+export function createWalletBundle(addresses, secretKey) {
+    // Canonical JSON: sorted keys, no undefined values
+    const clean = {};
+    for (const [k, v] of Object.entries(addresses)) {
+        if (v)
+            clean[k] = v;
+    }
+    const proof = didSign(clean, secretKey);
+    return { addresses: clean, proof };
+}
+/** Verify a wallet bundle's DID signature */
+export function verifyWalletBundle(bundle, publicKey) {
+    if (!bundle || !bundle.proof || !bundle.addresses)
+        return false;
+    const clean = {};
+    for (const [k, v] of Object.entries(bundle.addresses)) {
+        if (v)
+            clean[k] = v;
+    }
+    return verify(clean, bundle.proof, publicKey);
+}
+// ─── Handshake Manager ───────────────────────────────────────────
+/**
+ * Manages handshake flows, active sessions, and encryption.
+ *
+ * Supports both initiator and responder roles.
+ * Automatically establishes E2E encryption during handshake.
+ */
+export class HandshakeManager {
+    identity;
+    sessionTtlSec;
+    challengeBytes;
+    enableEncryption;
+    sessions = new Map();
+    pendingChallenges = new Map();
+    pendingEncKeys = new Map();
+    pendingInitPayloads = new Map();
+    /** Encryption manager for E2E encrypted communication */
+    encryption;
+    constructor(identity, config) {
+        this.identity = identity;
+        this.sessionTtlSec = config?.sessionTtlSec ?? 3600;
+        this.challengeBytes = config?.challengeBytes ?? 32;
+        this.enableEncryption = config?.enableEncryption ?? true;
+        this.encryption = new EncryptionManager();
+    }
+    // ── Initiator Side ───────────────────────────────────────────
+    /**
+     * Create a handshake_init message (Step 1).
+     */
+    createInit(remoteDid, wallets) {
+        const challenge = randomBytes(this.challengeBytes).toString('hex');
+        this.pendingChallenges.set(remoteDid, challenge);
+        // Generate ephemeral X25519 key pair for this handshake
+        const encKeyPair = generateEncryptionKeyPair();
+        this.pendingEncKeys.set(remoteDid, encKeyPair);
+        // Sign wallet addresses if provided
+        const walletBundle = wallets ? createWalletBundle(wallets, this.identity.secretKey) : undefined;
+        return createMessage({
+            type: 'handshake_init',
+            from: this.identity.did,
+            to: remoteDid,
+            payload: {
+                did: this.identity.did,
+                publicKey: Buffer.from(this.identity.publicKey).toString('base64'),
+                encPublicKey: Buffer.from(encKeyPair.publicKey).toString('base64'),
+                challenge,
+                wallets,
+                walletBundle,
+            },
+            secretKey: this.identity.secretKey,
+        });
+    }
+    /**
+     * Process a handshake_ack message and create handshake_confirm (Step 3).
+     */
+    processAck(ackMessage) {
+        const payload = ackMessage.payload;
+        // Verify the ack message signature
+        const remotePubKey = Uint8Array.from(Buffer.from(payload.publicKey, 'base64'));
+        const msgResult = verifyMessage(ackMessage, remotePubKey, { skipTimestampCheck: false });
+        if (!msgResult.valid) {
+            throw new HandshakeError(`Handshake ack verification failed: ${msgResult.error}`);
+        }
+        // Verify the challenge response
+        const ourChallenge = this.pendingChallenges.get(payload.did);
+        if (!ourChallenge) {
+            throw new HandshakeError(`No pending handshake with ${payload.did}`);
+        }
+        if (!verify(ourChallenge, payload.challengeResponse, remotePubKey)) {
+            throw new HandshakeError('Challenge response verification failed');
+        }
+        this.pendingChallenges.delete(payload.did);
+        // Establish E2E encryption
+        let encrypted = false;
+        if (this.enableEncryption && payload.encPublicKey) {
+            const remoteEncPubKey = Uint8Array.from(Buffer.from(payload.encPublicKey, 'base64'));
+            this.encryption.createSession(payload.did, remoteEncPubKey);
+            // Override with our pending key pair for correct DH
+            const ourEncKeyPair = this.pendingEncKeys.get(payload.did);
+            if (ourEncKeyPair) {
+                // Re-derive using our actual ephemeral key
+                const sharedKey = deriveSharedKey(ourEncKeyPair.secretKey, remoteEncPubKey);
+                this.encryption.destroySession(payload.did);
+                // Manually create session with correct keys
+                this.encryption.createSessionWithKeys(payload.did, ourEncKeyPair, remoteEncPubKey, sharedKey);
+                this.pendingEncKeys.delete(payload.did);
+                encrypted = true;
+            }
+        }
+        // Sign their challenge
+        const challengeResponse = this.identity.sign(payload.challenge);
+        const confirm = createMessage({
+            type: 'handshake_confirm',
+            from: this.identity.did,
+            to: payload.did,
+            payload: { challengeResponse },
+            secretKey: this.identity.secretKey,
+        });
+        const session = this.createSession(payload.did, remotePubKey, encrypted, payload.capabilities, payload.wallets, payload.walletBundle);
+        return { confirm, session };
+    }
+    // ── Responder Side ───────────────────────────────────────────
+    /**
+     * Process a handshake_init message and create handshake_ack (Step 2).
+     */
+    processInit(initMessage, wallets) {
+        const payload = initMessage.payload;
+        // Verify the init message signature
+        const remotePubKey = Uint8Array.from(Buffer.from(payload.publicKey, 'base64'));
+        const msgResult = verifyMessage(initMessage, remotePubKey, { skipTimestampCheck: false });
+        if (!msgResult.valid) {
+            throw new HandshakeError(`Handshake init verification failed: ${msgResult.error}`);
+        }
+        // Verify DID matches public key
+        const didPubKey = parseDID(payload.did);
+        if (Buffer.from(didPubKey).toString('base64') !== payload.publicKey) {
+            throw new HandshakeError('DID does not match provided public key');
+        }
+        // Generate our challenge
+        const ourChallenge = randomBytes(this.challengeBytes).toString('hex');
+        this.pendingChallenges.set(payload.did, ourChallenge);
+        this.pendingInitPayloads.set(payload.did, payload);
+        // Generate ephemeral X25519 key pair and set up encryption
+        const encKeyPair = generateEncryptionKeyPair();
+        if (this.enableEncryption && payload.encPublicKey) {
+            const remoteEncPubKey = Uint8Array.from(Buffer.from(payload.encPublicKey, 'base64'));
+            const sharedKey = deriveSharedKey(encKeyPair.secretKey, remoteEncPubKey);
+            this.encryption.createSessionWithKeys(payload.did, encKeyPair, remoteEncPubKey, sharedKey);
+        }
+        // Sign their challenge
+        const challengeResponse = this.identity.sign(payload.challenge);
+        // Sign wallet addresses if provided
+        const walletBundle = wallets ? createWalletBundle(wallets, this.identity.secretKey) : undefined;
+        return createMessage({
+            type: 'handshake_ack',
+            from: this.identity.did,
+            to: payload.did,
+            payload: {
+                did: this.identity.did,
+                publicKey: Buffer.from(this.identity.publicKey).toString('base64'),
+                encPublicKey: Buffer.from(encKeyPair.publicKey).toString('base64'),
+                challenge: ourChallenge,
+                challengeResponse,
+                wallets,
+                walletBundle,
+            },
+            secretKey: this.identity.secretKey,
+        });
+    }
+    /**
+     * Process a handshake_confirm message (Step 3, responder side).
+     */
+    processConfirm(confirmMessage, initiatorPublicKey, initiatorCapabilities, initiatorWallets, initiatorWalletBundle) {
+        const payload = confirmMessage.payload;
+        const msgResult = verifyMessage(confirmMessage, initiatorPublicKey, { skipTimestampCheck: false });
+        if (!msgResult.valid) {
+            throw new HandshakeError(`Handshake confirm verification failed: ${msgResult.error}`);
+        }
+        const ourChallenge = this.pendingChallenges.get(confirmMessage.from);
+        if (!ourChallenge) {
+            throw new HandshakeError(`No pending handshake with ${confirmMessage.from}`);
+        }
+        if (!verify(ourChallenge, payload.challengeResponse, initiatorPublicKey)) {
+            throw new HandshakeError('Challenge response verification failed');
+        }
+        this.pendingChallenges.delete(confirmMessage.from);
+        // Use stored init payload if explicit params not provided
+        const storedInit = this.pendingInitPayloads.get(confirmMessage.from);
+        this.pendingInitPayloads.delete(confirmMessage.from);
+        const caps = initiatorCapabilities ?? storedInit?.capabilities;
+        const wallets = initiatorWallets ?? storedInit?.wallets;
+        const bundle = initiatorWalletBundle ?? storedInit?.walletBundle;
+        const encrypted = this.encryption.hasSession(confirmMessage.from);
+        return this.createSession(confirmMessage.from, initiatorPublicKey, encrypted, caps, wallets, bundle);
+    }
+    // ── Session Management ───────────────────────────────────────
+    getSession(remoteDid) {
+        const session = this.sessions.get(remoteDid);
+        if (!session)
+            return undefined;
+        if (new Date(session.expiresAt).getTime() < Date.now()) {
+            session.state = 'expired';
+            this.sessions.delete(remoteDid);
+            this.encryption.destroySession(remoteDid);
+            return undefined;
+        }
+        return session;
+    }
+    hasActiveSession(remoteDid) {
+        return this.getSession(remoteDid) !== undefined;
+    }
+    getActiveSessions() {
+        const now = Date.now();
+        const active = [];
+        for (const [did, session] of this.sessions) {
+            if (new Date(session.expiresAt).getTime() < now) {
+                session.state = 'expired';
+                this.sessions.delete(did);
+                this.encryption.destroySession(did);
+            }
+            else {
+                active.push(session);
+            }
+        }
+        return active;
+    }
+    terminateSession(remoteDid) {
+        this.sessions.delete(remoteDid);
+        this.encryption.destroySession(remoteDid);
+    }
+    // ── Private ──────────────────────────────────────────────────
+    createSession(remoteDid, remotePublicKey, encrypted, remoteCapabilities, remoteWallets, remoteWalletBundle) {
+        const now = new Date();
+        const expiresAt = new Date(now.getTime() + this.sessionTtlSec * 1000);
+        // Verify wallet bundle if provided — cryptographic proof of ownership
+        let walletsVerified = false;
+        let finalWallets = remoteWallets;
+        if (remoteWalletBundle) {
+            walletsVerified = verifyWalletBundle(remoteWalletBundle, remotePublicKey);
+            if (walletsVerified) {
+                // Use addresses from verified bundle (authoritative)
+                finalWallets = remoteWalletBundle.addresses;
+            }
+        }
+        const session = {
+            sessionId: randomUUID(),
+            localDid: this.identity.did,
+            remoteDid,
+            remotePublicKey,
+            encrypted,
+            remoteCapabilities,
+            remoteWallets: finalWallets,
+            remoteWalletsVerified: walletsVerified,
+            createdAt: now.toISOString(),
+            expiresAt: expiresAt.toISOString(),
+            state: 'active',
+        };
+        this.sessions.set(remoteDid, session);
+        return session;
+    }
+}

package/dist/identity/index.d.ts

@@ -0,0 +1,155 @@
+export declare class IdentityError extends Error {
+    constructor(message: string);
+}
+export declare class SignatureError extends Error {
+    constructor(message: string);
+}
+export interface KeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export interface AgentIdentityData {
+    agent_id: string;
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+    did: string;
+}
+/** Optional metadata for an agent identity */
+export interface AgentMetadata {
+    /** Human-readable name */
+    name?: string;
+    /** Description of the agent's purpose */
+    description?: string;
+    /** List of capabilities the agent supports */
+    capabilities?: string[];
+    /** Agent version string */
+    version?: string;
+    /** Additional custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Generate an Ed25519 key pair using tweetnacl.
+ * @returns A KeyPair containing 32-byte publicKey and 64-byte secretKey.
+ */
+export declare function generateKeyPair(): KeyPair;
+/**
+ * Create a DID (Decentralized Identifier) from a public key.
+ * Format: "did:atel:ed25519:<base58(publicKey)>"
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @returns The DID string.
+ */
+export declare function createDID(publicKey: Uint8Array): string;
+/**
+ * Parse a DID string and extract the public key bytes.
+ * Supports both formats:
+ *   - "did:atel:ed25519:<base58>" (current)
+ *   - "did:atel:<base58>" (legacy, for backward compatibility)
+ * @param did - A DID string.
+ * @returns The decoded 32-byte public key.
+ */
+export declare function parseDID(did: string): Uint8Array;
+/**
+ * Deterministic JSON serialization — keys sorted recursively.
+ * Ensures identical payloads produce identical byte sequences for signing.
+ * @param obj - The object to serialize.
+ * @returns A deterministic JSON string.
+ */
+export declare function serializePayload(obj: unknown): string;
+/**
+ * Sign a payload with an Ed25519 secret key.
+ * The payload is first deterministically serialized, then signed.
+ * @param payload - The object or string to sign.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @returns A base64-encoded detached signature.
+ */
+export declare function sign(payload: unknown, secretKey: Uint8Array): string;
+/**
+ * Verify a detached Ed25519 signature against a payload.
+ * @param payload - The original object or string that was signed.
+ * @param signature - The base64-encoded signature to verify.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @returns True if the signature is valid.
+ */
+export declare function verify(payload: unknown, signature: string, publicKey: Uint8Array): boolean;
+/**
+ * Encapsulates an agent's cryptographic identity.
+ * Provides key generation, DID creation, signing, and verification.
+ */
+export declare class AgentIdentity {
+    readonly agent_id: string;
+    readonly publicKey: Uint8Array;
+    readonly secretKey: Uint8Array;
+    readonly did: string;
+    /** Optional metadata describing the agent */
+    readonly metadata?: AgentMetadata;
+    /**
+     * Create an AgentIdentity from an existing key pair.
+     * @param params - Optional agent_id, key pair, and metadata. Generates new keys if omitted.
+     */
+    constructor(params?: {
+        agent_id?: string;
+        publicKey?: Uint8Array;
+        secretKey?: Uint8Array;
+        metadata?: AgentMetadata;
+    });
+    /**
+     * Sign a payload using this agent's secret key.
+     * @param payload - The data to sign.
+     * @returns Base64-encoded signature.
+     */
+    sign(payload: unknown): string;
+    /**
+     * Verify a signature against this agent's public key.
+     * @param payload - The original data.
+     * @param signature - The base64 signature to verify.
+     * @returns True if valid.
+     */
+    verify(payload: unknown, signature: string): boolean;
+    /**
+     * Export identity data (excluding secret key) for sharing.
+     */
+    toPublic(): {
+        agent_id: string;
+        did: string;
+        publicKey: string;
+        metadata?: AgentMetadata;
+    };
+}
+/**
+ * Proof of key rotation: signed by both old and new keys.
+ * This allows verifiers to confirm the rotation was authorized by the original identity.
+ */
+export interface KeyRotationProof {
+    /** The agent's original DID (old key) */
+    oldDid: string;
+    /** The agent's new DID (new key) */
+    newDid: string;
+    /** New public key (base64) */
+    newPublicKey: string;
+    /** ISO 8601 timestamp of rotation */
+    timestamp: string;
+    /** Signature of {oldDid, newDid, newPublicKey, timestamp} by OLD secret key */
+    oldSignature: string;
+    /** Signature of {oldDid, newDid, newPublicKey, timestamp} by NEW secret key */
+    newSignature: string;
+}
+/**
+ * Rotate an agent's identity key pair.
+ * Generates a new key pair and produces a rotation proof signed by both old and new keys.
+ * The proof can be anchored on-chain and submitted to the Registry.
+ *
+ * @param oldIdentity - The current identity (with secret key).
+ * @returns The new identity and the rotation proof.
+ */
+export declare function rotateKey(oldIdentity: AgentIdentity): {
+    newIdentity: AgentIdentity;
+    proof: KeyRotationProof;
+};
+/**
+ * Verify a key rotation proof.
+ * Checks that both old and new keys signed the rotation data.
+ *
+ * @param proof - The rotation proof to verify.
+ * @returns True if both signatures are valid.
+ */
+export declare function verifyKeyRotation(proof: KeyRotationProof): boolean;

package/dist/identity/index.js

@@ -0,0 +1,250 @@
+import nacl from 'tweetnacl';
+import bs58 from 'bs58';
+import { v4 as uuidv4 } from 'uuid';
+// ─── Custom Errors ───────────────────────────────────────────────
+export class IdentityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IdentityError';
+    }
+}
+export class SignatureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SignatureError';
+    }
+}
+// ─── Core Functions ──────────────────────────────────────────────
+/**
+ * Generate an Ed25519 key pair using tweetnacl.
+ * @returns A KeyPair containing 32-byte publicKey and 64-byte secretKey.
+ */
+export function generateKeyPair() {
+    const kp = nacl.sign.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}
+/**
+ * Create a DID (Decentralized Identifier) from a public key.
+ * Format: "did:atel:ed25519:<base58(publicKey)>"
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @returns The DID string.
+ */
+export function createDID(publicKey) {
+    if (publicKey.length !== 32) {
+        throw new IdentityError(`Invalid public key length: expected 32, got ${publicKey.length}`);
+    }
+    const encoded = bs58.encode(publicKey);
+    return `did:atel:ed25519:${encoded}`;
+}
+/**
+ * Parse a DID string and extract the public key bytes.
+ * Supports both formats:
+ *   - "did:atel:ed25519:<base58>" (current)
+ *   - "did:atel:<base58>" (legacy, for backward compatibility)
+ * @param did - A DID string.
+ * @returns The decoded 32-byte public key.
+ */
+export function parseDID(did) {
+    const parts = did.split(':');
+    let base58Part;
+    if (parts.length === 4 && parts[0] === 'did' && parts[1] === 'atel' && parts[2] === 'ed25519') {
+        // New format: did:atel:ed25519:<base58>
+        base58Part = parts[3];
+    }
+    else if (parts.length === 3 && parts[0] === 'did' && parts[1] === 'atel') {
+        // Legacy format: did:atel:<base58>
+        base58Part = parts[2];
+    }
+    else {
+        throw new IdentityError(`Invalid DID format: ${did}`);
+    }
+    try {
+        const decoded = bs58.decode(base58Part);
+        if (decoded.length !== 32) {
+            throw new IdentityError(`Invalid public key in DID: expected 32 bytes, got ${decoded.length}`);
+        }
+        return decoded;
+    }
+    catch (e) {
+        if (e instanceof IdentityError)
+            throw e;
+        throw new IdentityError(`Failed to decode DID: ${e.message}`);
+    }
+}
+/**
+ * Deterministic JSON serialization — keys sorted recursively.
+ * Ensures identical payloads produce identical byte sequences for signing.
+ * @param obj - The object to serialize.
+ * @returns A deterministic JSON string.
+ */
+export function serializePayload(obj) {
+    return JSON.stringify(obj, (_key, value) => {
+        if (value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Uint8Array)) {
+            const sorted = {};
+            for (const k of Object.keys(value).sort()) {
+                sorted[k] = value[k];
+            }
+            return sorted;
+        }
+        return value;
+    });
+}
+/**
+ * Sign a payload with an Ed25519 secret key.
+ * The payload is first deterministically serialized, then signed.
+ * @param payload - The object or string to sign.
+ * @param secretKey - The 64-byte Ed25519 secret key.
+ * @returns A base64-encoded detached signature.
+ */
+export function sign(payload, secretKey) {
+    if (secretKey.length !== 64) {
+        throw new SignatureError(`Invalid secret key length: expected 64, got ${secretKey.length}`);
+    }
+    const message = typeof payload === 'string' ? payload : serializePayload(payload);
+    const messageBytes = new TextEncoder().encode(message);
+    const signature = nacl.sign.detached(messageBytes, secretKey);
+    return Buffer.from(signature).toString('base64');
+}
+/**
+ * Verify a detached Ed25519 signature against a payload.
+ * @param payload - The original object or string that was signed.
+ * @param signature - The base64-encoded signature to verify.
+ * @param publicKey - The 32-byte Ed25519 public key.
+ * @returns True if the signature is valid.
+ */
+export function verify(payload, signature, publicKey) {
+    if (publicKey.length !== 32) {
+        throw new SignatureError(`Invalid public key length: expected 32, got ${publicKey.length}`);
+    }
+    try {
+        const message = typeof payload === 'string' ? payload : serializePayload(payload);
+        const messageBytes = new TextEncoder().encode(message);
+        const sigBytes = Uint8Array.from(Buffer.from(signature, 'base64'));
+        return nacl.sign.detached.verify(messageBytes, sigBytes, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+// ─── AgentIdentity Class ─────────────────────────────────────────
+/**
+ * Encapsulates an agent's cryptographic identity.
+ * Provides key generation, DID creation, signing, and verification.
+ */
+export class AgentIdentity {
+    agent_id;
+    publicKey;
+    secretKey;
+    did;
+    /** Optional metadata describing the agent */
+    metadata;
+    /**
+     * Create an AgentIdentity from an existing key pair.
+     * @param params - Optional agent_id, key pair, and metadata. Generates new keys if omitted.
+     */
+    constructor(params) {
+        if (params?.publicKey && params?.secretKey) {
+            this.publicKey = params.publicKey;
+            this.secretKey = params.secretKey;
+        }
+        else {
+            const kp = generateKeyPair();
+            this.publicKey = kp.publicKey;
+            this.secretKey = kp.secretKey;
+        }
+        this.agent_id = params?.agent_id ?? uuidv4();
+        this.did = createDID(this.publicKey);
+        this.metadata = params?.metadata;
+    }
+    /**
+     * Sign a payload using this agent's secret key.
+     * @param payload - The data to sign.
+     * @returns Base64-encoded signature.
+     */
+    sign(payload) {
+        return sign(payload, this.secretKey);
+    }
+    /**
+     * Verify a signature against this agent's public key.
+     * @param payload - The original data.
+     * @param signature - The base64 signature to verify.
+     * @returns True if valid.
+     */
+    verify(payload, signature) {
+        return verify(payload, signature, this.publicKey);
+    }
+    /**
+     * Export identity data (excluding secret key) for sharing.
+     */
+    toPublic() {
+        const pub = {
+            agent_id: this.agent_id,
+            did: this.did,
+            publicKey: Buffer.from(this.publicKey).toString('base64'),
+        };
+        if (this.metadata) {
+            pub.metadata = this.metadata;
+        }
+        return pub;
+    }
+}
+/**
+ * Rotate an agent's identity key pair.
+ * Generates a new key pair and produces a rotation proof signed by both old and new keys.
+ * The proof can be anchored on-chain and submitted to the Registry.
+ *
+ * @param oldIdentity - The current identity (with secret key).
+ * @returns The new identity and the rotation proof.
+ */
+export function rotateKey(oldIdentity) {
+    const newKp = generateKeyPair();
+    const newIdentity = new AgentIdentity({
+        agent_id: oldIdentity.agent_id,
+        publicKey: newKp.publicKey,
+        secretKey: newKp.secretKey,
+        metadata: oldIdentity.metadata,
+    });
+    const rotationData = {
+        oldDid: oldIdentity.did,
+        newDid: newIdentity.did,
+        newPublicKey: Buffer.from(newKp.publicKey).toString('base64'),
+        timestamp: new Date().toISOString(),
+    };
+    const signable = serializePayload(rotationData);
+    const oldSignature = sign(signable, oldIdentity.secretKey);
+    const newSignature = sign(signable, newIdentity.secretKey);
+    return {
+        newIdentity,
+        proof: {
+            ...rotationData,
+            oldSignature,
+            newSignature,
+        },
+    };
+}
+/**
+ * Verify a key rotation proof.
+ * Checks that both old and new keys signed the rotation data.
+ *
+ * @param proof - The rotation proof to verify.
+ * @returns True if both signatures are valid.
+ */
+export function verifyKeyRotation(proof) {
+    try {
+        const oldPk = parseDID(proof.oldDid);
+        const newPk = parseDID(proof.newDid);
+        const rotationData = {
+            oldDid: proof.oldDid,
+            newDid: proof.newDid,
+            newPublicKey: proof.newPublicKey,
+            timestamp: proof.timestamp,
+        };
+        const signable = serializePayload(rotationData);
+        const oldValid = verify(signable, proof.oldSignature, oldPk);
+        const newValid = verify(signable, proof.newSignature, newPk);
+        return oldValid && newValid;
+    }
+    catch {
+        return false;
+    }
+}