@ajna-inc/vaults 0.1.0 → 0.1.2

package/build/VaultsApi.d.ts

@@ -0,0 +1,363 @@
+import type { VaultRecord } from './repository/VaultRecord';
+import type { KemKeypairWithKid } from './services/KemKeyExchangeService';
+import type { VaultInfo, CreateVaultOptions, OpenVaultOptions, UpdateVaultOptions } from './services/VaultService';
+import type { CreateSigningVaultOptions, SigningVaultResult, OpenSigningVaultResult, ReturnSignedDocumentOptions } from './services/VaultSigningService';
+import type { Logger } from '@credo-ts/core';
+import type { S3StorageConfig } from './storage/VaultStorageConfig';
+import { AgentContext, MessageHandlerRegistry, EventEmitter } from '@credo-ts/core';
+import { VaultService } from './services/VaultService';
+import { KemKeyExchangeService } from './services/KemKeyExchangeService';
+import { VaultSigningService } from './services/VaultSigningService';
+import { VaultStorageService } from './storage/VaultStorageService';
+import { VaultRepository } from './repository/VaultRepository';
+import { ThresholdSessionRepository } from './repository/ThresholdSessionRepository';
+import { VaultDataMessage } from './messages';
+/**
+ * Vaults API
+ *
+ * Public API for vault operations.
+ * Provides a clean interface for creating, opening, and managing encrypted vaults.
+ *
+ * All encryption and decryption happens client-side.
+ */
+export declare class VaultsApi {
+    private vaultService;
+    private agentContext;
+    private logger;
+    private kemKeyExchangeService;
+    private vaultSigningService;
+    private storageService;
+    constructor(agentContext: AgentContext, messageHandlerRegistry: MessageHandlerRegistry, eventEmitter: EventEmitter, logger: Logger, vaultService: VaultService, kemKeyExchangeService: KemKeyExchangeService, vaultSigningService: VaultSigningService, storageService: VaultStorageService, vaultRepository: VaultRepository, thresholdSessionRepository: ThresholdSessionRepository);
+    private registerMessageHandlers;
+    /**
+     * Configure external storage (S3) for large file support
+     *
+     * @param config - S3 storage configuration
+     *
+     * @example
+     * ```typescript
+     * await agent.modules.vaults.configureStorage({
+     *   type: 's3',
+     *   bucket: 'my-vault-bucket',
+     *   region: 'us-east-1',
+     *   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+     *   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+     * })
+     * ```
+     */
+    configureStorage(config: S3StorageConfig): Promise<void>;
+    /**
+     * Check if external storage is configured
+     */
+    isStorageConfigured(): boolean;
+    /**
+     * Get the storage service for direct operations
+     */
+    getStorageService(): VaultStorageService;
+    /**
+     * Create a new encrypted vault
+     *
+     * @param data - Raw data to encrypt (e.g., PDF bytes)
+     * @param options - Creation options including passphrase
+     * @returns Created vault identifiers
+     *
+     * @example
+     * ```typescript
+     * const pdfBytes = await fs.readFile('contract.pdf')
+     * const { vaultId } = await agent.modules.vaults.create(pdfBytes, {
+     *   passphrase: 'my-secure-passphrase',
+     *   metadata: { description: 'Employment Contract' }
+     * })
+     * ```
+     */
+    create(data: Uint8Array, options: CreateVaultOptions): Promise<{
+        vaultId: string;
+        docId: string;
+    }>;
+    /**
+     * Open (decrypt) a vault
+     *
+     * @param vaultId - Vault identifier
+     * @param options - Open options including passphrase
+     * @returns Decrypted data
+     *
+     * @example
+     * ```typescript
+     * const decrypted = await agent.modules.vaults.open(vaultId, {
+     *   passphrase: 'my-secure-passphrase'
+     * })
+     * await fs.writeFile('contract-decrypted.pdf', decrypted)
+     * ```
+     */
+    open(vaultId: string, options: OpenVaultOptions): Promise<Uint8Array>;
+    /**
+     * Update vault with new data
+     *
+     * @param vaultId - Vault identifier
+     * @param data - New data to encrypt
+     * @param options - Update options including passphrase
+     *
+     * @example
+     * ```typescript
+     * const newPdfBytes = await fs.readFile('contract-v2.pdf')
+     * await agent.modules.vaults.update(vaultId, newPdfBytes, {
+     *   passphrase: 'my-secure-passphrase'
+     * })
+     * ```
+     */
+    update(vaultId: string, data: Uint8Array, options: UpdateVaultOptions): Promise<void>;
+    /**
+     * Delete a vault
+     *
+     * @param vaultId - Vault identifier
+     *
+     * @example
+     * ```typescript
+     * await agent.modules.vaults.delete(vaultId)
+     * ```
+     */
+    delete(vaultId: string): Promise<void>;
+    /**
+     * List all vaults
+     *
+     * @returns Array of vault records
+     *
+     * @example
+     * ```typescript
+     * const vaults = await agent.modules.vaults.list()
+     * console.log(`Total vaults: ${vaults.length}`)
+     * ```
+     */
+    list(): Promise<VaultRecord[]>;
+    /**
+     * Get vault info (metadata without decrypting)
+     *
+     * @param vaultId - Vault identifier
+     * @returns Vault information
+     *
+     * @example
+     * ```typescript
+     * const info = await agent.modules.vaults.getInfo(vaultId)
+     * console.log(`Vault: ${info.vaultId}, Epoch: ${info.header.epoch}`)
+     * ```
+     */
+    getInfo(vaultId: string): Promise<VaultInfo>;
+    /**
+     * Check if a vault exists
+     *
+     * @param vaultId - Vault identifier
+     * @returns True if vault exists
+     *
+     * @example
+     * ```typescript
+     * if (await agent.modules.vaults.exists(vaultId)) {
+     *   console.log('Vault found!')
+     * }
+     * ```
+     */
+    exists(vaultId: string): Promise<boolean>;
+    /**
+     * Get the raw vault record (for advanced operations)
+     *
+     * @param vaultId - Vault identifier
+     * @returns Vault record or null
+     */
+    getRecord(vaultId: string): Promise<VaultRecord | null>;
+    /**
+     * Generate a new ML-KEM keypair for vault sharing
+     *
+     * @returns Keypair with key ID
+     *
+     * @example
+     * ```typescript
+     * const keypair = agent.modules.vaults.generateKemKeypair()
+     * console.log(`Generated KEM key: ${keypair.kid}`)
+     * ```
+     */
+    generateKemKeypair(): KemKeypairWithKid;
+    /**
+     * Store peer's ML-KEM public key for vault encryption
+     *
+     * @param connectionId - Connection to associate the key with
+     * @param kid - Key identifier
+     * @param publicKey - ML-KEM public key
+     *
+     * @example
+     * ```typescript
+     * await agent.modules.vaults.storePeerKemKey(connectionId, {
+     *   kid: 'peer-key-id',
+     *   publicKey: peerPublicKey
+     * })
+     * ```
+     */
+    storePeerKemKey(connectionId: string, keyInfo: {
+        kid: string;
+        publicKey: Uint8Array;
+    }): Promise<void>;
+    /**
+     * Get peer's ML-KEM public key
+     *
+     * @param connectionId - Connection ID
+     * @returns Peer's key info or null
+     *
+     * @example
+     * ```typescript
+     * const peerKey = await agent.modules.vaults.getPeerKemKey(connectionId)
+     * if (peerKey) {
+     *   // Can now create vault encrypted to peer
+     * }
+     * ```
+     */
+    getPeerKemKey(connectionId: string): Promise<import("./services/KemKeyExchangeService").KemPublicKeyInfo | null>;
+    /**
+     * Check if peer has a KEM key stored
+     *
+     * @param connectionId - Connection ID
+     * @returns True if peer has KEM key
+     */
+    hasPeerKemKey(connectionId: string): Promise<boolean>;
+    /**
+     * Store a local KEM keypair for a connection
+     *
+     * Call this after generateKemKeypair() to persist the keypair locally
+     * for later vault decryption.
+     *
+     * @param connectionId - Connection to associate the keypair with
+     * @param keypair - Full keypair including secret key
+     */
+    storeLocalKeypair(connectionId: string, keypair: KemKeypairWithKid): Promise<void>;
+    /**
+     * Get the local KEM keypair for a connection
+     *
+     * @param connectionId - Connection ID
+     * @returns Full keypair or null
+     */
+    getLocalKeypair(connectionId: string): Promise<KemKeypairWithKid | null>;
+    /**
+     * Check if a local keypair exists for a connection
+     *
+     * @param connectionId - Connection ID
+     * @returns True if local keypair exists
+     */
+    hasLocalKeypair(connectionId: string): Promise<boolean>;
+    /**
+     * Find a local keypair by key identifier (kid)
+     *
+     * @param kid - Key identifier to search for
+     * @returns Keypair and associated connectionId, or null
+     */
+    findKeypairByKid(kid: string): Promise<{
+        keypair: KemKeypairWithKid;
+        connectionId: string;
+    } | null>;
+    /**
+     * Delete the local keypair for a connection
+     *
+     * @param connectionId - Connection ID
+     */
+    deleteLocalKeypair(connectionId: string): Promise<void>;
+    /**
+     * Create a signing vault encrypted to a signer's ML-KEM key
+     *
+     * Use this to send a document to someone for signing.
+     * The document is encrypted so only the intended signer can decrypt it.
+     *
+     * @param options - Creation options
+     * @returns Created vault identifiers
+     *
+     * @example
+     * ```typescript
+     * // Create vault for Bob to sign
+     * const { vaultId } = await agent.modules.vaults.createSigningVault({
+     *   document: pdfBytes,
+     *   signerConnectionId: bobConnectionId,
+     *   documentType: 'pdf',
+     *   metadata: { description: 'Contract for signing' }
+     * })
+     *
+     * // Share with Bob
+     * await agent.modules.vaults.shareSigningVault(vaultId, bobConnectionId)
+     * ```
+     */
+    createSigningVault(options: CreateSigningVaultOptions): Promise<SigningVaultResult>;
+    /**
+     * Open (decrypt) a vault received for signing
+     *
+     * @param vaultData - Received vault data (message or record)
+     * @param secretKey - Your ML-KEM secret key
+     * @param kid - Your key identifier
+     * @returns Decrypted document and metadata
+     *
+     * @example
+     * ```typescript
+     * // Decrypt vault received for signing
+     * const { document, header } = await agent.modules.vaults.openSigningVault(
+     *   vaultRecord,
+     *   myKemKeypair.secretKey,
+     *   myKemKeypair.kid
+     * )
+     *
+     * // Sign the document
+     * const signedPdf = await signPdf(document)
+     * ```
+     */
+    openSigningVault(vaultData: VaultDataMessage | VaultRecord, secretKey: Uint8Array, kid: string): Promise<OpenSigningVaultResult>;
+    /**
+     * Share a signing vault with a connection
+     *
+     * Sends the encrypted vault to the specified connection via DIDComm
+     *
+     * @param vaultId - Vault to share
+     * @param connectionId - Connection to send to
+     *
+     * @example
+     * ```typescript
+     * await agent.modules.vaults.shareSigningVault(vaultId, bobConnectionId)
+     * ```
+     */
+    shareSigningVault(vaultId: string, connectionId: string): Promise<void>;
+    /**
+     * Return a signed document to the vault owner
+     *
+     * Creates a new vault with the signed document encrypted to the owner's key
+     *
+     * @param options - Return options
+     * @returns New vault containing the signed document
+     *
+     * @example
+     * ```typescript
+     * await agent.modules.vaults.returnSignedDocument({
+     *   signedDocument: signedPdfBytes,
+     *   originalVaultId: receivedVaultId,
+     *   ownerConnectionId: aliceConnectionId,
+     *   documentType: 'pdf',
+     *   metadata: { signatureType: 'pades-b-lta' }
+     * })
+     * ```
+     */
+    returnSignedDocument(options: ReturnSignedDocumentOptions): Promise<SigningVaultResult>;
+    /**
+     * Resolve the decryption key for a vault
+     *
+     * Automatically finds the correct local KEM keypair that can decrypt
+     * the specified vault by matching recipient kids in the vault header.
+     *
+     * @param vaultId - Vault to find decryption key for
+     * @returns Secret key, kid, and connectionId; or null if no matching key found
+     *
+     * @example
+     * ```typescript
+     * const key = await agent.modules.vaults.resolveVaultDecryptionKey(vaultId)
+     * if (key) {
+     *   const { document } = await agent.modules.vaults.openSigningVault(
+     *     vaultRecord, key.secretKey, key.kid
+     *   )
+     * }
+     * ```
+     */
+    resolveVaultDecryptionKey(vaultId: string): Promise<{
+        secretKey: Uint8Array;
+        kid: string;
+        connectionId: string;
+    } | null>;
+}