@attocash/cli 0.1.0

package/dist/cli/updates.js

@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gt, prerelease, valid } from 'semver';
+const checkInterval = 24 * 60 * 60 * 1000;
+const maxCacheBytes = 4096;
+function stableVersion(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const version = valid(value);
+    return version && prerelease(version) === null ? version : undefined;
+}
+function readCache(file) {
+    try {
+        if (statSync(file).size > maxCacheBytes)
+            return undefined;
+        const cache = JSON.parse(readFileSync(file, 'utf8'));
+        if (!cache || typeof cache.checkedAt !== 'number' || !Number.isFinite(cache.checkedAt) || cache.checkedAt < 0)
+            return undefined;
+        return { checkedAt: cache.checkedAt, latest: stableVersion(cache.latest) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCache(file, cache) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+        writeFileSync(temporary, JSON.stringify(cache), { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+// Only the CLI calls this module; shared wallet operations and MCP have no
+// update-check side effects. Network work runs in an independent, short-lived child.
+export function notifyUpdate(currentVersion) {
+    try {
+        if (!process.stdout.isTTY || !process.stderr.isTTY ||
+            (process.env.CI && process.env.CI !== 'false') || process.env.NODE_ENV === 'test' ||
+            process.env.NO_UPDATE_NOTIFIER !== undefined || !valid(currentVersion))
+            return;
+        const directory = process.platform === 'win32'
+            ? join(process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local'), 'atto-cli', 'Cache')
+            : process.platform === 'darwin'
+                ? join(homedir(), 'Library', 'Caches', 'atto-cli')
+                : join(process.env.XDG_CACHE_HOME && isAbsolute(process.env.XDG_CACHE_HOME)
+                    ? process.env.XDG_CACHE_HOME : join(homedir(), '.cache'), 'atto-cli');
+        const file = join(directory, 'update.json');
+        const cache = readCache(file);
+        if (cache?.latest && gt(cache.latest, currentVersion)) {
+            process.stderr.write(`Atto CLI update available: ${currentVersion} → ${cache.latest}\nUpdate: npm install --global @attocash/cli@${cache.latest}\n`);
+        }
+        const now = Date.now();
+        const age = cache ? now - cache.checkedAt : undefined;
+        if (age !== undefined && age >= 0 && age < checkInterval)
+            return;
+        // Reserve the attempt before spawning, so an unavailable registry or a
+        // failed child does not cause a new request on every command invocation.
+        writeCache(file, { checkedAt: now, latest: cache?.latest });
+        const child = spawn(process.execPath, [fileURLToPath(new URL('./update-check.js', import.meta.url)), file], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // Update notices are optional, including when the cache cannot be written.
+    }
+}
+export async function refreshUpdateCache(file) {
+    try {
+        const cache = readCache(file);
+        if (!cache)
+            return;
+        const response = await fetch('https://registry.npmjs.org/@attocash%2fcli/latest', {
+            signal: AbortSignal.timeout(3000),
+            redirect: 'error',
+            headers: { Accept: 'application/json' },
+        });
+        if (!response.ok)
+            return;
+        const metadata = await response.json();
+        const latest = metadata?.name === '@attocash/cli' ? stableVersion(metadata.version) : undefined;
+        if (latest)
+            writeCache(file, { checkedAt: cache.checkedAt, latest });
+    }
+    catch {
+        // Keep the last known version and attempt timestamp after any failure.
+    }
+}

package/dist/core.d.ts

@@ -0,0 +1,14 @@
+export { operations, type Operation } from './application/operations.js';
+export { errorResult } from './domain/errors.js';
+export { runDoctor, type DoctorOptions, type DoctorReport, type DoctorCheck, type DoctorStatus } from './doctor/doctor.js';
+/** Public wallet operations and their session lifetime. Recovery stays in the CLI. */
+export interface ApplicationSession {
+    call(name: string, input?: Record<string, unknown>): Promise<unknown>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+}
+export interface ApplicationOptions {
+    directory?: string;
+    access?: 'mcp';
+}
+export declare function createApplication(options?: ApplicationOptions): ApplicationSession;

package/dist/core.js

@@ -0,0 +1,14 @@
+import { AttoApplication } from './application/app.js';
+export { operations } from './application/operations.js';
+export { errorResult } from './domain/errors.js';
+export { runDoctor } from './doctor/doctor.js';
+export function createApplication(options = {}) {
+    const application = new AttoApplication(options);
+    // Expose only the supported session contract, including at runtime. Terminal
+    // recovery methods and mutable storage are not part of the library API.
+    return {
+        call: application.call.bind(application),
+        start: application.start.bind(application),
+        close: application.close.bind(application),
+    };
+}

package/dist/doctor/credential-probe.d.ts

@@ -0,0 +1,7 @@
+export type CredentialResult = 'matched' | 'readable' | 'missing' | 'invalid' | 'mismatch' | 'unavailable' | 'backend_unavailable' | 'timeout';
+export interface CredentialRequest {
+    service: 'Atto CLI' | 'Atto MCP';
+    account: string;
+    address?: string;
+    fingerprint?: string;
+}

package/dist/doctor/credential-probe.js

@@ -0,0 +1,49 @@
+// This process receives public identifiers only. Recovery material never leaves it.
+process.env.KOTLIN_LOGGING_STARTUP_MESSAGE = 'false';
+console.log = console.info = console.debug = console.error = () => { };
+process.once('message', async (request) => {
+    let result = 'unavailable';
+    try {
+        if (process.platform !== 'linux') {
+            try {
+                await import('@napi-rs/keyring');
+            }
+            catch {
+                process.send?.('backend_unavailable');
+                process.disconnect?.();
+                return;
+            }
+        }
+        const { OsSecretStore } = await import('../storage/secrets.js');
+        const phrase = await new OsSecretStore(request.account, request.service).get();
+        if (phrase === null)
+            result = 'missing';
+        else {
+            result = 'invalid';
+            const { mnemonicSeed } = await import('../wallet/signing.js');
+            const { AttoAlgorithm, toAttoIndex } = await import('@attocash/commons-core');
+            const { createHash } = await import('node:crypto');
+            const seed = await mnemonicSeed(phrase);
+            try {
+                const key = await seed.toPrivateKey(toAttoIndex(0));
+                try {
+                    const publicKey = await key.toPublicKey();
+                    const address = publicKey.toAddress(AttoAlgorithm.V1).value;
+                    const fingerprint = createHash('sha256').update(publicKey.toString()).digest('hex');
+                    result = request.address === undefined ? 'readable'
+                        : request.address === address && request.fingerprint === fingerprint ? 'matched' : 'mismatch';
+                }
+                finally {
+                    key.value.fill(0);
+                }
+            }
+            finally {
+                seed.value.fill(0);
+            }
+        }
+    }
+    catch { /* Only the allowlisted result is returned, never dependency diagnostics. */ }
+    process.send?.(result);
+    process.disconnect?.();
+});
+export {};

package/dist/doctor/doctor.d.ts

@@ -0,0 +1,4 @@
+import type { DoctorOptions, DoctorReport } from './types.js';
+export type { DoctorCheck, DoctorOptions, DoctorReport, DoctorStatus } from './types.js';
+/** Full diagnostics, independent of application startup and without wallet mutations. */
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorReport>;

package/dist/doctor/doctor.js

@@ -0,0 +1,213 @@
+import { fetchDirectory, DIRECTORY_URL } from '../labels/directory.js';
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { AttoAccount, AttoBlock, AttoInstant } from '@attocash/commons-core';
+import { satisfies } from 'semver';
+import { AttoError } from '../domain/errors.js';
+import { NodeReader } from '../network/reader.js';
+import { requestWork } from '../network/work.js';
+import { MarketData } from '../pricing/market.js';
+import { dedicatedMcpDirectory, inspectWalletProfile } from '../storage/profiles.js';
+import { checkKeyring } from './keyring.js';
+import { readDoctorProfile } from './profile.js';
+const skipped = (id, message) => ({ id, status: 'skipped', code: 'CHECK_PREREQUISITE_UNAVAILABLE', message });
+function failure(id, error, signal, steps, warn = false) {
+    // Never include upstream messages or bodies; even SDK failures may contain sensitive data.
+    const denied = id === 'profile' && ['EACCES', 'EPERM'].includes(error?.code ?? '');
+    const code = signal.aborted ? 'CHECK_TIMEOUT' : error instanceof AttoError ? error.code : denied ? 'PROFILE_ACCESS_DENIED' : id === 'profile' ? 'PROFILE_STATE_INVALID' : 'CHECK_FAILED';
+    const httpStatus = error instanceof AttoError ? error.details?.httpStatus : undefined;
+    return { id, status: warn ? 'warn' : 'fail', code,
+        message: signal.aborted ? 'The check did not complete before its deadline or was cancelled.'
+            : denied ? 'This process lacks the file or directory access needed to use the profile.'
+                : code === 'STATE_VERSION' ? 'The state database version is not supported by this CLI.'
+                    : code === 'PROFILE_STATE_INVALID' ? 'The selected state database or its public wallet data is invalid or unreadable.'
+                        : 'The check failed. Follow the suggested steps and rerun doctor.',
+        ...(typeof httpStatus === 'number' && Number.isInteger(httpStatus) ? { evidence: { httpStatus } } : {}), remediation: { steps } };
+}
+async function checkNode(profile, overall) {
+    const reader = new NodeReader(profile.settings);
+    const checks = [];
+    const signal = AbortSignal.any([overall, AbortSignal.timeout(10_000)]);
+    const fix = ['Verify nodeUrl with wallet status; use wallet configure --node-url only after selecting the intended endpoint.', 'Check network connectivity, TLS trust, and whether the server exposes the Atto public APIs.'];
+    let account = null;
+    const selectedAddress = profile.identity?.address ?? profile.settings.representative;
+    const lookupAccount = async (address) => {
+        const value = await reader.account(address, signal);
+        if (value && value.address.value !== address)
+            throw new AttoError('ACCOUNT_MISMATCH', 'The node returned another account.');
+        return value;
+    };
+    // Time and account APIs are independent; a clock endpoint alone does not prove account access.
+    const results = await Promise.allSettled([
+        reader.now(signal),
+        lookupAccount(selectedAddress),
+    ]);
+    const time = results[0];
+    if (time.status === 'fulfilled') {
+        const offsetMs = Number(time.value.toEpochMilliseconds() - BigInt(Date.now()));
+        checks.push({ id: 'node.time', status: Math.abs(offsetMs) > 60_000 ? 'warn' : 'pass', code: Math.abs(offsetMs) > 60_000 ? 'CLOCK_SKEW' : 'NODE_TIME_OK',
+            message: 'The node time API returned a valid response.', evidence: { offsetMs },
+            ...(Math.abs(offsetMs) > 60_000 ? { remediation: { steps: ['Check OS time synchronization and the configured node clock.'] } } : {}) });
+    }
+    else
+        checks.push(failure('node.time', time.reason, signal, fix));
+    const lookup = results[1];
+    if (lookup.status === 'fulfilled') {
+        account = lookup.value;
+        checks.push({ id: 'node.account', status: 'pass', code: account ? 'NODE_ACCOUNT_OK' : 'ACCOUNT_NOT_OPEN',
+            message: account ? 'The account API returned a valid account.' : 'The account API returned not found; the queried account may not be open.' });
+    }
+    else
+        checks.push(failure('node.account', lookup.reason, signal, fix));
+    if (lookup.status === 'fulfilled' && !account && selectedAddress !== profile.settings.representative) {
+        try {
+            account = await lookupAccount(profile.settings.representative);
+            checks.push({ id: 'node.representative', status: account ? 'pass' : 'warn', code: account ? 'NODE_REPRESENTATIVE_OK' : 'REPRESENTATIVE_NOT_OPEN',
+                message: account ? 'The configured representative provides an existing account for network and stream checks.' : 'The configured representative is also unopened; network and stream verification need an existing account.' });
+        }
+        catch (error) {
+            checks.push(failure('node.representative', error, signal, fix));
+        }
+    }
+    if (!account)
+        return [...checks, skipped('node.network', 'No existing account was available to verify the node network.'), skipped('node.stream', 'No existing account was available for an observable account-stream snapshot.')];
+    checks.push({ id: 'node.network', status: account.network.name === profile.settings.network ? 'pass' : 'fail',
+        code: account.network.name === profile.settings.network ? 'NODE_NETWORK_MATCHED' : 'NETWORK_MISMATCH',
+        message: 'Compared the account network with the wallet configuration.', evidence: { configured: profile.settings.network, observed: account.network.name },
+        ...(account.network.name === profile.settings.network ? {} : { remediation: { steps: ['Select node and worker endpoints for the intended network. A network setting alone does not change endpoints.'] } }) });
+    const streamDone = new AbortController();
+    const deadline = AbortSignal.any([overall, AbortSignal.timeout(10_000)]);
+    let observed = false;
+    try {
+        await reader.stream({ event: 'account', addresses: [account.address.value] }, model => {
+            if (!(model instanceof AttoAccount) || model.address.value !== account.address.value || model.network.name !== account.network.name)
+                throw new AttoError('ACCOUNT_MISMATCH', 'Unexpected account stream result.');
+            observed = true;
+            streamDone.abort();
+        }, AbortSignal.any([deadline, streamDone.signal]));
+        checks.push({ id: 'node.stream', status: observed ? 'pass' : 'warn', code: observed ? 'NODE_STREAM_OK' : 'NODE_STREAM_UNVERIFIED',
+            message: observed ? 'Commons received an account snapshot and closed the subscription.' : 'No account snapshot was observed during the check. An idle stream alone does not prove a failure.' });
+    }
+    catch (error) {
+        checks.push(failure('node.stream', error, deadline, fix));
+    }
+    finally {
+        streamDone.abort();
+    }
+    return checks;
+}
+async function checkWorker(profile, overall) {
+    const signal = AbortSignal.any([overall, AbortSignal.timeout(30_000)]);
+    try {
+        // A fresh public target ensures a real request; this block has no signer or funds.
+        const block = AttoBlock.fromJson(JSON.stringify({ type: 'CHANGE', network: profile.settings.network, version: 0, algorithm: 'V1',
+            publicKey: '11'.repeat(32), height: 2, balance: 0, timestamp: Number(AttoInstant.Companion.now().toEpochMilliseconds()),
+            previous: randomBytes(32).toString('hex'), representativeAlgorithm: 'V1', representativePublicKey: '11'.repeat(32) }));
+        await requestWork(block, profile.settings.workerUrl, signal);
+        return { id: 'worker.work', status: 'pass', code: 'WORKER_WORK_VALID', message: 'The worker generated fresh proof of work validated by Commons. Nothing was signed, published, or cached.' };
+    }
+    catch (error) {
+        return failure('worker.work', error, signal, ['Verify workerUrl and its network with wallet status.', 'Check worker connectivity and capacity. Run wallet configure --worker-url only after selecting the intended endpoint.']);
+    }
+}
+async function checkPrice(profile, overall) {
+    if (profile.settings.network !== 'LIVE')
+        return skipped('usd.price', 'USD-priced payments are available on LIVE only.');
+    const signal = AbortSignal.any([overall, AbortSignal.timeout(10_000)]);
+    try {
+        const quote = await new MarketData().quoteUsd('1', signal);
+        return { id: 'usd.price', status: 'pass', code: 'USD_PRICE_AVAILABLE', message: 'An indicative USD conversion is available; it is not an executable exchange quote.', evidence: { source: quote.source, priceDate: quote.priceDate } };
+    }
+    catch (error) {
+        return failure('usd.price', error, signal, ['Check the market metrics service and price observation date. Ordinary ATTO payments do not require USD pricing.'], true);
+    }
+}
+async function checkDirectory(profile, signal) {
+    if (profile.settings.network !== 'LIVE')
+        return skipped('labels.directory', 'The public directory applies to LIVE only.');
+    try {
+        const snapshot = await fetchDirectory(fetch, signal);
+        return { id: 'labels.directory', status: 'pass', code: 'DIRECTORY_AVAILABLE', message: 'The global address directory is available. No cache was updated.',
+            evidence: { source: DIRECTORY_URL, addresses: snapshot.addresses.length, voters: snapshot.voters.length } };
+    }
+    catch (error) {
+        return failure('labels.directory', error, signal, ['Check public directory connectivity. Personal-label payments use local storage and do not need this service.'], true);
+    }
+}
+function readiness(profile, options, directory) {
+    const checks = [{ id: 'wallet.initialization', status: profile.identity ? 'pass' : 'warn',
+            code: profile.identity ? 'WALLET_INITIALIZED' : 'WALLET_NOT_INITIALIZED', message: profile.identity ? 'A public wallet identity is saved.' : 'This profile has no initialized wallet.',
+            ...(!profile.identity ? { remediation: { steps: ['Create or import a wallet in your local terminal using this data directory.'], command: ['atto', '--data-dir', directory, 'wallet', 'create'] } } : {}) }];
+    if (profile.resetPending)
+        checks.push({ id: 'wallet.reset', status: 'fail', code: 'WALLET_RESET_REQUIRED', message: 'A previously requested wallet reset is unfinished.', remediation: { steps: ['Review wallet status and your backups in a local terminal before explicitly resuming the reset. Doctor does not resume it.'] } });
+    checks.push({ id: 'wallet.receiving', status: 'pass', code: 'RECEIVING_CONFIGURATION', message: 'Receiving prerequisites are configuration, not a receiver started by doctor.',
+        evidence: { enabled: profile.settings.autoReceive, activeAccounts: profile.addresses.filter(address => address.active).length,
+            ...(options.access === 'mcp' ? { approvedMcpAccess: profile.access, poolIndexes: profile.poolIndexes } : {}) } });
+    if (profile.identity && profile.settings.autoReceive && !profile.addresses.some(address => address.active))
+        checks.push({ id: 'wallet.activeAccounts', status: 'warn', code: 'NO_ACTIVE_ACCOUNTS', message: 'Receiving is enabled without any active accounts.', remediation: { steps: ['Activate a saved account to receive automatically.'], command: ['atto', '--data-dir', directory, 'address', 'activate', '0'] } });
+    if (options.access === 'mcp')
+        checks.push({ id: 'wallet.mcpAccess', status: 'pass', code: profile.access === 'spend' ? 'MCP_SPENDING_APPROVED' : 'MCP_READ_ONLY',
+            message: profile.access === 'spend' ? 'MCP spending access is approved, subject to the saved policy.' : 'Read-only MCP access is intentional. Spending needs a proposal and approval by the user in a local terminal; doctor cannot grant it.' });
+    checks.push({ id: 'wallet.pendingPayments', status: profile.pendingPayments ? 'warn' : 'pass', code: profile.pendingPayments ? 'PAYMENTS_UNFINISHED' : 'NO_PENDING_PAYMENTS',
+        message: profile.pendingPayments ? 'Unfinished payment records need inspection; doctor has not reconciled or retried them.' : 'No unfinished payment records are saved.', evidence: { count: profile.pendingPayments },
+        ...(profile.pendingPayments ? { remediation: { steps: ['Inspect the journal and retain original request IDs when checking existing payments.'], command: ['atto', '--data-dir', directory, 'journal', 'list'] } } : {}) });
+    if (profile.settings.network === 'LIVE')
+        checks.push({ id: 'usd.terms', status: profile.termsAccepted ? 'pass' : 'warn', code: profile.termsAccepted ? 'USD_TERMS_ACCEPTED' : 'USD_TERMS_REQUIRED',
+            message: profile.termsAccepted ? 'The current USD payment terms are accepted.' : 'USD payments require the user to read and explicitly accept the current terms. Ordinary ATTO payments do not.',
+            ...(!profile.termsAccepted ? { remediation: { steps: ['Show the terms to the user before requesting their acceptance.'], command: ['atto', '--data-dir', directory, 'terms', 'show'] } } : {}) });
+    return checks;
+}
+/** Full diagnostics, independent of application startup and without wallet mutations. */
+export async function runDoctor(options = {}) {
+    const started = Date.now();
+    const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 60_000);
+    const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
+    const report = { status: 'pass', context: { interface: options.access ?? 'cli', executable: process.execPath,
+            nodeVersion: process.version, cliVersion: pkg.version, platform: `${process.platform}/${process.arch}` }, checks: [], durationMs: 0 };
+    try {
+        const supported = satisfies(process.version, pkg.engines.node);
+        report.checks.push({ id: 'runtime', status: supported ? 'pass' : 'fail', code: supported ? 'RUNTIME_SUPPORTED' : 'RUNTIME_UNSUPPORTED', message: `This package requires Node.js ${pkg.engines.node}.` });
+        let profile;
+        let snapshot;
+        try {
+            const directory = options.directory ?? (options.access === 'mcp' ? dedicatedMcpDirectory() : undefined);
+            if (directory)
+                report.context.directory = resolve(directory);
+            profile = inspectWalletProfile(directory);
+            Object.assign(report.context, profile);
+            snapshot = readDoctorProfile(profile.directory);
+            Object.assign(report.context, { network: snapshot.settings.network, nodeUrl: snapshot.settings.nodeUrl, workerUrl: snapshot.settings.workerUrl, settingsSource: snapshot.settingsSource });
+            report.checks.push({ id: 'profile', status: 'pass', code: 'PROFILE_READABLE', message: snapshot.settingsSource === 'defaults' ? 'No state database exists. Checks use labelled defaults without creating a profile.' : 'The public wallet snapshot is readable and its directory is accessible.' });
+            if (snapshot.permissions)
+                report.checks.push({ id: 'profile.permissions', status: snapshot.permissions.private ? 'pass' : 'warn',
+                    code: snapshot.permissions.private ? 'PROFILE_PERMISSIONS_PRIVATE' : 'PROFILE_PERMISSIONS_BROAD',
+                    message: snapshot.permissions.private ? 'The profile directory and database restrict access to their owner.' : 'The profile directory or database allows access by other OS users.',
+                    evidence: snapshot.permissions,
+                    ...(!snapshot.permissions.private ? { remediation: { steps: ['Review ownership and permissions for this data directory and state.sqlite. Restrict the directory to mode 700 and the database to mode 600. Doctor has not changed them.'] } } : {}) });
+        }
+        catch (error) {
+            report.checks.push(failure('profile', error, signal, ['Verify the data directory, file permissions, and supported wallet state version.', 'Preserve the existing profile and restore valid metadata or state from its backup; do not reset the wallet to fix access.']));
+            for (const id of ['keyring.credential', 'node.time', 'node.account', 'node.network', 'node.stream', 'worker.work', 'wallet.readiness', 'usd.price'])
+                report.checks.push(skipped(id, 'The selected profile could not be inspected safely. No alternate profile or endpoints were substituted.'));
+            return report;
+        }
+        report.checks.push(...readiness(snapshot, options, profile.directory));
+        const jobs = await Promise.allSettled([checkKeyring(profile, snapshot.identity, signal), checkNode(snapshot, signal), checkWorker(snapshot, signal), checkPrice(snapshot, signal), ...(options.globalDirectory ? [checkDirectory(snapshot, signal)] : [])]);
+        for (const [index, job] of jobs.entries()) {
+            if (job.status === 'fulfilled')
+                report.checks.push(...(Array.isArray(job.value) ? job.value : [job.value]));
+            else
+                report.checks.push(failure(['keyring.credential', 'node', 'worker.work', 'usd.price', 'labels.directory'][index], job.reason, signal, ['Rerun doctor from the same launch environment.']));
+        }
+        return report;
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        report.status = report.checks.some(check => check.status === 'fail') ? 'fail' : report.checks.some(check => check.status === 'warn') ? 'warn' : 'pass';
+        report.durationMs = Date.now() - started;
+    }
+}

package/dist/doctor/keyring.d.ts

@@ -0,0 +1,7 @@
+import type { WalletProfile } from '../storage/profiles.js';
+import type { WalletIdentity } from '../wallet/types.js';
+import type { DoctorCheck } from './types.js';
+import type { CredentialRequest, CredentialResult } from './credential-probe.js';
+/** Bound native keyring calls too, and terminate any secret-tool subprocess with its parent. */
+export declare function probeCredential(request: CredentialRequest, signal: AbortSignal, env?: NodeJS.ProcessEnv): Promise<CredentialResult>;
+export declare function checkKeyring(profile: WalletProfile, identity: WalletIdentity | undefined, signal: AbortSignal): Promise<DoctorCheck[]>;

package/dist/doctor/keyring.js

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process';
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Bound native keyring calls too, and terminate any secret-tool subprocess with its parent. */
+export function probeCredential(request, signal, env = process.env) {
+    return new Promise(resolve => {
+        if (signal.aborted) {
+            resolve('timeout');
+            return;
+        }
+        const child = spawn(process.execPath, [fileURLToPath(new URL('./credential-probe.js', import.meta.url))], {
+            env, stdio: ['ignore', 'ignore', 'ignore', 'ipc'], detached: process.platform !== 'win32', windowsHide: true,
+        });
+        let result = 'unavailable';
+        let stopped = false;
+        const stop = () => {
+            stopped = true;
+            result = 'timeout';
+            if (child.pid) {
+                try {
+                    if (process.platform === 'win32')
+                        child.kill('SIGKILL');
+                    else
+                        process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* The child may already have exited. */ }
+            }
+        };
+        const timer = setTimeout(stop, 30_000);
+        signal.addEventListener('abort', stop, { once: true });
+        child.on('message', value => {
+            if (!stopped && !signal.aborted && typeof value === 'string' && ['matched', 'readable', 'missing', 'invalid', 'mismatch', 'unavailable', 'backend_unavailable'].includes(value))
+                result = value;
+        });
+        child.on('error', () => { });
+        child.once('close', () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', stop);
+            resolve(result);
+        });
+        child.once('spawn', () => {
+            if (signal.aborted)
+                stop();
+            else
+                child.send(request, error => { if (error)
+                    child.kill(); });
+        });
+    });
+}
+async function secretToolPath() {
+    for (const directory of (process.env.PATH ?? '').split(delimiter)) {
+        const candidate = join(directory || '.', 'secret-tool');
+        try {
+            await access(candidate, constants.X_OK);
+            if ((await stat(candidate)).isFile())
+                return candidate;
+        }
+        catch { /* Try the next PATH entry. */ }
+    }
+    return undefined;
+}
+function busPath(address) {
+    const match = address?.match(/^unix:path=([^,;]+)(?:,guid=[a-f\d]+)?$/i);
+    if (!match)
+        return;
+    try {
+        const path = decodeURIComponent(match[1]);
+        if (isAbsolute(path) && !/[\x00-\x1f\x7f]/.test(path))
+            return path;
+    }
+    catch { /* Other D-Bus address forms are left to the credential adapter. */ }
+}
+async function ownedSocket(path) {
+    try {
+        const [socket, directory] = await Promise.all([stat(path), stat(dirname(path))]);
+        return socket.isSocket() && socket.uid === process.getuid?.() && directory.isDirectory() && directory.uid === socket.uid;
+    }
+    catch {
+        return false;
+    }
+}
+export async function checkKeyring(profile, identity, signal) {
+    const checks = [];
+    if (process.platform === 'linux') {
+        const executable = await secretToolPath();
+        checks.push({ id: 'keyring.backend', status: executable ? 'pass' : 'fail', code: executable ? 'KEYRING_BACKEND_FOUND' : 'SECRET_TOOL_MISSING',
+            message: executable ? 'secret-tool is executable in this process PATH.' : 'secret-tool is not executable in this process PATH.',
+            ...(executable ? { evidence: { executable } } : { remediation: { steps: ['Install secret-tool using your OS package manager, or expose its installed directory in the MCP launch PATH.', 'Rerun doctor from the failing environment.'] } }) });
+        const configuredBus = busPath(process.env.DBUS_SESSION_BUS_ADDRESS);
+        const socketFound = configuredBus ? await ownedSocket(configuredBus) : false;
+        checks.push({ id: 'keyring.environment', status: 'pass', code: 'KEYRING_ENVIRONMENT',
+            message: 'Environment observations only; the credential check below verifies actual access.',
+            evidence: { sessionBusAddressPresent: Boolean(process.env.DBUS_SESSION_BUS_ADDRESS), runtimeDirectoryPresent: Boolean(process.env.XDG_RUNTIME_DIR), configuredUserSocketFound: socketFound } });
+        if (!executable)
+            return [...checks, { id: 'keyring.credential', status: 'skipped', code: 'KEYRING_BACKEND_REQUIRED', message: 'Credential verification requires secret-tool.' }];
+    }
+    const request = { service: profile.credentialService, account: profile.credentialAccount,
+        ...(identity ? { address: identity.address, fingerprint: identity.fingerprint } : {}) };
+    const result = await probeCredential(request, signal);
+    const outcomes = {
+        matched: { status: 'pass', code: 'KEYRING_CREDENTIAL_MATCHED', message: 'The stored credential is readable and matches this wallet.' },
+        readable: { status: 'warn', code: 'KEYRING_CREDENTIAL_WITHOUT_WALLET', message: 'A valid stored credential exists, but this profile has no initialized wallet.' },
+        missing: { status: identity ? 'fail' : 'warn', code: 'KEYRING_CREDENTIAL_MISSING', message: 'No credential was found for this profile.' },
+        invalid: { status: 'fail', code: 'KEYRING_CREDENTIAL_INVALID', message: 'The stored credential is not a valid Atto recovery phrase.' },
+        mismatch: { status: 'fail', code: 'KEYRING_CREDENTIAL_MISMATCH', message: 'The stored credential does not match the saved wallet identity.' },
+        unavailable: { status: 'fail', code: 'KEYRING_UNAVAILABLE', message: 'Credential access failed. The service may be unavailable, locked, or denying access.' },
+        backend_unavailable: { status: 'fail', code: 'KEYRING_BACKEND_UNAVAILABLE', message: 'The native password-store backend could not load.' },
+        timeout: { status: 'fail', code: 'KEYRING_TIMEOUT', message: 'The password-store check timed out or was cancelled.' },
+    };
+    const check = { id: 'keyring.credential', ...outcomes[result] };
+    if (['unavailable', 'timeout'].includes(result)) {
+        check.remediation = { steps: ['Unlock the OS password store and allow this application to access it.',
+                ...(process.platform === 'linux' ? ['In a working desktop terminal, inspect DBUS_SESSION_BUS_ADDRESS and XDG_RUNTIME_DIR with printenv. Supply the actual session values in the MCP server env configuration.'] : []),
+                'Restart the MCP connection after changing its launch environment, then rerun its doctor tool.'] };
+        if (process.platform === 'linux' && !signal.aborted) {
+            const directories = [...new Set([process.env.XDG_RUNTIME_DIR, `/run/user/${process.getuid()}`])];
+            for (const directory of directories) {
+                if (!directory || !isAbsolute(directory) || /[\x00-\x1f\x7f]/.test(directory))
+                    continue;
+                const path = join(directory, 'bus');
+                if (!await ownedSocket(path))
+                    continue;
+                const suggestedEnv = { DBUS_SESSION_BUS_ADDRESS: `unix:path=${encodeURIComponent(path).replace(/%2F/g, '/')}`, XDG_RUNTIME_DIR: directory };
+                if (Object.entries(suggestedEnv).every(([key, value]) => process.env[key] === value))
+                    continue;
+                const retried = await probeCredential(request, signal, { ...process.env, ...suggestedEnv });
+                // An absent credential does not prove the suggested environment fixes this wallet.
+                if (retried === 'matched' || (!identity && retried === 'readable')) {
+                    check.remediation = { steps: ['Credential access succeeded only in an isolated probe with these environment overrides.',
+                            'Add suggestedEnv to the MCP server env configuration, restart the connection, and rerun doctor. The current process was not changed.'], suggestedEnv, restartRequired: true };
+                    check.code = 'KEYRING_ENVIRONMENT_FIX_VERIFIED';
+                    break;
+                }
+                // Try at most one alternative session, within the overall doctor deadline.
+                break;
+            }
+        }
+    }
+    else if (result !== 'matched') {
+        check.remediation = { steps: result === 'backend_unavailable'
+                ? ['Reinstall the package for this OS and architecture, then rerun doctor.']
+                : !identity && result === 'missing'
+                    ? ['Create or import a wallet in your local terminal using this same data directory.']
+                    : ['Verify the selected data directory and credential service/account.', 'Preserve the original public wallet profile and recover its matching credential from your private backup. Do not reset or replace the wallet to repair access.'] };
+    }
+    checks.push(check);
+    return checks;
+}

package/dist/doctor/profile.d.ts

@@ -0,0 +1,19 @@
+import type { WalletAddress, WalletIdentity, WalletSettings } from '../wallet/types.js';
+export interface DoctorProfile {
+    settings: WalletSettings;
+    settingsSource: 'profile' | 'defaults';
+    identity?: WalletIdentity;
+    addresses: WalletAddress[];
+    access: 'read-only' | 'spend';
+    poolIndexes: number[];
+    pendingPayments: number;
+    resetPending: boolean;
+    termsAccepted: boolean;
+    permissions?: {
+        private: boolean;
+        directoryMode: string;
+        databaseMode?: string;
+    };
+}
+/** Read a consistent snapshot without StateStore's initialization, migration, or chmod. */
+export declare function readDoctorProfile(directory: string): DoctorProfile;