@cogcoin/client 0.5.2 → 0.5.4

package/dist/wallet/mnemonic-art.js

@@ -0,0 +1,54 @@
+import { readFileSync } from "node:fs";
+const WALLET_ART_WIDTH = 80;
+const WALLET_ART_SLOT_WIDTH = 8;
+const WALLET_ART_PLACEHOLDER_WORD = "achieved";
+const WALLET_ART_WORD_COUNT = 24;
+let walletArtTemplateCache = null;
+function normalizeWalletArtTemplate(raw) {
+    const lines = raw.replaceAll("\r\n", "\n").split("\n");
+    if (lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    for (const line of lines) {
+        if (line.length !== WALLET_ART_WIDTH) {
+            throw new Error(`wallet_art_template_width_invalid_${line.length}`);
+        }
+    }
+    const template = lines.join("\n");
+    for (let index = 1; index <= WALLET_ART_WORD_COUNT; index += 1) {
+        if (!template.includes(`${index}.${WALLET_ART_PLACEHOLDER_WORD}`)) {
+            throw new Error(`wallet_art_template_placeholder_missing_${index}`);
+        }
+    }
+    return lines;
+}
+function loadWalletArtTemplate() {
+    if (walletArtTemplateCache !== null) {
+        return walletArtTemplateCache;
+    }
+    walletArtTemplateCache = normalizeWalletArtTemplate(readFileSync(new URL("../art/wallet.txt", import.meta.url), "utf8"));
+    return walletArtTemplateCache;
+}
+function formatWalletArtWord(word) {
+    const normalized = word ?? "";
+    if (normalized.length > WALLET_ART_SLOT_WIDTH) {
+        throw new Error(`wallet_art_word_too_wide_${normalized.length}`);
+    }
+    return normalized.padEnd(WALLET_ART_SLOT_WIDTH, " ");
+}
+export function renderWalletMnemonicRevealArt(words) {
+    const rendered = loadWalletArtTemplate().map((line) => {
+        let next = line;
+        for (let index = 0; index < WALLET_ART_WORD_COUNT; index += 1) {
+            next = next.replace(`${index + 1}.${WALLET_ART_PLACEHOLDER_WORD}`, `${index + 1}.${formatWalletArtWord(words[index])}`);
+        }
+        return next;
+    });
+    if (rendered.some((line) => line.includes(`.${WALLET_ART_PLACEHOLDER_WORD}`))) {
+        throw new Error("wallet_art_render_placeholder_unreplaced");
+    }
+    return rendered;
+}
+export function loadWalletArtTemplateForTesting() {
+    return [...loadWalletArtTemplate()];
+}

package/dist/wallet/read/context.d.ts

@@ -8,12 +8,14 @@ declare function inspectWalletLocalState(options?: {
     secretProvider?: WalletSecretProvider;
     now?: number;
     paths?: WalletRuntimePaths;
+    walletControlLockHeld?: boolean;
 }): Promise<WalletLocalStateStatus>;
 export declare function openWalletReadContext(options: {
     dataDir: string;
     databasePath: string;
     walletStatePassphrase?: Uint8Array | string;
     secretProvider?: WalletSecretProvider;
+    walletControlLockHeld?: boolean;
     startupTimeoutMs?: number;
     now?: number;
     paths?: WalletRuntimePaths;

package/dist/wallet/read/context.js

@@ -5,11 +5,12 @@ import { createRpcClient } from "../../bitcoind/node.js";
 import { UNINITIALIZED_WALLET_ROOT_ID } from "../../bitcoind/service-paths.js";
 import { attachOrStartManagedBitcoindService, probeManagedBitcoindService, } from "../../bitcoind/service.js";
 import {} from "../../bitcoind/types.js";
-import { loadUnlockedWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
+import { loadOrAutoUnlockWalletState, verifyManagedCoreWalletReplica, } from "../lifecycle.js";
 import { persistNormalizedWalletDescriptorStateIfNeeded } from "../descriptor-normalization.js";
 import { inspectMiningControlPlane } from "../mining/index.js";
 import { normalizeMiningStateRecord } from "../mining/state.js";
 import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { loadWalletExplicitLock } from "../state/explicit-lock.js";
 import { loadWalletState } from "../state/storage.js";
 import { createDefaultWalletSecretProvider, createWalletSecretReference, } from "../state/provider.js";
 import { createWalletReadModel } from "./project.js";
@@ -24,6 +25,30 @@ async function pathExists(path) {
         return false;
     }
 }
+function isLockedWalletAccessError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message === "wallet_envelope_missing_secret_provider"
+        || message.startsWith("wallet_secret_missing_")
+        || message.startsWith("wallet_secret_provider_");
+}
+function describeLockedWalletMessage(options) {
+    if (options.explicitlyLocked) {
+        return "Wallet state exists but is explicitly locked until `cogcoin unlock` is run.";
+    }
+    const message = options.accessError instanceof Error ? options.accessError.message : String(options.accessError ?? "");
+    if (message === "wallet_envelope_missing_secret_provider") {
+        return "Wallet state exists but requires the local wallet-state passphrase.";
+    }
+    if (message.startsWith("wallet_secret_provider_")) {
+        return "Wallet state exists but the local secret provider is unavailable.";
+    }
+    if (message.startsWith("wallet_secret_missing_")) {
+        return "Wallet state exists but its local secret-provider material is unavailable.";
+    }
+    return options.hasUnlockSessionFile
+        ? "Wallet state exists but the unlock session is expired, invalid, or belongs to a different wallet root."
+        : "Wallet state exists but is currently locked.";
+}
 async function normalizeLoadedWalletStateForRead(options) {
     if (options.dataDir === undefined) {
         return options.loaded;
@@ -82,13 +107,16 @@ async function inspectWalletLocalState(options = {}) {
     if (options.passphrase === undefined) {
         try {
             const provider = options.secretProvider ?? createDefaultWalletSecretProvider();
-            const unlocked = await loadUnlockedWalletState({
+            const unlocked = await loadOrAutoUnlockWalletState({
                 provider,
                 nowUnixMs: now,
                 paths,
                 dataDir: options.dataDir,
+                controlLockHeld: options.walletControlLockHeld,
             });
             if (unlocked === null) {
+                const explicitLock = await loadWalletExplicitLock(paths.walletExplicitLockPath);
+                const hasUnlockSessionFileNow = await pathExists(paths.walletUnlockSessionPath);
                 try {
                     const loaded = await loadWalletState({
                         primaryPath: paths.walletStatePath,
@@ -103,8 +131,39 @@ async function inspectWalletLocalState(options = {}) {
                         now,
                         paths,
                     });
+                    return {
+                        availability: "locked",
+                        walletRootId: loaded.state.walletRootId,
+                        state: null,
+                        source: loaded.source,
+                        unlockUntilUnixMs: null,
+                        hasPrimaryStateFile,
+                        hasBackupStateFile,
+                        hasUnlockSessionFile: hasUnlockSessionFileNow,
+                        message: describeLockedWalletMessage({
+                            explicitlyLocked: explicitLock?.walletRootId === loaded.state.walletRootId,
+                            hasUnlockSessionFile: hasUnlockSessionFileNow,
+                        }),
+                    };
                 }
                 catch (error) {
+                    if (isLockedWalletAccessError(error)) {
+                        return {
+                            availability: "locked",
+                            walletRootId: null,
+                            state: null,
+                            source: null,
+                            unlockUntilUnixMs: null,
+                            hasPrimaryStateFile,
+                            hasBackupStateFile,
+                            hasUnlockSessionFile: hasUnlockSessionFileNow,
+                            message: describeLockedWalletMessage({
+                                accessError: error,
+                                explicitlyLocked: false,
+                                hasUnlockSessionFile: hasUnlockSessionFileNow,
+                            }),
+                        };
+                    }
                     return {
                         availability: "local-state-corrupt",
                         walletRootId: null,
@@ -113,23 +172,10 @@ async function inspectWalletLocalState(options = {}) {
                         unlockUntilUnixMs: null,
                         hasPrimaryStateFile,
                         hasBackupStateFile,
-                        hasUnlockSessionFile,
+                        hasUnlockSessionFile: hasUnlockSessionFileNow,
                         message: error instanceof Error ? error.message : String(error),
                     };
                 }
-                return {
-                    availability: "locked",
-                    walletRootId: null,
-                    state: null,
-                    source: null,
-                    unlockUntilUnixMs: null,
-                    hasPrimaryStateFile,
-                    hasBackupStateFile,
-                    hasUnlockSessionFile,
-                    message: hasUnlockSessionFile
-                        ? "Wallet state exists but the unlock session is expired, invalid, or belongs to a different wallet root."
-                        : "Wallet state exists but is currently locked.",
-                };
             }
             return {
                 availability: "ready",
@@ -142,7 +188,7 @@ async function inspectWalletLocalState(options = {}) {
                 unlockUntilUnixMs: unlocked.session.unlockUntilUnixMs,
                 hasPrimaryStateFile,
                 hasBackupStateFile,
-                hasUnlockSessionFile,
+                hasUnlockSessionFile: true,
                 message: null,
             };
         }
@@ -460,6 +506,7 @@ export async function openWalletReadContext(options) {
         dataDir: options.dataDir,
         passphrase: options.walletStatePassphrase,
         secretProvider: options.secretProvider,
+        walletControlLockHeld: options.walletControlLockHeld,
         now,
         paths: options.paths,
     });

package/dist/wallet/reset.d.ts

@@ -0,0 +1,61 @@
+import { type WalletRuntimePaths } from "./runtime.js";
+import { type WalletSecretProvider } from "./state/provider.js";
+import type { WalletPrompter } from "./lifecycle.js";
+export type WalletResetAction = "not-present" | "kept-unchanged" | "reset-base-entropy" | "deleted";
+export type WalletResetSecretCleanupStatus = "deleted" | "not-found" | "failed" | "unknown";
+export type WalletResetSnapshotResultStatus = "not-present" | "invalid-removed" | "deleted" | "preserved";
+export interface WalletResetResult {
+    dataRoot: string;
+    factoryResetReady: true;
+    stoppedProcesses: {
+        managedBitcoind: number;
+        indexerDaemon: number;
+        backgroundMining: number;
+        survivors: number;
+    };
+    secretCleanupStatus: WalletResetSecretCleanupStatus;
+    deletedSecretRefs: string[];
+    failedSecretRefs: string[];
+    preservedSecretRefs: string[];
+    walletAction: WalletResetAction;
+    walletOldRootId: string | null;
+    walletNewRootId: string | null;
+    bootstrapSnapshot: {
+        status: WalletResetSnapshotResultStatus;
+        path: string;
+    };
+    removedPaths: string[];
+}
+export interface WalletResetPreview {
+    dataRoot: string;
+    confirmationPhrase: "permanently reset";
+    walletPrompt: null | {
+        defaultAction: "reset-base-entropy";
+        acceptedInputs: ["", "skip", "delete wallet"];
+        entropyRetainingResetAvailable: boolean;
+        requiresPassphrase: boolean;
+        envelopeSource: "primary" | "backup" | null;
+    };
+    bootstrapSnapshot: {
+        status: "not-present" | "invalid" | "valid";
+        path: string;
+        defaultAction: "preserve" | "delete";
+    };
+    trackedProcessKinds: Array<"managed-bitcoind" | "indexer-daemon" | "background-mining">;
+    willDeleteOsSecrets: boolean;
+    removedPaths: string[];
+}
+export declare function previewResetWallet(options: {
+    dataDir: string;
+    provider?: WalletSecretProvider;
+    paths?: WalletRuntimePaths;
+    validateSnapshotFile?: (path: string) => Promise<void>;
+}): Promise<WalletResetPreview>;
+export declare function resetWallet(options: {
+    dataDir: string;
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+    validateSnapshotFile?: (path: string) => Promise<void>;
+}): Promise<WalletResetResult>;