@ajna-inc/vaults 0.1.0 → 0.1.2

package/build/services/VaultEncryptionService.d.ts

@@ -0,0 +1,120 @@
+import type { AeadAlgorithm } from '../models';
+import type { VaultDocument } from '../models/VaultDocument';
+export interface EncryptS3Options {
+    docId?: string;
+    vaultId?: string;
+    epoch?: number;
+    memory?: number;
+    iterations?: number;
+    aead?: AeadAlgorithm;
+}
+export interface EncryptP1Options {
+    docId?: string;
+    vaultId?: string;
+}
+export interface RecipientKey {
+    kid: string;
+    publicKey: Uint8Array;
+}
+export interface DecryptedShare {
+    index: number;
+    share: Uint8Array;
+}
+/**
+ * Vault Encryption Service
+ *
+ * Provides client-side encryption/decryption for all vault policy modes:
+ * - S3 suite: Passphrase-based (Argon2id → AES-256-GCM)
+ * - P1 suite: Post-quantum (ML-KEM-768 → AES-256-GCM)
+ *
+ * All encryption and decryption happens client-side per ZK-Vault spec.
+ */
+export declare class VaultEncryptionService {
+    /**
+     * Encrypt data with passphrase (S3 suite)
+     * All encryption happens CLIENT-SIDE
+     *
+     * @param plaintext - Data to encrypt
+     * @param passphrase - User passphrase
+     * @param options - Encryption options
+     * @returns Encrypted vault document
+     */
+    encryptWithPassphrase(plaintext: Uint8Array, passphrase: string, options?: EncryptS3Options): Promise<VaultDocument>;
+    /**
+     * Decrypt passphrase-protected vault (S3 suite)
+     * All decryption happens CLIENT-SIDE
+     *
+     * @param vault - Encrypted vault document
+     * @param passphrase - User passphrase
+     * @returns Decrypted plaintext
+     */
+    decryptWithPassphrase(vault: VaultDocument, passphrase: string): Promise<Uint8Array>;
+    /**
+     * Encrypt with any-of policy (spec §6.1)
+     * Each recipient gets their own KEM-wrapped CEK
+     *
+     * @param plaintext - Data to encrypt
+     * @param recipients - Array of recipient public keys
+     * @param options - Encryption options
+     * @returns Encrypted vault document
+     */
+    encryptAnyOf(plaintext: Uint8Array, recipients: RecipientKey[], options?: EncryptP1Options): Promise<VaultDocument>;
+    /**
+     * Decrypt any-of vault (spec §9.2)
+     * Try the specified recipient's wrap
+     *
+     * @param vault - Encrypted vault document
+     * @param recipientSecretKey - Recipient's ML-KEM secret key
+     * @param recipientKid - Recipient's key identifier
+     * @returns Decrypted plaintext
+     */
+    decryptAnyOf(vault: VaultDocument, recipientSecretKey: Uint8Array, recipientKid: string): Promise<Uint8Array>;
+    /**
+     * Encrypt with all-of policy (spec §6.2)
+     * Requires ALL listed keys to decrypt via HKDF-join
+     *
+     * @param plaintext - Data to encrypt
+     * @param participants - Array of participant public keys
+     * @param options - Encryption options
+     * @returns Encrypted vault document
+     */
+    encryptAllOf(plaintext: Uint8Array, participants: RecipientKey[], options?: EncryptP1Options): Promise<VaultDocument>;
+    /**
+     * Encrypt with threshold policy (spec §6.3)
+     * Any t-of-n participants can decrypt
+     *
+     * @param plaintext - Data to encrypt
+     * @param threshold - Minimum shares required (t)
+     * @param participants - Array of participant public keys (n)
+     * @param options - Encryption options
+     * @returns Encrypted vault document
+     */
+    encryptThreshold(plaintext: Uint8Array, threshold: number, participants: RecipientKey[], options?: EncryptP1Options): Promise<VaultDocument>;
+    /**
+     * Decrypt threshold vault with collected shares
+     *
+     * @param vault - Encrypted vault document
+     * @param decryptedShares - Array of decrypted shares (at least t shares)
+     * @returns Decrypted plaintext
+     */
+    decryptThreshold(vault: VaultDocument, decryptedShares: DecryptedShare[]): Promise<Uint8Array>;
+    /**
+     * Unwrap a single threshold share for a participant
+     *
+     * @param vault - Encrypted vault document
+     * @param participantSecretKey - Participant's ML-KEM secret key
+     * @param participantKid - Participant's key identifier
+     * @returns Decrypted share with its index
+     */
+    unwrapThresholdShare(vault: VaultDocument, participantSecretKey: Uint8Array, participantKid: string): Promise<DecryptedShare>;
+    /**
+     * Derive key from passphrase using Argon2id
+     * Spec §4.1 S1/S3 suite
+     */
+    private deriveKeyArgon2;
+    /**
+     * Zero out sensitive data from memory
+     * Security best practice to minimize exposure window
+     */
+    private zeroize;
+}