@vaultkeepr/core 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,60 @@
+# @vaultkeepr/core
+
+Vault cryptography for VaultKeepR: XChaCha20-Poly1305 AEAD encryption, Argon2id key derivation, ECIES wallet envelopes, TOTP, passkeys, BIP-39, password tooling, and import/export for 10+ password manager formats.
+
+Zero-knowledge by design: the master password never leaves the user's device, and plaintext never crosses a network boundary.
+
+## Install
+
+```bash
+npm install @vaultkeepr/core
+```
+
+## Usage
+
+```ts
+import {
+  addEntry,
+  createEmptyVault,
+  decryptVault,
+  deriveKeyFromPasswordArgon2,
+  encryptVault,
+  generatePassword,
+  generateSaltArgon2,
+  serializeVault,
+} from "@vaultkeepr/core";
+
+// Build a vault
+const vault = addEntry(createEmptyVault(), {
+  title: "GitHub",
+  url: "https://github.com",
+  username: "octocat",
+  password: generatePassword(),
+});
+
+// Encrypt locally — Argon2id (t=3, m=64 MiB, p=4) + XChaCha20-Poly1305
+const salt = generateSaltArgon2();
+const key = deriveKeyFromPasswordArgon2("correct horse battery staple", salt);
+const encrypted = encryptVault(serializeVault(vault), key);
+
+// Decrypt (the key is wiped after each use — re-derive it)
+const plaintext = decryptVault(encrypted, deriveKeyFromPasswordArgon2("correct horse battery staple", salt));
+```
+
+Other surfaces: TOTP (`getTOTPCode`, `parseTOTPUri`), importers (`importFromPgp`, `importVaultText`, LastPass, Keeper, Dashlane, Enpass, KeePass XML, RoboForm, Bitwarden/1Password exports), passkey/NFC/MRZ crypto, password health and entropy, BIP-39/EFF wordlists, three-way merge, pairing.
+
+## Security notes
+
+- Crypto primitives come from `@noble/ciphers`, `@noble/curves`, `@noble/hashes`.
+- `encryptVault`/`decryptVault` wipe the master key after use by default (`wipeKeyAfterUse`).
+- Vault integrity is enforced via an HMAC-SHA256 commitment — tampering throws.
+
+## Related packages
+
+- [`@vaultkeepr/sync`](https://www.npmjs.com/package/@vaultkeepr/sync) — CRDT synchronization
+- [`@vaultkeepr/ipfs`](https://www.npmjs.com/package/@vaultkeepr/ipfs) — CID storage and gateway fetch
+- [`@vaultkeepr/recovery`](https://www.npmjs.com/package/@vaultkeepr/recovery) — fragmented recovery
+
+Repository: [VaultKeepR/vaultkeepr-public](https://github.com/VaultKeepR/vaultkeepr-public) · Site: [vaultkeepr.xyz](https://vaultkeepr.xyz) · Threat model: [`docs/THREAT_MODEL.md`](https://github.com/VaultKeepR/vaultkeepr-public/blob/main/docs/THREAT_MODEL.md)
+
+MIT licensed.

package/dist/index.d.mts

@@ -149,6 +149,7 @@ interface Vault {
     legacyContacts?: LegacyContact[];
     prfCredentials?: PrfCredentialRecord[];
     monitoredEmails?: string[];
+    secretKey?: string;
 }
 interface PrfCredentialRecord {
     credentialId: string;
@@ -227,6 +228,8 @@ declare const DEFAULT_ENTRY_GROUP: EntryGroupId;
 declare const BUILTIN_FOLDER_IDS: Record<EntryGroupId | "passkeys", string>;
 declare const BUILTIN_FOLDER_NODES: FolderNode[];
 declare function getEntryGroupLabel(folder: string | undefined): string;
+declare function cleanEntryTitle(rawTitle: string, url?: string): string;
+declare function getEntryDisplayName(entry: VaultEntry, primaryUrl?: string): string;
 declare function resolveFolderName(folderId: string | undefined, folderTree: FolderNode[] | undefined): string;
 
 declare function generateMasterKey(): Uint8Array;
@@ -364,7 +367,10 @@ interface EncryptedImportResult {
     vault: Vault;
     secretKey?: string;
 }
-declare function importEncryptedVault(encryptedJson: string, password: string, argon2Opts?: Argon2Options): Promise<EncryptedImportResult>;
+declare function importEncryptedVault(encryptedJson: string, password: string, argon2Opts?: Argon2Options, precomputed?: {
+    key: Uint8Array;
+    salt?: Uint8Array;
+}): Promise<EncryptedImportResult>;
 
 interface SkippedExport {
     id: string;
@@ -412,6 +418,7 @@ type PwnedPasswordFetchOptions = {
     signal?: AbortSignal;
     fetchFn?: typeof fetch;
 };
+declare function getPwnedCountForHash(sha1Hex: string, options?: PwnedPasswordFetchOptions): Promise<number>;
 declare function getPwnedPasswordCount(password: string, options?: PwnedPasswordFetchOptions): Promise<number>;
 
 declare function uniformRandom(max: number): number;
@@ -582,6 +589,8 @@ declare function setArgon2Provider(fn: Argon2ProviderFn): void;
 declare function getHiddenWalletLegacy(masterPassword: string, secretKey?: string): LocalAccount;
 declare function getHiddenWalletPrivateKey(masterPassword: string, secretKey?: string): Promise<`0x${string}`>;
 declare function getHiddenWalletFromPassword(masterPassword: string, secretKey?: string): Promise<LocalAccount>;
+declare function getHiddenWalletFromSecretKey(secretKey: string): Promise<LocalAccount>;
+declare function getHiddenWalletPrivateKeyFromSecretKey(secretKey: string): Promise<`0x${string}`>;
 declare function clearHiddenWalletCache(): void;
 declare const FRAGMENT_DOMAIN: {
     readonly name: "VaultKeeperFragments";
@@ -685,7 +694,14 @@ interface ShareOptions {
     senderLabel?: string;
 }
 declare function generateSharePin(): string;
-declare function computeApiPinHash(pin: string): string;
+/**
+ * PIN proof stored by the server as `pinHash`. It is keyed by the share's URL key,
+ * which the server never receives, so the server cannot test a 6-digit PIN offline
+ * against what it stores. (An unkeyed SHA-256 of the PIN was invertible in ~10^6 steps.)
+ * Pass the key exactly as the recipient reads it in the URL fragment: `privateKeyHex`
+ * at creation time.
+ */
+declare function computeApiPinHash(pin: string, keyHex: string): string;
 declare function createSecureShare(payload: Omit<SharePayload, "version" | "createdAt">, pin?: string): ShareCreationResult;
 declare function decryptSecureShare(blobHex: string, keyHex: string, pin: string): SharePayload;
 declare function buildShareUrl(baseUrl: string, shareId: string, keyHex: string): string;
@@ -790,4 +806,131 @@ declare class VaultKeepR_SLM {
     summarizeBreach(breachCount: number, siteUrl: string, lang?: string): Promise<BreachSummaryResult>;
 }
 
-export { type AutoTagResult, BIP39_WORDLIST, BUILTIN_FOLDER_IDS, BUILTIN_FOLDER_NODES, type BreachReport, type BreachResult, type BreachSummaryResult, CARD_BRAND_LABELS, type CardBrand, type CloudFile, type CloudFileCategory, type CustomField, DEFAULT_ENTRY_GROUP, DEFAULT_FRAGMENT_COUNT, type DocumentOcrData, EFF_WORDLIST, ENTRY_GROUP_IDS, ENTRY_GROUP_LABELS, EXTENSION_MAX_PAYLOAD_VERSION, EXTENSION_MIN_PAYLOAD_VERSION, type EmailBreach, type EmailBreachReport, type EmailBreachResult, type EncryptedExportPayload, type EncryptedFragmentPayload, type EncryptedImportResult, type EncryptedVault, type EntryGroupId, type ErrorReport, type ExportResult, FRAGMENTED_DEFAULT_THRESHOLD, FRAGMENTED_DEFAULT_TOTAL, type FolderNode, type FragmentDestination, type FragmentedConfig, type FragmentedManifest, type FragmentedPayload, type GeneratePassphraseOptions, type GeneratePasswordOptions, type ImportVaultTextResult, type KeyEnvelope, type LegacyContact, MOBILE_MAX_PAYLOAD_VERSION, MOBILE_MIN_PAYLOAD_VERSION, type MRZResult, type MergeImportResult, type MergeImportStats, P256_SPKI_HEADER, PAIR_SEND_URI_SCHEME, PAIR_URI_SCHEME, PAYLOAD_VERSION_CURRENT, PAYLOAD_VERSION_V1, PAYLOAD_VERSION_V2, PAYLOAD_VERSION_V3, PAYLOAD_VERSION_V4, type PairKeypair, type PairPayload, type ParsedPairUri, type PasskeyEntry, type PasskeyKeyPair, type PasskeyPrfCredential, type PasswordHealthEntry, type PasswordHealthReport, type PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthResult, type PayloadVersion, type PgpImportResult, type PrfCredentialRecord, type PwnedPasswordFetchOptions, type SecureDocument, type SecureDocumentType, type SeedPhraseEntry, type ShareCreationResult, type ShareOptions, type SharePayload, type SkippedExport, type SkippedItem, TAG_COLORS, type TOTPAlgorithm, VALID_TAGS, type ValidTag, type Vault, type VaultEntry, type VaultEntryUri, type VaultEntryUriMatchType, VaultKeepR_SLM, type VaultPayload, addEntry, analyzeVaultHealth, buildAttestationObject, buildAuthDataForCreate, buildAuthDataForGet, buildMutualAuthData, buildPairPayload, buildPairSendUri, buildPairUri, buildShareUrl, calculateMrzChecksum, calculatePasswordStrength, captureError, checkEmailBreaches, checkVaultBreaches, cleanMrzField, clearErrorBuffer, clearHiddenWalletCache, compressVault, computeApiPinHash, createEmptyVault, createEntry, createExportPayload, createFolder, createKeyEnvelope, createSecureShare, createVaultPayload, decompressVault, decryptFromPair, decryptKeyEnvelope, decryptNfcPayload, decryptPasskeyPrivateKey, decryptPgpContent, decryptSecureShare, decryptVault, deduplicateEntries, deleteCloudFolder, deleteFolder, deleteUserFolder, deleteVaultEntry, deriveKeyFromPasskeyPrf, deriveKeyFromPasswordAndSignatureArgon2, deriveKeyFromPasswordAndSignatureLegacy, deriveKeyFromPasswordArgon2, deriveKeyFromPrfResult, deriveMrzKseed, deriveNfcKey, derivePairSecret, digitsOnly, encryptAndFragmentDocument, encryptForPair, encryptNfcPayload, encryptPasskeyPrivateKey, encryptPgpContent, encryptVault, enrollPasskeyForPrf, entryFingerprint, estimatePasswordEntropy, exportBitwardenJson, exportCsv, exportEncryptedVault, exportProtonPassJson, formatCardDisplayMasked, formatCardNumber, formatErrorReport, fromBase64Url, generateBlurredThumbnailCanvas, generateCredentialId, generateDocumentId, generateMasterKey, generateNfcDeviceSecret, generatePairKeypair, generatePasskeyKeyPair, generatePassphrase, generatePassword, generatePrfSalt, generateSaltArgon2, generateSharePin, getCardBrand, getChecksumAddress, getEntryGroupLabel, getErrorBuffer, getHiddenWalletFromPassword, getHiddenWalletLegacy, getHiddenWalletPrivateKey, getLast4, getMostUsedEntries, getPwnedPasswordCount, getTOTPCode, getTOTPRemainingSeconds, getTagColor, import1PasswordPif, importBitwardenJson, importCsv, importEncryptedVault, importFromPgp, importProtonPassJson, importVaultText, isAcceptablePayloadVersion, isCurrentPayloadVersion, isEncryptedExport, isNfcPayloadV1, isNfcPayloadV2, isNfcPayloadV3, isOnePasswordPif, isPairSendUri, isPairUri, isPasskeyPrivateKeyEncrypted, isPrfSupported, isProtonPassExport, isWebAuthnSupported, maskCardNumber, mergeFolderTrees, mergeFolders, mergeFragments, mergeImportedEntries, moveFolder, normalizeSignatureForKdf, normalizeUrl, parseMRZ, parseMrzDate, parsePairPayload, parsePairSendUri, parsePairUri, parseShareUrl, parseTOTPUri, parseVault, parseVaultPayload, publicKeyToCose, publicKeyToSpki, reassembleAndDecryptDocument, removeEntry, renameFolder, resolveFolderName, rpIdHash, scorePassword, secureCompare, secureWipe, sendErrorReport, serializeVault, setArgon2Provider, signPasskeyAssertion, signStoreFragmentMeta, signStoreFragmentMetaWithSigner, splitBuffer, suggestBip39Words, threeWayMerge, toBase64Url, ttlToMs, uniformRandom, updateEntry, updateEntryUseCount, verifyPasskeyAssertion };
+/**
+ * Account key rules shared by every client (extension, iOS, Android).
+ *
+ * One secret key per account, not per device. The unlock method (password, PRF, passkey,
+ * biometrics) only releases that key on the device: it never creates an identity.
+ * A device without the key must not write to a pointer.
+ */
+interface RemotePointer {
+    exists: boolean;
+    moved: boolean;
+}
+type KeyAccountState = {
+    kind: "ready";
+} | {
+    kind: "passage";
+} | {
+    kind: "read_only_pair";
+} | {
+    kind: "choose";
+};
+declare function accountKeyState(input: {
+    hasSecretKey: boolean;
+    hasLocalVault: boolean;
+    remote: RemotePointer | null;
+}): KeyAccountState;
+/** Address a device writes pointers under: the Smart Account only once moved and the key is here. */
+declare function pointerWalletFor(input: {
+    hasSecretKey: boolean;
+    remoteMoved: boolean;
+    eoa: string;
+    smartAccount: string;
+}): string;
+type PassageStep = "idle" | "key_pending" | "copied" | "moved" | "done";
+type PassageEvent = "key_generated" | "copy_ok" | "copy_failed" | "move_ok" | "move_failed" | "move_conflict" | "promote_ok";
+type PassageTransition = {
+    step: PassageStep;
+    discardPendingKey: boolean;
+} | {
+    error: string;
+};
+/**
+ * Passage of a legacy account to a key. The pending key is never the identity before "done":
+ * a failed copy discards it, a failed move keeps the copy and retries, a move conflict discards it.
+ */
+declare function passageNext(step: PassageStep, event: PassageEvent): PassageTransition;
+/** Identity used for writes during the passage. The key only takes over at "done". */
+declare function passageIdentity(step: PassageStep): "legacy" | "smart_account";
+
+declare const RECOVERY_CODE_LENGTH = 20;
+/**
+ * An account key is the standard 64-hex key, or any other text of 32 to 4096 characters, kept exactly as
+ * given: the account identity is derived from the exact string. The extension's envelope shape {v, iv, ct}
+ * and PGP armour are never account keys.
+ */
+declare function isAccountKeyText(value: string): boolean;
+/** Argon2id over the canonical code bytes. Mobile injects a WebView-backed implementation. */
+type RecoveryKdf = (codeBytes: Uint8Array, salt: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+declare const argon2RecoveryKdf: RecoveryKdf;
+interface RecoveryBlob {
+    version: 1;
+    salt: string;
+    encrypted: EncryptedVault;
+}
+declare function generateRecoveryCode(): string;
+/** Canonical form: uppercase, no spaces or hyphens, O -> 0, I and L -> 1. */
+declare function normalizeRecoveryCode(input: string): string;
+declare function isValidRecoveryCode(input: string): boolean;
+/** Display form, in groups of five: XXXXX-XXXXX-XXXXX-XXXXX. */
+declare function formatRecoveryCode(code: string): string;
+/** Lookup key for the server. Only someone holding the code can compute it. */
+declare function deriveRecoveryId(code: string, kdf?: RecoveryKdf): Promise<string>;
+/** Encrypts the account's secret key under a key derived from the recovery code. */
+declare function createRecoveryBlob(secretKeyHex: string, code: string, kdf?: RecoveryKdf): Promise<RecoveryBlob>;
+/** Recovers the secret key. A wrong code and a damaged blob give the same error. */
+declare function openRecoveryBlob(blob: RecoveryBlob, code: string, kdf?: RecoveryKdf): Promise<string>;
+
+/**
+ * Joining an account with its secret key, through a 100-bit code (recovery-code.ts).
+ *
+ * The sending device seals its secret key under a key derived from the code, and posts only the blob,
+ * under an ID derived from the code. The server never sees the code or the key. The receiving device
+ * types the code, derives the same ID, fetches the blob (the server forgets it after one read), and opens it.
+ *
+ * Transport is injected (post / fetchBlob), so each client uses its own HTTP stack.
+ */
+
+type JoinPost = (id: string, blob: RecoveryBlob) => Promise<void>;
+type JoinFetch = (id: string) => Promise<RecoveryBlob | null>;
+declare class KeyJoinError extends Error {
+    readonly code: "invalid_code" | "not_found";
+    constructor(code: "invalid_code" | "not_found");
+}
+/**
+ * Sending device: creates a code, seals the secret key under it, and posts the blob.
+ * Returns the code to show to the user (grouped, for reading). Nothing is sent before the blob exists.
+ */
+declare function prepareKeyJoin(secretKeyHex: string, post: JoinPost, kdf?: RecoveryKdf): Promise<{
+    code: string;
+}>;
+/**
+ * Receiving device: turns the typed code into the account's secret key. A malformed code fails before any
+ * request. A code with no blob (wrong, expired, or already used) fails with "not_found".
+ */
+declare function joinWithKeyCode(input: string, fetchBlob: JoinFetch, kdf?: RecoveryKdf): Promise<string>;
+
+/**
+ * What a device may do with an encrypted export (.vkenc) when it is imported.
+ *
+ * An export carries the account's secret key only if it was made with one. The import must never
+ * change which account a device belongs to, and must never mix a keyless file into a keyed device.
+ * Pure decision: the caller applies it, and a refusal changes nothing.
+ */
+type EncryptedImportDecision = {
+    action: "import_keyless";
+} | {
+    action: "join_with_file_key";
+} | {
+    action: "keep_device_key";
+} | {
+    action: "refuse";
+    reason: "keyless_file_on_keyed_device" | "other_account";
+};
+declare function decideEncryptedImport(input: {
+    deviceKey: string | null;
+    fileKey: string | null;
+}): EncryptedImportDecision;
+
+export { type AutoTagResult, BIP39_WORDLIST, BUILTIN_FOLDER_IDS, BUILTIN_FOLDER_NODES, type BreachReport, type BreachResult, type BreachSummaryResult, CARD_BRAND_LABELS, type CardBrand, type CloudFile, type CloudFileCategory, type CustomField, DEFAULT_ENTRY_GROUP, DEFAULT_FRAGMENT_COUNT, type DocumentOcrData, EFF_WORDLIST, ENTRY_GROUP_IDS, ENTRY_GROUP_LABELS, EXTENSION_MAX_PAYLOAD_VERSION, EXTENSION_MIN_PAYLOAD_VERSION, type EmailBreach, type EmailBreachReport, type EmailBreachResult, type EncryptedExportPayload, type EncryptedFragmentPayload, type EncryptedImportDecision, type EncryptedImportResult, type EncryptedVault, type EntryGroupId, type ErrorReport, type ExportResult, FRAGMENTED_DEFAULT_THRESHOLD, FRAGMENTED_DEFAULT_TOTAL, type FolderNode, type FragmentDestination, type FragmentedConfig, type FragmentedManifest, type FragmentedPayload, type GeneratePassphraseOptions, type GeneratePasswordOptions, type ImportVaultTextResult, type JoinFetch, type JoinPost, type KeyAccountState, type KeyEnvelope, KeyJoinError, type LegacyContact, MOBILE_MAX_PAYLOAD_VERSION, MOBILE_MIN_PAYLOAD_VERSION, type MRZResult, type MergeImportResult, type MergeImportStats, P256_SPKI_HEADER, PAIR_SEND_URI_SCHEME, PAIR_URI_SCHEME, PAYLOAD_VERSION_CURRENT, PAYLOAD_VERSION_V1, PAYLOAD_VERSION_V2, PAYLOAD_VERSION_V3, PAYLOAD_VERSION_V4, type PairKeypair, type PairPayload, type ParsedPairUri, type PassageEvent, type PassageStep, type PassageTransition, type PasskeyEntry, type PasskeyKeyPair, type PasskeyPrfCredential, type PasswordHealthEntry, type PasswordHealthReport, type PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthResult, type PayloadVersion, type PgpImportResult, type PrfCredentialRecord, type PwnedPasswordFetchOptions, RECOVERY_CODE_LENGTH, type RecoveryBlob, type RecoveryKdf, type RemotePointer, type SecureDocument, type SecureDocumentType, type SeedPhraseEntry, type ShareCreationResult, type ShareOptions, type SharePayload, type SkippedExport, type SkippedItem, TAG_COLORS, type TOTPAlgorithm, VALID_TAGS, type ValidTag, type Vault, type VaultEntry, type VaultEntryUri, type VaultEntryUriMatchType, VaultKeepR_SLM, type VaultPayload, accountKeyState, addEntry, analyzeVaultHealth, argon2RecoveryKdf, buildAttestationObject, buildAuthDataForCreate, buildAuthDataForGet, buildMutualAuthData, buildPairPayload, buildPairSendUri, buildPairUri, buildShareUrl, calculateMrzChecksum, calculatePasswordStrength, captureError, checkEmailBreaches, checkVaultBreaches, cleanEntryTitle, cleanMrzField, clearErrorBuffer, clearHiddenWalletCache, compressVault, computeApiPinHash, createEmptyVault, createEntry, createExportPayload, createFolder, createKeyEnvelope, createRecoveryBlob, createSecureShare, createVaultPayload, decideEncryptedImport, decompressVault, decryptFromPair, decryptKeyEnvelope, decryptNfcPayload, decryptPasskeyPrivateKey, decryptPgpContent, decryptSecureShare, decryptVault, deduplicateEntries, deleteCloudFolder, deleteFolder, deleteUserFolder, deleteVaultEntry, deriveKeyFromPasskeyPrf, deriveKeyFromPasswordAndSignatureArgon2, deriveKeyFromPasswordAndSignatureLegacy, deriveKeyFromPasswordArgon2, deriveKeyFromPrfResult, deriveMrzKseed, deriveNfcKey, derivePairSecret, deriveRecoveryId, digitsOnly, encryptAndFragmentDocument, encryptForPair, encryptNfcPayload, encryptPasskeyPrivateKey, encryptPgpContent, encryptVault, enrollPasskeyForPrf, entryFingerprint, estimatePasswordEntropy, exportBitwardenJson, exportCsv, exportEncryptedVault, exportProtonPassJson, formatCardDisplayMasked, formatCardNumber, formatErrorReport, formatRecoveryCode, fromBase64Url, generateBlurredThumbnailCanvas, generateCredentialId, generateDocumentId, generateMasterKey, generateNfcDeviceSecret, generatePairKeypair, generatePasskeyKeyPair, generatePassphrase, generatePassword, generatePrfSalt, generateRecoveryCode, generateSaltArgon2, generateSharePin, getCardBrand, getChecksumAddress, getEntryDisplayName, getEntryGroupLabel, getErrorBuffer, getHiddenWalletFromPassword, getHiddenWalletFromSecretKey, getHiddenWalletLegacy, getHiddenWalletPrivateKey, getHiddenWalletPrivateKeyFromSecretKey, getLast4, getMostUsedEntries, getPwnedCountForHash, getPwnedPasswordCount, getTOTPCode, getTOTPRemainingSeconds, getTagColor, import1PasswordPif, importBitwardenJson, importCsv, importEncryptedVault, importFromPgp, importProtonPassJson, importVaultText, isAcceptablePayloadVersion, isAccountKeyText, isCurrentPayloadVersion, isEncryptedExport, isNfcPayloadV1, isNfcPayloadV2, isNfcPayloadV3, isOnePasswordPif, isPairSendUri, isPairUri, isPasskeyPrivateKeyEncrypted, isPrfSupported, isProtonPassExport, isValidRecoveryCode, isWebAuthnSupported, joinWithKeyCode, maskCardNumber, mergeFolderTrees, mergeFolders, mergeFragments, mergeImportedEntries, moveFolder, normalizeRecoveryCode, normalizeSignatureForKdf, normalizeUrl, openRecoveryBlob, parseMRZ, parseMrzDate, parsePairPayload, parsePairSendUri, parsePairUri, parseShareUrl, parseTOTPUri, parseVault, parseVaultPayload, passageIdentity, passageNext, pointerWalletFor, prepareKeyJoin, publicKeyToCose, publicKeyToSpki, reassembleAndDecryptDocument, removeEntry, renameFolder, resolveFolderName, rpIdHash, scorePassword, secureCompare, secureWipe, sendErrorReport, serializeVault, setArgon2Provider, signPasskeyAssertion, signStoreFragmentMeta, signStoreFragmentMetaWithSigner, splitBuffer, suggestBip39Words, threeWayMerge, toBase64Url, ttlToMs, uniformRandom, updateEntry, updateEntryUseCount, verifyPasskeyAssertion };

package/dist/index.d.ts

@@ -149,6 +149,7 @@ interface Vault {
     legacyContacts?: LegacyContact[];
     prfCredentials?: PrfCredentialRecord[];
     monitoredEmails?: string[];
+    secretKey?: string;
 }
 interface PrfCredentialRecord {
     credentialId: string;
@@ -227,6 +228,8 @@ declare const DEFAULT_ENTRY_GROUP: EntryGroupId;
 declare const BUILTIN_FOLDER_IDS: Record<EntryGroupId | "passkeys", string>;
 declare const BUILTIN_FOLDER_NODES: FolderNode[];
 declare function getEntryGroupLabel(folder: string | undefined): string;
+declare function cleanEntryTitle(rawTitle: string, url?: string): string;
+declare function getEntryDisplayName(entry: VaultEntry, primaryUrl?: string): string;
 declare function resolveFolderName(folderId: string | undefined, folderTree: FolderNode[] | undefined): string;
 
 declare function generateMasterKey(): Uint8Array;
@@ -364,7 +367,10 @@ interface EncryptedImportResult {
     vault: Vault;
     secretKey?: string;
 }
-declare function importEncryptedVault(encryptedJson: string, password: string, argon2Opts?: Argon2Options): Promise<EncryptedImportResult>;
+declare function importEncryptedVault(encryptedJson: string, password: string, argon2Opts?: Argon2Options, precomputed?: {
+    key: Uint8Array;
+    salt?: Uint8Array;
+}): Promise<EncryptedImportResult>;
 
 interface SkippedExport {
     id: string;
@@ -412,6 +418,7 @@ type PwnedPasswordFetchOptions = {
     signal?: AbortSignal;
     fetchFn?: typeof fetch;
 };
+declare function getPwnedCountForHash(sha1Hex: string, options?: PwnedPasswordFetchOptions): Promise<number>;
 declare function getPwnedPasswordCount(password: string, options?: PwnedPasswordFetchOptions): Promise<number>;
 
 declare function uniformRandom(max: number): number;
@@ -582,6 +589,8 @@ declare function setArgon2Provider(fn: Argon2ProviderFn): void;
 declare function getHiddenWalletLegacy(masterPassword: string, secretKey?: string): LocalAccount;
 declare function getHiddenWalletPrivateKey(masterPassword: string, secretKey?: string): Promise<`0x${string}`>;
 declare function getHiddenWalletFromPassword(masterPassword: string, secretKey?: string): Promise<LocalAccount>;
+declare function getHiddenWalletFromSecretKey(secretKey: string): Promise<LocalAccount>;
+declare function getHiddenWalletPrivateKeyFromSecretKey(secretKey: string): Promise<`0x${string}`>;
 declare function clearHiddenWalletCache(): void;
 declare const FRAGMENT_DOMAIN: {
     readonly name: "VaultKeeperFragments";
@@ -685,7 +694,14 @@ interface ShareOptions {
     senderLabel?: string;
 }
 declare function generateSharePin(): string;
-declare function computeApiPinHash(pin: string): string;
+/**
+ * PIN proof stored by the server as `pinHash`. It is keyed by the share's URL key,
+ * which the server never receives, so the server cannot test a 6-digit PIN offline
+ * against what it stores. (An unkeyed SHA-256 of the PIN was invertible in ~10^6 steps.)
+ * Pass the key exactly as the recipient reads it in the URL fragment: `privateKeyHex`
+ * at creation time.
+ */
+declare function computeApiPinHash(pin: string, keyHex: string): string;
 declare function createSecureShare(payload: Omit<SharePayload, "version" | "createdAt">, pin?: string): ShareCreationResult;
 declare function decryptSecureShare(blobHex: string, keyHex: string, pin: string): SharePayload;
 declare function buildShareUrl(baseUrl: string, shareId: string, keyHex: string): string;
@@ -790,4 +806,131 @@ declare class VaultKeepR_SLM {
     summarizeBreach(breachCount: number, siteUrl: string, lang?: string): Promise<BreachSummaryResult>;
 }
 
-export { type AutoTagResult, BIP39_WORDLIST, BUILTIN_FOLDER_IDS, BUILTIN_FOLDER_NODES, type BreachReport, type BreachResult, type BreachSummaryResult, CARD_BRAND_LABELS, type CardBrand, type CloudFile, type CloudFileCategory, type CustomField, DEFAULT_ENTRY_GROUP, DEFAULT_FRAGMENT_COUNT, type DocumentOcrData, EFF_WORDLIST, ENTRY_GROUP_IDS, ENTRY_GROUP_LABELS, EXTENSION_MAX_PAYLOAD_VERSION, EXTENSION_MIN_PAYLOAD_VERSION, type EmailBreach, type EmailBreachReport, type EmailBreachResult, type EncryptedExportPayload, type EncryptedFragmentPayload, type EncryptedImportResult, type EncryptedVault, type EntryGroupId, type ErrorReport, type ExportResult, FRAGMENTED_DEFAULT_THRESHOLD, FRAGMENTED_DEFAULT_TOTAL, type FolderNode, type FragmentDestination, type FragmentedConfig, type FragmentedManifest, type FragmentedPayload, type GeneratePassphraseOptions, type GeneratePasswordOptions, type ImportVaultTextResult, type KeyEnvelope, type LegacyContact, MOBILE_MAX_PAYLOAD_VERSION, MOBILE_MIN_PAYLOAD_VERSION, type MRZResult, type MergeImportResult, type MergeImportStats, P256_SPKI_HEADER, PAIR_SEND_URI_SCHEME, PAIR_URI_SCHEME, PAYLOAD_VERSION_CURRENT, PAYLOAD_VERSION_V1, PAYLOAD_VERSION_V2, PAYLOAD_VERSION_V3, PAYLOAD_VERSION_V4, type PairKeypair, type PairPayload, type ParsedPairUri, type PasskeyEntry, type PasskeyKeyPair, type PasskeyPrfCredential, type PasswordHealthEntry, type PasswordHealthReport, type PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthResult, type PayloadVersion, type PgpImportResult, type PrfCredentialRecord, type PwnedPasswordFetchOptions, type SecureDocument, type SecureDocumentType, type SeedPhraseEntry, type ShareCreationResult, type ShareOptions, type SharePayload, type SkippedExport, type SkippedItem, TAG_COLORS, type TOTPAlgorithm, VALID_TAGS, type ValidTag, type Vault, type VaultEntry, type VaultEntryUri, type VaultEntryUriMatchType, VaultKeepR_SLM, type VaultPayload, addEntry, analyzeVaultHealth, buildAttestationObject, buildAuthDataForCreate, buildAuthDataForGet, buildMutualAuthData, buildPairPayload, buildPairSendUri, buildPairUri, buildShareUrl, calculateMrzChecksum, calculatePasswordStrength, captureError, checkEmailBreaches, checkVaultBreaches, cleanMrzField, clearErrorBuffer, clearHiddenWalletCache, compressVault, computeApiPinHash, createEmptyVault, createEntry, createExportPayload, createFolder, createKeyEnvelope, createSecureShare, createVaultPayload, decompressVault, decryptFromPair, decryptKeyEnvelope, decryptNfcPayload, decryptPasskeyPrivateKey, decryptPgpContent, decryptSecureShare, decryptVault, deduplicateEntries, deleteCloudFolder, deleteFolder, deleteUserFolder, deleteVaultEntry, deriveKeyFromPasskeyPrf, deriveKeyFromPasswordAndSignatureArgon2, deriveKeyFromPasswordAndSignatureLegacy, deriveKeyFromPasswordArgon2, deriveKeyFromPrfResult, deriveMrzKseed, deriveNfcKey, derivePairSecret, digitsOnly, encryptAndFragmentDocument, encryptForPair, encryptNfcPayload, encryptPasskeyPrivateKey, encryptPgpContent, encryptVault, enrollPasskeyForPrf, entryFingerprint, estimatePasswordEntropy, exportBitwardenJson, exportCsv, exportEncryptedVault, exportProtonPassJson, formatCardDisplayMasked, formatCardNumber, formatErrorReport, fromBase64Url, generateBlurredThumbnailCanvas, generateCredentialId, generateDocumentId, generateMasterKey, generateNfcDeviceSecret, generatePairKeypair, generatePasskeyKeyPair, generatePassphrase, generatePassword, generatePrfSalt, generateSaltArgon2, generateSharePin, getCardBrand, getChecksumAddress, getEntryGroupLabel, getErrorBuffer, getHiddenWalletFromPassword, getHiddenWalletLegacy, getHiddenWalletPrivateKey, getLast4, getMostUsedEntries, getPwnedPasswordCount, getTOTPCode, getTOTPRemainingSeconds, getTagColor, import1PasswordPif, importBitwardenJson, importCsv, importEncryptedVault, importFromPgp, importProtonPassJson, importVaultText, isAcceptablePayloadVersion, isCurrentPayloadVersion, isEncryptedExport, isNfcPayloadV1, isNfcPayloadV2, isNfcPayloadV3, isOnePasswordPif, isPairSendUri, isPairUri, isPasskeyPrivateKeyEncrypted, isPrfSupported, isProtonPassExport, isWebAuthnSupported, maskCardNumber, mergeFolderTrees, mergeFolders, mergeFragments, mergeImportedEntries, moveFolder, normalizeSignatureForKdf, normalizeUrl, parseMRZ, parseMrzDate, parsePairPayload, parsePairSendUri, parsePairUri, parseShareUrl, parseTOTPUri, parseVault, parseVaultPayload, publicKeyToCose, publicKeyToSpki, reassembleAndDecryptDocument, removeEntry, renameFolder, resolveFolderName, rpIdHash, scorePassword, secureCompare, secureWipe, sendErrorReport, serializeVault, setArgon2Provider, signPasskeyAssertion, signStoreFragmentMeta, signStoreFragmentMetaWithSigner, splitBuffer, suggestBip39Words, threeWayMerge, toBase64Url, ttlToMs, uniformRandom, updateEntry, updateEntryUseCount, verifyPasskeyAssertion };
+/**
+ * Account key rules shared by every client (extension, iOS, Android).
+ *
+ * One secret key per account, not per device. The unlock method (password, PRF, passkey,
+ * biometrics) only releases that key on the device: it never creates an identity.
+ * A device without the key must not write to a pointer.
+ */
+interface RemotePointer {
+    exists: boolean;
+    moved: boolean;
+}
+type KeyAccountState = {
+    kind: "ready";
+} | {
+    kind: "passage";
+} | {
+    kind: "read_only_pair";
+} | {
+    kind: "choose";
+};
+declare function accountKeyState(input: {
+    hasSecretKey: boolean;
+    hasLocalVault: boolean;
+    remote: RemotePointer | null;
+}): KeyAccountState;
+/** Address a device writes pointers under: the Smart Account only once moved and the key is here. */
+declare function pointerWalletFor(input: {
+    hasSecretKey: boolean;
+    remoteMoved: boolean;
+    eoa: string;
+    smartAccount: string;
+}): string;
+type PassageStep = "idle" | "key_pending" | "copied" | "moved" | "done";
+type PassageEvent = "key_generated" | "copy_ok" | "copy_failed" | "move_ok" | "move_failed" | "move_conflict" | "promote_ok";
+type PassageTransition = {
+    step: PassageStep;
+    discardPendingKey: boolean;
+} | {
+    error: string;
+};
+/**
+ * Passage of a legacy account to a key. The pending key is never the identity before "done":
+ * a failed copy discards it, a failed move keeps the copy and retries, a move conflict discards it.
+ */
+declare function passageNext(step: PassageStep, event: PassageEvent): PassageTransition;
+/** Identity used for writes during the passage. The key only takes over at "done". */
+declare function passageIdentity(step: PassageStep): "legacy" | "smart_account";
+
+declare const RECOVERY_CODE_LENGTH = 20;
+/**
+ * An account key is the standard 64-hex key, or any other text of 32 to 4096 characters, kept exactly as
+ * given: the account identity is derived from the exact string. The extension's envelope shape {v, iv, ct}
+ * and PGP armour are never account keys.
+ */
+declare function isAccountKeyText(value: string): boolean;
+/** Argon2id over the canonical code bytes. Mobile injects a WebView-backed implementation. */
+type RecoveryKdf = (codeBytes: Uint8Array, salt: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+declare const argon2RecoveryKdf: RecoveryKdf;
+interface RecoveryBlob {
+    version: 1;
+    salt: string;
+    encrypted: EncryptedVault;
+}
+declare function generateRecoveryCode(): string;
+/** Canonical form: uppercase, no spaces or hyphens, O -> 0, I and L -> 1. */
+declare function normalizeRecoveryCode(input: string): string;
+declare function isValidRecoveryCode(input: string): boolean;
+/** Display form, in groups of five: XXXXX-XXXXX-XXXXX-XXXXX. */
+declare function formatRecoveryCode(code: string): string;
+/** Lookup key for the server. Only someone holding the code can compute it. */
+declare function deriveRecoveryId(code: string, kdf?: RecoveryKdf): Promise<string>;
+/** Encrypts the account's secret key under a key derived from the recovery code. */
+declare function createRecoveryBlob(secretKeyHex: string, code: string, kdf?: RecoveryKdf): Promise<RecoveryBlob>;
+/** Recovers the secret key. A wrong code and a damaged blob give the same error. */
+declare function openRecoveryBlob(blob: RecoveryBlob, code: string, kdf?: RecoveryKdf): Promise<string>;
+
+/**
+ * Joining an account with its secret key, through a 100-bit code (recovery-code.ts).
+ *
+ * The sending device seals its secret key under a key derived from the code, and posts only the blob,
+ * under an ID derived from the code. The server never sees the code or the key. The receiving device
+ * types the code, derives the same ID, fetches the blob (the server forgets it after one read), and opens it.
+ *
+ * Transport is injected (post / fetchBlob), so each client uses its own HTTP stack.
+ */
+
+type JoinPost = (id: string, blob: RecoveryBlob) => Promise<void>;
+type JoinFetch = (id: string) => Promise<RecoveryBlob | null>;
+declare class KeyJoinError extends Error {
+    readonly code: "invalid_code" | "not_found";
+    constructor(code: "invalid_code" | "not_found");
+}
+/**
+ * Sending device: creates a code, seals the secret key under it, and posts the blob.
+ * Returns the code to show to the user (grouped, for reading). Nothing is sent before the blob exists.
+ */
+declare function prepareKeyJoin(secretKeyHex: string, post: JoinPost, kdf?: RecoveryKdf): Promise<{
+    code: string;
+}>;
+/**
+ * Receiving device: turns the typed code into the account's secret key. A malformed code fails before any
+ * request. A code with no blob (wrong, expired, or already used) fails with "not_found".
+ */
+declare function joinWithKeyCode(input: string, fetchBlob: JoinFetch, kdf?: RecoveryKdf): Promise<string>;
+
+/**
+ * What a device may do with an encrypted export (.vkenc) when it is imported.
+ *
+ * An export carries the account's secret key only if it was made with one. The import must never
+ * change which account a device belongs to, and must never mix a keyless file into a keyed device.
+ * Pure decision: the caller applies it, and a refusal changes nothing.
+ */
+type EncryptedImportDecision = {
+    action: "import_keyless";
+} | {
+    action: "join_with_file_key";
+} | {
+    action: "keep_device_key";
+} | {
+    action: "refuse";
+    reason: "keyless_file_on_keyed_device" | "other_account";
+};
+declare function decideEncryptedImport(input: {
+    deviceKey: string | null;
+    fileKey: string | null;
+}): EncryptedImportDecision;
+
+export { type AutoTagResult, BIP39_WORDLIST, BUILTIN_FOLDER_IDS, BUILTIN_FOLDER_NODES, type BreachReport, type BreachResult, type BreachSummaryResult, CARD_BRAND_LABELS, type CardBrand, type CloudFile, type CloudFileCategory, type CustomField, DEFAULT_ENTRY_GROUP, DEFAULT_FRAGMENT_COUNT, type DocumentOcrData, EFF_WORDLIST, ENTRY_GROUP_IDS, ENTRY_GROUP_LABELS, EXTENSION_MAX_PAYLOAD_VERSION, EXTENSION_MIN_PAYLOAD_VERSION, type EmailBreach, type EmailBreachReport, type EmailBreachResult, type EncryptedExportPayload, type EncryptedFragmentPayload, type EncryptedImportDecision, type EncryptedImportResult, type EncryptedVault, type EntryGroupId, type ErrorReport, type ExportResult, FRAGMENTED_DEFAULT_THRESHOLD, FRAGMENTED_DEFAULT_TOTAL, type FolderNode, type FragmentDestination, type FragmentedConfig, type FragmentedManifest, type FragmentedPayload, type GeneratePassphraseOptions, type GeneratePasswordOptions, type ImportVaultTextResult, type JoinFetch, type JoinPost, type KeyAccountState, type KeyEnvelope, KeyJoinError, type LegacyContact, MOBILE_MAX_PAYLOAD_VERSION, MOBILE_MIN_PAYLOAD_VERSION, type MRZResult, type MergeImportResult, type MergeImportStats, P256_SPKI_HEADER, PAIR_SEND_URI_SCHEME, PAIR_URI_SCHEME, PAYLOAD_VERSION_CURRENT, PAYLOAD_VERSION_V1, PAYLOAD_VERSION_V2, PAYLOAD_VERSION_V3, PAYLOAD_VERSION_V4, type PairKeypair, type PairPayload, type ParsedPairUri, type PassageEvent, type PassageStep, type PassageTransition, type PasskeyEntry, type PasskeyKeyPair, type PasskeyPrfCredential, type PasswordHealthEntry, type PasswordHealthReport, type PasswordStrength, type PasswordStrengthLevel, type PasswordStrengthResult, type PayloadVersion, type PgpImportResult, type PrfCredentialRecord, type PwnedPasswordFetchOptions, RECOVERY_CODE_LENGTH, type RecoveryBlob, type RecoveryKdf, type RemotePointer, type SecureDocument, type SecureDocumentType, type SeedPhraseEntry, type ShareCreationResult, type ShareOptions, type SharePayload, type SkippedExport, type SkippedItem, TAG_COLORS, type TOTPAlgorithm, VALID_TAGS, type ValidTag, type Vault, type VaultEntry, type VaultEntryUri, type VaultEntryUriMatchType, VaultKeepR_SLM, type VaultPayload, accountKeyState, addEntry, analyzeVaultHealth, argon2RecoveryKdf, buildAttestationObject, buildAuthDataForCreate, buildAuthDataForGet, buildMutualAuthData, buildPairPayload, buildPairSendUri, buildPairUri, buildShareUrl, calculateMrzChecksum, calculatePasswordStrength, captureError, checkEmailBreaches, checkVaultBreaches, cleanEntryTitle, cleanMrzField, clearErrorBuffer, clearHiddenWalletCache, compressVault, computeApiPinHash, createEmptyVault, createEntry, createExportPayload, createFolder, createKeyEnvelope, createRecoveryBlob, createSecureShare, createVaultPayload, decideEncryptedImport, decompressVault, decryptFromPair, decryptKeyEnvelope, decryptNfcPayload, decryptPasskeyPrivateKey, decryptPgpContent, decryptSecureShare, decryptVault, deduplicateEntries, deleteCloudFolder, deleteFolder, deleteUserFolder, deleteVaultEntry, deriveKeyFromPasskeyPrf, deriveKeyFromPasswordAndSignatureArgon2, deriveKeyFromPasswordAndSignatureLegacy, deriveKeyFromPasswordArgon2, deriveKeyFromPrfResult, deriveMrzKseed, deriveNfcKey, derivePairSecret, deriveRecoveryId, digitsOnly, encryptAndFragmentDocument, encryptForPair, encryptNfcPayload, encryptPasskeyPrivateKey, encryptPgpContent, encryptVault, enrollPasskeyForPrf, entryFingerprint, estimatePasswordEntropy, exportBitwardenJson, exportCsv, exportEncryptedVault, exportProtonPassJson, formatCardDisplayMasked, formatCardNumber, formatErrorReport, formatRecoveryCode, fromBase64Url, generateBlurredThumbnailCanvas, generateCredentialId, generateDocumentId, generateMasterKey, generateNfcDeviceSecret, generatePairKeypair, generatePasskeyKeyPair, generatePassphrase, generatePassword, generatePrfSalt, generateRecoveryCode, generateSaltArgon2, generateSharePin, getCardBrand, getChecksumAddress, getEntryDisplayName, getEntryGroupLabel, getErrorBuffer, getHiddenWalletFromPassword, getHiddenWalletFromSecretKey, getHiddenWalletLegacy, getHiddenWalletPrivateKey, getHiddenWalletPrivateKeyFromSecretKey, getLast4, getMostUsedEntries, getPwnedCountForHash, getPwnedPasswordCount, getTOTPCode, getTOTPRemainingSeconds, getTagColor, import1PasswordPif, importBitwardenJson, importCsv, importEncryptedVault, importFromPgp, importProtonPassJson, importVaultText, isAcceptablePayloadVersion, isAccountKeyText, isCurrentPayloadVersion, isEncryptedExport, isNfcPayloadV1, isNfcPayloadV2, isNfcPayloadV3, isOnePasswordPif, isPairSendUri, isPairUri, isPasskeyPrivateKeyEncrypted, isPrfSupported, isProtonPassExport, isValidRecoveryCode, isWebAuthnSupported, joinWithKeyCode, maskCardNumber, mergeFolderTrees, mergeFolders, mergeFragments, mergeImportedEntries, moveFolder, normalizeRecoveryCode, normalizeSignatureForKdf, normalizeUrl, openRecoveryBlob, parseMRZ, parseMrzDate, parsePairPayload, parsePairSendUri, parsePairUri, parseShareUrl, parseTOTPUri, parseVault, parseVaultPayload, passageIdentity, passageNext, pointerWalletFor, prepareKeyJoin, publicKeyToCose, publicKeyToSpki, reassembleAndDecryptDocument, removeEntry, renameFolder, resolveFolderName, rpIdHash, scorePassword, secureCompare, secureWipe, sendErrorReport, serializeVault, setArgon2Provider, signPasskeyAssertion, signStoreFragmentMeta, signStoreFragmentMetaWithSigner, splitBuffer, suggestBip39Words, threeWayMerge, toBase64Url, ttlToMs, uniformRandom, updateEntry, updateEntryUseCount, verifyPasskeyAssertion };