@cogcoin/client 1.1.6 → 1.1.8

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

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

@@ -0,0 +1,49 @@
+import { mkdir } from "node:fs/promises";
+import { createClientPasswordState, zeroizeBuffer, } from "./crypto.js";
+import { writeClientPasswordState } from "./files.js";
+import { migrateReferencedSecrets } from "./migration.js";
+import { promptForNewPassword } from "./prompts.js";
+import { inspectClientPasswordReadinessResolved } from "./readiness.js";
+import { resolveClientPasswordPromptSessionPolicy } from "./session-policy.js";
+import { finalizePendingClientPasswordRotationIfNeeded } from "./rotation.js";
+import { startClientPasswordSessionResolved } from "./session.js";
+import { readClientPasswordSessionStatusResolved } from "./session.js";
+export async function ensureClientPasswordConfiguredResolved(options) {
+    await finalizePendingClientPasswordRotationIfNeeded(options.context);
+    const readiness = await inspectClientPasswordReadinessResolved(options.context);
+    if (readiness === "ready") {
+        return {
+            action: "already-configured",
+            session: await readClientPasswordSessionStatusResolved(options.context),
+        };
+    }
+    const setup = await promptForNewPassword(options.prompt);
+    let derivedKey = null;
+    try {
+        const created = await createClientPasswordState({
+            passwordBytes: setup.passwordBytes,
+            passwordHint: setup.passwordHint,
+        });
+        derivedKey = created.derivedKey;
+        await mkdir(options.context.directoryPath, { recursive: true, mode: 0o700 });
+        await writeClientPasswordState(options.context.passwordStatePath, created.state);
+        const migrated = await migrateReferencedSecrets({
+            ...options.context,
+            derivedKey,
+        });
+        const session = await startClientPasswordSessionResolved({
+            ...options.context,
+            derivedKey,
+            sessionPolicy: resolveClientPasswordPromptSessionPolicy(options.prompt),
+        });
+        derivedKey = null;
+        return {
+            action: migrated || readiness === "migration-required" ? "migrated" : "created",
+            session,
+        };
+    }
+    finally {
+        zeroizeBuffer(setup.passwordBytes);
+        zeroizeBuffer(derivedKey);
+    }
+}

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

@@ -0,0 +1,82 @@
+export declare const CLIENT_PASSWORD_STATE_FORMAT = "cogcoin-client-password";
+export declare const CLIENT_PASSWORD_ROTATION_JOURNAL_FORMAT = "cogcoin-client-password-rotation";
+export declare const CLIENT_PASSWORD_VERIFIER_FORMAT = "cogcoin-client-password-verifier";
+export declare const LOCAL_SECRET_ENVELOPE_FORMAT = "cogcoin-local-wallet-secret";
+export declare const CLIENT_PASSWORD_VERIFIER_TEXT = "cogcoin-client-password-verifier-v1";
+export type ClientPasswordReadiness = "ready" | "setup-required" | "migration-required";
+export type ClientPasswordSetupAction = "created" | "migrated" | "already-configured";
+export interface ClientPasswordPrompt {
+    readonly isInteractive: boolean;
+    writeLine(message: string): void;
+    prompt(message: string): Promise<string>;
+    promptHidden?(message: string): Promise<string>;
+}
+export interface ClientPasswordSessionStatus {
+    unlocked: boolean;
+    unlockUntilUnixMs: number | null;
+}
+export interface ClientPasswordLegacyKeychainReader {
+    loadSecret(keyId: string): Promise<Uint8Array>;
+}
+export interface ClientPasswordStorageOptions {
+    platform: NodeJS.Platform;
+    stateRoot: string;
+    runtimeRoot: string;
+    directoryPath: string;
+    runtimeErrorCode: string;
+    legacyMacKeychainReader?: ClientPasswordLegacyKeychainReader | null;
+}
+export interface ClientPasswordResolvedContext extends ClientPasswordStorageOptions {
+    legacyMacKeychainReader?: ClientPasswordLegacyKeychainReader | null;
+    passwordStatePath: string;
+    rotationJournalPath: string;
+}
+export interface ClientPasswordStateV1 {
+    format: typeof CLIENT_PASSWORD_STATE_FORMAT;
+    version: 1;
+    passwordHint: string;
+    kdf: {
+        name: "argon2id";
+        memoryKib: number;
+        iterations: number;
+        parallelism: number;
+        salt: string;
+    };
+    verifier: {
+        cipher: "aes-256-gcm";
+        nonce: string;
+        tag: string;
+        ciphertext: string;
+    };
+}
+export interface WrappedSecretEnvelopeV1 {
+    format: typeof LOCAL_SECRET_ENVELOPE_FORMAT;
+    version: 1;
+    cipher: "aes-256-gcm";
+    wrappedBy: "client-password";
+    nonce: string;
+    tag: string;
+    ciphertext: string;
+}
+export interface ClientPasswordRotationJournalV1 {
+    format: typeof CLIENT_PASSWORD_ROTATION_JOURNAL_FORMAT;
+    version: 1;
+    nextState: ClientPasswordStateV1;
+    secrets: Array<{
+        keyId: string;
+        envelope: WrappedSecretEnvelopeV1;
+    }>;
+}
+export interface ClientPasswordAgentBootstrapState {
+    unlockUntilUnixMs: number;
+    derivedKeyBase64: string;
+}
+export type LocalSecretFile = {
+    state: "missing";
+} | {
+    state: "raw";
+    secret: Uint8Array;
+} | {
+    state: "wrapped";
+    envelope: WrappedSecretEnvelopeV1;
+};

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

@@ -0,0 +1,5 @@
+export const CLIENT_PASSWORD_STATE_FORMAT = "cogcoin-client-password";
+export const CLIENT_PASSWORD_ROTATION_JOURNAL_FORMAT = "cogcoin-client-password-rotation";
+export const CLIENT_PASSWORD_VERIFIER_FORMAT = "cogcoin-client-password-verifier";
+export const LOCAL_SECRET_ENVELOPE_FORMAT = "cogcoin-local-wallet-secret";
+export const CLIENT_PASSWORD_VERIFIER_TEXT = "cogcoin-client-password-verifier-v1";

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

@@ -1,27 +1,10 @@
-export declare const CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS = 86400;
-export type ClientPasswordReadiness = "ready" | "setup-required" | "migration-required";
-export type ClientPasswordSetupAction = "created" | "migrated" | "already-configured";
-export interface ClientPasswordPrompt {
-    readonly isInteractive: boolean;
-    writeLine(message: string): void;
-    prompt(message: string): Promise<string>;
-    promptHidden?(message: string): Promise<string>;
-}
-export interface ClientPasswordSessionStatus {
-    unlocked: boolean;
-    unlockUntilUnixMs: number | null;
-}
-export interface ClientPasswordStorageOptions {
-    platform: NodeJS.Platform;
-    stateRoot: string;
-    runtimeRoot: string;
-    directoryPath: string;
-    runtimeErrorCode: string;
-    legacyMacKeychainReader?: {
-        loadSecret(keyId: string): Promise<Uint8Array>;
-    } | null;
-}
-export declare function resolveLocalSecretFilePath(directoryPath: string, keyId: string): string;
+export { CLIENT_PASSWORD_SETUP_AUTO_UNLOCK_SECONDS } from "./client-password/crypto.js";
+export type { ClientPasswordPrompt, ClientPasswordReadiness, ClientPasswordSessionStatus, ClientPasswordSetupAction, ClientPasswordStorageOptions, } from "./client-password/types.js";
+export { resolveLocalSecretFilePath, createLegacyKeychainServiceName, } from "./client-password/context.js";
+export { createAgentBootstrapState } from "./client-password/bootstrap.js";
+export { describeClientPasswordLockedMessage, describeClientPasswordMigrationMessage, describeClientPasswordSetupMessage, } from "./client-password/messages.js";
+export { listLocalSecretFilesForTesting } from "./client-password/files.js";
+import type { ClientPasswordPrompt, ClientPasswordReadiness, ClientPasswordSessionStatus, ClientPasswordSetupAction, ClientPasswordStorageOptions } from "./client-password/types.js";
 export declare function inspectClientPasswordReadiness(options: ClientPasswordStorageOptions): Promise<ClientPasswordReadiness>;
 export declare function readClientPasswordSessionStatus(options: ClientPasswordStorageOptions): Promise<ClientPasswordSessionStatus>;
 export declare function lockClientPasswordSession(options: ClientPasswordStorageOptions): Promise<ClientPasswordSessionStatus>;
@@ -49,17 +32,3 @@ export declare function unlockClientPasswordSession(options: ClientPasswordStora
 export declare function changeClientPassword(options: ClientPasswordStorageOptions & {
     prompt: ClientPasswordPrompt;
 }): Promise<ClientPasswordSessionStatus>;
-export declare function createLegacyKeychainServiceName(): string;
-export declare function createAgentBootstrapState(options: {
-    unlockUntilUnixMs: number;
-    derivedKeyBase64: string;
-}): {
-    unlockUntilUnixMs: number;
-    derivedKeyBase64: string;
-};
-export declare function describeClientPasswordLockedMessage(): string;
-export declare function describeClientPasswordSetupMessage(): string;
-export declare function describeClientPasswordMigrationMessage(): string;
-export declare function listLocalSecretFilesForTesting(options: {
-    directoryPath: string;
-}): Promise<string[]>;