@brightchain/brightchain-api-lib 0.14.0 → 0.15.0

package/src/lib/services/brightpass.d.ts

@@ -0,0 +1,294 @@
+/**
+ * BrightPassService — core vault operations for the BrightPass password manager.
+ *
+ * Manages vault lifecycle (create, open, list, delete), entry CRUD,
+ * search, sharing, emergency access, and import operations.
+ *
+ * Uses IBlockStore for persistent storage, VCBLService for VCBL operations,
+ * BlockService for encryption, and maintains a lightweight in-memory index
+ * for quick lookups.
+ *
+ * Requirements: 1.1–1.8, 2.1–2.9, 3.1–3.5, 4.1–4.4
+ */
+import { AttachmentReference, AuditLogEntry, AutofillPayload, BlockService, DecryptedVault, EmergencyAccessConfig, EncryptedShare, EntryPropertyRecord, EntrySearchQuery, IBlockStore, ImportFormat, ImportResult, VaultEntry, VaultMetadata, VCBLService } from '@brightchain/brightchain-lib';
+import { Member, PlatformID } from '@digitaldefiance/ecies-lib';
+/**
+ * Errors specific to BrightPass operations
+ */
+export declare class VaultNotFoundError extends Error {
+    constructor(vaultId: string);
+}
+export declare class VaultAuthenticationError extends Error {
+    constructor();
+}
+export declare class VaultConflictError extends Error {
+    constructor(name: string);
+}
+export declare class EntryNotFoundError extends Error {
+    constructor(entryId: string);
+}
+export declare class EmergencyAccessError extends Error {
+    constructor(message: string);
+}
+export declare class BrightPassService<TID extends PlatformID = Uint8Array> {
+    /** Block store for persistent storage (injected) */
+    private readonly blockStore;
+    /** VCBL service for vault operations (injected) */
+    private readonly vcblService;
+    /** Block service for encryption/decryption (injected) */
+    private readonly blockService;
+    /** Member for block creation (injected) */
+    private readonly member;
+    /** vaultId → StoredVault for vault data management */
+    private readonly vaults;
+    /** vaultId → VaultIndexEntry for lightweight lookups */
+    private readonly vaultIndex;
+    /** memberId → Set<vaultId> for quick listing */
+    private readonly memberVaults;
+    /**
+     * Create a new BrightPassService.
+     *
+     * @param blockStore - Block store for persistent storage (defaults to MemoryBlockStore)
+     * @param vcblService - VCBL service for vault operations
+     * @param blockService - Block service for encryption
+     * @param member - Member for block creation
+     *
+     * Requirements: 1.1, 1.5
+     */
+    constructor(blockStore?: IBlockStore, vcblService?: VCBLService<TID>, blockService?: BlockService<TID>, member?: Member<TID>);
+    /** bcrypt cost factor - 12 rounds provides ~300ms hash time on modern hardware */
+    private static readonly BCRYPT_ROUNDS;
+    /**
+     * Hash a master password using bcrypt for secure storage and comparison.
+     * Uses bcrypt with 12 rounds for strong protection against brute-force attacks.
+     *
+     * Security: bcrypt includes salt automatically and is designed to be slow,
+     * making brute-force attacks computationally expensive.
+     */
+    private hashMasterPasswordAsync;
+    /**
+     * Verify a master password against a stored bcrypt hash.
+     * Uses constant-time comparison internally via bcrypt.compare().
+     */
+    private verifyMasterPassword;
+    /**
+     * Generate a new BIP39 mnemonic and seed for a vault.
+     * Each vault has its own independent mnemonic that can be cycled/regenerated.
+     *
+     * Security: Uses 256 bits of entropy for a 24-word mnemonic.
+     * The mnemonic should be stored encrypted and can be backed up separately.
+     *
+     * @returns Object containing the mnemonic (24 words) and derived seed (64 bytes)
+     */
+    private generateVaultBip39;
+    /**
+     * Regenerate a vault's BIP39 seed (key rotation).
+     * This creates a new mnemonic and re-encrypts all entries with the new key.
+     *
+     * Security: This is a critical operation that should be used when:
+     * - A share has been revoked and the vault needs re-keying
+     * - The vault owner suspects key compromise
+     * - Periodic key rotation policy requires it
+     *
+     * @param vaultId - The vault to regenerate
+     * @param masterPassword - Current master password for verification
+     * @returns The new mnemonic (should be backed up by the user)
+     */
+    regenerateVaultSeed(vaultId: string, masterPassword: string): Promise<string>;
+    /**
+     * Extract an EntryPropertyRecord from a VaultEntry.
+     */
+    private entryToPropertyRecord;
+    /**
+     * Check if block store operations are safe to perform.
+     * Block store operations require the global service provider to be initialized.
+     * Returns false if the service provider is not available.
+     */
+    private isBlockStoreOperationsSafe;
+    /**
+     * Get a vault or throw VaultNotFoundError.
+     */
+    private getVaultOrThrow;
+    /**
+     * Update the VCBL in the block store after entry changes.
+     * Creates a new VCBL with updated property records and entry addresses,
+     * encrypts it, and stores it in the block store.
+     * Requirements: 2.2, 2.3, 2.4, 3.2
+     */
+    private updateVcblInBlockStore;
+    /**
+     * Create a new vault.
+     * Generates a vault-specific BIP39 mnemonic and derives the vault key from it.
+     * Uses bcrypt for secure password hashing.
+     *
+     * Security: Each vault has its own independent BIP39 seed that can be
+     * regenerated/cycled without affecting other vaults or the member's identity.
+     *
+     * Requirements: 1.1, 3.1, 3.2
+     */
+    createVault(memberId: string, name: string, masterPassword: string): Promise<VaultMetadata>;
+    /**
+     * Open an existing vault with the correct master password.
+     * Returns vault metadata and property records (no entry decryption).
+     * When VCBLService is available, retrieves and parses VCBL from block store.
+     * Requirements: 1.2, 1.3, 3.3, 3.4
+     */
+    openVault(memberId: string, vaultId: string, masterPassword: string): Promise<DecryptedVault>;
+    /**
+     * List all vaults owned by or shared with a member.
+     * Returns metadata only — no decryption needed.
+     * Requirements: 1.4
+     */
+    listVaults(memberId: string): Promise<VaultMetadata[]>;
+    /**
+     * Delete a vault and all its entries.
+     * Requirements: 1.5
+     */
+    deleteVault(memberId: string, vaultId: string, masterPassword: string): Promise<void>;
+    /**
+     * Add a new entry to a vault.
+     * Encrypts the entry using AES-256-GCM, stores in block store (when available),
+     * and appends block checksum + property record to VCBL parallel arrays.
+     * Requirements: 2.1, 2.2, 3.2
+     */
+    addEntry(vaultId: string, entry: VaultEntry): Promise<VaultEntry>;
+    /**
+     * Get a single entry by ID from a vault.
+     * Retrieves from block store and decrypts the entry using AES-256-GCM.
+     * Requirements: 2.2, 2.3, 3.2
+     */
+    getEntry(vaultId: string, entryId: string): Promise<VaultEntry>;
+    /**
+     * Update an existing entry in a vault.
+     * Decrypts, updates, re-encrypts using AES-256-GCM, stores in block store (when available),
+     * and updates the VCBL property record.
+     * Requirements: 2.3, 2.4, 3.2
+     */
+    updateEntry(vaultId: string, entryId: string, updates: Partial<VaultEntry>): Promise<VaultEntry>;
+    /**
+     * Delete an entry from a vault.
+     * Removes the entry block from block store (when available), and removes from VCBL at the matching index.
+     * Requirements: 2.4
+     */
+    deleteEntry(vaultId: string, entryId: string): Promise<void>;
+    /**
+     * Search entries in a vault by filtering VCBL property records.
+     * Requirements: 2.9
+     */
+    searchEntries(vaultId: string, query: EntrySearchQuery): Promise<EntryPropertyRecord[]>;
+    /**
+     * Share a vault with one or more recipients.
+     * Updates the VCBL header shared list and tracks member→vault mapping.
+     * Requirements: 4.1, 4.2
+     */
+    shareVault(vaultId: string, recipientMemberIds: string[]): Promise<void>;
+    /**
+     * Revoke a member's access to a shared vault.
+     * Removes from VCBL header shared list and re-keys the vault.
+     * Requirements: 4.3
+     */
+    revokeShare(vaultId: string, memberId: string): Promise<void>;
+    /**
+     * Configure quorum governance for a shared vault.
+     * When threshold > 0, opening the vault requires that many member approvals.
+     * Requirements: 4.4
+     */
+    configureQuorumGovernance(vaultId: string, threshold: number): Promise<void>;
+    /**
+     * Submit a quorum approval for a vault.
+     * The member must be the owner or a shared member.
+     * Returns true if the quorum threshold has been met.
+     * Requirements: 4.4
+     */
+    approveQuorumAccess(vaultId: string, memberId: string): boolean;
+    /**
+     * Check whether the quorum threshold has been met for a vault.
+     */
+    isQuorumMet(vaultId: string): boolean;
+    /**
+     * Reset quorum approvals (e.g. after vault is closed or session ends).
+     */
+    resetQuorumApprovals(vaultId: string): void;
+    /**
+     * Change the master password for a vault.
+     * Verifies old password, re-derives vault key with new password,
+     * decrypts all entries with old key, and re-encrypts with new key.
+     *
+     * Note: This only changes the password, not the vault's BIP39 seed.
+     * Use regenerateVaultSeed() for full key rotation.
+     *
+     * Requirements: 3.4, 3.2
+     */
+    changeMasterPassword(memberId: string, vaultId: string, oldPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Split the vault key into Shamir shares for emergency recovery.
+     * Uses proper Shamir Secret Sharing (polynomial interpolation over GF(256)).
+     * Each trustee receives an encrypted share; threshold shares are needed to reconstruct.
+     *
+     * Security: Uses @digitaldefiance/secrets library which implements proper
+     * Shamir Secret Sharing with cryptographically secure random coefficients.
+     *
+     * Requirements: 10.1, 10.2, 10.3
+     */
+    configureEmergencyAccess(vaultId: string, threshold: number, trustees: string[]): Promise<EmergencyAccessConfig>;
+    /**
+     * Recover a vault using emergency shares.
+     * Uses proper Shamir Secret Sharing reconstruction (polynomial interpolation).
+     * Requires at least threshold shares to reconstruct the vault key.
+     *
+     * Security: The combine() function performs Lagrange interpolation over GF(256)
+     * to reconstruct the secret. With fewer than threshold shares, reconstruction
+     * is cryptographically impossible.
+     *
+     * Requirements: 10.2, 10.3, 10.4
+     */
+    recoverWithShares(vaultId: string, shares: EncryptedShare[]): Promise<DecryptedVault>;
+    /**
+     * Revoke emergency access configuration, invalidating all existing shares.
+     * Requirements: 10.5
+     */
+    revokeEmergencyAccess(vaultId: string): Promise<void>;
+    /**
+     * Get the encrypted shares for a vault's emergency access.
+     * In production, shares would be distributed to trustees via secure channels.
+     * Requirements: 10.2
+     */
+    getEmergencyShares(vaultId: string): EncryptedShare[];
+    /**
+     * Get autofill payload for a given site URL.
+     * Searches VCBL property records by siteUrl, decrypts matching login entries,
+     * and includes TOTP code if configured.
+     * Requirements: 5.7
+     */
+    getAutofillPayload(vaultId: string, siteUrl: string): Promise<AutofillPayload>;
+    /**
+     * Add an attachment to a vault entry.
+     * Stores the file as an encrypted block and adds a reference to the entry.
+     * Requirements: 1.7, 2.8
+     */
+    addAttachment(vaultId: string, entryId: string, file: Buffer, filename: string, mimeType?: string): Promise<AttachmentReference>;
+    /**
+     * Get an attachment's data by ID.
+     * Decrypts the attachment using AES-256-GCM.
+     * Requirements: 2.8, 3.2
+     */
+    getAttachment(vaultId: string, entryId: string, attachmentId: string): Promise<Buffer>;
+    /**
+     * Delete an attachment from a vault entry.
+     * Removes the attachment block and updates the entry reference.
+     * Requirements: 2.8, 3.2
+     */
+    deleteAttachment(vaultId: string, entryId: string, attachmentId: string): Promise<void>;
+    /**
+     * Import entries from a password manager export file.
+     * Parses the file, maps to VaultEntry types, and adds each to the vault.
+     * Requirements: 12.1–12.10
+     */
+    importFromFile(vaultId: string, format: ImportFormat, fileContent: Buffer): Promise<ImportResult>;
+    /**
+     * Get audit log entries for a vault.
+     * Requirements: 9.3
+     */
+    getAuditLog(vaultId: string): Promise<AuditLogEntry[]>;
+}
+//# sourceMappingURL=brightpass.d.ts.map

package/src/lib/services/brightpass.d.ts.map

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