gnoman 0.1.0

package/gnoman2.0/docs/etherscan-chainlink-integration.md

@@ -0,0 +1,44 @@
+# Etherscan + Chainlink Integration
+
+## Environment Variables
+
+Required for Etherscan features:
+
+- `ETHERSCAN_API_KEY`
+
+Optional Etherscan overrides:
+
+- `ETHERSCAN_CHAIN_ID` (default `1`)
+- `ETHERSCAN_BASE_URL` (default `https://api.etherscan.io/api`)
+
+Required for Chainlink runtime configuration:
+
+- `CHAINLINK_NODE_URL`
+- `CHAINLINK_JOB_ID`
+- `CHAINLINK_OPERATOR_ADDRESS`
+- `CHAINLINK_LINK_TOKEN`
+- `RPC_URL` (or `GNOMAN_RPC_URL` / `SAFE_RPC_URL`)
+
+## Service Modules
+
+- `backend/services/etherscanService.ts`
+  - ABI auto-resolve by address
+  - proxy-aware implementation ABI resolution (`getsourcecode` then `getabi`)
+  - address-tethered cache + metadata sidecar
+  - in-process cache and per-process fetch-once semantics
+  - 3 req/sec limiter for free-tier compatibility
+  - tx history and gas oracle helpers
+- `backend/services/chainlinkService.ts`
+  - price feed helper for `latestRoundData`
+  - runtime env validation helper for node/job/operator/link settings
+- `backend/utils/http.ts`
+  - reusable axios HTTP client for Etherscan
+- `backend/utils/signer.ts`
+  - backend signer helper for server-side execution
+
+## Solidity Examples
+
+- `contracts/PriceFeedConsumer.sol`
+- `contracts/OracleConsumer.sol`
+
+These examples are minimal references for using Chainlink feed reads and oracle request/fulfillment flow scaffolding.

package/gnoman2.0/docs/license-dev-guide.md

@@ -0,0 +1,106 @@
+# GNOMAN 2.0 License Development Guide
+
+This reference walks through generating, issuing, and validating offline license
+tokens for GNOMAN 2.0. All examples assume you run commands from the repository
+root (the directory containing `package.json`).
+
+> ℹ️ A mirrored copy of this document lives at
+> `docs/wiki/license-dev-guide.md` so the in-app wiki surfaces the same
+> instructions. Update both files whenever you make changes.
+
+## 1. Prerequisites
+
+- Python 3.10 or newer
+- `pip install cryptography`
+- Access to the environment-specific Ed25519 private key (keep it offline)
+
+## 2. Generate a keypair
+
+Run the helper once per environment to mint a fresh Ed25519 keypair:
+
+```bash
+python backend/licenses/make_keys.py
+```
+
+Outputs:
+
+- `backend/licenses/license_private.pem` – keep offline, never commit.
+- `backend/licenses/license_public.pem` – check into source control and ship
+  with the application.
+
+## 3. Configure the CLI environment
+
+Copy `.env.example` to `.env` and set `LICENSE_PRIVATE_KEY` to the path of the
+private key relative to the repository root. The default value
+`backend/licenses/license_private.pem` is resolved automatically.
+
+## 4. Issue a license token
+
+Run the issuer with explicit arguments so the command is copy/paste friendly:
+
+```bash
+python backend/licenses/gen_license.py \
+  --priv backend/licenses/license_private.pem \
+  --id customer-or-workstation \
+  --product GNOMAN \
+  --version 2.0.0 \
+  --days 365
+```
+
+- `--priv` overrides the default private key path.
+- `--id` can be any identifier useful for auditing (customer, workstation, etc.).
+- `--product` and `--version` must match what the application expects.
+- `--days` controls the validity window.
+
+The script prints:
+
+- **RAW TOKEN** – base64url payload + signature separated by a dot.
+- **HUMAN-FRIENDLY** – Base32 groups separated by dashes for manual entry.
+
+Store the raw token securely. If you need the Base32 form later, you can derive
+it by running the same command again or by base32-encoding the raw value with a
+short Python snippet.
+
+## 5. Validate a token locally
+
+Confirm a token is still valid before distributing it:
+
+```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>
+```
+
+Substitute `<token>` with either representation. A valid token prints `True`;
+any failure (bad signature, wrong product/version, expired timestamp) prints
+`False`.
+
+## 6. Desktop activation flow
+
+1. Launch the Electron app (`npm run dev:electron`).
+2. Enter the raw or Base32 token on the activation screen.
+3. The preload bridge executes `verify_license.py` with the checked-in public
+   key. Successful validation creates `.safevault/license.env` containing:
+   ```
+   LICENSE_KEY=<raw token>
+   VALIDATED_AT=<unix timestamp>
+   ```
+4. On subsequent launches the preload re-verifies the stored token. Expired or
+   tampered tokens force the user back to the activation screen.
+
+## 7. Backend compatibility endpoint
+
+Automation can continue to call the REST endpoint `POST /api/license`. It
+performs the same Ed25519 verification in Node.js and persists metadata to
+`.gnoman/license.json`. The renderer no longer depends on this file, but legacy
+integrations may still read it.
+
+## 8. Troubleshooting
+
+| Symptom | Resolution |
+| --- | --- |
+| `FileNotFoundError` for the private key | Confirm `LICENSE_PRIVATE_KEY` points at the correct path and that the key lives outside version control. |
+| `ModuleNotFoundError: No module named 'cryptography'` | Install the dependency with `pip install cryptography`. |
+| Token prints `False` unexpectedly | Decode the payload with `python -c "import base64,sys; payload=sys.argv[1].split('.')[0]; pad='='*((4-len(payload)%4)%4); print(base64.urlsafe_b64decode(payload+pad).decode())" <token>` to confirm the product, version, and expiry are correct. |
+| Desktop app refuses a known-good token | Delete `.safevault/license.env` and re-run activation to ensure the cached token has not been modified. |
+
+Following this checklist ensures every issued license aligns with the offline
+verification logic that ships with GNOMAN 2.0.

package/gnoman2.0/docs/robinhood-integration.md

@@ -0,0 +1,30 @@
+# Robinhood integration templates for Gnoman
+
+Robinhood currently publishes official developer APIs for **crypto trading**, while stock/ETF execution relies on undocumented endpoints used by first-party applications.
+
+## Supported path: Robinhood Crypto API
+
+The backend includes template helpers under `backend/services/robinhood`:
+
+- `auth.ts` – ECDSA request-signing helper (`signRobinhoodRequest`).
+- `client.ts` – `RobinhoodCryptoClient` with:
+  - `getAccountBalance()`
+  - `placeOrder(symbol, amountCash)`
+  - `getOrderStatus(orderID)`
+  - built-in HTTP 429 retry handling
+- `purchaseCryptoWithCash(...)` convenience helper for Gnoman purchase flows.
+
+### Environment variables
+
+- `ROBINHOOD_API_KEY` – API key from Robinhood portal.
+- `ROBINHOOD_PRIVATE_KEY` – PEM private key used to sign requests.
+
+## Unsupported path: Robinhood equity endpoints (use at your own risk)
+
+`unofficialClient.ts` is intentionally guarded behind:
+
+- `GNOMAN_ENABLE_UNOFFICIAL_ROBINHOOD=true`
+
+If the feature flag is not set, calls throw immediately.
+
+> ⚠️ Undocumented endpoints can change without notice and may violate platform terms. Use only for local experiments.

package/gnoman2.0/docs/system-audit-gpt-guide.md

@@ -0,0 +1,208 @@
+# GPT System Robustness Audit Playbook
+
+This document defines a standardized set of prompts and configuration blocks for guiding a GPT-based agent through a comprehensive robustness audit. The guidance is organized into reusable instruction dictionaries that can be injected into the agent's context verbatim or adapted as needed.
+
+## Basic Audit Instructions
+
+```python
+def generate_audit_instructions():
+    instructions = {
+        "audit_type": "system_robustness",
+        "scope": {
+            "components": ["core", "security", "infrastructure"],
+            "depth": "comprehensive",
+            "timeline": "historical_and_current"
+        },
+        "evaluation_criteria": {
+            "security": ["vulnerabilities", "access_controls", "data_protection"],
+            "performance": ["response_times", "resource_usage", "scaling"],
+            "reliability": ["uptime", "error_rates", "recovery_procedures"]
+        },
+        "output_format": {
+            "structure": "detailed_report",
+            "sections": ["findings", "recommendations", "enhancements"],
+            "metrics": ["quantitative", "qualitative"]
+        }
+    }
+    return instructions
+```
+
+## Enhanced Audit Parameters
+
+```python
+def create_enhanced_audit_parameters():
+    parameters = {
+        "analysis_depth": {
+            "code_review": "detailed",
+            "configuration_audit": "thorough",
+            "security_assessment": "penetration_testing",
+            "performance_profiling": "comprehensive"
+        },
+        "risk_assessment": {
+            "categories": ["critical", "high", "medium", "low"],
+            "metrics": ["impact", "likelihood", "mitigation_effectiveness"]
+        },
+        "enhancement_evaluation": {
+            "criteria": ["feasibility", "impact", "cost_benefit"],
+            "prioritization": "must_should_could_wont"
+        }
+    }
+    return parameters
+```
+
+## System Component Analysis
+
+```python
+def define_component_analysis():
+    components = {
+        "core_systems": {
+            "evaluation_points": [
+                "architecture_integrity",
+                "data_consistency",
+                "business_logic_validation",
+                "state_management"
+            ],
+            "metrics": {
+                "processing_latency": "ms",
+                "error_rate": "percentage",
+                "resource_utilization": "percentage"
+            }
+        },
+        "security_controls": {
+            "evaluation_points": [
+                "authentication_strength",
+                "authorization_effectiveness",
+                "data_encryption",
+                "access_logging"
+            ],
+            "metrics": {
+                "authentication_success_rate": "percentage",
+                "authorization_check_performance": "ms",
+                "encryption_strength": "bits"
+            }
+        }
+    }
+    return components
+```
+
+## Enhancement Recommendation Guidelines
+
+```python
+def create_enhancement_guidelines():
+    guidelines = {
+        "recommendation_format": {
+            "description": "clear_and_concise",
+            "justification": "required",
+            "implementation_steps": "detailed",
+            "risk_assessment": "included",
+            "cost_estimate": "required"
+        },
+        "priority_levels": {
+            "critical": {
+                "criteria": ["security_vulnerability", "data_integrity", "system_stability"],
+                "implementation_timeline": "immediate"
+            },
+            "high": {
+                "criteria": ["performance_impact", "user_experience", "compliance"],
+                "implementation_timeline": "short_term"
+            },
+            "medium": {
+                "criteria": ["enhancement", "optimization", "maintenance"],
+                "implementation_timeline": "medium_term"
+            }
+        }
+    }
+    return guidelines
+```
+
+## Output Format Specifications
+
+```python
+def define_report_structure():
+    structure = {
+        "executive_summary": {
+            "length": "1-2_pages",
+            "content": ["key_findings", "critical_issues", "high_priority_recommendations"]
+        },
+        "detailed_findings": {
+            "sections": [
+                "system_architecture",
+                "security_controls",
+                "performance_metrics",
+                "reliability_assessment"
+            ],
+            "format": "structured_with_evidence"
+        },
+        "recommendations": {
+            "format": "prioritized_list",
+            "details": ["implementation_steps", "resource_requirements", "expected_outcomes"]
+        },
+        "enhancement_proposals": {
+            "format": "detailed_specifications",
+            "sections": ["technical_design", "implementation_plan", "risk_assessment"]
+        }
+    }
+    return structure
+```
+
+## Implementation Timeline
+
+```python
+def create_implementation_plan():
+    timeline = {
+        "critical_enhancements": {
+            "implementation_window": "0-2_weeks",
+            "verification_steps": ["testing", "validation", "documentation"],
+            "review_requirements": ["security_audit", "performance_testing"]
+        },
+        "high_priority_enhancements": {
+            "implementation_window": "2-6_weeks",
+            "verification_steps": ["unit_testing", "integration_testing", "user_acceptance"],
+            "review_requirements": ["code_review", "security_assessment"]
+        },
+        "medium_priority_enhancements": {
+            "implementation_window": "6-12_weeks",
+            "verification_steps": ["testing", "documentation", "training"],
+            "review_requirements": ["technical_review", "stakeholder_approval"]
+        }
+    }
+    return timeline
+```
+
+## Verification and Validation
+
+```python
+def define_verification_procedures():
+    procedures = {
+        "implementation_verification": {
+            "steps": [
+                "code_review",
+                "unit_testing",
+                "integration_testing",
+                "security_testing",
+                "performance_testing"
+            ],
+            "success_criteria": {
+                "test_coverage": "90%",
+                "security_compliance": "100%",
+                "performance_metrics": "within_thresholds"
+            }
+        },
+        "validation_procedures": {
+            "steps": [
+                "functional_validation",
+                "security_validation",
+                "performance_validation",
+                "user_acceptance_testing"
+            ],
+            "documentation_requirements": {
+                "test_results": "detailed",
+                "validation_reports": "signed_off",
+                "implementation_records": "complete"
+            }
+        }
+    }
+    return procedures
+```
+
+These blocks can be supplied individually or composed together to provide GPT agents with precise and comprehensive direction when auditing the robustness of a software system.

package/gnoman2.0/docs/system-robustness-audit.md

@@ -0,0 +1,50 @@
+# GNOMAN 2.0 System Robustness Audit
+
+## Executive Summary
+- **Assessment window:** Historical architecture review and point-in-time verification on current main branch (commit HEAD prior to this audit).
+- **Focus areas:** Core wallet lifecycle, sandbox tooling, secure storage, and backend service reliability.
+- **Overall posture:** Medium risk. Critical issues were identified around sandbox command execution and wallet data durability. These have been remediated in this change set. Additional medium-risk gaps remain (notably lack of authentication and rate limiting) and are called out below.
+
+## Methodology
+1. Enumerated backend services (`backend/`) and sandbox modules (`modules/sandbox/`) with emphasis on security-sensitive flows.
+2. Reviewed persistence and secret-handling mechanisms for wallet operations.
+3. Exercised threat modelling for RPC sandbox operations and external tool integrations.
+4. Implemented targeted mitigations for high-risk findings, followed by TypeScript compilation to validate correctness (`npm run build:backend`).
+
+## Findings & Current Status
+| Area | Issue | Risk | Status |
+| --- | --- | --- | --- |
+| Security | Sandbox fork endpoint accepted arbitrary `command` allowing remote code execution. | **Critical** | **Mitigated** – enforced allow-list validation in service layer and worker orchestration. |
+| Security | Wallet secrets only stored in-memory; loss on restart and vulnerable to process crashes. | **High** | **Mitigated** – introduced encrypted SQLite persistence with durable settings. |
+| Security | RPC fork inputs were not validated (arbitrary ports, malformed URLs). | High | **Mitigated** – strict validation for URL, port, block height, and command fields. |
+| Reliability | Vanity job mnemonic persistence already handled; wallet lifecycle previously volatile. | Medium | **Improved** – wallet metadata now survives restarts. |
+| Reliability | No audit trail for sandbox operations beyond existing logs. | Medium | **Existing** – retained history mechanism; recommend centralising log rotation. |
+| Security | No authentication / rate-limiting on backend API. | High | **Open** – requires product decision; recommendation provided. |
+| Security | Renderer-to-backend communication relies on implicit trust. | Medium | **Open** – recommend API key or signed requests. |
+| Performance | Wallet listing now I/O bound; still acceptable (<1 ms per query in local testing). | Low | **Monitored** – future optimisation optional if dataset grows. |
+
+## Remediation Actions Implemented
+1. **Wallet persistence hardening**
+   - Added `backend/services/walletStore.ts` with encrypted, journaled SQLite storage inside `.gnoman/wallets.db` using `WAL` + `FULL` sync for crash resilience.
+   - Updated `walletService` to sanitise aliases, persist records, and decrypt from durable storage when exporting.
+2. **Sandbox command execution controls**
+   - Validated RPC fork inputs server-side, enforcing protocol, numeric port ranges, and non-negative block heights.
+   - Restricted fork commands to an allow-list (default `anvil`, extendable via `GNOMAN_FORK_ALLOWLIST`) in both `sandboxService` and the worker harness (`LocalFork`). Path separators and unexpected characters are rejected.
+3. **Operational verification**
+   - Built backend TypeScript targets (`npm run build:backend`) ensuring all new modules compile and existing code adapts to persistence changes.
+
+## Additional Recommendations
+1. **Introduce authenticated API access** – require a local API token or OS keychain bound secret before serving wallet/sandbox endpoints to prevent unauthorised local usage.
+2. **Rate limiting & request quotas** – apply middleware (e.g. `express-rate-limit`) on wallet export/import endpoints to reduce brute-force attempts.
+3. **Secure configuration checks** – extend startup to verify `.gnoman` permissions (warn if more permissive than `0700`).
+4. **Comprehensive automated tests** – add integration tests that cover wallet import/export persistence and sandbox fork lifecycle to guard against regressions.
+
+## Verification & Evidence
+- TypeScript compilation succeeded: `npm run build:backend`.
+- Manual code review confirms new SQLite-backed storage and command validation pathways.
+- See source updates in:
+  - `backend/services/walletStore.ts`
+  - `backend/services/walletService.ts`
+  - `backend/services/sandboxService.ts`
+  - `modules/sandbox/localFork.ts`
+

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

@@ -0,0 +1,73 @@
+@@ -109,57 +109,59 @@ The renderer surfaces the core workflows through a set of tabs defined in
+  `GET /api/safes/:address/owners` and `GET /api/safes/:address/transactions/held`
+  to populate data and to surface aggregated hold counters plus the effective
+  policy (global defaults + Safe override).
+- Tune Safe-specific hold duration and enable/disable flags directly from the
+  page. Changes are persisted to SQLite (`holds.sqlite`) and mirrored back via
+  `POST /api/safes/:address/hold`.
+- Held transactions reflect entries tracked by the SQLite-backed hold service in
+  `backend/services/transactionHoldService.ts`, complete with live countdowns
+  and manual release controls.
+
+### 4.4 Sandbox
+- Toggle between the legacy Safe callStatic form and the advanced sandbox panel
+  in `modules/sandbox/ui/SandboxPanel.tsx`.
+- Upload or paste ABIs, select contract functions, provide parameters, and run
+  simulations via `POST /api/sandbox/contract/simulate`.
+- Replay previous simulations pulled from `GET /api/sandbox/contract/history`
+  and optionally run them against a local fork started with
+  `POST /api/sandbox/fork/start` (defaults to the `anvil` command).
+- Provide a `forkRpcUrl` to execute simulations against a remote Hardhat/Anvil
+  fork when no managed local fork is available—the backend automatically falls
+  back to standard RPC calls if neither option is configured.
+- Use the Safe-focused tab to call `POST /api/sandbox/call-static` for quick
+  guard checks.
+
+### 4.5 Keyring
+- Lists secrets registered through the Electron IPC bridge (`window.gnoman.invoke('keyring:list')`).
+- Proxies every request to the backend AES keyring service (`/api/keyring/*`),
+  which stores encrypted payloads under `.gnoman/keyrings/<service>.json`.
+- Reveals a selected secret via `keyring:get`, which maps to `POST /api/keyring/get`.
+  If the `keyring` module cannot load (for example, inside a sandbox), the backend
+  switches to an in-memory store and logs a warning so you know the data is
+  ephemeral.
+- Encrypt, reveal, and delete secrets entirely inside the renderer. Each UI action
+  forwards to `/api/keyring/*`, guaranteeing parity with the legacy CLI while
+  capturing an auditable activity feed for operators.
+- Switch between keyring services (for example `production`, `staging`, or
+  `aes`) without leaving the UI. The currently active service is displayed in the
+  global header and sidebar so you never lose track of your namespace.
+- The backend still falls back to an in-memory store if the native `keyring`
+  module is unavailable. The UI highlights this state and keeps secrets scoped to
+  the session, while the CLI bridge remains for legacy automation only.
+
+### 4.6 License & Settings
+- The activation screen uses the preload bridge (`window.safevault`) to run the
+  Python verifier (`backend/licenses/verify_license.py`) entirely offline.
+- Successful validation writes `.safevault/license.env` with the raw token and a
+  `VALIDATED_AT` timestamp. The preload re-verifies this token on every launch.
+- Settings exposes the stored license metadata, the global transaction hold
+  toggle/duration (persisted in the AES keyring via `SAFE_TX_HOLD_ENABLED`), and a
+  vanity wallet generator surface with live job dashboards.
+- Vanity jobs are executed in worker threads, persisted to `.gnoman/vanity-jobs.json`
+  for auditability, and only expose mnemonic aliases so secrets stay in the
+  secure store.
+- For automation, the backend still accepts `POST /api/license`, which stores a
+  JSON record in `.gnoman/license.json`. This endpoint exists for legacy flows
+  that expect the previous storage format.
+
+### 4.7 Wiki Guide
+- Renders Markdown content from `docs/wiki/`, including the mirrored developer
+  and licensing guides.
+
+---
+
+## 5. Offline licensing quick reference
+
+| Task | Command |
+
+### 4.8 Integrations & Runtime Features (Settings)
+- Settings now includes a dedicated **Integrations & Runtime Features** section that surfaces one-glance enablement + reason status for `safe`, `etherscan`, and `robinhood`.
+- Status values come from `GET /api/runtime/capabilities`, which reflects backend runtime decisions instead of UI guesses.
+- Robinhood credential management is grouped under **Integration Configuration: Robinhood Crypto Trading API** to keep integration setup separate from license/hold/vanity controls.
+- Runtime diagnostics remain available under **Runtime Diagnostics** for detailed ABI cache activity, secrets source status, Safe runtime state, and Robinhood request telemetry.