gnoman 0.1.0

package/backend/services/diagnosticsService.ts

@@ -0,0 +1,350 @@
+import fs from 'fs/promises';
+import os from 'os';
+import path from 'path';
+import { execFile as execFileCallback } from 'child_process';
+import { promisify } from 'util';
+import { KeyringManager } from '../../src/core/keyringManager';
+import type { KeyringBackendName } from '../../src/core/backends/types';
+import { walletRepository } from './walletStore';
+
+const execFile = promisify(execFileCallback);
+
+export type DiagnosticStatus = 'ok' | 'warn' | 'error';
+
+export interface DiagnosticCheck {
+  id: string;
+  label: string;
+  status: DiagnosticStatus;
+  detail?: string;
+  suggestion?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface DiagnosticSummary {
+  total: number;
+  ok: number;
+  warn: number;
+  error: number;
+}
+
+export interface DiagnosticReport {
+  generatedAt: string;
+  environment: {
+    platform: NodeJS.Platform;
+    arch: NodeJS.Architecture;
+    cwd: string;
+    nodeVersion: string;
+    recommendedNodeVersion: string;
+  };
+  summary: DiagnosticSummary;
+  checks: DiagnosticCheck[];
+}
+
+export interface DiagnosticOptions {
+  autoFix?: boolean;
+  skipGpg?: boolean;
+}
+
+type PathCheckDefinition = {
+  id: string;
+  label: string;
+  target: string;
+  type: 'directory' | 'file';
+  optional?: boolean;
+  autoCreate?: boolean;
+  dirMode?: number;
+  fileMode?: number;
+  suggestion?: string;
+};
+
+const MINIMUM_NODE_VERSION = '18.17.0';
+
+const PATH_CHECKS: PathCheckDefinition[] = [
+  {
+    id: 'logs-dir',
+    label: 'Logs directory (./logs)',
+    target: path.join(process.cwd(), 'logs'),
+    type: 'directory',
+    autoCreate: true,
+    dirMode: 0o700
+  },
+  {
+    id: 'sandbox-logs',
+    label: 'Sandbox logs (modules/sandbox/logs)',
+    target: path.join(process.cwd(), 'modules', 'sandbox', 'logs'),
+    type: 'directory',
+    autoCreate: true,
+    dirMode: 0o700,
+    suggestion: 'Re-run npm install to restore the sandbox logs directory if it was removed.'
+  },
+  {
+    id: 'wallet-storage',
+    label: 'Wallet storage directory (.gnoman)',
+    target: path.join(process.cwd(), '.gnoman'),
+    type: 'directory',
+    autoCreate: true,
+    dirMode: 0o700
+  },
+  {
+    id: 'wallet-db',
+    label: 'Wallet database (.gnoman/wallets.db)',
+    target: path.join(process.cwd(), '.gnoman', 'wallets.db'),
+    type: 'file',
+    optional: true,
+    suggestion: 'Trigger any wallet operation to recreate the encrypted database if needed.'
+  },
+  {
+    id: 'license-directory',
+    label: 'Offline license directory (.safevault)',
+    target: path.join(process.cwd(), '.safevault'),
+    type: 'directory',
+    autoCreate: true,
+    dirMode: 0o700,
+    optional: true
+  },
+  {
+    id: 'license-token',
+    label: 'Offline license token (.safevault/license.env)',
+    target: path.join(process.cwd(), '.safevault', 'license.env'),
+    type: 'file',
+    optional: true,
+    suggestion: 'Use the Settings panel or CLI to validate and store a license token.'
+  },
+  {
+    id: 'keyring-file',
+    label: 'File keyring payload (~/.gnoman/secrets.enc)',
+    target: path.join(os.homedir(), '.gnoman', 'secrets.enc'),
+    type: 'file',
+    optional: true,
+    suggestion: 'Create at least one secret with the file backend to persist the encrypted payload.'
+  }
+];
+
+const versionToTuple = (value: string) =>
+  value
+    .replace(/^v/, '')
+    .split('.')
+    .map((part) => Number.parseInt(part, 10));
+
+const isVersionAtLeast = (current: string, minimum: string) => {
+  const currentParts = versionToTuple(current);
+  const minimumParts = versionToTuple(minimum);
+  const length = Math.max(currentParts.length, minimumParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const currentValue = currentParts[index] ?? 0;
+    const minimumValue = minimumParts[index] ?? 0;
+    if (currentValue > minimumValue) {
+      return true;
+    }
+    if (currentValue < minimumValue) {
+      return false;
+    }
+  }
+  return true;
+};
+
+const toMessage = (error: unknown) => (error instanceof Error ? error.message : String(error));
+
+const evaluatePath = async (definition: PathCheckDefinition, autoFix: boolean): Promise<DiagnosticCheck> => {
+  const metadata = { path: definition.target, kind: definition.type } as Record<string, unknown>;
+  try {
+    const stats = await fs.stat(definition.target);
+    const isExpectedType = definition.type === 'directory' ? stats.isDirectory() : stats.isFile();
+    if (!isExpectedType) {
+      return {
+        id: definition.id,
+        label: definition.label,
+        status: 'error',
+        detail: `Expected ${definition.type} but found a different filesystem entry at ${definition.target}.`,
+        suggestion: definition.suggestion,
+        metadata
+      };
+    }
+    return {
+      id: definition.id,
+      label: definition.label,
+      status: 'ok',
+      detail: `Located ${definition.type} at ${definition.target}.`,
+      metadata
+    };
+  } catch (error) {
+    if (autoFix && definition.autoCreate) {
+      try {
+        if (definition.type === 'directory') {
+          await fs.mkdir(definition.target, { recursive: true, mode: definition.dirMode ?? 0o700 });
+        } else {
+          await fs.mkdir(path.dirname(definition.target), { recursive: true, mode: definition.dirMode ?? 0o700 });
+          await fs.writeFile(definition.target, '', { mode: definition.fileMode ?? 0o600 });
+        }
+        return {
+          id: definition.id,
+          label: definition.label,
+          status: 'ok',
+          detail: `Created missing ${definition.type} at ${definition.target}.`,
+          metadata
+        };
+      } catch (fixError) {
+        return {
+          id: definition.id,
+          label: definition.label,
+          status: 'error',
+          detail: `Unable to create ${definition.type} at ${definition.target}: ${toMessage(fixError)}.`,
+          suggestion: definition.suggestion,
+          metadata
+        };
+      }
+    }
+    return {
+      id: definition.id,
+      label: definition.label,
+      status: definition.optional ? 'warn' : 'error',
+      detail: `Missing ${definition.type} at ${definition.target}.`,
+      suggestion: definition.suggestion,
+      metadata
+    };
+  }
+};
+
+const evaluateKeyringBackend = async (backend: KeyringBackendName): Promise<DiagnosticCheck> => {
+  const manager = new KeyringManager();
+  try {
+    await manager.switchBackend(backend);
+    const active = manager.currentBackend();
+    const metadata = { requested: backend, active } as Record<string, unknown>;
+    if (active === backend) {
+      return {
+        id: `keyring-${backend}`,
+        label: `Keyring backend: ${backend}`,
+        status: 'ok',
+        detail: `Backend '${backend}' is operational.`,
+        metadata
+      };
+    }
+    return {
+      id: `keyring-${backend}`,
+      label: `Keyring backend: ${backend}`,
+      status: 'warn',
+      detail: `Requested backend '${backend}' fell back to '${active}'.`,
+      suggestion:
+        backend === 'system'
+          ? 'Ensure the keytar dependency is installed and the OS keyring is available to enable the system backend.'
+          : undefined,
+      metadata
+    };
+  } catch (error) {
+    return {
+      id: `keyring-${backend}`,
+      label: `Keyring backend: ${backend}`,
+      status: 'error',
+      detail: toMessage(error),
+      suggestion:
+        backend === 'system'
+          ? 'Ensure the keytar dependency is installed and the OS keyring is available to enable the system backend.'
+          : 'Investigate filesystem permissions and environment variables for the keyring backend.',
+      metadata: { requested: backend }
+    };
+  }
+};
+
+const checkNodeVersion = (): DiagnosticCheck => {
+  const nodeVersion = process.version;
+  const meetsRequirement = isVersionAtLeast(nodeVersion, MINIMUM_NODE_VERSION);
+  return {
+    id: 'node-version',
+    label: 'Node.js runtime',
+    status: meetsRequirement ? 'ok' : 'warn',
+    detail: `Detected ${nodeVersion}. Minimum recommended version is ${MINIMUM_NODE_VERSION}.`,
+    suggestion: meetsRequirement ? undefined : 'Upgrade Node.js to the recommended version or newer.',
+    metadata: {
+      current: nodeVersion,
+      minimum: MINIMUM_NODE_VERSION
+    }
+  };
+};
+
+const checkGpgAvailability = async (): Promise<DiagnosticCheck> => {
+  try {
+    const { stdout } = await execFile('gpg', ['--version'], { timeout: 3000 });
+    const headline = stdout.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim();
+    return {
+      id: 'gpg',
+      label: 'GnuPG availability',
+      status: 'ok',
+      detail: headline ?? 'gpg --version succeeded.',
+      metadata: {
+        version: headline
+      }
+    };
+  } catch (error) {
+    const message = toMessage(error);
+    return {
+      id: 'gpg',
+      label: 'GnuPG availability',
+      status: 'warn',
+      detail: `Unable to execute gpg --version: ${message}.`,
+      suggestion: 'Install GnuPG to enable encrypted keyring exports.',
+      metadata: {
+        error: message
+      }
+    };
+  }
+};
+
+const computeSummary = (checks: DiagnosticCheck[]): DiagnosticSummary =>
+  checks.reduce<DiagnosticSummary>(
+    (accumulator, check) => {
+      accumulator.total += 1;
+      accumulator[check.status] += 1;
+      return accumulator;
+    },
+    { total: 0, ok: 0, warn: 0, error: 0 }
+  );
+
+export const runSystemDiagnostics = async (options: DiagnosticOptions = {}): Promise<DiagnosticReport> => {
+  const checks: DiagnosticCheck[] = [];
+
+  checks.push(checkNodeVersion());
+
+  if (!options.skipGpg) {
+    checks.push(await checkGpgAvailability());
+  }
+
+  const walletInventory = walletRepository.list();
+  checks.push({
+    id: 'wallet-inventory',
+    label: 'Wallet inventory',
+    status: 'ok',
+    detail:
+      walletInventory.length === 0
+        ? 'No wallets stored in the encrypted database.'
+        : `${walletInventory.length} wallet(s) stored in the encrypted database.`,
+    metadata: {
+      count: walletInventory.length
+    }
+  });
+
+  for (const definition of PATH_CHECKS) {
+    checks.push(await evaluatePath(definition, Boolean(options.autoFix)));
+  }
+
+  for (const backend of ['system', 'file', 'memory'] as KeyringBackendName[]) {
+    checks.push(await evaluateKeyringBackend(backend));
+  }
+
+  const summary = computeSummary(checks);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    environment: {
+      platform: process.platform,
+      arch: process.arch,
+      cwd: process.cwd(),
+      nodeVersion: process.version,
+      recommendedNodeVersion: MINIMUM_NODE_VERSION
+    },
+    summary,
+    checks
+  };
+};
+
+export default runSystemDiagnostics;

package/backend/services/etherscanService.ts

@@ -0,0 +1,152 @@
+import { isAddress, getAddress } from 'ethers';
+import { http } from '../utils/http';
+import { abiResolver } from '../utils/abiResolver';
+import { secretsResolver } from '../utils/secretsResolver';
+
+const DEFAULT_CHAIN_ID = 1;
+const MAX_CALLS_PER_SECOND = 3;
+
+type EtherscanResult<T> = {
+  status: string;
+  message: string;
+  result: T;
+};
+
+const callTimestamps: number[] = [];
+let missingKeyLogged = false;
+
+const normalizeAddress = (address: string) => {
+  if (!isAddress(address)) {
+    throw new Error(`Invalid Ethereum address: ${address}`);
+  }
+  return getAddress(address).toLowerCase();
+};
+
+const normalizeChainId = (chainId?: number) => {
+  if (chainId && Number.isInteger(chainId) && chainId > 0) {
+    return chainId;
+  }
+  const envValue = Number.parseInt(process.env.ETHERSCAN_CHAIN_ID ?? `${DEFAULT_CHAIN_ID}`, 10);
+  return Number.isInteger(envValue) && envValue > 0 ? envValue : DEFAULT_CHAIN_ID;
+};
+
+const waitForRateLimit = async () => {
+  const now = Date.now();
+  while (callTimestamps.length && now - callTimestamps[0] >= 1000) {
+    callTimestamps.shift();
+  }
+  if (callTimestamps.length < MAX_CALLS_PER_SECOND) {
+    callTimestamps.push(now);
+    return;
+  }
+  const waitMs = 1000 - (now - callTimestamps[0]);
+  await new Promise((resolve) => setTimeout(resolve, Math.max(waitMs, 1)));
+  return waitForRateLimit();
+};
+
+const ensureEtherscanEnabled = async () => {
+  if (process.env.ETHERSCAN_ENABLED === 'false') {
+    throw new Error('ETHERSCAN disabled by ETHERSCAN_ENABLED=false');
+  }
+  const key = await secretsResolver.resolve('ETHERSCAN_API_KEY', { required: false, failClosed: false });
+  if (!key) {
+    if (!missingKeyLogged) {
+      missingKeyLogged = true;
+      console.error(JSON.stringify({ event: 'ETHERSCAN', enabled: false, reason: 'missing_key' }));
+    }
+    throw new Error('Missing ABI and no ETHERSCAN_API_KEY configured');
+  }
+  return key;
+};
+
+const etherscanRequest = async <T>(
+  action: 'txlist' | 'gasoracle',
+  chainId: number,
+  params: Record<string, string>
+) => {
+  await waitForRateLimit();
+  const key = await ensureEtherscanEnabled();
+  const response = await http.get<EtherscanResult<T>>('', {
+    params: {
+      module: action === 'txlist' ? 'account' : 'gastracker',
+      action,
+      apikey: key,
+      chainid: chainId,
+      ...params
+    }
+  });
+  return response.data;
+};
+
+export const resolveAbiFileForAddress = async (
+  chainIdInput: number,
+  address: string,
+  abiNameHint?: string | null
+): Promise<string> => {
+  const chainId = normalizeChainId(chainIdInput);
+  const normalizedAddress = normalizeAddress(address);
+  console.info(JSON.stringify({ event: 'ABI_RESOLVE start', address: normalizedAddress, chainId }));
+  const resolved = await abiResolver.resolve(chainId, normalizedAddress, abiNameHint ?? undefined);
+  console.info(
+    JSON.stringify({
+      event: 'ABI_RESOLVE',
+      source: resolved.source,
+      status: 'success',
+      cacheKey: `${chainId}:${normalizedAddress}`
+    })
+  );
+  return resolved.cachePath;
+};
+
+export const resolveAbiByAddress = async (
+  chainIdInput: number,
+  address: string,
+  abiNameHint?: string | null
+): Promise<unknown[]> => {
+  const chainId = normalizeChainId(chainIdInput);
+  const normalizedAddress = normalizeAddress(address);
+  console.info(JSON.stringify({ event: 'ABI_RESOLVE start', address: normalizedAddress, chainId }));
+  try {
+    const resolved = await abiResolver.resolve(chainId, normalizedAddress, abiNameHint ?? undefined);
+    console.info(
+      JSON.stringify({
+        event: 'ABI_RESOLVE',
+        source: resolved.source,
+        status: 'success',
+        cacheKey: `${chainId}:${normalizedAddress}`
+      })
+    );
+    return resolved.abi;
+  } catch (error) {
+    console.error(
+      JSON.stringify({
+        event: 'ABI_RESOLVE',
+        status: 'fail',
+        reason: error instanceof Error ? error.message : String(error),
+        attemptedNetwork: true,
+        cacheKey: `${chainId}:${normalizedAddress}`
+      })
+    );
+    throw error;
+  }
+};
+
+export const getTxHistory = async (address: string, chainIdInput?: number) => {
+  const chainId = normalizeChainId(chainIdInput);
+  return etherscanRequest<unknown[]>('txlist', chainId, {
+    address: normalizeAddress(address),
+    sort: 'desc'
+  });
+};
+
+export const getGasOracle = async (chainIdInput?: number) => {
+  const chainId = normalizeChainId(chainIdInput);
+  return etherscanRequest<Record<string, string>>('gasoracle', chainId, {});
+};
+
+export const _internal = {
+  clearCaches: () => {
+    callTimestamps.splice(0, callTimestamps.length);
+    missingKeyLogged = false;
+  }
+};

package/backend/services/historyService.ts

@@ -0,0 +1,89 @@
+import { listContracts } from './contractRegistryService';
+import { getHistory } from './sandboxService';
+import { listSafeTransactions } from './safeService';
+import { walletRepository } from './walletStore';
+
+export type HistoryCategory = 'wallet' | 'safe' | 'contract';
+
+export interface HistoryEntry {
+  id: string;
+  category: HistoryCategory;
+  action: string;
+  timestamp: string;
+  summary: string;
+  metadata: Record<string, unknown>;
+}
+
+const safeTimestamp = (value?: string) => {
+  if (!value) {
+    return 0;
+  }
+  const parsed = new Date(value).getTime();
+  return Number.isNaN(parsed) ? 0 : parsed;
+};
+
+export const getHistoryEntries = (): HistoryEntry[] => {
+  const walletEntries = walletRepository.list().map((wallet) => ({
+    id: `wallet-${wallet.address}`,
+    category: 'wallet' as const,
+    action: wallet.source === 'generated' ? 'Wallet generated' : `Wallet imported (${wallet.source})`,
+    timestamp: wallet.createdAt,
+    summary: wallet.alias ? `${wallet.alias} · ${wallet.address}` : wallet.address,
+    metadata: {
+      address: wallet.address,
+      alias: wallet.alias,
+      source: wallet.source,
+      network: wallet.network,
+      hidden: wallet.hidden
+    }
+  }));
+
+  const safeEntries = listSafeTransactions().map(({ safeAddress, transaction }) => ({
+    id: `safe-${safeAddress}-${transaction.hash}`,
+    category: 'safe' as const,
+    action: transaction.executed ? 'Safe transaction executed' : 'Safe transaction proposed',
+    timestamp: transaction.createdAt,
+    summary: `${safeAddress} · ${transaction.hash.slice(0, 10)}…`,
+    metadata: {
+      safeAddress,
+      hash: transaction.hash,
+      approvals: transaction.approvals,
+      executed: transaction.executed,
+      meta: transaction.meta
+    }
+  }));
+
+  const contractEntries = getHistory().map((entry) => ({
+    id: `contract-sim-${entry.id}`,
+    category: 'contract' as const,
+    action: entry.success ? 'Contract simulation succeeded' : 'Contract simulation failed',
+    timestamp: entry.timestamp,
+    summary: `${entry.functionName} · ${entry.contractAddress}`,
+    metadata: {
+      contractAddress: entry.contractAddress,
+      functionName: entry.functionName,
+      rpcUrl: entry.rpcUrl,
+      network: entry.network,
+      success: entry.success
+    }
+  }));
+
+  const contractRegistryEntries = listContracts().map((contract) => ({
+    id: `contract-${contract.id}`,
+    category: 'contract' as const,
+    action: 'Contract registered',
+    timestamp: contract.createdAt,
+    summary: contract.name ? `${contract.name} · ${contract.address}` : contract.address,
+    metadata: {
+      address: contract.address,
+      name: contract.name,
+      network: contract.network,
+      tags: contract.tags,
+      type: contract.type
+    }
+  }));
+
+  return [...walletEntries, ...safeEntries, ...contractEntries, ...contractRegistryEntries].sort(
+    (a, b) => safeTimestamp(b.timestamp) - safeTimestamp(a.timestamp)
+  );
+};

package/backend/services/keyringAccessor.ts

@@ -0,0 +1,4 @@
+import keyringManager, { KeyringManager } from '../../src/core/keyringManager';
+
+export default keyringManager;
+export { KeyringManager };