@cogcoin/client 1.1.6 → 1.1.8

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

@@ -0,0 +1,2 @@
+import type { ClientPasswordAgentBootstrapState } from "./types.js";
+export declare function createAgentBootstrapState(state: ClientPasswordAgentBootstrapState): ClientPasswordAgentBootstrapState;

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

@@ -0,0 +1,3 @@
+export function createAgentBootstrapState(state) {
+    return state;
+}

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

@@ -0,0 +1,10 @@
+import type { WalletRuntimePaths } from "../../runtime.js";
+import type { ClientPasswordResolvedContext, ClientPasswordStorageOptions } from "./types.js";
+export declare function resolveLocalSecretFilePath(directoryPath: string, keyId: string): string;
+export declare function resolveClientPasswordStatePath(directoryPath: string): string;
+export declare function resolveClientPasswordRotationJournalPath(directoryPath: string): string;
+export declare function isMissingFileError(error: unknown): boolean;
+export declare function createRuntimeError(code: string, cause?: unknown): Error;
+export declare function resolveClientPasswordContext(options: ClientPasswordStorageOptions): ClientPasswordResolvedContext;
+export declare function resolveClientPasswordStorageOptionsForWalletPaths(paths: Pick<WalletRuntimePaths, "stateRoot" | "runtimeRoot">, platform?: NodeJS.Platform): ClientPasswordStorageOptions;
+export declare function createLegacyKeychainServiceName(): string;

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

@@ -0,0 +1,46 @@
+import { join } from "node:path";
+function sanitizeSecretKeyId(keyId) {
+    return keyId.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+export function resolveLocalSecretFilePath(directoryPath, keyId) {
+    return join(directoryPath, `${sanitizeSecretKeyId(keyId)}.secret`);
+}
+export function resolveClientPasswordStatePath(directoryPath) {
+    return join(directoryPath, "client-password.json");
+}
+export function resolveClientPasswordRotationJournalPath(directoryPath) {
+    return join(directoryPath, "client-password-rotation.json");
+}
+export function isMissingFileError(error) {
+    return error instanceof Error
+        && "code" in error
+        && error.code === "ENOENT";
+}
+export function createRuntimeError(code, cause) {
+    return cause === undefined ? new Error(code) : new Error(code, { cause });
+}
+export function resolveClientPasswordContext(options) {
+    return {
+        ...options,
+        legacyMacKeychainReader: options.legacyMacKeychainReader ?? null,
+        passwordStatePath: resolveClientPasswordStatePath(options.directoryPath),
+        rotationJournalPath: resolveClientPasswordRotationJournalPath(options.directoryPath),
+    };
+}
+export function resolveClientPasswordStorageOptionsForWalletPaths(paths, platform = process.platform) {
+    return {
+        platform,
+        stateRoot: paths.stateRoot,
+        runtimeRoot: paths.runtimeRoot,
+        directoryPath: join(paths.stateRoot, "secrets"),
+        runtimeErrorCode: platform === "win32"
+            ? "wallet_secret_provider_windows_runtime_error"
+            : platform === "darwin"
+                ? "wallet_secret_provider_macos_runtime_error"
+                : "wallet_secret_provider_linux_runtime_error",
+        legacyMacKeychainReader: null,
+    };
+}
+export function createLegacyKeychainServiceName() {
+    return "org.cogcoin.wallet";
+}

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

@@ -0,0 +1,34 @@
+import type { ClientPasswordStateV1, WrappedSecretEnvelopeV1 } from "./types.js";
+export declare const CLIENT_PASSWORD_DEFAULT_UNLOCK_SECONDS = 3600;
+export declare const CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS = 86400;
+export declare function zeroizeBuffer(buffer: Uint8Array | null | undefined): void;
+export declare function derivePasswordKey(passwordBytes: Uint8Array, saltBytes: Uint8Array): Promise<Buffer>;
+export declare function createClientPasswordState(options: {
+    passwordBytes: Uint8Array;
+    passwordHint: string;
+}): Promise<{
+    state: ClientPasswordStateV1;
+    derivedKey: Buffer;
+}>;
+export declare function createWrappedSecretEnvelope(secret: Uint8Array, derivedKey: Uint8Array): WrappedSecretEnvelopeV1;
+export declare function verifyPassword(options: {
+    state: ClientPasswordStateV1;
+    passwordBytes: Uint8Array;
+}): Promise<Buffer | null>;
+export declare function decryptWrappedSecretEnvelope(envelope: WrappedSecretEnvelopeV1, derivedKey: Uint8Array): Uint8Array;
+export declare function encryptSessionSecretBase64(options: {
+    key: Uint8Array;
+    secretBase64: string;
+}): {
+    nonce: string;
+    tag: string;
+    ciphertext: string;
+};
+export declare function decryptSessionSecretBase64(options: {
+    key: Uint8Array;
+    envelope: {
+        nonce: string;
+        tag: string;
+        ciphertext: string;
+    };
+}): string;

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

@@ -0,0 +1,117 @@
+import { createCipheriv, createDecipheriv, randomBytes, } from "node:crypto";
+import { argon2idAsync } from "@noble/hashes/argon2.js";
+import { decryptBytesWithKey, encryptBytesWithKey } from "../crypto.js";
+import { CLIENT_PASSWORD_STATE_FORMAT, CLIENT_PASSWORD_VERIFIER_FORMAT, CLIENT_PASSWORD_VERIFIER_TEXT, LOCAL_SECRET_ENVELOPE_FORMAT, } from "./types.js";
+const CLIENT_PASSWORD_DERIVED_KEY_BYTES = 32;
+const CLIENT_PASSWORD_KDF = {
+    memoryKib: 65_536,
+    iterations: 3,
+    parallelism: 1,
+};
+export const CLIENT_PASSWORD_DEFAULT_UNLOCK_SECONDS = 3_600;
+export const CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS = 86_400;
+export function zeroizeBuffer(buffer) {
+    if (buffer != null) {
+        buffer.fill(0);
+    }
+}
+export async function derivePasswordKey(passwordBytes, saltBytes) {
+    return Buffer.from(await argon2idAsync(passwordBytes, saltBytes, {
+        m: CLIENT_PASSWORD_KDF.memoryKib,
+        t: CLIENT_PASSWORD_KDF.iterations,
+        p: CLIENT_PASSWORD_KDF.parallelism,
+        dkLen: CLIENT_PASSWORD_DERIVED_KEY_BYTES,
+    }));
+}
+export async function createClientPasswordState(options) {
+    const salt = randomBytes(16);
+    const derivedKey = await derivePasswordKey(options.passwordBytes, salt);
+    const verifier = encryptBytesWithKey(Buffer.from(CLIENT_PASSWORD_VERIFIER_TEXT, "utf8"), derivedKey, {
+        format: CLIENT_PASSWORD_VERIFIER_FORMAT,
+        wrappedBy: "client-password-verifier",
+    });
+    return {
+        state: {
+            format: CLIENT_PASSWORD_STATE_FORMAT,
+            version: 1,
+            passwordHint: options.passwordHint,
+            kdf: {
+                name: "argon2id",
+                memoryKib: CLIENT_PASSWORD_KDF.memoryKib,
+                iterations: CLIENT_PASSWORD_KDF.iterations,
+                parallelism: CLIENT_PASSWORD_KDF.parallelism,
+                salt: salt.toString("base64"),
+            },
+            verifier: {
+                cipher: "aes-256-gcm",
+                nonce: verifier.nonce,
+                tag: verifier.tag,
+                ciphertext: verifier.ciphertext,
+            },
+        },
+        derivedKey,
+    };
+}
+export function createWrappedSecretEnvelope(secret, derivedKey) {
+    const envelope = encryptBytesWithKey(secret, derivedKey, {
+        format: LOCAL_SECRET_ENVELOPE_FORMAT,
+        wrappedBy: "client-password",
+    });
+    return {
+        format: LOCAL_SECRET_ENVELOPE_FORMAT,
+        version: 1,
+        cipher: "aes-256-gcm",
+        wrappedBy: "client-password",
+        nonce: envelope.nonce,
+        tag: envelope.tag,
+        ciphertext: envelope.ciphertext,
+    };
+}
+export async function verifyPassword(options) {
+    const derivedKey = await derivePasswordKey(options.passwordBytes, Buffer.from(options.state.kdf.salt, "base64"));
+    try {
+        const plaintext = decryptBytesWithKey({
+            format: CLIENT_PASSWORD_VERIFIER_FORMAT,
+            version: 1,
+            cipher: "aes-256-gcm",
+            wrappedBy: "client-password-verifier",
+            nonce: options.state.verifier.nonce,
+            tag: options.state.verifier.tag,
+            ciphertext: options.state.verifier.ciphertext,
+        }, derivedKey);
+        if (plaintext.toString("utf8") !== CLIENT_PASSWORD_VERIFIER_TEXT) {
+            zeroizeBuffer(derivedKey);
+            return null;
+        }
+        return derivedKey;
+    }
+    catch {
+        zeroizeBuffer(derivedKey);
+        return null;
+    }
+}
+export function decryptWrappedSecretEnvelope(envelope, derivedKey) {
+    return decryptBytesWithKey(envelope, derivedKey);
+}
+export function encryptSessionSecretBase64(options) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", options.key, nonce);
+    const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(options.secretBase64, "base64")),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag();
+    return {
+        nonce: nonce.toString("base64"),
+        tag: tag.toString("base64"),
+        ciphertext: ciphertext.toString("base64"),
+    };
+}
+export function decryptSessionSecretBase64(options) {
+    const decipher = createDecipheriv("aes-256-gcm", options.key, Buffer.from(options.envelope.nonce, "base64"));
+    decipher.setAuthTag(Buffer.from(options.envelope.tag, "base64"));
+    return Buffer.concat([
+        decipher.update(Buffer.from(options.envelope.ciphertext, "base64")),
+        decipher.final(),
+    ]).toString("base64");
+}

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

@@ -0,0 +1,10 @@
+import type { ClientPasswordRotationJournalV1, ClientPasswordStateV1, LocalSecretFile, WrappedSecretEnvelopeV1 } from "./types.js";
+export declare function readLocalSecretFile(path: string): Promise<LocalSecretFile>;
+export declare function loadClientPasswordStateOrNull(path: string): Promise<ClientPasswordStateV1 | null>;
+export declare function loadClientPasswordRotationJournalOrNull(path: string): Promise<ClientPasswordRotationJournalV1 | null>;
+export declare function writeClientPasswordState(path: string, state: ClientPasswordStateV1): Promise<void>;
+export declare function writeClientPasswordRotationJournal(path: string, journal: ClientPasswordRotationJournalV1): Promise<void>;
+export declare function writeWrappedSecretEnvelope(path: string, envelope: WrappedSecretEnvelopeV1): Promise<void>;
+export declare function listLocalSecretFilesForTesting(options: {
+    directoryPath: string;
+}): Promise<string[]>;

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

@@ -0,0 +1,109 @@
+import { readdir, readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../../fs/atomic.js";
+import { isMissingFileError, } from "./context.js";
+import { CLIENT_PASSWORD_ROTATION_JOURNAL_FORMAT, CLIENT_PASSWORD_STATE_FORMAT, LOCAL_SECRET_ENVELOPE_FORMAT, } from "./types.js";
+function isClientPasswordStateV1(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.format === CLIENT_PASSWORD_STATE_FORMAT
+        && value.version === 1
+        && typeof value.passwordHint === "string"
+        && value.kdf?.name === "argon2id"
+        && typeof value.verifier?.nonce === "string"
+        && typeof value.verifier?.tag === "string"
+        && typeof value.verifier?.ciphertext === "string";
+}
+function isWrappedSecretEnvelope(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.format === LOCAL_SECRET_ENVELOPE_FORMAT
+        && value.version === 1
+        && value.cipher === "aes-256-gcm"
+        && value.wrappedBy === "client-password"
+        && typeof value.nonce === "string"
+        && typeof value.tag === "string"
+        && typeof value.ciphertext === "string";
+}
+function isClientPasswordRotationJournalV1(value) {
+    return value !== null
+        && typeof value === "object"
+        && value.format === CLIENT_PASSWORD_ROTATION_JOURNAL_FORMAT
+        && value.version === 1
+        && isClientPasswordStateV1(value.nextState)
+        && Array.isArray(value.secrets)
+        && (value.secrets).every((entry) => (entry !== null
+            && typeof entry === "object"
+            && typeof entry.keyId === "string"
+            && entry.keyId.trim().length > 0
+            && isWrappedSecretEnvelope(entry.envelope)));
+}
+export async function readLocalSecretFile(path) {
+    try {
+        const raw = await readFile(path, "utf8");
+        const trimmed = raw.trim();
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (isWrappedSecretEnvelope(parsed)) {
+                return {
+                    state: "wrapped",
+                    envelope: parsed,
+                };
+            }
+        }
+        catch {
+            // Legacy local secrets were raw base64 bytes.
+        }
+        return {
+            state: "raw",
+            secret: new Uint8Array(Buffer.from(trimmed, "base64")),
+        };
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return { state: "missing" };
+        }
+        throw error;
+    }
+}
+export async function loadClientPasswordStateOrNull(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isClientPasswordStateV1(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        return null;
+    }
+}
+export async function loadClientPasswordRotationJournalOrNull(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isClientPasswordRotationJournalV1(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return null;
+        }
+        return null;
+    }
+}
+export async function writeClientPasswordState(path, state) {
+    await writeJsonFileAtomic(path, state, { mode: 0o600 });
+}
+export async function writeClientPasswordRotationJournal(path, journal) {
+    await writeJsonFileAtomic(path, journal, { mode: 0o600 });
+}
+export async function writeWrappedSecretEnvelope(path, envelope) {
+    await writeJsonFileAtomic(path, envelope, { mode: 0o600 });
+}
+export function listLocalSecretFilesForTesting(options) {
+    return readdir(options.directoryPath).catch(() => []);
+}

package/dist/wallet/state/client-password/legacy-cleanup.d.ts

@@ -0,0 +1,11 @@
+import type { ClientPasswordResolvedContext } from "./types.js";
+export interface LegacyClientPasswordCleanupDependencies {
+    runCleanupPass?(context: ClientPasswordResolvedContext): Promise<void>;
+}
+export declare function resolveLegacyClientPasswordAgentEndpointForTesting(stateRoot: string, hostPlatform?: NodeJS.Platform): string;
+export declare function extractLegacyClientPasswordAgentProcessIdsForTesting(options: {
+    endpoint: string;
+    hostPlatform: NodeJS.Platform;
+    stdout: string;
+}): number[];
+export declare function cleanupLegacyClientPasswordArtifactsResolved(context: ClientPasswordResolvedContext, deps?: LegacyClientPasswordCleanupDependencies): Promise<void>;

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);
+        }
+    }
+}