gnoman 0.1.0

package/gnoman2.0/docs/wiki/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.

package/gnoman2.0/docs/wiki/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/wiki/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.

package/gnoman2.0/eslint.config.js

@@ -0,0 +1,85 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tsParser from '@typescript-eslint/parser';
+import tsPlugin from '@typescript-eslint/eslint-plugin';
+import reactPlugin from 'eslint-plugin-react';
+import eslintConfigPrettier from 'eslint-config-prettier';
+
+export default [
+  {
+    ignores: ['dist/**', 'renderer/dist/**', 'node_modules/**']
+  },
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+        ecmaFeatures: {
+          jsx: true
+        }
+      },
+      globals: {
+        ...globals.es2021,
+        ...globals.node
+      }
+    },
+    plugins: {
+      '@typescript-eslint': tsPlugin,
+      react: reactPlugin
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tsPlugin.configs.recommended.rules,
+      ...reactPlugin.configs.recommended.rules,
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }
+      ],
+      'react/react-in-jsx-scope': 'off'
+    },
+    settings: {
+      react: {
+        version: 'detect'
+      }
+    }
+  },
+  {
+    files: ['**/*.{ts,tsx}'],
+    rules: {
+      'no-undef': 'off'
+    }
+  },
+  {
+    files: ['renderer/**/*.{ts,tsx,js,jsx}'],
+    languageOptions: {
+      globals: {
+        ...globals.es2021,
+        ...globals.browser
+      }
+    }
+  },
+  {
+    files: ['modules/**/*.{ts,tsx,js,jsx}'],
+    languageOptions: {
+      globals: {
+        ...globals.es2021,
+        ...globals.browser
+      }
+    }
+  },
+  {
+    files: ['**/*.d.ts'],
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'off'
+    }
+  },
+  {
+    files: ['**/*.js'],
+    rules: {
+      '@typescript-eslint/no-var-requires': 'off'
+    }
+  },
+  eslintConfigPrettier
+];

package/gnoman2.0/gnomon/api/etherscan_tracker.py

@@ -0,0 +1,72 @@
+"""
+Etherscan Tracker Integration for GNOMAN
+Tracks Safe transactions and performs lookup queries.
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+
+import requests
+from keyring import get_password
+
+SAFE_STATE_PATH = Path("state/gnosis_safe_state.json")
+LOG_PATH = Path("logs/safe_tx_log.json")
+ETHERSCAN_BASE_URL = "https://api.etherscan.io/api"
+POLL_INTERVAL = 30  # seconds
+
+
+def get_etherscan_api_key() -> str:
+    service = os.getenv("GNOMAN_KEYRING_SERVICE", "gnoman")
+    api_key = get_password(service, "ETHERSCAN_API_KEY")
+    if not api_key:
+        raise RuntimeError("ETHERSCAN_API_KEY is not configured in the keyring.")
+    return api_key
+
+
+def get_safe_address() -> str:
+    with open(SAFE_STATE_PATH, encoding="utf-8") as handle:
+        data = json.load(handle)
+    return data["address"]
+
+
+def load_safe_state() -> dict:
+    if not SAFE_STATE_PATH.exists():
+        raise RuntimeError("Safe state missing — persistence failure detected.")
+    with open(SAFE_STATE_PATH, encoding="utf-8") as handle:
+        state = json.load(handle)
+    if not state.get("owners") or len(state["owners"]) < 3:
+        raise ValueError("Safe loaded without correct owner list (3 required).")
+    return state
+
+
+def fetch_transactions(address: str, api_key: str | None = None):
+    api_key = api_key or get_etherscan_api_key()
+    url = (
+        f"{ETHERSCAN_BASE_URL}?module=account&action=txlist&address={address}"
+        f"&apikey={api_key}"
+    )
+    response = requests.get(url, timeout=20)
+    response.raise_for_status()
+    data = response.json()
+    if data["status"] != "1":
+        raise ValueError(f"Etherscan error: {data['message']}")
+    return data["result"]
+
+
+def track_safe_transactions():
+    safe = load_safe_state()
+    api_key = get_etherscan_api_key()
+    LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    print(f"[EtherscanTracker] Tracking transactions for Safe: {safe['address']}")
+    while True:
+        txs = fetch_transactions(safe["address"], api_key)
+        with open(LOG_PATH, "w", encoding="utf-8") as handle:
+            json.dump(txs, handle, indent=2)
+        print(f"[EtherscanTracker] {len(txs)} transactions logged.")
+        time.sleep(POLL_INTERVAL)
+
+
+if __name__ == "__main__":
+    track_safe_transactions()

package/gnoman2.0/gnomon/core/safe_manager.py

@@ -0,0 +1,111 @@
+"""Safe manager utilities for persisting and reloading Safe state."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable, Dict, Iterable, Optional
+
+SAFE_STATE_PATH = Path("state/gnosis_safe_state.json")
+
+
+def _normalize_owners(raw_owners: Any) -> list[str]:
+    if raw_owners is None:
+        return []
+    if callable(raw_owners):
+        raw_owners = raw_owners()
+    if isinstance(raw_owners, dict):
+        raw_owners = list(raw_owners.values())
+    if isinstance(raw_owners, str):
+        return [raw_owners]
+    if isinstance(raw_owners, Iterable):
+        return [str(owner) for owner in raw_owners]
+    return []
+
+
+def _extract_threshold(safe_instance: Any) -> int:
+    threshold = None
+    if hasattr(safe_instance, "getThreshold"):
+        threshold = safe_instance.getThreshold()
+    elif hasattr(safe_instance, "threshold"):
+        attr = safe_instance.threshold
+        threshold = attr() if callable(attr) else attr
+    if threshold is None:
+        raise ValueError("Safe instance does not expose a threshold value")
+    return int(threshold)
+
+
+def persist_safe_state(safe_instance: Any) -> Dict[str, Any]:
+    """Persist the current Safe metadata to disk.
+
+    Parameters
+    ----------
+    safe_instance: Any
+        Object exposing ``address``, ``owners`` (method or iterable) and
+        ``getThreshold`` or ``threshold``.
+    """
+
+    if safe_instance is None:
+        raise ValueError("Safe instance is required to persist state")
+
+    address = getattr(safe_instance, "address", None)
+    if callable(address):  # defensive: handle SDKs exposing callables
+        address = address()
+    if not address:
+        raise ValueError("Safe instance is missing an address")
+
+    owners = _normalize_owners(getattr(safe_instance, "owners", None))
+    if len(owners) < 3:
+        raise ValueError("Safe must have at least three owners before persisting")
+
+    threshold = _extract_threshold(safe_instance)
+
+    SAFE_STATE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    data = {"address": str(address), "owners": owners, "threshold": threshold}
+    with open(SAFE_STATE_PATH, "w", encoding="utf-8") as handle:
+        json.dump(data, handle, indent=2)
+    print("[SafeManager] Safe state persisted successfully.")
+    return data
+
+
+def load_persisted_safe() -> Dict[str, Any]:
+    if not SAFE_STATE_PATH.exists():
+        raise RuntimeError("Safe state file missing.")
+    with open(SAFE_STATE_PATH, "r", encoding="utf-8") as handle:
+        data = json.load(handle)
+    owners = data.get("owners") or []
+    if len(owners) < 3:
+        raise ValueError("Invalid Safe state — missing or incomplete owners.")
+    print(f"[SafeManager] Loaded Safe with owners: {owners}")
+    return data
+
+
+class SafeManager:
+    """Utility orchestrating Safe persistence and retrieval."""
+
+    def __init__(self, safe_factory: Callable[..., Any]):
+        self._safe_factory = safe_factory
+        self._safe_instance: Optional[Any] = None
+
+    @property
+    def safe(self) -> Any:
+        if self._safe_instance is None:
+            raise RuntimeError("Safe has not been initialised. Call `load_safe`." )
+        return self._safe_instance
+
+    def load_safe(self, *factory_args: Any, **factory_kwargs: Any) -> Any:
+        """Instantiate a Safe instance and persist its state immediately."""
+        safe_instance = self._safe_factory(*factory_args, **factory_kwargs)
+        self._safe_instance = safe_instance
+        persist_safe_state(safe_instance)
+        return safe_instance
+
+    def refresh_state(self) -> Dict[str, Any]:
+        """Persist the currently tracked Safe instance again and return the cache."""
+        if self._safe_instance is None:
+            raise RuntimeError("Safe has not been initialised.")
+        return persist_safe_state(self._safe_instance)
+
+    def get_cached_state(self) -> Dict[str, Any]:
+        """Load Safe metadata from the persisted cache on disk."""
+        return load_persisted_safe()