dexbot 1.1.10

package/dist/modules/chain_keys.d.ts

@@ -0,0 +1,302 @@
+/**
+ * modules/chain_keys.ts - Authentication and Key Management
+ *
+ * Secure storage and management of BitShares private keys.
+ * Provides authentication, key storage, and transaction signing capabilities.
+ *
+ * Features:
+ * - Master password authentication with derived vault-key verification
+ * - AES-256-GCM encryption with random salt and IV
+ * - Private key retrieval for transaction signing
+ * - Interactive CLI for key management (add/modify/remove)
+ * - Daemon readiness checking
+ *
+ * Storage: profiles/keys.json (gitignored, never committed)
+ *
+ * Supported key formats:
+ * - WIF (Wallet Import Format): 51-52 character Base58Check encoded
+ * - PVT_K1_* style keys used by some Graphene chains
+ * - Raw 64-character hexadecimal private keys
+ *
+ * Security: Master password never stored; only a derived vault key is kept in memory.
+ * Legacy SHA-256 password hashes are supported only to migrate existing vaults.
+ * All newly written private keys use the v2 vault format.
+ *
+ * ===============================================================================
+ * EXPORTS (13 functions + 1 error class)
+ * ===============================================================================
+ *
+ * AUTHENTICATION (1 function)
+ *   1. authenticate() - Authenticate and return a derived vault secret (async)
+ *      Prompts user for password, verifies vault metadata
+ *      Throws MasterPasswordError on failure
+ *
+ * KEY MANAGEMENT (3 functions)
+ *   2. getPrivateKey(accountName, vaultSecret) - Get private key for account
+ *      Returns decrypted private key string
+ *      Throws Error if account not found
+ *
+ *   3. main() - Interactive CLI for key management (async)
+ *      Add/modify/remove keys from storage
+ *      Re-encrypts entire key store
+ *
+ *   4. validatePrivateKey(key) - Validate private key format
+ *
+ * CRYPTO HELPERS (7 functions)
+ *   5. encrypt(text, secret) - AES-256-GCM encryption
+ *   6. decrypt(encryptedHex, secret) - AES-256-GCM decryption
+ *   7. deriveVaultKey(password, vaultSalt) - Derive the session vault key
+ *   8. deriveSessionSecret(vaultSecret, sessionSalt) - Derive a session-only signing key
+ *   9. loadAccounts() - Load accounts from keys.json
+ *  10. saveAccounts(data) - Save accounts to keys.json
+ *  11. createVaultSecret(...) - Build a serializable derived secret object
+ *
+ * DAEMON (5 functions)
+ *  10. isDaemonReady() - Check if credential daemon is ready
+ *  11. isDaemonResponsive() - Check if daemon is responsive
+ *  12. waitForDaemon(timeoutMs) - Wait for daemon to become ready (async)
+ *  13. probeAccountInDaemon(accountName) - Probe daemon for account (async)
+ *  14. pingDaemon(accountName) - Lightweight daemon health check (async)
+ *
+ * ERROR HANDLING (1 error class)
+ *  14. MasterPasswordError - Thrown when authentication fails
+ *
+ * ===============================================================================
+ *
+ * KEY STORAGE STRUCTURE (profiles/keys.json):
+ * {
+ *   "vaultVersion": 2,
+ *   "vaultSalt": "hex-salt",
+ *   "vaultVerifier": "hex-hmac",
+ *   "accounts": {
+ *     "accountName": "v2:recordSalt:iv:authTag:ciphertext"
+ *   }
+ * }
+ *
+ * ENCRYPTION PROCESS:
+ * 1. Generate random vault salt (16 bytes) and derive a vault key with scrypt
+ * 2. Derive a per-record key from the vault key with HKDF and a record salt
+ * 3. Encrypt private key with AES-256-GCM and a 12-byte IV
+ * 4. Store: v2:recordSalt:iv:authTag:ciphertext
+ *
+ * ===============================================================================
+ */
+declare function isVaultSecret(value: any): boolean;
+declare function createVaultSecret(vaultKey: any, extra?: Record<string, any>): {
+    kind: string;
+    version: any;
+    vaultKeyHex: string;
+};
+declare function createSessionSecret(vaultKey: any, sessionSalt?: any): {
+    kind: string;
+    version: number;
+    sessionSaltHex: string;
+    vaultKeyHex: string;
+};
+declare function createDaemonSigningToken(accountName: string, options?: Record<string, any>): {
+    kind: string;
+    accountName: string;
+    socketPath: any;
+    sessionId: any;
+    botHmacSecret: any;
+};
+declare function isDaemonSigningToken(value: any): boolean;
+declare function deriveVaultKey(password: any, vaultSalt: any): any;
+/**
+ * Encrypt text using the v2 AES-256-GCM vault format.
+ * @param {string} text - Plain text to encrypt
+ * @param {Object|Buffer} secret - Derived vault secret
+ * @returns {string} Encrypted data as hex string
+ */
+declare function encrypt(text: any, secret: any): string;
+/**
+ * Decrypt text encrypted with the encrypt() function.
+ * @param {string} encrypted - Colon-separated encrypted data
+ * @param {Object|Buffer} secret - Derived vault secret
+ * @returns {string} Decrypted plain text
+ * @throws {Error} If decryption fails (wrong password or corrupted data)
+ */
+declare function decrypt(encrypted: any, secret: any): any;
+/**
+ * Validate a private key format.
+ * Supports WIF (Base58Check), PVT_K1_* style, and 64-char hex.
+ * @param {string} key - Private key to validate
+ * @returns {Object} { valid: boolean, reason?: string }
+ */
+declare function validatePrivateKey(key: any): {
+    valid: boolean;
+    reason: string;
+} | {
+    valid: boolean;
+    reason?: undefined;
+};
+/**
+ * Load stored accounts from profiles/keys.json.
+ * Returns empty structure if file doesn't exist or is corrupted.
+ * @returns {Object} { vaultVersion: number, vaultSalt: string, vaultVerifier: string, masterPasswordHash: string, accounts: Object }
+ */
+declare function loadAccounts(): {
+    vaultVersion: number;
+    vaultSalt: string;
+    vaultVerifier: string;
+    masterPasswordHash: string;
+    accounts: any;
+};
+/**
+ * Check that the keys file has restrictive permissions (0o600) and is owned by
+ * the current user.  Returns silently if the file doesn't exist yet (it will be
+ * created correctly by saveAccounts).
+ *
+ * MIGRATION: If the file has the legacy 0o644 mode (from before the atomic-write
+ * fix), auto-remediate to 0o600 and log a warning.  This prevents the first run
+ * after upgrade from crashing with "Unexpected permissions".
+ *
+ * Should be called early in every entry point that may read or write keys.json.
+ */
+declare function checkKeysFileSecurity(): void;
+/**
+ * Unlock the key vault with a master password.
+ * Uses modern scrypt v2 vault format with HMAC verification.
+ * @param {string} password - Master password
+ * @param {import('./types').KeysFile} [accountsData=loadAccounts()] - Accounts data object
+ * @returns {import('./types').VaultSecret} Derived vault secret
+ * @throws {MasterPasswordError} If password is incorrect
+ * @throws {Error} If vault format is unsupported
+ */
+declare function unlockWithPassword(password: any, accountsData?: {
+    vaultVersion: number;
+    vaultSalt: string;
+    vaultVerifier: string;
+    masterPasswordHash: string;
+    accounts: any;
+}): {
+    kind: string;
+    version: any;
+    vaultKeyHex: string;
+};
+declare class MasterPasswordError extends Error {
+    static code: string;
+    code: string;
+    constructor(message: string);
+}
+/**
+ * Check if an error is a master password authentication failure.
+ * @param {Error} err - Error to check
+ * @returns {boolean} True if the error indicates a master password failure
+ */
+declare function isMasterPasswordFailure(err: any): boolean;
+/**
+ * Authenticate and return a derived vault secret.
+ * Prompts user interactively with limited retry attempts.
+ * @returns {Promise<Object>} The verified vault secret
+ * @throws {Error} If no master password is set
+ * @throws {MasterPasswordError} If max attempts exceeded
+ */
+declare function authenticate(): Promise<{
+    kind: string;
+    version: any;
+    vaultKeyHex: string;
+}>;
+/**
+ * Retrieve and decrypt a stored private key.
+ * @param {string} accountName - Name of the account
+ * @param {Object|Buffer} vaultSecret - Derived vault secret
+ * @returns {string} Decrypted private key
+ * @throws {Error} If account not found
+ */
+declare function getPrivateKey(accountName: any, vaultSecret: any): any;
+/**
+ * Resolve a signing key for an account, following on-chain authority structures
+ * (account_auths, key_auths) when no direct key is stored.
+ *
+ * @param {string} accountName - Target account to sign for
+ * @param {Object|Buffer} vaultSecret - Derived vault secret
+ * @param {object} chainClient - Native chain client with db.get_full_accounts
+ * @returns {Promise<string>} Private key WIF string
+ * @throws {Error} If no key can be found through direct lookup or authority resolution
+ */
+declare function resolvePrivateKey(accountName: any, vaultSecret: any, chainClient: any): Promise<any>;
+/**
+ * Save accounts data to profiles/keys.json atomically with restrictive permissions.
+ * Writes to a temp file in the same directory, fsyncs, then renames over the target.
+ * The file is always created with mode 0o600 so that even if the calling process
+ * inherited a permissive umask (e.g. 0o022), the key material is never world-readable.
+ *
+ * @param {Object} data - Accounts data to save
+ */
+declare function saveAccounts(data: any): void;
+/**
+ * Launch the interactive key management CLI.
+ * Provides menu for: add/modify/remove keys, test decryption,
+ * change master password.
+ */
+declare function main(): Promise<void>;
+/**
+ * Check if dexbot-cred daemon is ready and responsive
+ * @param {Object} [options={}] - Optional socket/ready-file path overrides
+ * @returns {boolean} True if daemon socket is responsive
+ */
+declare function isDaemonReady(options?: {}): any;
+/**
+ * Check if dexbot-cred daemon is actually responsive by opening a socket
+ * connection and waiting for any reply. This catches stale socket/ready
+ * files left behind by a crashed daemon.
+ * @param {Object} options - Optional socket/ready-file path overrides
+ * @param {number} timeout - Probe timeout in milliseconds (default 2000)
+ * @returns {Promise<boolean>} True if the daemon accepts connections and replies
+ */
+declare function isDaemonResponsive(options?: {}, timeout?: number): Promise<unknown>;
+/**
+ * Wait for dexbot-cred daemon to be ready
+ * @param {number} maxWaitMs - Maximum time to wait in milliseconds (default 60000)
+ * @param {Object} [options] - Optional socket/ready-file path overrides
+ * @returns {Promise<void>} Resolves when daemon is ready
+ * @throws {Error} If daemon doesn't start within timeout
+ */
+declare function waitForDaemon(maxWaitMs?: any, options?: {}): Promise<void>;
+/**
+ * Lightweight daemon health check.  Does NOT create a session or write
+ * an audit log entry — used by the credential daemon watchdog and
+ * pre-write probes where only liveness matters.
+ * @param {string} accountName - Ignored for ping; included for API consistency
+ * @param {number} timeout - Timeout in milliseconds (default 5000)
+ * @param {Object} options - Optional socket path overrides
+ * @returns {Promise<boolean>} Resolves with true if daemon responds
+ */
+declare function pingDaemon(accountName: any, timeout?: any, options?: {}): Promise<unknown>;
+/**
+ * Verifies the account exists in the daemon's session cache.
+ * @param {string} accountName - Name of the account to probe
+ * @param {number} timeout - Timeout in milliseconds (default 5000)
+ * @param {Object} options - Optional socket path overrides
+ * @returns {Promise<string|null>} Resolves with sessionId if account is available, rejects otherwise
+ */
+declare function probeAccountInDaemon(accountName: any, timeout?: any, options?: {}): Promise<unknown>;
+declare const _default: {
+    validatePrivateKey: typeof validatePrivateKey;
+    loadAccounts: typeof loadAccounts;
+    saveAccounts: typeof saveAccounts;
+    checkKeysFileSecurity: typeof checkKeysFileSecurity;
+    encrypt: typeof encrypt;
+    decrypt: typeof decrypt;
+    deriveVaultKey: typeof deriveVaultKey;
+    createDaemonSigningToken: typeof createDaemonSigningToken;
+    createSessionSecret: typeof createSessionSecret;
+    createVaultSecret: typeof createVaultSecret;
+    isVaultSecret: typeof isVaultSecret;
+    isDaemonSigningToken: typeof isDaemonSigningToken;
+    unlockWithPassword: typeof unlockWithPassword;
+    main: typeof main;
+    authenticate: typeof authenticate;
+    getPrivateKey: typeof getPrivateKey;
+    resolvePrivateKey: typeof resolvePrivateKey;
+    isMasterPasswordFailure: typeof isMasterPasswordFailure;
+    MasterPasswordError: typeof MasterPasswordError;
+    isDaemonReady: typeof isDaemonReady;
+    isDaemonResponsive: typeof isDaemonResponsive;
+    waitForDaemon: typeof waitForDaemon;
+    probeAccountInDaemon: typeof probeAccountInDaemon;
+    pingDaemon: typeof pingDaemon;
+};
+export = _default;
+//# sourceMappingURL=chain_keys.d.ts.map

package/dist/modules/chain_keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain_keys.d.ts","sourceRoot":"","sources":["../../modules/chain_keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAwFH,iBAAS,aAAa,CAAC,KAAK,KAAA,WAE3B;AAmBD,iBAAS,iBAAiB,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;;;;EAUxE;AAED,iBAAS,mBAAmB,CAAC,QAAQ,KAAA,EAAE,WAAW,MAAgC;;;;;EAiBjF;AAED,iBAAS,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM;;;;;;EAYvF;AAED,iBAAS,oBAAoB,CAAC,KAAK,KAAA,WAElC;AAED,iBAAS,cAAc,CAAC,QAAQ,KAAA,EAAE,SAAS,KAAA,OAG1C;AA6ED;;;;;GAKG;AACH,iBAAS,OAAO,CAAC,IAAI,KAAA,EAAE,MAAM,KAAA,UAc5B;AAED;;;;;;GAMG;AACH,iBAAS,OAAO,CAAC,SAAS,KAAA,EAAE,MAAM,KAAA,OAuCjC;AAID;;;;;GAKG;AACH,iBAAS,kBAAkB,CAAC,GAAG,KAAA;;;;;;EAoD9B;AAED;;;;GAIG;AACH,iBAAS,YAAY;;;;;;EASpB;AAYD;;;;;;;;;;GAUG;AACH,iBAAS,qBAAqB,SAiB7B;AAED;;;;;;;;GAQG;AACH,iBAAS,kBAAkB,CAAC,QAAQ,KAAA,EAAE,YAAY;;;;;;CAAiB;;;;EAYlE;AAMD,cAAM,mBAAoB,SAAQ,KAAK;IACnC,MAAM,CAAC,IAAI,SAA4B;IACvC,IAAI,EAAE,MAAM,CAAC;gBACD,OAAO,EAAE,MAAM;CAK9B;AAED;;;;GAIG;AACH,iBAAS,uBAAuB,CAAC,GAAG,KAAA,WAEnC;AAoBD;;;;;;GAMG;AACH,iBAAe,YAAY;;;;GA+B1B;AAED;;;;;;GAMG;AACH,iBAAS,aAAa,CAAC,WAAW,KAAA,EAAE,WAAW,KAAA,OAY9C;AAED;;;;;;;;;GASG;AACH,iBAAe,iBAAiB,CAAC,WAAW,KAAA,EAAE,WAAW,KAAA,EAAE,WAAW,KAAA,gBAqBrE;AAwGD;;;;;;;GAOG;AACH,iBAAS,YAAY,CAAC,IAAI,KAAA,QA4BzB;AAED;;;;GAIG;AACH,iBAAe,IAAI,kBAqIlB;AAED;;;;GAIG;AACH,iBAAS,aAAa,CAAC,OAAO,KAAK,OAMlC;AAED;;;;;;;GAOG;AACH,iBAAS,kBAAkB,CAAC,OAAO,KAAK,EAAE,OAAO,SAAO,oBA0DvD;AAED;;;;;;GAMG;AACH,iBAAe,aAAa,CAAC,SAAS,MAAmC,EAAE,OAAO,KAAK,iBAYtF;AA2ED;;;;;;;;GAQG;AACH,iBAAS,UAAU,CAAC,WAAW,KAAA,EAAE,OAAO,MAAgC,EAAE,OAAO,KAAK,oBAKrF;AAED;;;;;;GAMG;AACH,iBAAS,oBAAoB,CAAC,WAAW,KAAA,EAAE,OAAO,MAAgC,EAAE,OAAO,KAAK,oBAK/F;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED,kBAyBE"}