@ajna-inc/vaults 0.1.0 → 0.1.2

package/build/services/VaultSigningService.d.ts

@@ -0,0 +1,216 @@
+import type { AgentContext } from '@credo-ts/core';
+import type { VaultHeader } from '../models';
+import type { VaultStorageReference } from '../repository/VaultRecord';
+import { ConnectionRepository, EventEmitter, MessageSender } from '@credo-ts/core';
+import type { Logger } from '@credo-ts/core';
+import { VaultEncryptionService } from './VaultEncryptionService';
+import { KemKeyExchangeService } from './KemKeyExchangeService';
+import { VaultStorageService } from '../storage/VaultStorageService';
+import { VaultRepository } from '../repository/VaultRepository';
+import { VaultRecord } from '../repository/VaultRecord';
+import { StoreVaultMessage, VaultDataMessage } from '../messages';
+export interface CreateSigningVaultOptions {
+    /** Document to encrypt for signing */
+    document: Uint8Array;
+    /** Connection ID of the signer */
+    signerConnectionId: string;
+    /** Document type hint */
+    documentType: 'pdf' | 'json' | 'xml' | 'other';
+    /** Optional vault ID */
+    vaultId?: string;
+    /** Optional metadata */
+    metadata?: {
+        description?: string;
+        filename?: string;
+        tags?: string[];
+    };
+    /** Force use of external storage even for small files */
+    forceExternalStorage?: boolean;
+    /** Custom inline threshold (bytes) - files larger than this use external storage */
+    inlineThreshold?: number;
+}
+export interface SigningVaultResult {
+    vaultId: string;
+    docId: string;
+    /** The vault record for local storage */
+    record: VaultRecord;
+    /** Storage reference if using external storage */
+    storageReference?: VaultStorageReference;
+    /** Whether external storage was used */
+    usedExternalStorage: boolean;
+}
+export interface OpenSigningVaultResult {
+    /** Decrypted document */
+    document: Uint8Array;
+    /** Vault metadata */
+    header: VaultHeader;
+    /** Document type if present */
+    documentType?: string;
+}
+export interface ReturnSignedDocumentOptions {
+    /** Signed document bytes */
+    signedDocument: Uint8Array;
+    /** Original vault ID this is a response to */
+    originalVaultId: string;
+    /** Connection ID of the vault owner */
+    ownerConnectionId: string;
+    /** Document type */
+    documentType: 'pdf' | 'json' | 'xml' | 'other';
+    /** Optional metadata */
+    metadata?: {
+        signatureType?: string;
+        signedAt?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Vault Signing Service
+ *
+ * Orchestrates vault operations for document signing workflows:
+ * - Create vaults encrypted to signer's ML-KEM key
+ * - Open vaults received for signing
+ * - Return signed documents via encrypted vault
+ *
+ * Flow:
+ * 1. Alice creates signing vault encrypted to Bob's ML-KEM key
+ * 2. Alice sends vault reference to Bob
+ * 3. Bob retrieves and decrypts vault
+ * 4. Bob signs document
+ * 5. Bob creates response vault encrypted to Alice's ML-KEM key
+ * 6. Bob sends signed document back to Alice
+ */
+export declare class VaultSigningService {
+    private encryptionService;
+    private kemKeyExchangeService;
+    private vaultRepository;
+    private connectionRepository;
+    private eventEmitter;
+    private messageSender;
+    private logger;
+    private storageService?;
+    constructor(logger: Logger, encryptionService: VaultEncryptionService, kemKeyExchangeService: KemKeyExchangeService, vaultRepository: VaultRepository, connectionRepository: ConnectionRepository, eventEmitter: EventEmitter, messageSender: MessageSender);
+    /**
+     * Set the storage service for large file support
+     */
+    setStorageService(storageService: VaultStorageService): void;
+    /**
+     * Check if external storage is available
+     */
+    hasExternalStorage(): boolean;
+    /**
+     * Create a vault encrypted to a signer's ML-KEM public key
+     *
+     * @param agentContext - Agent context
+     * @param options - Creation options
+     * @returns Created vault identifiers
+     *
+     * @example
+     * ```typescript
+     * const { vaultId } = await vaultSigningService.createSigningVault(agentContext, {
+     *   document: pdfBytes,
+     *   signerConnectionId: bobConnectionId,
+     *   documentType: 'pdf',
+     *   metadata: { description: 'Contract for signing' }
+     * })
+     * ```
+     */
+    createSigningVault(agentContext: AgentContext, options: CreateSigningVaultOptions): Promise<SigningVaultResult>;
+    /**
+     * Open (decrypt) a vault received for signing
+     *
+     * Uses the agent's own ML-KEM secret key to decrypt
+     *
+     * @param agentContext - Agent context
+     * @param vaultData - Received vault data message or vault record
+     * @param secretKey - ML-KEM secret key to decrypt with
+     * @param kid - Key identifier
+     * @returns Decrypted document and metadata
+     *
+     * @example
+     * ```typescript
+     * const { document, header } = await vaultSigningService.openSigningVault(
+     *   agentContext,
+     *   vaultData,
+     *   myKemKeypair.secretKey,
+     *   myKemKeypair.kid
+     * )
+     * // Now sign the document
+     * const signedPdf = await signPdf(document)
+     * ```
+     */
+    openSigningVault(agentContext: AgentContext, vaultData: VaultDataMessage | VaultRecord, secretKey: Uint8Array, kid: string): Promise<OpenSigningVaultResult>;
+    /**
+     * Share a signing vault with a connection
+     *
+     * Sends the vault data to the specified connection
+     *
+     * @param agentContext - Agent context
+     * @param vaultId - Vault to share
+     * @param connectionId - Connection to send to
+     */
+    shareSigningVault(agentContext: AgentContext, vaultId: string, connectionId: string, options?: {
+        /** Include pre-signed download URL for recipient */
+        includeDownloadUrl?: boolean;
+        /** Download URL expiration in seconds */
+        downloadUrlExpiry?: number;
+    }): Promise<void>;
+    /**
+     * Return a signed document to the original vault owner
+     *
+     * Creates a new vault with the signed document encrypted to the owner's ML-KEM key
+     *
+     * @param agentContext - Agent context
+     * @param options - Return options
+     * @returns New vault containing signed document
+     *
+     * @example
+     * ```typescript
+     * await vaultSigningService.returnSignedDocument(agentContext, {
+     *   signedDocument: signedPdfBytes,
+     *   originalVaultId: receivedVaultId,
+     *   ownerConnectionId: aliceConnectionId,
+     *   documentType: 'pdf',
+     *   metadata: { signatureType: 'pades-b-lta' }
+     * })
+     * ```
+     */
+    returnSignedDocument(agentContext: AgentContext, options: ReturnSignedDocumentOptions): Promise<SigningVaultResult>;
+    /**
+     * Store a received signing vault locally
+     *
+     * Called when receiving a vault for signing from another agent
+     *
+     * @param agentContext - Agent context
+     * @param message - Received vault message
+     * @param senderConnectionId - Connection that sent the vault
+     * @returns Stored vault record
+     */
+    storeReceivedSigningVault(agentContext: AgentContext, message: StoreVaultMessage | VaultDataMessage, senderConnectionId: string): Promise<VaultRecord>;
+    /**
+     * Resolve the decryption key for a vault
+     *
+     * Implements the unified KEM key resolution strategy:
+     * 1. Extract recipient kids from vault header
+     * 2. Search local KEM keypairs for a matching kid (works for both received and owned vaults)
+     * 3. Fall back to connection-based lookup via signerConnectionId metadata
+     *
+     * @param agentContext - Agent context
+     * @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 vaultSigningService.resolveVaultDecryptionKey(agentContext, vaultId)
+     * if (key) {
+     *   const { document } = await vaultSigningService.openSigningVault(
+     *     agentContext, vaultRecord, key.secretKey, key.kid
+     *   )
+     * }
+     * ```
+     */
+    resolveVaultDecryptionKey(agentContext: AgentContext, vaultId: string): Promise<{
+        secretKey: Uint8Array;
+        kid: string;
+        connectionId: string;
+    } | null>;
+}