@lawrenceliang-btc/atel-sdk 0.8.7

package/dist/collaboration/index.js

@@ -0,0 +1,237 @@
+/**
+ * Module: Collaboration Anchor
+ *
+ * Enhanced on-chain anchoring for multi-agent collaboration scenarios.
+ * Records the full lifecycle of agent collaboration on-chain:
+ *
+ *   1. Handshake Anchor — proves two agents established a verified session
+ *   2. Task Delegation Anchor — proves a task was delegated with consent
+ *   3. Execution Proof Anchor — proves task execution result (existing ProofBundle)
+ *   4. Trust Score Anchor — proves trust score at a point in time
+ *   5. Dispute Evidence Anchor — immutable evidence for dispute resolution
+ *
+ * Each anchor is a SHA-256 hash of the relevant data, stored on-chain
+ * via the existing AnchorManager infrastructure.
+ */
+import { createHash } from 'node:crypto';
+// ─── Hash Helpers ────────────────────────────────────────────────
+function sha256(input) {
+    return createHash('sha256').update(input, 'utf-8').digest('hex');
+}
+function sortedStringify(obj) {
+    if (obj === null || obj === undefined)
+        return JSON.stringify(obj);
+    if (typeof obj !== 'object')
+        return JSON.stringify(obj);
+    if (Array.isArray(obj))
+        return `[${obj.map(sortedStringify).join(',')}]`;
+    const record = obj;
+    const keys = Object.keys(record).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${sortedStringify(record[k])}`).join(',')}}`;
+}
+function hashObject(obj) {
+    return sha256(sortedStringify(obj));
+}
+// ─── Collaboration Anchor Manager ────────────────────────────────
+/**
+ * Manages on-chain anchoring of multi-agent collaboration events.
+ *
+ * Builds on top of AnchorManager to provide typed, structured
+ * anchoring for the full collaboration lifecycle.
+ */
+export class CollaborationAnchor {
+    anchorManager;
+    defaultChain;
+    records = [];
+    constructor(anchorManager, defaultChain = 'mock') {
+        this.anchorManager = anchorManager;
+        this.defaultChain = defaultChain;
+    }
+    /**
+     * Anchor a handshake session establishment.
+     * Proves that two agents verified each other's identity at a specific time.
+     */
+    async anchorHandshake(session, chain) {
+        const data = {
+            type: 'handshake',
+            sessionId: session.sessionId,
+            localDid: session.localDid,
+            remoteDid: session.remoteDid,
+            encrypted: session.encrypted,
+            createdAt: session.createdAt,
+        };
+        const hash = hashObject(data);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'handshake',
+            participants: [session.localDid, session.remoteDid],
+        });
+        const record = {
+            type: 'handshake',
+            hash,
+            anchor,
+            participants: [session.localDid, session.remoteDid],
+            description: `Handshake between ${session.localDid} and ${session.remoteDid}`,
+            eventTimestamp: session.createdAt,
+        };
+        this.records.push(record);
+        return record;
+    }
+    /**
+     * Anchor a task delegation event.
+     * Proves that a task was delegated with specific consent and policy.
+     */
+    async anchorTaskDelegation(delegation, chain) {
+        const hash = hashObject(delegation);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'task_delegation',
+            taskType: delegation.taskType,
+            participants: [delegation.requestorDid, delegation.executorDid],
+        });
+        const record = {
+            type: 'task_delegation',
+            hash,
+            anchor,
+            participants: [delegation.requestorDid, delegation.executorDid],
+            description: `Task "${delegation.taskType}" delegated from ${delegation.requestorDid} to ${delegation.executorDid}`,
+            eventTimestamp: delegation.timestamp,
+        };
+        this.records.push(record);
+        return record;
+    }
+    /**
+     * Anchor an execution proof bundle.
+     * Proves the result of a task execution with full Merkle proof.
+     */
+    async anchorExecutionProof(proof, chain) {
+        // Anchor the proof_id + trace_root combination
+        const hash = sha256(`${proof.proof_id}:${proof.trace_root}:${proof.executor}`);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'execution_proof',
+            proof_id: proof.proof_id,
+            trace_root: proof.trace_root,
+            executor: proof.executor,
+            trace_length: proof.trace_length,
+        });
+        const record = {
+            type: 'execution_proof',
+            hash,
+            anchor,
+            participants: [proof.executor],
+            description: `Execution proof ${proof.proof_id} by ${proof.executor} (${proof.trace_length} events)`,
+            eventTimestamp: proof.created_at,
+        };
+        this.records.push(record);
+        return record;
+    }
+    /**
+     * Anchor a trust score snapshot.
+     * Creates an immutable record of an agent's trust score at a point in time.
+     * Links to previous snapshot for chain integrity.
+     */
+    async anchorTrustScore(snapshot, chain) {
+        const hash = hashObject(snapshot);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'trust_score',
+            agentDid: snapshot.agentDid,
+            score: snapshot.score,
+            previousHash: snapshot.previousHash,
+        });
+        const record = {
+            type: 'trust_score',
+            hash,
+            anchor,
+            participants: [snapshot.agentDid],
+            description: `Trust score ${snapshot.score} for ${snapshot.agentDid} (${snapshot.completedTasks} completed, ${snapshot.failedTasks} failed)`,
+            eventTimestamp: snapshot.timestamp,
+        };
+        this.records.push(record);
+        return record;
+    }
+    /**
+     * Anchor dispute evidence.
+     * Creates an immutable record for dispute resolution.
+     */
+    async anchorDisputeEvidence(evidence, chain) {
+        const hash = hashObject(evidence);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'dispute_evidence',
+            disputeId: evidence.disputeId,
+        });
+        const record = {
+            type: 'dispute_evidence',
+            hash,
+            anchor,
+            participants: [evidence.complainantDid, evidence.respondentDid],
+            description: `Dispute ${evidence.disputeId}: ${evidence.complainantDid} vs ${evidence.respondentDid}`,
+            eventTimestamp: evidence.timestamp,
+        };
+        this.records.push(record);
+        return record;
+    }
+    /**
+     * Anchor a key rotation event.
+     * Proves that an agent rotated their encryption keys at a specific time.
+     */
+    async anchorKeyRotation(agentDid, rotationSeq, newPublicKeyHash, chain) {
+        const data = {
+            type: 'key_rotation',
+            agentDid,
+            rotationSeq,
+            newPublicKeyHash,
+            timestamp: new Date().toISOString(),
+        };
+        const hash = hashObject(data);
+        const anchor = await this.anchorManager.anchor(hash, chain ?? this.defaultChain, {
+            type: 'key_rotation',
+            agentDid,
+            rotationSeq,
+        });
+        const record = {
+            type: 'key_rotation',
+            hash,
+            anchor,
+            participants: [agentDid],
+            description: `Key rotation #${rotationSeq} for ${agentDid}`,
+            eventTimestamp: data.timestamp,
+        };
+        this.records.push(record);
+        return record;
+    }
+    // ── Query ────────────────────────────────────────────────────
+    /**
+     * Get all collaboration anchor records.
+     */
+    getRecords() {
+        return [...this.records];
+    }
+    /**
+     * Get records by type.
+     */
+    getRecordsByType(type) {
+        return this.records.filter((r) => r.type === type);
+    }
+    /**
+     * Get records involving a specific agent.
+     */
+    getRecordsByParticipant(did) {
+        return this.records.filter((r) => r.participants.includes(did));
+    }
+    /**
+     * Verify a collaboration anchor against the chain.
+     */
+    async verifyAnchor(record) {
+        try {
+            const verification = await this.anchorManager.verify(record.hash, record.anchor.txHash, record.anchor.chain);
+            return {
+                valid: verification.valid,
+                detail: verification.detail ?? (verification.valid ? 'Anchor verified on-chain' : 'Verification failed'),
+            };
+        }
+        catch (err) {
+            return {
+                valid: false,
+                detail: `Verification error: ${err.message}`,
+            };
+        }
+    }
+}

package/dist/crypto/index.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Module: Crypto
+ *
+ * End-to-end encryption for ATEL inter-agent communication.
+ * Uses X25519 key exchange + XSalsa20-Poly1305 symmetric encryption.
+ *
+ * Flow:
+ *   1. During handshake, agents exchange X25519 public keys
+ *   2. Both derive a shared secret via Diffie-Hellman
+ *   3. All subsequent messages are encrypted with the shared key
+ *
+ * Also provides key rotation utilities.
+ */
+/** X25519 key pair for Diffie-Hellman key exchange */
+export interface EncryptionKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+/** An encrypted payload with nonce */
+export interface EncryptedPayload {
+    /** Encryption version marker */
+    enc: 'atel.enc.v1';
+    /** Base64-encoded encrypted ciphertext */
+    ciphertext: string;
+    /** Base64-encoded 24-byte nonce */
+    nonce: string;
+    /** Sender's ephemeral X25519 public key (base64), for forward secrecy */
+    ephemeralPubKey?: string;
+}
+/** Session encryption state */
+export interface EncryptionSession {
+    /** Remote agent DID */
+    remoteDid: string;
+    /** Shared secret derived from DH exchange */
+    sharedKey: Uint8Array;
+    /** Our X25519 key pair for this session */
+    localKeyPair: EncryptionKeyPair;
+    /** Remote agent's X25519 public key */
+    remotePublicKey: Uint8Array;
+    /** Session creation time */
+    createdAt: number;
+    /** Key rotation counter */
+    rotationCount: number;
+}
+/** Key rotation event */
+export interface KeyRotationEvent {
+    /** New X25519 public key (base64) */
+    newPublicKey: string;
+    /** Signature over the new key using Ed25519 identity key */
+    signature: string;
+    /** Rotation sequence number */
+    rotationSeq: number;
+    /** Timestamp */
+    timestamp: string;
+}
+export declare class CryptoError extends Error {
+    constructor(message: string);
+}
+/**
+ * Generate an X25519 key pair for Diffie-Hellman key exchange.
+ */
+export declare function generateEncryptionKeyPair(): EncryptionKeyPair;
+/**
+ * Derive a shared secret from local secret key and remote public key.
+ * Uses X25519 Diffie-Hellman + SHA-256 key derivation.
+ *
+ * @param localSecretKey - Our X25519 secret key (32 bytes).
+ * @param remotePublicKey - Their X25519 public key (32 bytes).
+ * @returns 32-byte shared secret.
+ */
+export declare function deriveSharedKey(localSecretKey: Uint8Array, remotePublicKey: Uint8Array): Uint8Array;
+/**
+ * Encrypt a plaintext message using a shared key.
+ * Uses XSalsa20-Poly1305 (NaCl secretbox).
+ *
+ * @param plaintext - The message to encrypt (UTF-8 string).
+ * @param sharedKey - 32-byte shared secret.
+ * @returns EncryptedPayload with ciphertext and nonce.
+ */
+export declare function encrypt(plaintext: string, sharedKey: Uint8Array): EncryptedPayload;
+/**
+ * Decrypt an encrypted payload using a shared key.
+ *
+ * @param payload - The encrypted payload.
+ * @param sharedKey - 32-byte shared secret.
+ * @returns The decrypted plaintext string.
+ * @throws CryptoError if decryption fails (wrong key, tampered data).
+ */
+export declare function decrypt(payload: EncryptedPayload, sharedKey: Uint8Array): string;
+/**
+ * Manages encryption sessions with remote agents.
+ * Handles key exchange, encryption/decryption, and key rotation.
+ */
+export declare class EncryptionManager {
+    private sessions;
+    /**
+     * Create an encryption session with a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param remoteEncPubKey - The remote agent's X25519 public key.
+     * @returns The local X25519 public key to send to the remote agent.
+     */
+    createSession(remoteDid: string, remoteEncPubKey: Uint8Array): Uint8Array;
+    /**
+     * Create an encryption session with pre-computed keys.
+     * Used by HandshakeManager when keys are already exchanged.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param localKeyPair - Our X25519 key pair.
+     * @param remotePublicKey - Their X25519 public key.
+     * @param sharedKey - Pre-derived shared secret.
+     */
+    createSessionWithKeys(remoteDid: string, localKeyPair: EncryptionKeyPair, remotePublicKey: Uint8Array, sharedKey: Uint8Array): void;
+    /**
+     * Encrypt a message for a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param plaintext - The message to encrypt.
+     * @returns The encrypted payload.
+     * @throws CryptoError if no session exists.
+     */
+    encryptFor(remoteDid: string, plaintext: string): EncryptedPayload;
+    /**
+     * Decrypt a message from a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param payload - The encrypted payload.
+     * @returns The decrypted plaintext.
+     * @throws CryptoError if no session exists or decryption fails.
+     */
+    decryptFrom(remoteDid: string, payload: EncryptedPayload): string;
+    /**
+     * Rotate the encryption key for a session.
+     * Generates a new key pair and re-derives the shared secret.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param newRemotePublicKey - The remote agent's new X25519 public key.
+     * @returns The new local X25519 public key.
+     */
+    rotateKey(remoteDid: string, newRemotePublicKey: Uint8Array): Uint8Array;
+    /**
+     * Check if an encryption session exists.
+     */
+    hasSession(remoteDid: string): boolean;
+    /**
+     * Get session info (without exposing the shared key).
+     */
+    getSessionInfo(remoteDid: string): {
+        remoteDid: string;
+        createdAt: number;
+        rotationCount: number;
+    } | undefined;
+    /**
+     * Destroy a session and zero out all key material.
+     */
+    destroySession(remoteDid: string): void;
+    /**
+     * Destroy all sessions.
+     */
+    destroyAll(): void;
+    private getSessionOrThrow;
+}

package/dist/crypto/index.js

@@ -0,0 +1,231 @@
+/**
+ * Module: Crypto
+ *
+ * End-to-end encryption for ATEL inter-agent communication.
+ * Uses X25519 key exchange + XSalsa20-Poly1305 symmetric encryption.
+ *
+ * Flow:
+ *   1. During handshake, agents exchange X25519 public keys
+ *   2. Both derive a shared secret via Diffie-Hellman
+ *   3. All subsequent messages are encrypted with the shared key
+ *
+ * Also provides key rotation utilities.
+ */
+import nacl from 'tweetnacl';
+import { createHash } from 'node:crypto';
+// ─── Custom Errors ───────────────────────────────────────────────
+export class CryptoError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CryptoError';
+    }
+}
+// ─── Key Generation ──────────────────────────────────────────────
+/**
+ * Generate an X25519 key pair for Diffie-Hellman key exchange.
+ */
+export function generateEncryptionKeyPair() {
+    const kp = nacl.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}
+/**
+ * Derive a shared secret from local secret key and remote public key.
+ * Uses X25519 Diffie-Hellman + SHA-256 key derivation.
+ *
+ * @param localSecretKey - Our X25519 secret key (32 bytes).
+ * @param remotePublicKey - Their X25519 public key (32 bytes).
+ * @returns 32-byte shared secret.
+ */
+export function deriveSharedKey(localSecretKey, remotePublicKey) {
+    const rawShared = nacl.box.before(remotePublicKey, localSecretKey);
+    // KDF: SHA-256 over the raw shared secret + context string
+    const kdf = createHash('sha256');
+    kdf.update(Buffer.from('atel-session-key-v1'));
+    kdf.update(Buffer.from(rawShared));
+    return new Uint8Array(kdf.digest());
+}
+// ─── Encryption / Decryption ─────────────────────────────────────
+/**
+ * Encrypt a plaintext message using a shared key.
+ * Uses XSalsa20-Poly1305 (NaCl secretbox).
+ *
+ * @param plaintext - The message to encrypt (UTF-8 string).
+ * @param sharedKey - 32-byte shared secret.
+ * @returns EncryptedPayload with ciphertext and nonce.
+ */
+export function encrypt(plaintext, sharedKey) {
+    if (sharedKey.length !== 32) {
+        throw new CryptoError(`Invalid shared key length: expected 32, got ${sharedKey.length}`);
+    }
+    const nonce = nacl.randomBytes(24);
+    const messageBytes = new TextEncoder().encode(plaintext);
+    const ciphertext = nacl.secretbox(messageBytes, nonce, sharedKey);
+    if (!ciphertext) {
+        throw new CryptoError('Encryption failed');
+    }
+    return {
+        enc: 'atel.enc.v1',
+        ciphertext: Buffer.from(ciphertext).toString('base64'),
+        nonce: Buffer.from(nonce).toString('base64'),
+    };
+}
+/**
+ * Decrypt an encrypted payload using a shared key.
+ *
+ * @param payload - The encrypted payload.
+ * @param sharedKey - 32-byte shared secret.
+ * @returns The decrypted plaintext string.
+ * @throws CryptoError if decryption fails (wrong key, tampered data).
+ */
+export function decrypt(payload, sharedKey) {
+    if (sharedKey.length !== 32) {
+        throw new CryptoError(`Invalid shared key length: expected 32, got ${sharedKey.length}`);
+    }
+    if (payload.enc !== 'atel.enc.v1') {
+        throw new CryptoError(`Unsupported encryption version: ${payload.enc}`);
+    }
+    const ciphertext = Uint8Array.from(Buffer.from(payload.ciphertext, 'base64'));
+    const nonce = Uint8Array.from(Buffer.from(payload.nonce, 'base64'));
+    const plaintext = nacl.secretbox.open(ciphertext, nonce, sharedKey);
+    if (!plaintext) {
+        throw new CryptoError('Decryption failed: invalid key or tampered ciphertext');
+    }
+    return new TextDecoder().decode(plaintext);
+}
+// ─── Encryption Session Manager ──────────────────────────────────
+/**
+ * Manages encryption sessions with remote agents.
+ * Handles key exchange, encryption/decryption, and key rotation.
+ */
+export class EncryptionManager {
+    sessions = new Map();
+    /**
+     * Create an encryption session with a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param remoteEncPubKey - The remote agent's X25519 public key.
+     * @returns The local X25519 public key to send to the remote agent.
+     */
+    createSession(remoteDid, remoteEncPubKey) {
+        const localKeyPair = generateEncryptionKeyPair();
+        const sharedKey = deriveSharedKey(localKeyPair.secretKey, remoteEncPubKey);
+        this.sessions.set(remoteDid, {
+            remoteDid,
+            sharedKey,
+            localKeyPair,
+            remotePublicKey: remoteEncPubKey,
+            createdAt: Date.now(),
+            rotationCount: 0,
+        });
+        return localKeyPair.publicKey;
+    }
+    /**
+     * Create an encryption session with pre-computed keys.
+     * Used by HandshakeManager when keys are already exchanged.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param localKeyPair - Our X25519 key pair.
+     * @param remotePublicKey - Their X25519 public key.
+     * @param sharedKey - Pre-derived shared secret.
+     */
+    createSessionWithKeys(remoteDid, localKeyPair, remotePublicKey, sharedKey) {
+        this.sessions.set(remoteDid, {
+            remoteDid,
+            sharedKey,
+            localKeyPair,
+            remotePublicKey,
+            createdAt: Date.now(),
+            rotationCount: 0,
+        });
+    }
+    /**
+     * Encrypt a message for a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param plaintext - The message to encrypt.
+     * @returns The encrypted payload.
+     * @throws CryptoError if no session exists.
+     */
+    encryptFor(remoteDid, plaintext) {
+        const session = this.getSessionOrThrow(remoteDid);
+        return encrypt(plaintext, session.sharedKey);
+    }
+    /**
+     * Decrypt a message from a remote agent.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param payload - The encrypted payload.
+     * @returns The decrypted plaintext.
+     * @throws CryptoError if no session exists or decryption fails.
+     */
+    decryptFrom(remoteDid, payload) {
+        const session = this.getSessionOrThrow(remoteDid);
+        return decrypt(payload, session.sharedKey);
+    }
+    /**
+     * Rotate the encryption key for a session.
+     * Generates a new key pair and re-derives the shared secret.
+     *
+     * @param remoteDid - The remote agent's DID.
+     * @param newRemotePublicKey - The remote agent's new X25519 public key.
+     * @returns The new local X25519 public key.
+     */
+    rotateKey(remoteDid, newRemotePublicKey) {
+        const session = this.getSessionOrThrow(remoteDid);
+        const newLocalKeyPair = generateEncryptionKeyPair();
+        const newSharedKey = deriveSharedKey(newLocalKeyPair.secretKey, newRemotePublicKey);
+        // Zero out old keys
+        session.sharedKey.fill(0);
+        session.localKeyPair.secretKey.fill(0);
+        session.sharedKey = newSharedKey;
+        session.localKeyPair = newLocalKeyPair;
+        session.remotePublicKey = newRemotePublicKey;
+        session.rotationCount++;
+        return newLocalKeyPair.publicKey;
+    }
+    /**
+     * Check if an encryption session exists.
+     */
+    hasSession(remoteDid) {
+        return this.sessions.has(remoteDid);
+    }
+    /**
+     * Get session info (without exposing the shared key).
+     */
+    getSessionInfo(remoteDid) {
+        const session = this.sessions.get(remoteDid);
+        if (!session)
+            return undefined;
+        return {
+            remoteDid: session.remoteDid,
+            createdAt: session.createdAt,
+            rotationCount: session.rotationCount,
+        };
+    }
+    /**
+     * Destroy a session and zero out all key material.
+     */
+    destroySession(remoteDid) {
+        const session = this.sessions.get(remoteDid);
+        if (session) {
+            session.sharedKey.fill(0);
+            session.localKeyPair.secretKey.fill(0);
+            this.sessions.delete(remoteDid);
+        }
+    }
+    /**
+     * Destroy all sessions.
+     */
+    destroyAll() {
+        for (const [did] of this.sessions) {
+            this.destroySession(did);
+        }
+    }
+    getSessionOrThrow(remoteDid) {
+        const session = this.sessions.get(remoteDid);
+        if (!session) {
+            throw new CryptoError(`No encryption session with ${remoteDid}`);
+        }
+        return session;
+    }
+}