@cogcoin/client 1.1.5 → 1.1.7

package/dist/wallet/state/client-password/legacy-cleanup.js

@@ -0,0 +1,338 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, readdir, rm, rmdir } from "node:fs/promises";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const LEGACY_AGENT_MARKER = "client-password-agent.js";
+const LEGACY_AGENT_TIMEOUT_MS = 500;
+const LEGACY_AGENT_STOP_TIMEOUT_MS = 5_000;
+const LEGACY_AGENT_STOP_POLL_MS = 100;
+const LEGACY_SOCKET_REMOVAL_WAIT_MS = 500;
+const LEGACY_SOCKET_REMOVAL_POLL_MS = 25;
+const inFlightCleanupByStateRoot = new Map();
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isWindowsHostPlatform(platform) {
+    return platform === "win32";
+}
+function isLegacyStatusResponse(value) {
+    if (value === null || typeof value !== "object" || value.ok !== true) {
+        return false;
+    }
+    const unlockUntilUnixMs = value.unlockUntilUnixMs;
+    return unlockUntilUnixMs === undefined
+        || unlockUntilUnixMs === null
+        || Number.isFinite(unlockUntilUnixMs);
+}
+function isLegacyLockResponse(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.ok === true;
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isExactCommandArgument(command, argument) {
+    return new RegExp(`(^|\\s|["'])${escapeRegex(argument)}(?=$|\\s|["'])`).test(command);
+}
+function isLegacyAgentCommand(command, endpoint) {
+    return command.includes(LEGACY_AGENT_MARKER)
+        && isExactCommandArgument(command, endpoint);
+}
+async function sendLegacyAgentRequest(options) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection(options.endpoint);
+        const timeoutMs = options.timeoutMs ?? LEGACY_AGENT_TIMEOUT_MS;
+        let settled = false;
+        let received = "";
+        const cleanup = () => {
+            clearTimeout(timer);
+            socket.off("connect", onConnect);
+            socket.off("data", onData);
+            socket.off("error", onError);
+            socket.off("end", onEnd);
+            socket.off("close", onClose);
+        };
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            cleanup();
+            socket.destroy();
+            resolve(result);
+        };
+        const timer = setTimeout(() => {
+            finish({ kind: "invalid" });
+        }, timeoutMs);
+        timer.unref();
+        const onConnect = () => {
+            socket.write(`${JSON.stringify(options.request)}\n`);
+        };
+        const onData = (chunk) => {
+            received += chunk.toString("utf8");
+            const newlineIndex = received.indexOf("\n");
+            if (newlineIndex === -1) {
+                return;
+            }
+            try {
+                finish({
+                    kind: "ok",
+                    response: JSON.parse(received.slice(0, newlineIndex)),
+                });
+            }
+            catch {
+                finish({ kind: "invalid" });
+            }
+        };
+        const onError = (error) => {
+            const code = error instanceof Error && "code" in error
+                ? String(error.code ?? "")
+                : "";
+            if (code === "ENOENT") {
+                finish({ kind: "missing" });
+                return;
+            }
+            if (!isWindowsHostPlatform(options.hostPlatform)
+                && (code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EPIPE")) {
+                finish({ kind: "stale" });
+                return;
+            }
+            finish({ kind: "invalid" });
+        };
+        const onEnd = () => {
+            if (received.length === 0) {
+                finish({ kind: "invalid" });
+            }
+        };
+        const onClose = () => {
+            if (received.length === 0) {
+                finish({ kind: "invalid" });
+            }
+        };
+        socket.on("connect", onConnect);
+        socket.on("data", onData);
+        socket.on("error", onError);
+        socket.on("end", onEnd);
+        socket.on("close", onClose);
+    });
+}
+async function waitForLegacySocketCleanup(endpoint) {
+    const deadline = Date.now() + LEGACY_SOCKET_REMOVAL_WAIT_MS;
+    while (Date.now() < deadline) {
+        if (!await pathExists(endpoint)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, LEGACY_SOCKET_REMOVAL_POLL_MS));
+    }
+    const probe = await sendLegacyAgentRequest({
+        endpoint,
+        request: { command: "status" },
+        hostPlatform: process.platform,
+        timeoutMs: LEGACY_AGENT_TIMEOUT_MS,
+    });
+    if (probe.kind === "missing" || probe.kind === "stale") {
+        await rm(endpoint, { force: true }).catch(() => undefined);
+    }
+}
+async function cleanupLegacyAgentEndpoint(options) {
+    const endpoint = resolveLegacyClientPasswordAgentEndpointForTesting(options.stateRoot, options.hostPlatform);
+    const status = await sendLegacyAgentRequest({
+        endpoint,
+        request: { command: "status" },
+        hostPlatform: options.hostPlatform,
+    });
+    if (status.kind === "missing") {
+        return;
+    }
+    if (status.kind === "stale") {
+        if (!isWindowsHostPlatform(options.hostPlatform)) {
+            await rm(endpoint, { force: true }).catch(() => undefined);
+        }
+        return;
+    }
+    if (status.kind !== "ok" || !isLegacyStatusResponse(status.response)) {
+        return;
+    }
+    const lock = await sendLegacyAgentRequest({
+        endpoint,
+        request: { command: "lock" },
+        hostPlatform: options.hostPlatform,
+    });
+    if (lock.kind === "ok" && isLegacyLockResponse(lock.response) && !isWindowsHostPlatform(options.hostPlatform)) {
+        await waitForLegacySocketCleanup(endpoint).catch(() => undefined);
+    }
+}
+export function resolveLegacyClientPasswordAgentEndpointForTesting(stateRoot, hostPlatform = process.platform) {
+    const hash = createHash("sha256").update(stateRoot).digest("hex").slice(0, 24);
+    if (isWindowsHostPlatform(hostPlatform)) {
+        return `\\\\.\\pipe\\cogcoin-client-password-${hash}`;
+    }
+    return join(tmpdir(), `cogcoin-client-password-${hash}.sock`);
+}
+export function extractLegacyClientPasswordAgentProcessIdsForTesting(options) {
+    const matches = new Set();
+    if (isWindowsHostPlatform(options.hostPlatform)) {
+        const trimmed = options.stdout.trim();
+        if (trimmed.length === 0 || trimmed === "null") {
+            return [];
+        }
+        const parsed = JSON.parse(trimmed);
+        const entries = Array.isArray(parsed) ? parsed : [parsed];
+        for (const entry of entries) {
+            const processId = typeof entry.ProcessId === "number"
+                ? entry.ProcessId
+                : typeof entry.processId === "number"
+                    ? entry.processId
+                    : null;
+            const commandLine = typeof entry.CommandLine === "string"
+                ? entry.CommandLine
+                : typeof entry.commandLine === "string"
+                    ? entry.commandLine
+                    : "";
+            if (processId !== null && isLegacyAgentCommand(commandLine, options.endpoint)) {
+                matches.add(processId);
+            }
+        }
+        return [...matches];
+    }
+    for (const line of options.stdout.split(/\r?\n/)) {
+        const match = line.match(/^\s*(\d+)\s+(.*)$/);
+        if (match === null) {
+            continue;
+        }
+        const processId = Number(match[1]);
+        const command = match[2] ?? "";
+        if (Number.isInteger(processId) && isLegacyAgentCommand(command, options.endpoint)) {
+            matches.add(processId);
+        }
+    }
+    return [...matches];
+}
+async function listLegacyAgentProcessIds(options) {
+    if (isWindowsHostPlatform(options.hostPlatform)) {
+        const { stdout } = await execFileAsync("powershell.exe", [
+            "-NoProfile",
+            "-Command",
+            "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress",
+        ]);
+        return extractLegacyClientPasswordAgentProcessIdsForTesting({
+            endpoint: options.endpoint,
+            hostPlatform: options.hostPlatform,
+            stdout,
+        });
+    }
+    const { stdout } = await execFileAsync("ps", ["-axo", "pid=,command="]);
+    return extractLegacyClientPasswordAgentProcessIdsForTesting({
+        endpoint: options.endpoint,
+        hostPlatform: options.hostPlatform,
+        stdout,
+    });
+}
+async function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+            return false;
+        }
+        return true;
+    }
+}
+async function waitForProcessExit(pid) {
+    const deadline = Date.now() + LEGACY_AGENT_STOP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (!await isProcessAlive(pid)) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, LEGACY_AGENT_STOP_POLL_MS));
+    }
+}
+async function stopLegacyAgentProcess(pid) {
+    if (pid === process.pid || !await isProcessAlive(pid)) {
+        return;
+    }
+    try {
+        process.kill(pid, "SIGTERM");
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+            throw error;
+        }
+    }
+    try {
+        await waitForProcessExit(pid);
+        return;
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "ESRCH")) {
+                throw error;
+            }
+        }
+    }
+    await waitForProcessExit(pid).catch(() => undefined);
+}
+async function cleanupLegacyAgentProcesses(options) {
+    const endpoint = resolveLegacyClientPasswordAgentEndpointForTesting(options.stateRoot, options.hostPlatform);
+    const processIds = await listLegacyAgentProcessIds({
+        endpoint,
+        hostPlatform: options.hostPlatform,
+    });
+    for (const pid of processIds) {
+        await stopLegacyAgentProcess(pid).catch(() => undefined);
+    }
+}
+async function pruneLegacyRuntimeLeak(stateRoot) {
+    const legacyRuntimeRoot = join(stateRoot, ".client-runtime");
+    const entries = await readdir(legacyRuntimeRoot).catch(() => null);
+    if (entries === null || entries.length > 0) {
+        return;
+    }
+    await rmdir(legacyRuntimeRoot).catch(() => undefined);
+}
+async function runDefaultCleanupPass(context) {
+    const hostPlatform = process.platform;
+    await cleanupLegacyAgentEndpoint({
+        stateRoot: context.stateRoot,
+        hostPlatform,
+    }).catch(() => undefined);
+    await cleanupLegacyAgentProcesses({
+        stateRoot: context.stateRoot,
+        hostPlatform,
+    }).catch(() => undefined);
+    await pruneLegacyRuntimeLeak(context.stateRoot).catch(() => undefined);
+}
+export async function cleanupLegacyClientPasswordArtifactsResolved(context, deps = {}) {
+    const cacheKey = context.stateRoot;
+    const inFlight = inFlightCleanupByStateRoot.get(cacheKey);
+    if (inFlight !== undefined) {
+        await inFlight;
+        return;
+    }
+    const cleanupPromise = (deps.runCleanupPass ?? runDefaultCleanupPass)(context).catch(() => undefined);
+    inFlightCleanupByStateRoot.set(cacheKey, cleanupPromise);
+    try {
+        await cleanupPromise;
+    }
+    finally {
+        if (inFlightCleanupByStateRoot.get(cacheKey) === cleanupPromise) {
+            inFlightCleanupByStateRoot.delete(cacheKey);
+        }
+    }
+}

package/dist/wallet/state/client-password/messages.d.ts

@@ -0,0 +1,3 @@
+export declare function describeClientPasswordLockedMessage(): string;
+export declare function describeClientPasswordSetupMessage(): string;
+export declare function describeClientPasswordMigrationMessage(): string;

package/dist/wallet/state/client-password/messages.js

@@ -0,0 +1,9 @@
+export function describeClientPasswordLockedMessage() {
+    return "Wallet state exists but the client password is locked.";
+}
+export function describeClientPasswordSetupMessage() {
+    return "Wallet-local secret access is not configured yet. Run `cogcoin init` to create the client password.";
+}
+export function describeClientPasswordMigrationMessage() {
+    return "Wallet-local secret migration is still required. Run `cogcoin init` to migrate this client to password-protected local secrets.";
+}

package/dist/wallet/state/client-password/migration.d.ts

@@ -0,0 +1,4 @@
+import type { ClientPasswordResolvedContext } from "./types.js";
+export declare function migrateReferencedSecrets(options: ClientPasswordResolvedContext & {
+    derivedKey: Uint8Array;
+}): Promise<boolean>;

package/dist/wallet/state/client-password/migration.js

@@ -0,0 +1,32 @@
+import { resolveLocalSecretFilePath } from "./context.js";
+import { createWrappedSecretEnvelope } from "./crypto.js";
+import { readLocalSecretFile, writeWrappedSecretEnvelope } from "./files.js";
+import { collectReferencedSecretIds } from "./references.js";
+import { legacyMacKeychainHasSecret } from "./readiness.js";
+export async function migrateReferencedSecrets(options) {
+    const keyIds = await collectReferencedSecretIds(options.stateRoot);
+    let migrated = false;
+    for (const keyId of keyIds) {
+        const localPath = resolveLocalSecretFilePath(options.directoryPath, keyId);
+        const localState = await readLocalSecretFile(localPath);
+        if (localState.state === "wrapped") {
+            continue;
+        }
+        if (localState.state === "raw") {
+            await writeWrappedSecretEnvelope(localPath, createWrappedSecretEnvelope(localState.secret, options.derivedKey));
+            migrated = true;
+            continue;
+        }
+        if (await legacyMacKeychainHasSecret(options, keyId)) {
+            try {
+                const secret = await options.legacyMacKeychainReader.loadSecret(keyId);
+                await writeWrappedSecretEnvelope(localPath, createWrappedSecretEnvelope(secret, options.derivedKey));
+                migrated = true;
+            }
+            catch {
+                // Best-effort legacy migration only.
+            }
+        }
+    }
+    return migrated;
+}

package/dist/wallet/state/client-password/prompts.d.ts

@@ -0,0 +1,12 @@
+import type { ClientPasswordPrompt, ClientPasswordResolvedContext } from "./types.js";
+export declare function promptForHiddenValue(prompt: ClientPasswordPrompt, message: string): Promise<string>;
+export declare function promptForVerifiedClientPassword(options: {
+    context: ClientPasswordResolvedContext;
+    prompt: ClientPasswordPrompt;
+    promptMessage: string;
+    ttyErrorCode: string;
+}): Promise<Buffer>;
+export declare function promptForNewPassword(prompt: ClientPasswordPrompt): Promise<{
+    passwordBytes: Buffer;
+    passwordHint: string;
+}>;

package/dist/wallet/state/client-password/prompts.js

@@ -0,0 +1,79 @@
+import { loadClientPasswordStateOrNull } from "./files.js";
+import { verifyPassword, zeroizeBuffer, } from "./crypto.js";
+import { describeReadinessError, inspectClientPasswordReadinessResolved } from "./readiness.js";
+export async function promptForHiddenValue(prompt, message) {
+    const value = prompt.promptHidden != null
+        ? await prompt.promptHidden(message)
+        : await prompt.prompt(message);
+    return value.trim();
+}
+export async function promptForVerifiedClientPassword(options) {
+    const readiness = await inspectClientPasswordReadinessResolved(options.context);
+    if (readiness !== "ready") {
+        throw new Error(describeReadinessError(readiness));
+    }
+    if (!options.prompt.isInteractive) {
+        throw new Error(options.ttyErrorCode);
+    }
+    const state = await loadClientPasswordStateOrNull(options.context.passwordStatePath);
+    if (state === null) {
+        throw new Error("wallet_client_password_setup_required");
+    }
+    let attempts = 0;
+    while (true) {
+        if (attempts >= 2 && state.passwordHint.trim().length > 0) {
+            options.prompt.writeLine(`Hint: ${state.passwordHint}`);
+        }
+        const passwordText = await promptForHiddenValue(options.prompt, options.promptMessage);
+        const passwordBytes = Buffer.from(passwordText, "utf8");
+        let derivedKey = null;
+        try {
+            derivedKey = await verifyPassword({
+                state,
+                passwordBytes,
+            });
+        }
+        finally {
+            zeroizeBuffer(passwordBytes);
+        }
+        if (derivedKey !== null) {
+            return derivedKey;
+        }
+        attempts += 1;
+        options.prompt.writeLine("Incorrect client password.");
+    }
+}
+export async function promptForNewPassword(prompt) {
+    if (!prompt.isInteractive) {
+        throw new Error("wallet_client_password_setup_requires_tty");
+    }
+    while (true) {
+        const first = await promptForHiddenValue(prompt, "Create client password: ");
+        const firstBytes = Buffer.from(first, "utf8");
+        if (firstBytes.length === 0) {
+            zeroizeBuffer(firstBytes);
+            prompt.writeLine("Client password cannot be blank.");
+            continue;
+        }
+        const second = await promptForHiddenValue(prompt, "Confirm client password: ");
+        const secondBytes = Buffer.from(second, "utf8");
+        if (!firstBytes.equals(secondBytes)) {
+            zeroizeBuffer(firstBytes);
+            zeroizeBuffer(secondBytes);
+            prompt.writeLine("Client password entries did not match.");
+            continue;
+        }
+        zeroizeBuffer(secondBytes);
+        let passwordHint = "";
+        while (passwordHint.length === 0) {
+            passwordHint = (await prompt.prompt("Password hint: ")).trim();
+            if (passwordHint.length === 0) {
+                prompt.writeLine("Password hint cannot be blank.");
+            }
+        }
+        return {
+            passwordBytes: firstBytes,
+            passwordHint,
+        };
+    }
+}

package/dist/wallet/state/client-password/protected-secrets.d.ts

@@ -0,0 +1,13 @@
+import type { ClientPasswordPrompt, ClientPasswordResolvedContext } from "./types.js";
+export declare function loadClientProtectedSecretResolved(options: ClientPasswordResolvedContext & {
+    keyId: string;
+    prompt?: ClientPasswordPrompt;
+}): Promise<Uint8Array>;
+export declare function storeClientProtectedSecretResolved(options: ClientPasswordResolvedContext & {
+    keyId: string;
+    secret: Uint8Array;
+    prompt?: ClientPasswordPrompt;
+}): Promise<void>;
+export declare function deleteClientProtectedSecretResolved(options: ClientPasswordResolvedContext & {
+    keyId: string;
+}): Promise<void>;

package/dist/wallet/state/client-password/protected-secrets.js

@@ -0,0 +1,90 @@
+import { mkdir, rm } from "node:fs/promises";
+import { createRuntimeError, resolveLocalSecretFilePath } from "./context.js";
+import { loadClientPasswordStateOrNull, readLocalSecretFile, writeWrappedSecretEnvelope, } from "./files.js";
+import { legacyMacKeychainHasSecret } from "./readiness.js";
+import { finalizePendingClientPasswordRotationIfNeeded } from "./rotation.js";
+import { decryptClientProtectedSecretWithSessionResolved, encryptClientProtectedSecretWithSessionResolved, unlockClientPasswordSessionResolved, } from "./session.js";
+async function decryptWrappedSecretWithSessionResolved(options) {
+    let secret = decryptClientProtectedSecretWithSessionResolved(options, options.envelope);
+    if (secret === null && options.prompt != null && options.prompt.isInteractive) {
+        await unlockClientPasswordSessionResolved({
+            context: options,
+            prompt: options.prompt,
+        });
+        secret = decryptClientProtectedSecretWithSessionResolved(options, options.envelope);
+    }
+    if (secret === null) {
+        throw new Error("wallet_client_password_locked");
+    }
+    return secret;
+}
+async function encryptWrappedSecretWithSessionResolved(options) {
+    let envelope = encryptClientProtectedSecretWithSessionResolved(options, options.secret);
+    if (envelope === null && options.prompt != null && options.prompt.isInteractive) {
+        await unlockClientPasswordSessionResolved({
+            context: options,
+            prompt: options.prompt,
+        });
+        envelope = encryptClientProtectedSecretWithSessionResolved(options, options.secret);
+    }
+    if (envelope === null) {
+        throw new Error("wallet_client_password_locked");
+    }
+    return envelope;
+}
+export async function loadClientProtectedSecretResolved(options) {
+    try {
+        await finalizePendingClientPasswordRotationIfNeeded(options);
+        const passwordState = await loadClientPasswordStateOrNull(options.passwordStatePath);
+        const localState = await readLocalSecretFile(resolveLocalSecretFilePath(options.directoryPath, options.keyId));
+        if (passwordState === null) {
+            if (localState.state === "raw" || await legacyMacKeychainHasSecret(options, options.keyId)) {
+                throw new Error("wallet_client_password_migration_required");
+            }
+            throw new Error("wallet_client_password_setup_required");
+        }
+        if (localState.state === "missing") {
+            if (await legacyMacKeychainHasSecret(options, options.keyId)) {
+                throw new Error("wallet_client_password_migration_required");
+            }
+            throw new Error(`wallet_secret_missing_${options.keyId}`);
+        }
+        if (localState.state === "raw") {
+            throw new Error("wallet_client_password_migration_required");
+        }
+        return await decryptWrappedSecretWithSessionResolved({
+            ...options,
+            envelope: localState.envelope,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("wallet_client_password_")
+            || message.startsWith("wallet_secret_missing_")) {
+            throw error;
+        }
+        throw createRuntimeError(options.runtimeErrorCode, error);
+    }
+}
+export async function storeClientProtectedSecretResolved(options) {
+    try {
+        await finalizePendingClientPasswordRotationIfNeeded(options);
+        const passwordState = await loadClientPasswordStateOrNull(options.passwordStatePath);
+        if (passwordState === null) {
+            throw new Error("wallet_client_password_setup_required");
+        }
+        await mkdir(options.directoryPath, { recursive: true, mode: 0o700 });
+        const envelope = await encryptWrappedSecretWithSessionResolved(options);
+        await writeWrappedSecretEnvelope(resolveLocalSecretFilePath(options.directoryPath, options.keyId), envelope);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("wallet_client_password_")) {
+            throw error;
+        }
+        throw createRuntimeError(options.runtimeErrorCode, error);
+    }
+}
+export async function deleteClientProtectedSecretResolved(options) {
+    await rm(resolveLocalSecretFilePath(options.directoryPath, options.keyId), { force: true }).catch(() => undefined);
+}

package/dist/wallet/state/client-password/readiness.d.ts

@@ -0,0 +1,4 @@
+import type { ClientPasswordReadiness, ClientPasswordResolvedContext } from "./types.js";
+export declare function legacyMacKeychainHasSecret(context: ClientPasswordResolvedContext, keyId: string): Promise<boolean>;
+export declare function inspectClientPasswordReadinessResolved(context: ClientPasswordResolvedContext): Promise<ClientPasswordReadiness>;
+export declare function describeReadinessError(readiness: ClientPasswordReadiness): string;

package/dist/wallet/state/client-password/readiness.js

@@ -0,0 +1,48 @@
+import { resolveLocalSecretFilePath } from "./context.js";
+import { readLocalSecretFile, loadClientPasswordStateOrNull } from "./files.js";
+import { collectReferencedSecretIds } from "./references.js";
+export async function legacyMacKeychainHasSecret(context, keyId) {
+    if (context.platform !== "darwin" || context.legacyMacKeychainReader == null) {
+        return false;
+    }
+    try {
+        await context.legacyMacKeychainReader.loadSecret(keyId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function inspectReadinessForKey(context, keyId) {
+    const local = await readLocalSecretFile(resolveLocalSecretFilePath(context.directoryPath, keyId));
+    const keychain = await legacyMacKeychainHasSecret(context, keyId);
+    return { local, keychain };
+}
+export async function inspectClientPasswordReadinessResolved(context) {
+    const passwordState = await loadClientPasswordStateOrNull(context.passwordStatePath);
+    const keyIds = await collectReferencedSecretIds(context.stateRoot);
+    if (keyIds.length === 0) {
+        return passwordState === null ? "setup-required" : "ready";
+    }
+    for (const keyId of keyIds) {
+        const sourceState = await inspectReadinessForKey(context, keyId);
+        if (passwordState === null) {
+            if (sourceState.local.state === "raw" || sourceState.keychain) {
+                return "migration-required";
+            }
+            continue;
+        }
+        if (sourceState.local.state === "raw") {
+            return "migration-required";
+        }
+        if (sourceState.local.state === "missing" && sourceState.keychain) {
+            return "migration-required";
+        }
+    }
+    return passwordState === null ? "setup-required" : "ready";
+}
+export function describeReadinessError(readiness) {
+    return readiness === "migration-required"
+        ? "wallet_client_password_migration_required"
+        : "wallet_client_password_setup_required";
+}

package/dist/wallet/state/client-password/references.d.ts

@@ -0,0 +1 @@
+export declare function collectReferencedSecretIds(stateRoot: string): Promise<string[]>;