@cogcoin/client 1.1.6 → 1.1.7

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[]>;

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

@@ -0,0 +1,56 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isMissingFileError } from "./context.js";
+async function collectWalletStateRoots(stateRoot) {
+    const roots = [stateRoot];
+    const seedsRoot = join(stateRoot, "seeds");
+    try {
+        const entries = await readdir(seedsRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                roots.push(join(seedsRoot, entry.name));
+            }
+        }
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            throw error;
+        }
+    }
+    return roots;
+}
+async function readReferencedSecretIdsFromWalletStateRoot(walletStateRoot) {
+    const ids = new Set();
+    const candidatePaths = [
+        join(walletStateRoot, "wallet-state.enc"),
+        join(walletStateRoot, "wallet-state.enc.bak"),
+        join(walletStateRoot, "wallet-init-pending.enc"),
+        join(walletStateRoot, "wallet-init-pending.enc.bak"),
+    ];
+    for (const candidatePath of candidatePaths) {
+        try {
+            const parsed = JSON.parse(await readFile(candidatePath, "utf8"));
+            const keyId = parsed.secretProvider?.keyId?.trim() ?? "";
+            if (keyId.length > 0) {
+                ids.add(keyId);
+            }
+        }
+        catch (error) {
+            if (!isMissingFileError(error)) {
+                continue;
+            }
+        }
+    }
+    return ids;
+}
+export async function collectReferencedSecretIds(stateRoot) {
+    const ids = new Set();
+    const roots = await collectWalletStateRoots(stateRoot);
+    for (const root of roots) {
+        const rootIds = await readReferencedSecretIdsFromWalletStateRoot(root);
+        for (const keyId of rootIds) {
+            ids.add(keyId);
+        }
+    }
+    return [...ids].sort((left, right) => left.localeCompare(right));
+}

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

@@ -0,0 +1,6 @@
+import type { ClientPasswordPrompt, ClientPasswordResolvedContext, ClientPasswordSessionStatus } from "./types.js";
+export declare function finalizePendingClientPasswordRotationIfNeeded(context: ClientPasswordResolvedContext): Promise<void>;
+export declare function changeClientPasswordResolved(options: {
+    context: ClientPasswordResolvedContext;
+    prompt: ClientPasswordPrompt;
+}): Promise<ClientPasswordSessionStatus>;

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

@@ -0,0 +1,98 @@
+import { mkdir, rm } from "node:fs/promises";
+import { resolveLocalSecretFilePath } from "./context.js";
+import { createClientPasswordState, createWrappedSecretEnvelope, decryptWrappedSecretEnvelope, zeroizeBuffer, } from "./crypto.js";
+import { loadClientPasswordRotationJournalOrNull, readLocalSecretFile, writeClientPasswordRotationJournal, writeClientPasswordState, writeWrappedSecretEnvelope, } from "./files.js";
+import { collectReferencedSecretIds } from "./references.js";
+import { promptForNewPassword, promptForVerifiedClientPassword, } from "./prompts.js";
+import { resolveClientPasswordPromptSessionPolicy, resolvePostChangeClientPasswordUnlockUntilUnixMs, } from "./session-policy.js";
+import { readClientPasswordSessionStatusResolved, startClientPasswordSessionWithExpiryResolved, } from "./session.js";
+export async function finalizePendingClientPasswordRotationIfNeeded(context) {
+    const journal = await loadClientPasswordRotationJournalOrNull(context.rotationJournalPath);
+    if (journal === null) {
+        return;
+    }
+    await mkdir(context.directoryPath, { recursive: true, mode: 0o700 });
+    for (const secretEntry of journal.secrets) {
+        await writeWrappedSecretEnvelope(resolveLocalSecretFilePath(context.directoryPath, secretEntry.keyId), secretEntry.envelope);
+    }
+    await writeClientPasswordState(context.passwordStatePath, journal.nextState);
+    await rm(context.rotationJournalPath, { force: true });
+}
+async function prepareClientPasswordRotation(options) {
+    const next = await createClientPasswordState({
+        passwordBytes: options.newPasswordBytes,
+        passwordHint: options.newPasswordHint,
+    });
+    const keyIds = await collectReferencedSecretIds(options.stateRoot);
+    const secrets = [];
+    try {
+        for (const keyId of keyIds) {
+            const localState = await readLocalSecretFile(resolveLocalSecretFilePath(options.directoryPath, keyId));
+            if (localState.state === "missing") {
+                throw new Error(`wallet_secret_missing_${keyId}`);
+            }
+            if (localState.state === "raw") {
+                throw new Error("wallet_client_password_migration_required");
+            }
+            const secret = decryptWrappedSecretEnvelope(localState.envelope, options.currentDerivedKey);
+            try {
+                secrets.push({
+                    keyId,
+                    envelope: createWrappedSecretEnvelope(secret, next.derivedKey),
+                });
+            }
+            finally {
+                zeroizeBuffer(secret);
+            }
+        }
+        return {
+            journal: {
+                format: "cogcoin-client-password-rotation",
+                version: 1,
+                nextState: next.state,
+                secrets,
+            },
+            newDerivedKey: next.derivedKey,
+        };
+    }
+    catch (error) {
+        zeroizeBuffer(next.derivedKey);
+        throw error;
+    }
+}
+export async function changeClientPasswordResolved(options) {
+    await finalizePendingClientPasswordRotationIfNeeded(options.context);
+    const previousSession = await readClientPasswordSessionStatusResolved(options.context);
+    const currentDerivedKey = await promptForVerifiedClientPassword({
+        context: options.context,
+        prompt: options.prompt,
+        promptMessage: "Current client password: ",
+        ttyErrorCode: "wallet_client_password_change_requires_tty",
+    });
+    const nextPassword = await promptForNewPassword(options.prompt);
+    let newDerivedKey = null;
+    try {
+        const prepared = await prepareClientPasswordRotation({
+            ...options.context,
+            currentDerivedKey,
+            newPasswordBytes: nextPassword.passwordBytes,
+            newPasswordHint: nextPassword.passwordHint,
+        });
+        newDerivedKey = prepared.newDerivedKey;
+        await mkdir(options.context.directoryPath, { recursive: true, mode: 0o700 });
+        await writeClientPasswordRotationJournal(options.context.rotationJournalPath, prepared.journal);
+        await finalizePendingClientPasswordRotationIfNeeded(options.context);
+        const session = await startClientPasswordSessionWithExpiryResolved({
+            ...options.context,
+            derivedKey: newDerivedKey,
+            unlockUntilUnixMs: resolvePostChangeClientPasswordUnlockUntilUnixMs(previousSession, resolveClientPasswordPromptSessionPolicy(options.prompt)),
+        });
+        newDerivedKey = null;
+        return session;
+    }
+    finally {
+        zeroizeBuffer(currentDerivedKey);
+        zeroizeBuffer(nextPassword.passwordBytes);
+        zeroizeBuffer(newDerivedKey);
+    }
+}

package/dist/wallet/state/client-password/session-policy.d.ts

@@ -0,0 +1,6 @@
+import type { ClientPasswordPrompt, ClientPasswordSessionStatus } from "./types.js";
+export type ClientPasswordSessionPolicy = "default-60m" | "init-24h" | "mining-indefinite";
+export declare function bindClientPasswordPromptSessionPolicy<T extends ClientPasswordPrompt>(prompt: T, policy: ClientPasswordSessionPolicy): T;
+export declare function resolveClientPasswordPromptSessionPolicy(prompt: ClientPasswordPrompt | null | undefined): ClientPasswordSessionPolicy;
+export declare function resolveClientPasswordSessionUnlockUntilUnixMs(policy: ClientPasswordSessionPolicy, nowUnixMs?: number): number | null;
+export declare function resolvePostChangeClientPasswordUnlockUntilUnixMs(status: ClientPasswordSessionStatus, policy: ClientPasswordSessionPolicy, nowUnixMs?: number): number | null;

package/dist/wallet/state/client-password/session-policy.js

@@ -0,0 +1,28 @@
+import { CLIENT_PASSWORD_DEFAULT_UNLOCK_SECONDS, CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS } from "./crypto.js";
+const promptPolicies = new WeakMap();
+export function bindClientPasswordPromptSessionPolicy(prompt, policy) {
+    promptPolicies.set(prompt, policy);
+    return prompt;
+}
+export function resolveClientPasswordPromptSessionPolicy(prompt) {
+    if (prompt == null) {
+        return "default-60m";
+    }
+    return promptPolicies.get(prompt) ?? "default-60m";
+}
+export function resolveClientPasswordSessionUnlockUntilUnixMs(policy, nowUnixMs = Date.now()) {
+    switch (policy) {
+        case "default-60m":
+            return nowUnixMs + (CLIENT_PASSWORD_DEFAULT_UNLOCK_SECONDS * 1_000);
+        case "init-24h":
+            return nowUnixMs + (CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS * 1_000);
+        case "mining-indefinite":
+            return null;
+    }
+}
+export function resolvePostChangeClientPasswordUnlockUntilUnixMs(status, policy, nowUnixMs = Date.now()) {
+    if (status.unlocked) {
+        return status.unlockUntilUnixMs;
+    }
+    return resolveClientPasswordSessionUnlockUntilUnixMs(policy, nowUnixMs);
+}

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

@@ -0,0 +1,19 @@
+import { type ClientPasswordSessionPolicy } from "./session-policy.js";
+import type { ClientPasswordPrompt, ClientPasswordResolvedContext, ClientPasswordSessionStatus, WrappedSecretEnvelopeV1 } from "./types.js";
+export declare function destroyAllClientPasswordSessionsResolved(): void;
+export declare function readClientPasswordSessionStatusResolved(context: ClientPasswordResolvedContext): Promise<ClientPasswordSessionStatus>;
+export declare function lockClientPasswordSessionResolved(context: ClientPasswordResolvedContext): Promise<ClientPasswordSessionStatus>;
+export declare function startClientPasswordSessionResolved(options: ClientPasswordResolvedContext & {
+    derivedKey: Buffer;
+    sessionPolicy: ClientPasswordSessionPolicy;
+}): Promise<ClientPasswordSessionStatus>;
+export declare function startClientPasswordSessionWithExpiryResolved(options: ClientPasswordResolvedContext & {
+    derivedKey: Buffer;
+    unlockUntilUnixMs: number | null;
+}): Promise<ClientPasswordSessionStatus>;
+export declare function unlockClientPasswordSessionResolved(options: {
+    context: ClientPasswordResolvedContext;
+    prompt: ClientPasswordPrompt;
+}): Promise<ClientPasswordSessionStatus>;
+export declare function decryptClientProtectedSecretWithSessionResolved(context: ClientPasswordResolvedContext, envelope: WrappedSecretEnvelopeV1): Uint8Array | null;
+export declare function encryptClientProtectedSecretWithSessionResolved(context: ClientPasswordResolvedContext, secret: Uint8Array): WrappedSecretEnvelopeV1 | null;

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

@@ -0,0 +1,170 @@
+import { createWrappedSecretEnvelope, decryptWrappedSecretEnvelope, zeroizeBuffer, } from "./crypto.js";
+import { promptForVerifiedClientPassword } from "./prompts.js";
+import { resolveClientPasswordPromptSessionPolicy, resolveClientPasswordSessionUnlockUntilUnixMs, } from "./session-policy.js";
+const activeSessions = new Map();
+let processCleanupRegistered = false;
+function resolveSessionCacheKey(context) {
+    return `${context.platform}\n${context.stateRoot}\n${context.directoryPath}\n${context.passwordStatePath}`;
+}
+function clearExpiryTimer(session) {
+    if (session.expiryTimer !== null) {
+        clearTimeout(session.expiryTimer);
+        session.expiryTimer = null;
+    }
+}
+function destroySession(session) {
+    if (session === undefined) {
+        return;
+    }
+    clearExpiryTimer(session);
+    zeroizeBuffer(session.derivedKey);
+}
+function clearSessionByKey(cacheKey) {
+    const existing = activeSessions.get(cacheKey);
+    if (existing === undefined) {
+        return;
+    }
+    activeSessions.delete(cacheKey);
+    destroySession(existing);
+}
+function scheduleSessionExpiry(cacheKey, session) {
+    clearExpiryTimer(session);
+    if (session.unlockUntilUnixMs === null) {
+        return;
+    }
+    const remainingMs = Math.max(0, session.unlockUntilUnixMs - Date.now());
+    session.expiryTimer = setTimeout(() => {
+        clearSessionByKey(cacheKey);
+    }, remainingMs);
+    session.expiryTimer.unref();
+}
+export function destroyAllClientPasswordSessionsResolved() {
+    for (const session of activeSessions.values()) {
+        destroySession(session);
+    }
+    activeSessions.clear();
+}
+function registerProcessCleanup() {
+    if (processCleanupRegistered) {
+        return;
+    }
+    processCleanupRegistered = true;
+    process.once("exit", () => {
+        destroyAllClientPasswordSessionsResolved();
+    });
+}
+function getActiveSession(context) {
+    const cacheKey = resolveSessionCacheKey(context);
+    const session = activeSessions.get(cacheKey);
+    if (session === undefined) {
+        return null;
+    }
+    if (session.unlockUntilUnixMs !== null && session.unlockUntilUnixMs <= Date.now()) {
+        clearSessionByKey(cacheKey);
+        return null;
+    }
+    return session;
+}
+function putActiveSession(options) {
+    registerProcessCleanup();
+    const cacheKey = resolveSessionCacheKey(options);
+    clearSessionByKey(cacheKey);
+    if (options.unlockUntilUnixMs !== null && options.unlockUntilUnixMs <= Date.now()) {
+        return {
+            unlocked: false,
+            unlockUntilUnixMs: null,
+        };
+    }
+    const session = {
+        derivedKey: Buffer.from(options.derivedKey),
+        unlockUntilUnixMs: options.unlockUntilUnixMs,
+        expiryTimer: null,
+    };
+    activeSessions.set(cacheKey, session);
+    scheduleSessionExpiry(cacheKey, session);
+    return {
+        unlocked: true,
+        unlockUntilUnixMs: session.unlockUntilUnixMs,
+    };
+}
+export async function readClientPasswordSessionStatusResolved(context) {
+    const session = getActiveSession(context);
+    return {
+        unlocked: session !== null,
+        unlockUntilUnixMs: session?.unlockUntilUnixMs ?? null,
+    };
+}
+export async function lockClientPasswordSessionResolved(context) {
+    clearSessionByKey(resolveSessionCacheKey(context));
+    return {
+        unlocked: false,
+        unlockUntilUnixMs: null,
+    };
+}
+export async function startClientPasswordSessionResolved(options) {
+    return await startClientPasswordSessionWithExpiryResolved({
+        ...options,
+        unlockUntilUnixMs: resolveClientPasswordSessionUnlockUntilUnixMs(options.sessionPolicy),
+    });
+}
+export async function startClientPasswordSessionWithExpiryResolved(options) {
+    try {
+        return putActiveSession(options);
+    }
+    finally {
+        zeroizeBuffer(options.derivedKey);
+    }
+}
+async function refreshClientPasswordSessionResolved(context) {
+    const session = getActiveSession(context);
+    if (session === null) {
+        return null;
+    }
+    session.unlockUntilUnixMs = context.unlockUntilUnixMs;
+    scheduleSessionExpiry(resolveSessionCacheKey(context), session);
+    return await readClientPasswordSessionStatusResolved(context);
+}
+async function unlockClientPasswordSessionWithPromptResolved(options) {
+    const derivedKey = await promptForVerifiedClientPassword({
+        context: options.context,
+        prompt: options.prompt,
+        promptMessage: "Client password: ",
+        ttyErrorCode: "wallet_client_password_unlock_requires_tty",
+    });
+    return await startClientPasswordSessionResolved({
+        ...options.context,
+        derivedKey,
+        sessionPolicy: resolveClientPasswordPromptSessionPolicy(options.prompt),
+    });
+}
+export async function unlockClientPasswordSessionResolved(options) {
+    const sessionPolicy = resolveClientPasswordPromptSessionPolicy(options.prompt);
+    const currentStatus = await readClientPasswordSessionStatusResolved(options.context);
+    if (currentStatus.unlocked) {
+        const refreshed = await refreshClientPasswordSessionResolved({
+            ...options.context,
+            unlockUntilUnixMs: resolveClientPasswordSessionUnlockUntilUnixMs(sessionPolicy),
+        });
+        if (refreshed !== null) {
+            return refreshed;
+        }
+    }
+    if (!options.prompt.isInteractive) {
+        throw new Error("wallet_client_password_unlock_requires_tty");
+    }
+    return await unlockClientPasswordSessionWithPromptResolved(options);
+}
+export function decryptClientProtectedSecretWithSessionResolved(context, envelope) {
+    const session = getActiveSession(context);
+    if (session === null) {
+        return null;
+    }
+    return new Uint8Array(decryptWrappedSecretEnvelope(envelope, session.derivedKey));
+}
+export function encryptClientProtectedSecretWithSessionResolved(context, secret) {
+    const session = getActiveSession(context);
+    if (session === null) {
+        return null;
+    }
+    return createWrappedSecretEnvelope(secret, session.derivedKey);
+}

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

@@ -0,0 +1,8 @@
+import type { ClientPasswordPrompt, ClientPasswordResolvedContext, ClientPasswordSessionStatus, ClientPasswordSetupAction } from "./types.js";
+export declare function ensureClientPasswordConfiguredResolved(options: {
+    context: ClientPasswordResolvedContext;
+    prompt: ClientPasswordPrompt;
+}): Promise<{
+    action: ClientPasswordSetupAction;
+    session: ClientPasswordSessionStatus;
+}>;