@ajna-inc/vaults 0.1.0 → 0.1.2

package/build/services/HPKEService.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * HPKE Service for Vaults
+ *
+ * Implements RFC 9180 HPKE for sealing ML-KEM public keys during key exchange.
+ *
+ * Uses:
+ * - KEM: DHKEM(P-256, HKDF-SHA256)
+ * - KDF: HKDF-SHA256
+ * - AEAD: AES-256-GCM
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HPKEService = void 0;
+const core_1 = require("@credo-ts/core");
+const core_2 = require("@hpke/core");
+const sha256_1 = require("@noble/hashes/sha256");
+let HPKEService = class HPKEService {
+    /**
+     * Get CipherSuite for HPKE operations
+     */
+    getCipherSuite() {
+        return new core_2.CipherSuite({
+            kem: new core_2.DhkemP256HkdfSha256(),
+            kdf: new core_2.HkdfSha256(),
+            aead: new core_2.Aes256Gcm(),
+        });
+    }
+    /**
+     * Encrypt payload with HPKE
+     *
+     * @param recipientPublicKey - Recipient's P-256 public key (raw bytes)
+     * @param plaintext - Payload to encrypt
+     * @param aad - Additional authenticated data (optional)
+     * @returns Encryption result with ciphertext and ephemeral key
+     */
+    async encrypt(recipientPublicKey, plaintext, aad) {
+        const suite = this.getCipherSuite();
+        // Import recipient public key
+        const pkR = await suite.kem.importKey('raw', recipientPublicKey, true);
+        // Encrypt using HPKE Base mode
+        const sender = await suite.createSenderContext({
+            recipientPublicKey: pkR,
+        });
+        const ciphertext = new Uint8Array(await sender.seal(plaintext, aad));
+        return {
+            ciphertext,
+            ephemeralPublicKey: new Uint8Array(sender.enc),
+        };
+    }
+    /**
+     * Decrypt payload with HPKE
+     *
+     * @param recipientPrivateKey - Recipient's P-256 private key (raw bytes)
+     * @param ciphertext - Encrypted payload
+     * @param ephemeralPublicKey - Ephemeral public key from encryption
+     * @param aad - Additional authenticated data (must match encryption)
+     * @returns Decryption result with plaintext
+     */
+    async decrypt(recipientPrivateKey, ciphertext, ephemeralPublicKey, aad) {
+        const suite = this.getCipherSuite();
+        // Import recipient private key
+        const skR = await suite.kem.importKey('raw', recipientPrivateKey, false);
+        // Decrypt using HPKE Base mode
+        const recipient = await suite.createRecipientContext({
+            recipientKey: skR,
+            enc: ephemeralPublicKey,
+        });
+        const plaintext = new Uint8Array(await recipient.open(ciphertext, aad));
+        return { plaintext };
+    }
+    /**
+     * Generate key pair for HPKE (P-256)
+     *
+     * @returns Object with public and private keys
+     */
+    async generateKeyPair() {
+        const suite = this.getCipherSuite();
+        const keyPair = await suite.kem.generateKeyPair();
+        const publicKeyRaw = await suite.kem.serializePublicKey(keyPair.publicKey);
+        const privateKeyRaw = await suite.kem.serializePrivateKey(keyPair.privateKey);
+        return {
+            publicKey: new Uint8Array(publicKeyRaw),
+            privateKey: new Uint8Array(privateKeyRaw),
+        };
+    }
+    /**
+     * Compute digest for AAD binding
+     *
+     * @param data - Data to hash
+     * @returns SHA-256 hash
+     */
+    computeDigest(data) {
+        return (0, sha256_1.sha256)(data);
+    }
+};
+exports.HPKEService = HPKEService;
+exports.HPKEService = HPKEService = __decorate([
+    (0, core_1.injectable)()
+], HPKEService);
+//# sourceMappingURL=HPKEService.js.map

package/build/services/HPKEService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HPKEService.js","sourceRoot":"","sources":["../../src/services/HPKEService.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;AAEH,yCAA2C;AAC3C,qCAAoF;AACpF,iDAA6C;AAqBtC,IAAM,WAAW,GAAjB,MAAM,WAAW;IACtB;;OAEG;IACK,cAAc;QACpB,OAAO,IAAI,kBAAW,CAAC;YACrB,GAAG,EAAE,IAAI,0BAAmB,EAAE;YAC9B,GAAG,EAAE,IAAI,iBAAU,EAAE;YACrB,IAAI,EAAE,IAAI,gBAAS,EAAE;SACtB,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;;OAOG;IACI,KAAK,CAAC,OAAO,CAClB,kBAA8B,EAC9B,SAAqB,EACrB,GAAgB;QAEhB,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;QAEnC,8BAA8B;QAC9B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,kBAAkB,EAAE,IAAI,CAAC,CAAA;QAEtE,+BAA+B;QAC/B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,mBAAmB,CAAC;YAC7C,kBAAkB,EAAE,GAAG;SACxB,CAAC,CAAA;QAEF,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAA;QAEpE,OAAO;YACL,UAAU;YACV,kBAAkB,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC;SAC/C,CAAA;IACH,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,OAAO,CAClB,mBAA+B,EAC/B,UAAsB,EACtB,kBAA8B,EAC9B,GAAgB;QAEhB,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;QAEnC,+BAA+B;QAC/B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,CAAC,CAAA;QAExE,+BAA+B;QAC/B,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,sBAAsB,CAAC;YACnD,YAAY,EAAE,GAAG;YACjB,GAAG,EAAE,kBAAkB;SACxB,CAAC,CAAA;QAEF,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,MAAM,SAAS,CAAC,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,CAAA;QAEvE,OAAO,EAAE,SAAS,EAAE,CAAA;IACtB,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,eAAe;QAI1B,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;QACnC,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,eAAe,EAAE,CAAA;QAEjD,MAAM,YAAY,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QAC1E,MAAM,aAAa,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,mBAAmB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;QAE7E,OAAO;YACL,SAAS,EAAE,IAAI,UAAU,CAAC,YAAY,CAAC;YACvC,UAAU,EAAE,IAAI,UAAU,CAAC,aAAa,CAAC;SAC1C,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACI,aAAa,CAAC,IAAgB;QACnC,OAAO,IAAA,eAAM,EAAC,IAAI,CAAC,CAAA;IACrB,CAAC;CACF,CAAA;AAxGY,kCAAW;sBAAX,WAAW;IADvB,IAAA,iBAAU,GAAE;GACA,WAAW,CAwGvB"}

package/build/services/KemKeyExchangeService.d.ts

@@ -0,0 +1,207 @@
+/**
+ * KEM Key Exchange Service
+ *
+ * Exchanges ML-KEM public keys between agents for quantum-safe vault encryption.
+ *
+ * Key Design:
+ * - Uses existing X25519 channel to bootstrap ML-KEM key exchange
+ * - Seals ML-KEM public keys in HPKE envelopes (RFC 9180)
+ * - Stores peer's ML-KEM keys in connection metadata
+ * - Uses signing protocol's provide-artifacts message (sealed-secret@1)
+ *
+ * Flow:
+ * 1. Agent A generates ML-KEM keypair
+ * 2. Agent A seals their ML-KEM public key using peer's X25519 key
+ * 3. Agent A sends sealed key via provide-artifacts message
+ * 4. Agent B unwraps the ML-KEM key using their X25519 private key
+ * 5. Agent B stores Agent A's ML-KEM key in connection metadata
+ * 6. Agent B can now encrypt vaults to Agent A's ML-KEM key
+ */
+import type { AgentContext, Logger } from '@credo-ts/core';
+import { ConnectionRepository } from '@credo-ts/core';
+import { HPKEService } from './HPKEService';
+import { KemKeypairRepository } from '../repository/KemKeypairRepository';
+/**
+ * ML-KEM keypair with derived key ID
+ */
+export interface KemKeypairWithKid {
+    /** Key identifier (derived from public key hash) */
+    kid: string;
+    /** ML-KEM public key (1184 bytes for ML-KEM-768) */
+    publicKey: Uint8Array;
+    /** ML-KEM secret key (2400 bytes for ML-KEM-768) */
+    secretKey: Uint8Array;
+}
+/**
+ * ML-KEM public key info (no secret key)
+ */
+export interface KemPublicKeyInfo {
+    /** Key identifier */
+    kid: string;
+    /** ML-KEM public key */
+    publicKey: Uint8Array;
+    /** Timestamp when the key was stored */
+    storedAt?: string;
+}
+/**
+ * Sealed artifact containing ML-KEM public key
+ * Encrypted with HPKE to recipient's X25519 key
+ */
+export interface SealedKemKeyArtifact {
+    /** Artifact type identifier */
+    type: 'sealed-ml-kem-key@1';
+    /** HPKE envelope suite */
+    envelope: 'envelope-hpke@1';
+    /** Base64url-encoded ciphertext */
+    ciphertext: string;
+    /** Base64url-encoded ephemeral public key */
+    ephemeralPublicKey: string;
+    /** Key ID of the sealed ML-KEM key */
+    kid: string;
+}
+/**
+ * Connection metadata key for ML-KEM keys
+ */
+export declare const KEM_KEY_METADATA_KEY = "vaults/kem-key";
+/**
+ * Metadata stored in connection for peer's KEM key
+ */
+export interface KemKeyMetadata {
+    /** Key identifier */
+    kid: string;
+    /** Base64url-encoded ML-KEM public key */
+    publicKey: string;
+    /** When the key was stored */
+    storedAt: string;
+    /** Optional: when the key exchange session was initiated */
+    exchangeSessionId?: string;
+}
+export declare class KemKeyExchangeService {
+    private logger;
+    private connectionRepository;
+    private hpkeService;
+    private kemKeypairRepository;
+    constructor(logger: Logger, connectionRepository: ConnectionRepository, hpkeService: HPKEService, kemKeypairRepository: KemKeypairRepository);
+    /**
+     * Generate a new ML-KEM-768 keypair
+     *
+     * @returns Keypair with derived key ID
+     */
+    generateKemKeypair(): KemKeypairWithKid;
+    /**
+     * Create a sealed artifact containing our ML-KEM public key
+     *
+     * This creates an artifact suitable for sending via provide-artifacts message.
+     * The ML-KEM public key is sealed using HPKE (RFC 9180) to the recipient's P-256 public key.
+     *
+     * @param keypair - Our ML-KEM keypair
+     * @param recipientPublicKey - Recipient's P-256 public key for HPKE encryption
+     * @returns Sealed artifact ready for transmission
+     */
+    createKemKeyArtifact(keypair: KemKeypairWithKid, recipientPublicKey: Uint8Array): Promise<SealedKemKeyArtifact>;
+    /**
+     * Unwrap a sealed KEM key artifact
+     *
+     * Decrypts the sealed artifact using HPKE to extract the peer's ML-KEM public key.
+     *
+     * @param artifact - Sealed artifact received from peer
+     * @param recipientSecretKey - Our P-256 private key to decrypt
+     * @returns Peer's ML-KEM public key info
+     */
+    unwrapKemKeyArtifact(artifact: SealedKemKeyArtifact, recipientSecretKey: Uint8Array): Promise<KemPublicKeyInfo>;
+    /**
+     * Store peer's ML-KEM public key in connection metadata
+     *
+     * This allows retrieving the peer's KEM key later for vault encryption.
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @param keyInfo - Peer's ML-KEM public key info
+     */
+    storePeerKemKey(agentContext: AgentContext, connectionId: string, keyInfo: KemPublicKeyInfo): Promise<void>;
+    /**
+     * Retrieve peer's ML-KEM public key from connection metadata
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns Peer's KEM key info, or null if not found
+     */
+    getPeerKemKey(agentContext: AgentContext, connectionId: string): Promise<KemPublicKeyInfo | null>;
+    /**
+     * Delete peer's ML-KEM public key from connection metadata
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     */
+    deletePeerKemKey(agentContext: AgentContext, connectionId: string): Promise<void>;
+    /**
+     * Check if a connection has a peer KEM key
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns True if peer has KEM key stored
+     */
+    hasPeerKemKey(agentContext: AgentContext, connectionId: string): Promise<boolean>;
+    /**
+     * Store a local KEM keypair (including secret key) for a connection
+     *
+     * Call this after generateKemKeypair() to persist the keypair so it can
+     * be retrieved later for vault decryption.
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection to associate the keypair with
+     * @param keypair - Full ML-KEM keypair
+     */
+    storeLocalKeypair(agentContext: AgentContext, connectionId: string, keypair: KemKeypairWithKid): Promise<void>;
+    /**
+     * Get the local KEM keypair for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns Full keypair including secret key, or null if not found
+     */
+    getLocalKeypair(agentContext: AgentContext, connectionId: string): Promise<KemKeypairWithKid | null>;
+    /**
+     * Find a local keypair by its key identifier (kid)
+     *
+     * This is the primary lookup used during vault decryption: extract recipient
+     * kids from vault header, then find which local keypair matches.
+     *
+     * @param agentContext - Agent context
+     * @param kid - Key identifier to search for
+     * @returns Keypair and associated connectionId, or null
+     */
+    findKeypairByKid(agentContext: AgentContext, kid: string): Promise<{
+        keypair: KemKeypairWithKid;
+        connectionId: string;
+    } | null>;
+    /**
+     * Find a local keypair matching any of the given recipient kids
+     *
+     * Used to find which local key can decrypt a vault when the vault header
+     * lists multiple possible recipients.
+     *
+     * @param agentContext - Agent context
+     * @param kids - Set of key identifiers from vault recipients
+     * @returns Matching keypair and connectionId, or null
+     */
+    findKeypairByRecipientKids(agentContext: AgentContext, kids: Set<string>): Promise<{
+        keypair: KemKeypairWithKid;
+        connectionId: string;
+    } | null>;
+    /**
+     * Check if a local keypair exists for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns True if local keypair exists
+     */
+    hasLocalKeypair(agentContext: AgentContext, connectionId: string): Promise<boolean>;
+    /**
+     * Delete the local keypair for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     */
+    deleteLocalKeypair(agentContext: AgentContext, connectionId: string): Promise<void>;
+}

package/build/services/KemKeyExchangeService.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * KEM Key Exchange Service
+ *
+ * Exchanges ML-KEM public keys between agents for quantum-safe vault encryption.
+ *
+ * Key Design:
+ * - Uses existing X25519 channel to bootstrap ML-KEM key exchange
+ * - Seals ML-KEM public keys in HPKE envelopes (RFC 9180)
+ * - Stores peer's ML-KEM keys in connection metadata
+ * - Uses signing protocol's provide-artifacts message (sealed-secret@1)
+ *
+ * Flow:
+ * 1. Agent A generates ML-KEM keypair
+ * 2. Agent A seals their ML-KEM public key using peer's X25519 key
+ * 3. Agent A sends sealed key via provide-artifacts message
+ * 4. Agent B unwraps the ML-KEM key using their X25519 private key
+ * 5. Agent B stores Agent A's ML-KEM key in connection metadata
+ * 6. Agent B can now encrypt vaults to Agent A's ML-KEM key
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KemKeyExchangeService = exports.KEM_KEY_METADATA_KEY = void 0;
+const core_1 = require("@credo-ts/core");
+const VaultCrypto_1 = require("../crypto/wasm/VaultCrypto");
+const HPKEService_1 = require("./HPKEService");
+const KemKeypairRepository_1 = require("../repository/KemKeypairRepository");
+const KemKeypairRecord_1 = require("../repository/KemKeypairRecord");
+/**
+ * Connection metadata key for ML-KEM keys
+ */
+exports.KEM_KEY_METADATA_KEY = 'vaults/kem-key';
+// ═══════════════════════════════════════════════════════════════════════════
+// Service
+// ═══════════════════════════════════════════════════════════════════════════
+let KemKeyExchangeService = class KemKeyExchangeService {
+    constructor(logger, connectionRepository, hpkeService, kemKeypairRepository) {
+        this.logger = logger;
+        this.connectionRepository = connectionRepository;
+        this.hpkeService = hpkeService;
+        this.kemKeypairRepository = kemKeypairRepository;
+    }
+    /**
+     * Generate a new ML-KEM-768 keypair
+     *
+     * @returns Keypair with derived key ID
+     */
+    generateKemKeypair() {
+        this.logger.debug('Generating ML-KEM-768 keypair');
+        const keypair = (0, VaultCrypto_1.kemGenerateKeypair)();
+        const kid = (0, VaultCrypto_1.deriveKid)(keypair.publicKey);
+        this.logger.debug(`Generated ML-KEM keypair with kid: ${kid.substring(0, 20)}...`);
+        return {
+            kid,
+            publicKey: keypair.publicKey,
+            secretKey: keypair.secretKey,
+        };
+    }
+    /**
+     * Create a sealed artifact containing our ML-KEM public key
+     *
+     * This creates an artifact suitable for sending via provide-artifacts message.
+     * The ML-KEM public key is sealed using HPKE (RFC 9180) to the recipient's P-256 public key.
+     *
+     * @param keypair - Our ML-KEM keypair
+     * @param recipientPublicKey - Recipient's P-256 public key for HPKE encryption
+     * @returns Sealed artifact ready for transmission
+     */
+    async createKemKeyArtifact(keypair, recipientPublicKey) {
+        this.logger.debug(`Creating sealed KEM key artifact for kid: ${keypair.kid.substring(0, 20)}...`);
+        // Prepare payload: { kid, publicKey }
+        const payload = JSON.stringify({
+            kid: keypair.kid,
+            publicKey: (0, VaultCrypto_1.toBase64Url)(keypair.publicKey),
+        });
+        const payloadBytes = new TextEncoder().encode(payload);
+        // Create AAD binding the artifact to the key ID
+        const aad = new TextEncoder().encode(`sealed-ml-kem-key:${keypair.kid}`);
+        // Encrypt using HPKE
+        const result = await this.hpkeService.encrypt(recipientPublicKey, payloadBytes, aad);
+        return {
+            type: 'sealed-ml-kem-key@1',
+            envelope: 'envelope-hpke@1',
+            ciphertext: (0, VaultCrypto_1.toBase64Url)(result.ciphertext),
+            ephemeralPublicKey: (0, VaultCrypto_1.toBase64Url)(result.ephemeralPublicKey),
+            kid: keypair.kid,
+        };
+    }
+    /**
+     * Unwrap a sealed KEM key artifact
+     *
+     * Decrypts the sealed artifact using HPKE to extract the peer's ML-KEM public key.
+     *
+     * @param artifact - Sealed artifact received from peer
+     * @param recipientSecretKey - Our P-256 private key to decrypt
+     * @returns Peer's ML-KEM public key info
+     */
+    async unwrapKemKeyArtifact(artifact, recipientSecretKey) {
+        this.logger.debug(`Unwrapping KEM key artifact: ${artifact.kid.substring(0, 20)}...`);
+        const ciphertext = (0, VaultCrypto_1.fromBase64Url)(artifact.ciphertext);
+        const ephemeralPublicKey = (0, VaultCrypto_1.fromBase64Url)(artifact.ephemeralPublicKey);
+        // Create AAD (must match encryption)
+        const aad = new TextEncoder().encode(`sealed-ml-kem-key:${artifact.kid}`);
+        // Decrypt using HPKE
+        const result = await this.hpkeService.decrypt(recipientSecretKey, ciphertext, ephemeralPublicKey, aad);
+        const payload = JSON.parse(new TextDecoder().decode(result.plaintext));
+        return {
+            kid: payload.kid,
+            publicKey: (0, VaultCrypto_1.fromBase64Url)(payload.publicKey),
+            storedAt: new Date().toISOString(),
+        };
+    }
+    /**
+     * Store peer's ML-KEM public key in connection metadata
+     *
+     * This allows retrieving the peer's KEM key later for vault encryption.
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @param keyInfo - Peer's ML-KEM public key info
+     */
+    async storePeerKemKey(agentContext, connectionId, keyInfo) {
+        this.logger.debug(`Storing peer KEM key for connection ${connectionId}: ${keyInfo.kid.substring(0, 20)}...`);
+        // Get connection record
+        const connection = await this.connectionRepository.getById(agentContext, connectionId);
+        // Store KEM key in metadata
+        const metadata = {
+            kid: keyInfo.kid,
+            publicKey: (0, VaultCrypto_1.toBase64Url)(keyInfo.publicKey),
+            storedAt: keyInfo.storedAt ?? new Date().toISOString(),
+        };
+        connection.metadata.set(exports.KEM_KEY_METADATA_KEY, metadata);
+        // Save connection
+        await this.connectionRepository.update(agentContext, connection);
+        this.logger.info(`Stored peer KEM key for connection ${connectionId}`);
+    }
+    /**
+     * Retrieve peer's ML-KEM public key from connection metadata
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns Peer's KEM key info, or null if not found
+     */
+    async getPeerKemKey(agentContext, connectionId) {
+        this.logger.debug(`Retrieving peer KEM key for connection ${connectionId}`);
+        // Get connection record
+        const connection = await this.connectionRepository.getById(agentContext, connectionId);
+        // Get KEM key from metadata
+        const metadata = connection.metadata.get(exports.KEM_KEY_METADATA_KEY);
+        if (!metadata) {
+            this.logger.debug(`No peer KEM key found for connection ${connectionId}`);
+            return null;
+        }
+        return {
+            kid: metadata.kid,
+            publicKey: (0, VaultCrypto_1.fromBase64Url)(metadata.publicKey),
+            storedAt: metadata.storedAt,
+        };
+    }
+    /**
+     * Delete peer's ML-KEM public key from connection metadata
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     */
+    async deletePeerKemKey(agentContext, connectionId) {
+        this.logger.debug(`Deleting peer KEM key for connection ${connectionId}`);
+        // Get connection record
+        const connection = await this.connectionRepository.getById(agentContext, connectionId);
+        // Delete KEM key from metadata
+        connection.metadata.delete(exports.KEM_KEY_METADATA_KEY);
+        // Save connection
+        await this.connectionRepository.update(agentContext, connection);
+        this.logger.info(`Deleted peer KEM key for connection ${connectionId}`);
+    }
+    /**
+     * Check if a connection has a peer KEM key
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns True if peer has KEM key stored
+     */
+    async hasPeerKemKey(agentContext, connectionId) {
+        const keyInfo = await this.getPeerKemKey(agentContext, connectionId);
+        return keyInfo !== null;
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Local Keypair Storage
+    // ═══════════════════════════════════════════════════════════════════════════
+    /**
+     * Store a local KEM keypair (including secret key) for a connection
+     *
+     * Call this after generateKemKeypair() to persist the keypair so it can
+     * be retrieved later for vault decryption.
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection to associate the keypair with
+     * @param keypair - Full ML-KEM keypair
+     */
+    async storeLocalKeypair(agentContext, connectionId, keypair) {
+        this.logger.debug(`Storing local KEM keypair for connection ${connectionId}: kid=${keypair.kid.substring(0, 20)}...`);
+        // Check for existing keypair on this connection
+        const existing = await this.kemKeypairRepository.findByConnectionId(agentContext, connectionId);
+        if (existing) {
+            this.logger.debug(`Updating existing keypair for connection ${connectionId}`);
+            existing.kid = keypair.kid;
+            existing.publicKey = (0, VaultCrypto_1.toBase64Url)(keypair.publicKey);
+            existing.secretKey = (0, VaultCrypto_1.toBase64Url)(keypair.secretKey);
+            await this.kemKeypairRepository.update(agentContext, existing);
+            return;
+        }
+        const record = new KemKeypairRecord_1.KemKeypairRecord({
+            connectionId,
+            kid: keypair.kid,
+            publicKey: (0, VaultCrypto_1.toBase64Url)(keypair.publicKey),
+            secretKey: (0, VaultCrypto_1.toBase64Url)(keypair.secretKey),
+        });
+        await this.kemKeypairRepository.save(agentContext, record);
+        this.logger.info(`Stored local KEM keypair for connection ${connectionId}`);
+    }
+    /**
+     * Get the local KEM keypair for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns Full keypair including secret key, or null if not found
+     */
+    async getLocalKeypair(agentContext, connectionId) {
+        const record = await this.kemKeypairRepository.findByConnectionId(agentContext, connectionId);
+        if (!record) {
+            return null;
+        }
+        return {
+            kid: record.kid,
+            publicKey: (0, VaultCrypto_1.fromBase64Url)(record.publicKey),
+            secretKey: (0, VaultCrypto_1.fromBase64Url)(record.secretKey),
+        };
+    }
+    /**
+     * Find a local keypair by its key identifier (kid)
+     *
+     * This is the primary lookup used during vault decryption: extract recipient
+     * kids from vault header, then find which local keypair matches.
+     *
+     * @param agentContext - Agent context
+     * @param kid - Key identifier to search for
+     * @returns Keypair and associated connectionId, or null
+     */
+    async findKeypairByKid(agentContext, kid) {
+        const record = await this.kemKeypairRepository.findByKid(agentContext, kid);
+        if (!record) {
+            return null;
+        }
+        return {
+            keypair: {
+                kid: record.kid,
+                publicKey: (0, VaultCrypto_1.fromBase64Url)(record.publicKey),
+                secretKey: (0, VaultCrypto_1.fromBase64Url)(record.secretKey),
+            },
+            connectionId: record.connectionId,
+        };
+    }
+    /**
+     * Find a local keypair matching any of the given recipient kids
+     *
+     * Used to find which local key can decrypt a vault when the vault header
+     * lists multiple possible recipients.
+     *
+     * @param agentContext - Agent context
+     * @param kids - Set of key identifiers from vault recipients
+     * @returns Matching keypair and connectionId, or null
+     */
+    async findKeypairByRecipientKids(agentContext, kids) {
+        for (const kid of kids) {
+            const result = await this.findKeypairByKid(agentContext, kid);
+            if (result) {
+                return result;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a local keypair exists for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     * @returns True if local keypair exists
+     */
+    async hasLocalKeypair(agentContext, connectionId) {
+        const record = await this.kemKeypairRepository.findByConnectionId(agentContext, connectionId);
+        return record !== null;
+    }
+    /**
+     * Delete the local keypair for a connection
+     *
+     * @param agentContext - Agent context
+     * @param connectionId - Connection record ID
+     */
+    async deleteLocalKeypair(agentContext, connectionId) {
+        await this.kemKeypairRepository.deleteByConnectionId(agentContext, connectionId);
+        this.logger.info(`Deleted local KEM keypair for connection ${connectionId}`);
+    }
+};
+exports.KemKeyExchangeService = KemKeyExchangeService;
+exports.KemKeyExchangeService = KemKeyExchangeService = __decorate([
+    (0, core_1.injectable)(),
+    __param(0, (0, core_1.inject)(core_1.InjectionSymbols.Logger)),
+    __metadata("design:paramtypes", [Object, core_1.ConnectionRepository,
+        HPKEService_1.HPKEService,
+        KemKeypairRepository_1.KemKeypairRepository])
+], KemKeyExchangeService);
+//# sourceMappingURL=KemKeyExchangeService.js.map

package/build/services/KemKeyExchangeService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KemKeyExchangeService.js","sourceRoot":"","sources":["../../src/services/KemKeyExchangeService.ts"],"names":[],"mappings":"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"}