gnoman 0.1.0

package/gnoman2.0/cli/gnoman.ts

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+import fs from 'fs/promises';
+import path from 'path';
+import { spawn } from 'child_process';
+import process from 'process';
+import keyringManager from '../src/core/keyringManager';
+import type { KeyringBackendName } from '../src/core/backends/types';
+import {
+  exportWallet,
+  importWalletFromEncryptedJson,
+  listWalletMetadata
+} from '../backend/services/walletService';
+import {
+  runSystemDiagnostics,
+  type DiagnosticReport,
+  type DiagnosticCheck
+} from '../backend/services/diagnosticsService';
+
+const AVAILABLE_BACKENDS: KeyringBackendName[] = ['system', 'file', 'memory'];
+
+type CommandHandler = (args: string[]) => Promise<void>;
+
+const maskSecret = (value: string | null) => {
+  if (!value) {
+    return null;
+  }
+  if (value.length <= 4) {
+    return '*'.repeat(value.length);
+  }
+  return `${value.slice(0, 2)}***${value.slice(-2)}`;
+};
+
+const takeOption = (args: string[], option: string) => {
+  const index = args.indexOf(option);
+  if (index === -1) {
+    return undefined;
+  }
+  const value = args[index + 1];
+  if (typeof value !== 'string') {
+    throw new Error(`Option ${option} requires a value.`);
+  }
+  args.splice(index, 2);
+  return value;
+};
+
+const takeFlag = (args: string[], option: string) => {
+  const index = args.indexOf(option);
+  if (index === -1) {
+    return false;
+  }
+  args.splice(index, 1);
+  return true;
+};
+
+const ensureBackend = async (backend?: string) => {
+  if (!backend) {
+    return;
+  }
+  if (!AVAILABLE_BACKENDS.includes(backend as KeyringBackendName)) {
+    throw new Error(`Unsupported backend '${backend}'. Use one of: ${AVAILABLE_BACKENDS.join(', ')}`);
+  }
+  await keyringManager.switchBackend(backend as KeyringBackendName);
+};
+
+const ensureFileOutput = async (filePath: string, data: string) => {
+  const directory = path.dirname(filePath);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  await fs.writeFile(filePath, data, 'utf8');
+};
+
+const readSource = async (source: string) => {
+  if (source === '-' || source === '/dev/stdin') {
+    return new Promise<string>((resolve, reject) => {
+      let buffer = '';
+      process.stdin.setEncoding('utf8');
+      process.stdin.on('data', (chunk) => {
+        buffer += chunk.toString();
+      });
+      process.stdin.on('end', () => resolve(buffer));
+      process.stdin.on('error', (error) => reject(error));
+    });
+  }
+  return fs.readFile(source, 'utf8');
+};
+
+const parseEnvFile = (content: string) => {
+  const records: Record<string, string> = {};
+  const lines = content.split(/\r?\n/);
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.length === 0 || line.startsWith('#')) {
+      continue;
+    }
+    const match = line.match(/^([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match) {
+      continue;
+    }
+    const [, key, remainder] = match;
+    let value = remainder.trim();
+    if (value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1).replace(/\\"/g, '"');
+    }
+    records[key] = value;
+  }
+  return records;
+};
+
+const serializeEnv = (records: Record<string, string>) =>
+  Object.entries(records)
+    .map(([key, value]) => `${key}="${value.replace(/"/g, '\\"')}"`)
+    .join('\n');
+
+const encryptWithGpg = async (data: string, recipient: string, output: string) => {
+  return new Promise<void>((resolve, reject) => {
+    const child = spawn('gpg', ['--batch', '--yes', '--encrypt', '--recipient', recipient, '--output', output], {
+      stdio: ['pipe', 'inherit', 'inherit']
+    });
+    child.on('error', (error) => reject(error));
+    child.on('exit', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`gpg exited with code ${code}`));
+      }
+    });
+    child.stdin.end(data, 'utf8');
+  });
+};
+
+const keyringHandlers: Record<string, CommandHandler> = {
+  async backend(args) {
+    const action = args.shift();
+    if (!action || action === 'list') {
+      await keyringManager.list();
+      console.log(`Active backend: ${keyringManager.currentBackend()}`);
+      console.log(`Available: ${AVAILABLE_BACKENDS.join(', ')}`);
+      return;
+    }
+    if (action === 'switch') {
+      const target = args.shift();
+      if (!target) {
+        throw new Error('Backend name is required.');
+      }
+      await ensureBackend(target);
+      console.log(`Switched to backend: ${keyringManager.currentBackend()}`);
+      return;
+    }
+    throw new Error(`Unsupported backend action '${action}'.`);
+  },
+
+  async list(args) {
+    const backend = takeOption(args, '--backend');
+    await ensureBackend(backend);
+    const secrets = await keyringManager.list();
+    if (Object.keys(secrets).length === 0) {
+      console.log('No keyring entries found.');
+      return;
+    }
+    for (const [key, value] of Object.entries(secrets)) {
+      console.log(`${key}: ${maskSecret(value)}`);
+    }
+  },
+
+  async set(args) {
+    const backend = takeOption(args, '--backend');
+    const key = args.shift();
+    const value = args.shift();
+    if (!key || typeof value !== 'string') {
+      throw new Error('Usage: gnoman keyring set <key> <value>');
+    }
+    await ensureBackend(backend);
+    await keyringManager.set(key, value);
+    console.log(`Stored secret '${key}'.`);
+  },
+
+  async add(args) {
+    await keyringHandlers.set(args);
+  },
+
+  async edit(args) {
+    await keyringHandlers.set(args);
+  },
+
+  async get(args) {
+    const backend = takeOption(args, '--backend');
+    const key = args.shift();
+    if (!key) {
+      throw new Error('Usage: gnoman keyring get <key>');
+    }
+    await ensureBackend(backend);
+    const value = await keyringManager.get(key);
+    if (value === null) {
+      console.error('Secret not found.');
+      process.exitCode = 1;
+      return;
+    }
+    console.log(value);
+  },
+
+  async delete(args) {
+    const backend = takeOption(args, '--backend');
+    const key = args.shift();
+    if (!key) {
+      throw new Error('Usage: gnoman keyring delete <key>');
+    }
+    await ensureBackend(backend);
+    await keyringManager.delete(key);
+    console.log(`Deleted secret '${key}'.`);
+  },
+
+  async remove(args) {
+    await keyringHandlers.delete(args);
+  },
+
+  async export(args) {
+    const backend = takeOption(args, '--backend');
+    const format = (takeOption(args, '--format') ?? 'json').toLowerCase();
+    const output = takeOption(args, '--output');
+    const gpgRecipient = takeOption(args, '--gpg');
+    await ensureBackend(backend);
+    const secrets = await keyringManager.list();
+    let payload: string;
+    if (format === 'env') {
+      payload = `${serializeEnv(secrets)}\n`;
+    } else if (format === 'json') {
+      payload = `${JSON.stringify(secrets, null, 2)}\n`;
+    } else {
+      throw new Error(`Unsupported export format '${format}'. Use env or json.`);
+    }
+    if (gpgRecipient) {
+      if (!output) {
+        throw new Error('The --output option is required when using --gpg.');
+      }
+      await encryptWithGpg(payload, gpgRecipient, output);
+      console.log(`Exported secrets to ${output} using GPG recipient ${gpgRecipient}.`);
+      return;
+    }
+    if (output) {
+      await ensureFileOutput(output, payload);
+      console.log(`Exported secrets to ${output}.`);
+    } else {
+      process.stdout.write(payload);
+    }
+  },
+
+  async import(args) {
+    const backend = takeOption(args, '--backend');
+    const format = (takeOption(args, '--format') ?? 'json').toLowerCase();
+    const source = args.shift();
+    if (!source) {
+      throw new Error('Usage: gnoman keyring import <file> [--format env|json]');
+    }
+    await ensureBackend(backend);
+    const content = await readSource(source);
+    let records: Record<string, string>;
+    if (format === 'env') {
+      records = parseEnvFile(content);
+    } else if (format === 'json') {
+      const parsed = JSON.parse(content);
+      if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('Invalid JSON payload for keyring import.');
+      }
+      records = Object.fromEntries(
+        Object.entries(parsed).filter(([, value]) => typeof value === 'string') as [string, string][]
+      );
+    } else {
+      throw new Error(`Unsupported import format '${format}'. Use env or json.`);
+    }
+    for (const [key, value] of Object.entries(records)) {
+      await keyringManager.set(key, value);
+    }
+    console.log(`Imported ${Object.keys(records).length} secrets into backend ${keyringManager.currentBackend()}.`);
+  }
+};
+
+const walletHandlers: Record<string, CommandHandler> = {
+  async list(_args) {
+    const wallets = await listWalletMetadata();
+    if (wallets.length === 0) {
+      console.log('No wallets stored.');
+      return;
+    }
+    for (const wallet of wallets) {
+      console.log(`${wallet.address} (${wallet.alias ?? 'unnamed'})`);
+    }
+  },
+
+  async export(args) {
+    const address = args.shift();
+    const password = takeOption(args, '--password');
+    const output = takeOption(args, '--output');
+    if (!address || !password) {
+      throw new Error('Usage: gnoman wallets export <address> --password <password> [--output <file>]');
+    }
+    const keystore = await exportWallet(address, password);
+    if (output) {
+      await ensureFileOutput(output, `${keystore}\n`);
+      console.log(`Exported wallet ${address} to ${output}.`);
+    } else {
+      process.stdout.write(`${keystore}\n`);
+    }
+  },
+
+  async import(args) {
+    const source = args.shift();
+    const password = takeOption(args, '--password');
+    const alias = takeOption(args, '--alias');
+    const hidden = takeFlag(args, '--hidden');
+    if (!source || !password) {
+      throw new Error('Usage: gnoman wallets import <file> --password <password> [--alias <alias>] [--hidden]');
+    }
+    const json = await readSource(source);
+    const wallet = await importWalletFromEncryptedJson({ json, password, alias, hidden });
+    console.log(`Imported wallet ${wallet.address} (${wallet.alias ?? 'unnamed'}).`);
+  }
+};
+
+const printDiagnosticReport = (report: DiagnosticReport, { verbose = false } = {}) => {
+  const icon: Record<DiagnosticCheck['status'], string> = {
+    ok: '✅',
+    warn: '⚠️',
+    error: '❌'
+  };
+
+  console.log('GNOMAN system diagnostics');
+  console.log(`Generated: ${report.generatedAt}`);
+  console.log(
+    `Environment: ${report.environment.platform}/${report.environment.arch} · Node ${report.environment.nodeVersion} (recommended ${report.environment.recommendedNodeVersion})`
+  );
+  console.log(
+    `Summary: ${report.summary.ok} ok, ${report.summary.warn} warn, ${report.summary.error} error`
+  );
+  console.log('');
+
+  for (const check of report.checks) {
+    console.log(`${icon[check.status]} ${check.label}`);
+    if (check.detail) {
+      console.log(`    ${check.detail}`);
+    }
+    if (check.suggestion) {
+      console.log(`    Suggestion: ${check.suggestion}`);
+    }
+    if (verbose && check.metadata) {
+      console.log(`    Metadata: ${JSON.stringify(check.metadata)}`);
+    }
+  }
+};
+
+const diagnosticsHandlers: Record<string, CommandHandler> = {
+  async run(args) {
+    const jsonOutput = takeFlag(args, '--json');
+    const autoFix = takeFlag(args, '--fix');
+    const verbose = takeFlag(args, '--verbose');
+    const skipGpg = takeFlag(args, '--skip-gpg');
+    const report = await runSystemDiagnostics({ autoFix, skipGpg });
+    if (jsonOutput) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    printDiagnosticReport(report, { verbose });
+  },
+
+  async list(args) {
+    await diagnosticsHandlers.run(args);
+  }
+};
+
+const printHelp = () => {
+  console.log(`GNOMAN CLI
+
+Usage:
+  gnoman keyring <command> [...args]
+  gnoman wallets <command> [...args]
+  gnoman diagnostics <command> [...args]
+
+Keyring commands:
+  keyring backend list
+  keyring backend switch <system|file|memory>
+  keyring list [--backend <name>]
+  keyring set <key> <value> [--backend <name>]
+  keyring get <key> [--backend <name>]
+  keyring delete <key> [--backend <name>]
+  keyring export [--format env|json] [--output <file>] [--gpg <recipient>] [--backend <name>]
+  keyring import <file|-> [--format env|json] [--backend <name>]
+
+Wallet commands:
+  wallets list
+  wallets export <address> --password <password> [--output <file>]
+  wallets import <file|-> --password <password> [--alias <alias>] [--hidden]
+
+Diagnostics commands:
+  diagnostics run [--json] [--verbose] [--fix] [--skip-gpg]
+`);
+};
+
+const handlers: Record<string, Record<string, CommandHandler>> = {
+  keyring: keyringHandlers,
+  wallets: walletHandlers,
+  diagnostics: diagnosticsHandlers
+};
+
+const main = async () => {
+  const args = process.argv.slice(2);
+  const namespace = args.shift();
+  if (!namespace) {
+    printHelp();
+    return;
+  }
+  const group = handlers[namespace as keyof typeof handlers];
+  if (!group) {
+    throw new Error(`Unknown command group '${namespace}'.`);
+  }
+  const subcommand = args.shift() ?? 'list';
+  const handler = group[subcommand];
+  if (!handler) {
+    throw new Error(`Unknown ${namespace} command '${subcommand}'.`);
+  }
+  await handler(args);
+};
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/gnoman2.0/contracts/OracleConsumer.sol

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+contract OracleConsumer {
+    uint256 public data;
+
+    event Requested(bytes32 requestId, string jobId, string url, string path);
+    event Fulfilled(bytes32 requestId, uint256 value);
+
+    function requestData(string memory jobId, string memory url, string memory path) external returns (bytes32) {
+        bytes32 requestId = keccak256(abi.encodePacked(block.timestamp, msg.sender, jobId, url, path));
+        emit Requested(requestId, jobId, url, path);
+        return requestId;
+    }
+
+    function fulfill(bytes32 requestId, uint256 value) external {
+        data = value;
+        emit Fulfilled(requestId, value);
+    }
+}

package/gnoman2.0/contracts/PriceFeedConsumer.sol

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+interface AggregatorV3Interface {
+    function latestRoundData()
+        external
+        view
+        returns (uint80, int256, uint256, uint256, uint80);
+}
+
+contract PriceFeedConsumer {
+    AggregatorV3Interface internal priceFeed;
+
+    constructor(address feedAddress) {
+        priceFeed = AggregatorV3Interface(feedAddress);
+    }
+
+    function getLatestPrice() external view returns (int256) {
+        (, int256 price, , , ) = priceFeed.latestRoundData();
+        return price;
+    }
+}

package/gnoman2.0/docs/development-guide.md

@@ -0,0 +1,203 @@
+# GNOMAN 2.0 Development Guide
+
+This guide documents the authoritative workflow for standing up a GNOMAN 2.0
+workstation, exercising the offline licensing stack, and producing builds that
+match what ships to customers. Every path is written relative to the repository
+root (the directory that contains `package.json`).
+
+> ℹ️ A byte-for-byte copy of this guide lives at
+> `docs/wiki/development-guide.md` for the in-app wiki. Whenever you update this
+> file, mirror the edits in the wiki directory so desktop users and GitHub
+> readers see the same information.
+
+## 1. Tooling prerequisites
+
+| Tool | Required version | Notes |
+| ---- | ---------------- | ----- |
+| Node.js | 18 LTS | Bundles npm 9, which is required by the build scripts. |
+| npm | 9.x | Installed with Node.js. |
+| Python | 3.10 or newer | Powers the Ed25519 licensing utilities. |
+| pip package | `cryptography` | Install with `pip install cryptography`. |
+| Native build chain | OS specific | Xcode Command Line Tools on macOS, `build-essential` on Linux, or Windows Build Tools to compile `better-sqlite3`. The AES keyring runs entirely in user space (no native bindings). |
+
+Clone the repository and install dependencies:
+
+```bash
+npm install
+(cd renderer && npm install)
+```
+
+The root install triggers the renderer install via the `postinstall` hook, but
+running both commands explicitly surfaces dependency errors sooner.
+
+## 2. Environment configuration
+
+1. Copy the template to create a working `.env`:
+   ```bash
+   cp .env.example .env
+   ```
+2. Adjust variables as needed:
+   - `PORT` controls the Express API port (defaults to `4399`).
+   - `VITE_DEV_SERVER_URL` points the Electron shell at the renderer dev server
+     during development.
+   - `LICENSE_PRIVATE_KEY` points to the Ed25519 signing key used by
+     `backend/licenses/gen_license.py`. The default
+     `backend/licenses/license_private.pem` is resolved relative to the
+     repository root. Keep the actual private key outside of source control.
+
+### 2.1 AES keyring management
+
+The backend, main process, and renderer now rely on a unified keyring manager
+that can hot-swap between the system keychain, an AES-GCM encrypted file store,
+or an in-memory fallback. Use the REST endpoints to administer secrets without
+restarting the app:
+
+```bash
+# List masked secrets for the active backend
+curl http://127.0.0.1:${PORT:-4399}/api/keyring | jq
+
+# Store a secret
+curl -X POST http://127.0.0.1:${PORT:-4399}/api/keyring/RPC_URL \
+  -H 'Content-Type: application/json' \
+  -d '{"value":"https://sepolia.infura.io/v3/..."}'
+
+# Reveal a secret (returns the decrypted payload)
+curl http://127.0.0.1:${PORT:-4399}/api/keyring/RPC_URL | jq
+
+# Remove a secret
+curl -X DELETE http://127.0.0.1:${PORT:-4399}/api/keyring/RPC_URL
+
+# Inspect the active backend and available backends
+curl http://127.0.0.1:${PORT:-4399}/api/keyring/backend | jq
+
+# Switch to another backend and reload configuration in place
+curl -X POST http://127.0.0.1:${PORT:-4399}/api/keyring/backend/file
+```
+
+When the system keychain is unavailable (for example, inside a sandboxed CI
+runner), the manager automatically falls back to the encrypted file store and,
+if needed, to the in-memory backend while logging warnings so you know secrets
+may not persist between restarts.
+
+## 3. Running the stack locally
+
+Use separate terminals so logs stay readable.
+
+```bash
+npm run dev:backend    # Express API at http://localhost:4399
+npm run dev:renderer   # Vite dev server at http://localhost:5173
+```
+
+If you prefer to start both web stacks together, run `npm run dev`, which wraps
+the two commands above with `concurrently`.
+
+Launch the Electron shell after the TypeScript projects finish compiling:
+
+```bash
+npm run dev:electron   # Builds backend/main/renderer and opens the desktop window
+```
+
+The Electron shell loads the renderer URL in development and the packaged
+`dist/renderer/index.html` file after a production build.
+
+## 4. Offline licensing workflows
+
+GNOMAN 2.0 keeps the private key offline and validates tokens locally. The
+preload bridge (`main/preload/licenseBridge.ts`) invokes the existing Python
+verifier and persists successful validations under `.safevault/license.env`.
+
+### 4.1 Generate an Ed25519 keypair (one-time)
+
+```bash
+python backend/licenses/make_keys.py
+```
+
+The command writes two files:
+
+- `backend/licenses/license_private.pem` – keep this file offline and untracked.
+- `backend/licenses/license_public.pem` – commit this file; it ships with the
+  application and is used by the verifier.
+
+### 4.2 Issue a license token
+
+Run the issuer from the repository root so relative paths resolve correctly:
+
+```bash
+python backend/licenses/gen_license.py \
+  --priv backend/licenses/license_private.pem \
+  --id workstation-001 \
+  --product GNOMAN \
+  --version 2.0.0 \
+  --days 365
+```
+
+The script prints two representations:
+
+- **RAW TOKEN** – base64url payload and signature separated by a dot.
+- **HUMAN-FRIENDLY** – dashed Base32 string that is easier to transcribe.
+
+Either format can be supplied to the desktop client. Store the value somewhere
+secure so you do not need to reissue it later.
+
+### 4.3 Validate a token without the UI
+
+Use the Python helper to verify a token directly from the command line. The
+verifier returns `True` for a valid token and `False` otherwise.
+
+```bash
+python -c "import sys; from backend.licenses.verify_license import verify_token; print(verify_token(sys.argv[1], sys.argv[2], 'GNOMAN', '2.0.0'))" backend/licenses/license_public.pem <token>
+```
+
+Replace `<token>` with either the raw token or a Base32 string that decodes to
+one. The helper resolves relative paths with respect to the repository root, so
+invoking it from other directories works as long as you supply the correct
+inputs.
+
+### 4.4 Desktop activation flow
+
+1. Launch the Electron shell (`npm run dev:electron`) and navigate to the
+   license screen if it does not appear automatically.
+2. Enter either token representation. The preload bridge runs
+   `verify_license.py` with the checked-in public key.
+3. When verification succeeds, the preload writes `.safevault/license.env` with:
+   ```
+   LICENSE_KEY=<raw token>
+   VALIDATED_AT=<unix timestamp>
+   ```
+4. On subsequent launches the preload re-verifies the stored token. If it has
+   expired or the verification fails, the renderer prompts for a new license.
+
+For headless automation or regression tests, the REST endpoint
+`POST /api/license` remains available. It performs the same Ed25519 checks using
+Node.js and persists JSON metadata under `.gnoman/license.json` for backwards
+compatibility.
+
+## 5. Build, lint, and packaging commands
+
+| Command | Description |
+| ------- | ----------- |
+| `npm run lint` | Run ESLint across the backend, main process, renderer, and shared modules. |
+| `npm run build:backend` | Compile the Express API to `dist/backend`. |
+| `npm run build:main` | Compile the Electron main process to `dist/main`. |
+| `npm run build:renderer` | Build the renderer UI into `renderer/dist`. |
+| `npm run build` | Clean and produce all distributable artifacts (backend, main, renderer). |
+| `npm start` | Rebuild and launch the packaged Electron shell. |
+| `npm run start:backend` | Run the compiled backend directly from `dist/backend/index.js`. |
+
+Distribution builds live under the `dist/` directory. The `scripts/copyRenderer.js`
+helper copies the renderer bundle into `dist/main/` so the packaged Electron app
+can load it from disk.
+
+## 6. Troubleshooting checklist
+
+| Symptom | Suggested fix |
+| ------- | -------------- |
+| `ModuleNotFoundError: No module named 'cryptography'` | Install the Python dependency with `pip install cryptography`. |
+| `python3` not found when validating a license | Ensure Python 3.10+ is installed and available on your `PATH`. Update the preload bridge to point at the correct executable if you use pyenv. |
+| `better-sqlite3` fails to compile | Install the platform build tools (Xcode CLI tools, `build-essential`, or Windows Build Tools) before running `npm install` again. |
+| Renderer cannot reach the backend | Confirm `npm run dev:backend` is running and the port matches `renderer/src/config/api.ts`. |
+| License verification unexpectedly fails | Delete `.safevault/license.env` and re-run activation to ensure the stored token has not been corrupted. |
+| Electron window opens without UI in production mode | Run `npm run build:renderer` before launching `npm start` so the packaged assets exist. |
+
+Following these conventions keeps every workstation aligned with the offline
+licensing flow and build system that GNOMAN 2.0 expects in production.