@cogcoin/client 0.5.0

package/dist/wallet/state/provider.d.ts

@@ -0,0 +1,37 @@
+export interface LinuxSecretToolResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+}
+export interface LinuxSecretToolInvocationOptions {
+    stdin?: string;
+}
+export type LinuxSecretToolRunner = (args: readonly string[], options?: LinuxSecretToolInvocationOptions) => Promise<LinuxSecretToolResult>;
+export interface DefaultWalletSecretProviderFactoryOptions {
+    platform?: NodeJS.Platform;
+    linuxSecretToolRunner?: LinuxSecretToolRunner;
+}
+export interface WalletSecretReference {
+    kind: string;
+    keyId: string;
+}
+export interface WalletSecretProvider {
+    readonly kind: string;
+    loadSecret(keyId: string): Promise<Uint8Array>;
+    storeSecret(keyId: string, secret: Uint8Array): Promise<void>;
+    deleteSecret(keyId: string): Promise<void>;
+}
+export declare function createWalletSecretReference(walletRootId: string): WalletSecretReference;
+export declare class MemoryWalletSecretProvider implements WalletSecretProvider {
+    #private;
+    readonly kind = "memory-test";
+    loadSecret(keyId: string): Promise<Uint8Array>;
+    storeSecret(keyId: string, secret: Uint8Array): Promise<void>;
+    deleteSecret(keyId: string): Promise<void>;
+}
+export declare function createDefaultWalletSecretProvider(): WalletSecretProvider;
+export declare function createDefaultWalletSecretProviderForTesting(options?: DefaultWalletSecretProviderFactoryOptions): WalletSecretProvider;
+export declare function createLazyDefaultWalletSecretProvider(): WalletSecretProvider;
+export declare function createMemoryWalletSecretProviderForTesting(): WalletSecretProvider;
+export declare function createWalletRootId(): string;

package/dist/wallet/state/provider.js

@@ -0,0 +1,312 @@
+import { randomUUID } from "node:crypto";
+import { execFile, spawn } from "node:child_process";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { resolveWalletRuntimePathsForTesting } from "../runtime.js";
+import { writeFileAtomic } from "../fs/atomic.js";
+const execFileAsync = promisify(execFile);
+const KEYCHAIN_SERVICE_NAME = "org.cogcoin.wallet";
+const LINUX_SECRET_TOOL_ATTRIBUTE_APPLICATION = "application";
+const LINUX_SECRET_TOOL_ATTRIBUTE_KIND = "secret-kind";
+const LINUX_SECRET_TOOL_ATTRIBUTE_KEY_ID = "key-id";
+const LINUX_SECRET_TOOL_SECRET_KIND = "wallet-secret";
+export function createWalletSecretReference(walletRootId) {
+    return {
+        kind: "wallet-state-key",
+        keyId: `wallet-state:${walletRootId}`,
+    };
+}
+function bytesToBase64(secret) {
+    return Buffer.from(secret).toString("base64");
+}
+function base64ToBytes(secret) {
+    return new Uint8Array(Buffer.from(secret, "base64"));
+}
+function createLinuxSecretToolAttributes(keyId) {
+    return [
+        LINUX_SECRET_TOOL_ATTRIBUTE_APPLICATION,
+        KEYCHAIN_SERVICE_NAME,
+        LINUX_SECRET_TOOL_ATTRIBUTE_KIND,
+        LINUX_SECRET_TOOL_SECRET_KIND,
+        LINUX_SECRET_TOOL_ATTRIBUTE_KEY_ID,
+        keyId,
+    ];
+}
+function createLinuxSecretToolError(message, cause) {
+    return cause === undefined ? new Error(message) : new Error(message, { cause });
+}
+function isLinuxSecretServiceUnavailableMessage(stderr) {
+    const normalized = stderr.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return false;
+    }
+    return normalized.includes("secret service")
+        || normalized.includes("org.freedesktop.secrets")
+        || normalized.includes("dbus")
+        || normalized.includes("d-bus")
+        || normalized.includes("cannot autolaunch")
+        || normalized.includes("no such secret collection")
+        || normalized.includes("collection is locked")
+        || normalized.includes("prompt dismissed")
+        || normalized.includes("not available");
+}
+function isLinuxSecretToolMissingSecretMessage(stderr) {
+    const normalized = stderr.trim().toLowerCase();
+    if (normalized.length === 0) {
+        return true;
+    }
+    return normalized.includes("no matching")
+        || normalized.includes("not found")
+        || normalized.includes("does not exist")
+        || normalized.includes("no such item")
+        || normalized.includes("no secret");
+}
+async function runLinuxSecretTool(args, options = {}) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn("secret-tool", [...args], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.once("error", reject);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("close", (exitCode, signal) => {
+            resolve({
+                stdout,
+                stderr,
+                exitCode,
+                signal,
+            });
+        });
+        child.stdin.on("error", (error) => {
+            if ("code" in error && error.code === "EPIPE") {
+                return;
+            }
+            reject(error);
+        });
+        child.stdin.end(options.stdin ?? undefined, "utf8");
+    });
+}
+export class MemoryWalletSecretProvider {
+    kind = "memory-test";
+    #values = new Map();
+    async loadSecret(keyId) {
+        const secret = this.#values.get(keyId);
+        if (secret === undefined) {
+            throw new Error(`wallet_secret_missing_${keyId}`);
+        }
+        return new Uint8Array(secret);
+    }
+    async storeSecret(keyId, secret) {
+        this.#values.set(keyId, new Uint8Array(secret));
+    }
+    async deleteSecret(keyId) {
+        this.#values.delete(keyId);
+    }
+}
+class MacOsKeychainWalletSecretProvider {
+    kind = "macos-keychain";
+    async loadSecret(keyId) {
+        try {
+            const { stdout } = await execFileAsync("security", [
+                "find-generic-password",
+                "-a",
+                keyId,
+                "-s",
+                KEYCHAIN_SERVICE_NAME,
+                "-w",
+            ]);
+            return base64ToBytes(stdout.trim());
+        }
+        catch (error) {
+            throw new Error(`wallet_secret_missing_${keyId}`, { cause: error });
+        }
+    }
+    async storeSecret(keyId, secret) {
+        await execFileAsync("security", [
+            "add-generic-password",
+            "-a",
+            keyId,
+            "-s",
+            KEYCHAIN_SERVICE_NAME,
+            "-w",
+            bytesToBase64(secret),
+            "-U",
+        ]);
+    }
+    async deleteSecret(keyId) {
+        await execFileAsync("security", [
+            "delete-generic-password",
+            "-a",
+            keyId,
+            "-s",
+            KEYCHAIN_SERVICE_NAME,
+        ]).catch(() => undefined);
+    }
+}
+class LinuxSecretToolWalletSecretProvider {
+    kind = "linux-secret-service";
+    #runner;
+    constructor(runner = runLinuxSecretTool) {
+        this.#runner = runner;
+    }
+    async #invoke(options) {
+        try {
+            const result = await this.#runner(options.args, {
+                stdin: options.stdin,
+            });
+            if (result.exitCode === 0) {
+                return result;
+            }
+            if (isLinuxSecretServiceUnavailableMessage(result.stderr)) {
+                throw createLinuxSecretToolError("wallet_secret_provider_linux_secret_service_unavailable");
+            }
+            if ((options.operation === "load" || options.ignoreMissing)
+                && isLinuxSecretToolMissingSecretMessage(result.stderr)) {
+                throw createLinuxSecretToolError(`wallet_secret_missing_${options.keyId}`);
+            }
+            throw createLinuxSecretToolError("wallet_secret_provider_linux_runtime_error");
+        }
+        catch (error) {
+            if (error instanceof Error
+                && (error.message === "wallet_secret_provider_linux_secret_tool_missing"
+                    || error.message === "wallet_secret_provider_linux_secret_service_unavailable"
+                    || error.message === "wallet_secret_provider_linux_runtime_error"
+                    || error.message === `wallet_secret_missing_${options.keyId}`)) {
+                throw error;
+            }
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                throw createLinuxSecretToolError("wallet_secret_provider_linux_secret_tool_missing", error);
+            }
+            throw createLinuxSecretToolError("wallet_secret_provider_linux_runtime_error", error);
+        }
+    }
+    async loadSecret(keyId) {
+        const result = await this.#invoke({
+            args: ["lookup", ...createLinuxSecretToolAttributes(keyId)],
+            keyId,
+            operation: "load",
+        });
+        return base64ToBytes(result.stdout.trim());
+    }
+    async storeSecret(keyId, secret) {
+        await this.#invoke({
+            args: [
+                "store",
+                "--label",
+                `Cogcoin wallet secret (${keyId})`,
+                ...createLinuxSecretToolAttributes(keyId),
+            ],
+            keyId,
+            operation: "store",
+            stdin: bytesToBase64(secret),
+        });
+    }
+    async deleteSecret(keyId) {
+        try {
+            await this.#invoke({
+                args: ["clear", ...createLinuxSecretToolAttributes(keyId)],
+                keyId,
+                operation: "delete",
+                ignoreMissing: true,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === `wallet_secret_missing_${keyId}`) {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+class WindowsDpapiWalletSecretProvider {
+    kind = "windows-dpapi";
+    #directoryPath;
+    constructor(directoryPath) {
+        this.#directoryPath = directoryPath;
+    }
+    #resolveSecretPath(keyId) {
+        const fileId = keyId.replace(/[^a-zA-Z0-9._-]+/g, "-");
+        return join(this.#directoryPath, `${fileId}.dpapi`);
+    }
+    async loadSecret(keyId) {
+        const secretPath = this.#resolveSecretPath(keyId);
+        const encoded = await readFile(secretPath, "utf8");
+        const { stdout } = await execFileAsync("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "$data=[Convert]::FromBase64String($args[0]);$value=[System.Security.Cryptography.ProtectedData]::Unprotect($data,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Convert]::ToBase64String($value));",
+            encoded.trim(),
+        ]);
+        return base64ToBytes(stdout.trim());
+    }
+    async storeSecret(keyId, secret) {
+        const secretPath = this.#resolveSecretPath(keyId);
+        await mkdir(dirname(secretPath), { recursive: true });
+        const { stdout } = await execFileAsync("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "$data=[Convert]::FromBase64String($args[0]);$value=[System.Security.Cryptography.ProtectedData]::Protect($data,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser);[Console]::Out.Write([Convert]::ToBase64String($value));",
+            bytesToBase64(secret),
+        ]);
+        await writeFileAtomic(secretPath, `${stdout.trim()}\n`, { mode: 0o600 });
+    }
+    async deleteSecret(keyId) {
+        await rm(this.#resolveSecretPath(keyId), { force: true }).catch(() => undefined);
+    }
+}
+function createWalletSecretProviderForPlatform(platform, options = {}) {
+    if (platform === "darwin") {
+        return new MacOsKeychainWalletSecretProvider();
+    }
+    if (platform === "win32") {
+        return new WindowsDpapiWalletSecretProvider(join(resolveWalletRuntimePathsForTesting().stateRoot, "secrets"));
+    }
+    if (platform === "linux") {
+        return new LinuxSecretToolWalletSecretProvider(options.linuxSecretToolRunner);
+    }
+    throw new Error(`wallet_secret_provider_unsupported_${platform}`);
+}
+export function createDefaultWalletSecretProvider() {
+    return createWalletSecretProviderForPlatform(process.platform);
+}
+export function createDefaultWalletSecretProviderForTesting(options = {}) {
+    return createWalletSecretProviderForPlatform(options.platform ?? process.platform, options);
+}
+export function createLazyDefaultWalletSecretProvider() {
+    let resolved = null;
+    const getResolved = () => {
+        resolved ??= createDefaultWalletSecretProvider();
+        return resolved;
+    };
+    return {
+        get kind() {
+            return resolved?.kind ?? "lazy-default";
+        },
+        async loadSecret(keyId) {
+            return getResolved().loadSecret(keyId);
+        },
+        async storeSecret(keyId, secret) {
+            await getResolved().storeSecret(keyId, secret);
+        },
+        async deleteSecret(keyId) {
+            await getResolved().deleteSecret(keyId);
+        },
+    };
+}
+export function createMemoryWalletSecretProviderForTesting() {
+    return new MemoryWalletSecretProvider();
+}
+export function createWalletRootId() {
+    return `wallet-${randomUUID().replaceAll("-", "")}`;
+}

package/dist/wallet/state/session.d.ts

@@ -0,0 +1,12 @@
+import type { UnlockSessionStateV1 } from "../types.js";
+import type { WalletSecretProvider, WalletSecretReference } from "./provider.js";
+export type UnlockSessionSaveAccess = Uint8Array | string | {
+    provider: WalletSecretProvider;
+    secretReference: WalletSecretReference;
+};
+export type UnlockSessionLoadAccess = Uint8Array | string | {
+    provider: WalletSecretProvider;
+};
+export declare function saveUnlockSession(sessionPath: string, session: UnlockSessionStateV1, access: UnlockSessionSaveAccess): Promise<void>;
+export declare function loadUnlockSession(sessionPath: string, access: UnlockSessionLoadAccess): Promise<UnlockSessionStateV1>;
+export declare function clearUnlockSession(sessionPath: string): Promise<void>;

package/dist/wallet/state/session.js

@@ -0,0 +1,23 @@
+import { readFile, rm } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../fs/atomic.js";
+import { decryptJsonWithPassphrase, decryptJsonWithSecretProvider, encryptJsonWithPassphrase, encryptJsonWithSecretProvider, } from "./crypto.js";
+export async function saveUnlockSession(sessionPath, session, access) {
+    const envelope = typeof access === "string" || access instanceof Uint8Array
+        ? await encryptJsonWithPassphrase(session, access, {
+            format: "cogcoin-wallet-unlock-session",
+        })
+        : await encryptJsonWithSecretProvider(session, access.provider, access.secretReference, {
+            format: "cogcoin-wallet-unlock-session",
+        });
+    await writeJsonFileAtomic(sessionPath, envelope, { mode: 0o600 });
+}
+export async function loadUnlockSession(sessionPath, access) {
+    const raw = await readFile(sessionPath, "utf8");
+    const envelope = JSON.parse(raw);
+    return typeof access === "string" || access instanceof Uint8Array
+        ? decryptJsonWithPassphrase(envelope, access)
+        : decryptJsonWithSecretProvider(envelope, access.provider);
+}
+export async function clearUnlockSession(sessionPath) {
+    await rm(sessionPath, { force: true });
+}

package/dist/wallet/state/storage.d.ts

@@ -0,0 +1,19 @@
+import type { WalletStateV1 } from "../types.js";
+import type { WalletSecretProvider, WalletSecretReference } from "./provider.js";
+export interface WalletStateStoragePaths {
+    primaryPath: string;
+    backupPath: string;
+}
+export interface LoadedWalletState {
+    source: "primary" | "backup";
+    state: WalletStateV1;
+}
+export type WalletStateSaveAccess = Uint8Array | string | {
+    provider: WalletSecretProvider;
+    secretReference: WalletSecretReference;
+};
+export type WalletStateLoadAccess = Uint8Array | string | {
+    provider: WalletSecretProvider;
+};
+export declare function saveWalletState(paths: WalletStateStoragePaths, state: WalletStateV1, access: WalletStateSaveAccess): Promise<void>;
+export declare function loadWalletState(paths: WalletStateStoragePaths, access: WalletStateLoadAccess): Promise<LoadedWalletState>;

package/dist/wallet/state/storage.js

@@ -0,0 +1,55 @@
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "../fs/atomic.js";
+import { decryptJsonWithPassphrase, decryptJsonWithSecretProvider, encryptJsonWithPassphrase, encryptJsonWithSecretProvider, } from "./crypto.js";
+async function readEnvelope(path) {
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+export async function saveWalletState(paths, state, access) {
+    let previousPrimary = null;
+    try {
+        previousPrimary = await readEnvelope(paths.primaryPath);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            previousPrimary = null;
+        }
+        else if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) {
+            throw error;
+        }
+    }
+    const envelope = typeof access === "string" || access instanceof Uint8Array
+        ? await encryptJsonWithPassphrase(state, access, {
+            format: "cogcoin-local-wallet-state",
+        })
+        : await encryptJsonWithSecretProvider(state, access.provider, access.secretReference, {
+            format: "cogcoin-local-wallet-state",
+        });
+    await writeJsonFileAtomic(paths.primaryPath, envelope, { mode: 0o600 });
+    if (previousPrimary !== null) {
+        await writeJsonFileAtomic(paths.backupPath, previousPrimary, { mode: 0o600 });
+    }
+}
+export async function loadWalletState(paths, access) {
+    try {
+        return {
+            source: "primary",
+            state: typeof access === "string" || access instanceof Uint8Array
+                ? await decryptJsonWithPassphrase(await readEnvelope(paths.primaryPath), access)
+                : await decryptJsonWithSecretProvider(await readEnvelope(paths.primaryPath), access.provider),
+        };
+    }
+    catch (primaryError) {
+        try {
+            return {
+                source: "backup",
+                state: typeof access === "string" || access instanceof Uint8Array
+                    ? await decryptJsonWithPassphrase(await readEnvelope(paths.backupPath), access)
+                    : await decryptJsonWithSecretProvider(await readEnvelope(paths.backupPath), access.provider),
+            };
+        }
+        catch {
+            throw primaryError;
+        }
+    }
+}

package/dist/wallet/tx/anchor.d.ts

@@ -0,0 +1,40 @@
+import { attachOrStartManagedBitcoindService } from "../../bitcoind/service.js";
+import { createRpcClient } from "../../bitcoind/node.js";
+import type { RpcTransaction } from "../../bitcoind/types.js";
+import type { WalletPrompter } from "../lifecycle.js";
+import { type WalletRuntimePaths } from "../runtime.js";
+import { type WalletSecretProvider } from "../state/provider.js";
+import { openWalletReadContext } from "../read/index.js";
+import { type WalletMutationRpcClient } from "./common.js";
+interface WalletAnchorRpcClient extends WalletMutationRpcClient {
+    getBlockchainInfo(): Promise<{
+        blocks: number;
+    }>;
+    sendRawTransaction(hex: string): Promise<string>;
+    getRawMempool(): Promise<string[]>;
+    getRawTransaction(txid: string, verbose?: boolean): Promise<RpcTransaction>;
+}
+export interface AnchorDomainOptions {
+    domainName: string;
+    foundingMessageText?: string | null;
+    dataDir: string;
+    databasePath: string;
+    provider?: WalletSecretProvider;
+    prompter: WalletPrompter;
+    nowUnixMs?: number;
+    paths?: WalletRuntimePaths;
+    openReadContext?: typeof openWalletReadContext;
+    attachService?: typeof attachOrStartManagedBitcoindService;
+    rpcFactory?: (config: Parameters<typeof createRpcClient>[0]) => WalletAnchorRpcClient;
+}
+export interface AnchorDomainResult {
+    domainName: string;
+    txid: string;
+    tx1Txid: string;
+    tx2Txid: string;
+    dedicatedIndex: number;
+    status: "live" | "confirmed";
+    reusedExisting: boolean;
+}
+export declare function anchorDomain(options: AnchorDomainOptions): Promise<AnchorDomainResult>;
+export {};