gnoman 0.1.0

package/gnomon/utils/abi_resolver.py

@@ -0,0 +1,255 @@
+"""ABI resolver with address-tethered caching and Etherscan proxy awareness."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+import time
+from collections import deque
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CHAIN_ID = 1
+DEFAULT_ETHERSCAN_BASE_URL = "https://api.etherscan.io/api"
+ABI_ROOT = Path("abi")
+ADDRESS_ABI_ROOT = ABI_ROOT / "address"
+ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+
+
+class _RateLimiter:
+    """Simple sleep-based limiter constrained to 3 calls per second."""
+
+    def __init__(self, max_calls: int = 3, period_seconds: float = 1.0):
+        self.max_calls = max_calls
+        self.period_seconds = period_seconds
+        self._calls: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> None:
+        while True:
+            sleep_for = 0.0
+            with self._lock:
+                now = time.monotonic()
+                while self._calls and now - self._calls[0] >= self.period_seconds:
+                    self._calls.popleft()
+                if len(self._calls) < self.max_calls:
+                    self._calls.append(now)
+                    return
+                sleep_for = self.period_seconds - (now - self._calls[0])
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+
+
+_RATE_LIMITER = _RateLimiter()
+_ABI_CACHE: dict[tuple[int, str], dict[str, Any]] = {}
+_FILE_CACHE: dict[tuple[int, str], Path] = {}
+_FETCH_ONCE_CACHE: dict[tuple[int, str], bool] = {}
+
+
+def _normalize_address(address: str) -> str:
+    address = address.strip().lower()
+    if not address.startswith("0x"):
+        raise ValueError(f"Invalid address format: {address}")
+    return address
+
+
+def _address_abi_path(chain_id: int, address: str) -> Path:
+    return ADDRESS_ABI_ROOT / str(chain_id) / f"{_normalize_address(address)}.json"
+
+
+def _address_meta_path(chain_id: int, address: str) -> Path:
+    return ADDRESS_ABI_ROOT / str(chain_id) / f"{_normalize_address(address)}.meta.json"
+
+
+def _read_abi_file(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as handle:
+        parsed = json.load(handle)
+    if isinstance(parsed, list):
+        return {"abi": parsed}
+    if isinstance(parsed, dict) and "abi" in parsed:
+        return parsed
+    raise ValueError(f"Unexpected ABI payload in {path}")
+
+
+def _write_address_cache(
+    chain_id: int,
+    original_address: str,
+    abi_payload: dict[str, Any],
+    *,
+    abi_target_address: str,
+    is_proxy: bool,
+    implementation: str | None,
+    abi_name_hint: str | None,
+    source: str,
+) -> Path:
+    abi_path = _address_abi_path(chain_id, original_address)
+    meta_path = _address_meta_path(chain_id, original_address)
+    abi_path.parent.mkdir(parents=True, exist_ok=True)
+
+    abi_json_canonical = json.dumps(abi_payload, sort_keys=True, separators=(",", ":"))
+    with open(abi_path, "w", encoding="utf-8") as handle:
+        json.dump(abi_payload, handle, indent=2)
+
+    metadata = {
+        "chainId": chain_id,
+        "address": _normalize_address(original_address),
+        "abiTargetAddress": _normalize_address(abi_target_address),
+        "isProxy": bool(is_proxy),
+        "implementation": _normalize_address(implementation) if implementation else None,
+        "abiNameHint": abi_name_hint,
+        "source": source,
+        "fetchedAt": datetime.now(timezone.utc).isoformat(),
+        "abiSha256": hashlib.sha256(abi_json_canonical.encode("utf-8")).hexdigest(),
+    }
+
+    with open(meta_path, "w", encoding="utf-8") as handle:
+        json.dump(metadata, handle, indent=2)
+
+    return abi_path
+
+
+def _etherscan_request(action: str, *, chain_id: int, address: str, api_key: str) -> dict[str, Any]:
+    _RATE_LIMITER.acquire()
+    base_url = os.getenv("ETHERSCAN_BASE_URL", DEFAULT_ETHERSCAN_BASE_URL)
+    response = requests.get(
+        base_url,
+        params={
+            "module": "contract",
+            "action": action,
+            "address": _normalize_address(address),
+            "apikey": api_key,
+            "chainid": chain_id,
+        },
+        timeout=20,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+def _resolve_via_etherscan(chain_id: int, original_address: str, abi_name_hint: str | None) -> Path:
+    key = (chain_id, _normalize_address(original_address))
+    if key in _FETCH_ONCE_CACHE:
+        raise RuntimeError(
+            f"ABI fetch already attempted for {original_address} on chain {chain_id} during this run"
+        )
+    _FETCH_ONCE_CACHE[key] = True
+
+    api_key = os.getenv("ETHERSCAN_API_KEY")
+    if not api_key:
+        raise RuntimeError("Missing ABI and no ETHERSCAN_API_KEY configured")
+
+    logger.info("ABI cache miss → fetching from Etherscan: %s chainId=%s", original_address, chain_id)
+
+    source_data = _etherscan_request("getsourcecode", chain_id=chain_id, address=original_address, api_key=api_key)
+    implementation = None
+    is_proxy = False
+    source_result = source_data.get("result")
+    if isinstance(source_result, list) and source_result:
+        implementation = (source_result[0].get("Implementation") or "").strip()
+        if implementation and implementation.lower() != ZERO_ADDRESS:
+            is_proxy = True
+
+    abi_target = implementation if is_proxy else original_address
+    if is_proxy:
+        logger.info(
+            "Proxy detected → implementation=%s (caching ABI for original address)",
+            _normalize_address(abi_target),
+        )
+
+    abi_data = _etherscan_request("getabi", chain_id=chain_id, address=abi_target, api_key=api_key)
+    status = str(abi_data.get("status", ""))
+    result = abi_data.get("result")
+    if status != "1" or not isinstance(result, str):
+        message = abi_data.get("result") or abi_data.get("message") or "Unknown Etherscan error"
+        raise RuntimeError(f"Failed to fetch ABI from Etherscan for {original_address}: {message}")
+
+    try:
+        abi = json.loads(result)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(f"Invalid ABI payload returned by Etherscan for {original_address}") from exc
+
+    if not abi:
+        raise RuntimeError(f"Failed to fetch ABI from Etherscan for {original_address}: empty ABI response")
+
+    payload = {"abi": abi}
+    abi_path = _write_address_cache(
+        chain_id,
+        original_address,
+        payload,
+        abi_target_address=abi_target,
+        is_proxy=is_proxy,
+        implementation=implementation,
+        abi_name_hint=abi_name_hint,
+        source="etherscan",
+    )
+    return abi_path
+
+
+def resolve_abi_file_for_address(chain_id: int, address: str, abi_name_hint: str | None = None) -> Path:
+    normalized_address = _normalize_address(address)
+    key = (chain_id, normalized_address)
+
+    if key in _FILE_CACHE:
+        return _FILE_CACHE[key]
+
+    address_path = _address_abi_path(chain_id, normalized_address)
+    if address_path.exists():
+        logger.info("ABI cache hit: %s", address_path.as_posix())
+        _FILE_CACHE[key] = address_path
+        return address_path
+
+    if abi_name_hint:
+        for candidate in (ABI_ROOT / f"{abi_name_hint}.json", ABI_ROOT / f"_{abi_name_hint}.json"):
+            if candidate.exists():
+                payload = _read_abi_file(candidate)
+                cache_path = _write_address_cache(
+                    chain_id,
+                    normalized_address,
+                    payload,
+                    abi_target_address=normalized_address,
+                    is_proxy=False,
+                    implementation=None,
+                    abi_name_hint=abi_name_hint,
+                    source="name-cache",
+                )
+                _FILE_CACHE[key] = cache_path
+                _ABI_CACHE[key] = payload
+                return cache_path
+
+    abi_path = _resolve_via_etherscan(chain_id, normalized_address, abi_name_hint)
+    _FILE_CACHE[key] = abi_path
+    return abi_path
+
+
+def resolve_abi_by_address(chain_id: int, address: str, abi_name_hint: str | None = None) -> dict[str, Any]:
+    normalized_address = _normalize_address(address)
+    key = (chain_id, normalized_address)
+    if key in _ABI_CACHE:
+        return _ABI_CACHE[key]
+
+    abi_file = resolve_abi_file_for_address(chain_id, normalized_address, abi_name_hint)
+    payload = _read_abi_file(abi_file)
+    _ABI_CACHE[key] = payload
+    return payload
+
+
+# Public API aliases requested in the spec.
+def resolveAbiByAddress(chainId: int, address: str, abiNameHint: str | None = None) -> dict[str, Any]:
+    return resolve_abi_by_address(chainId, address, abiNameHint)
+
+
+def resolveAbiFileForAddress(chainId: int, address: str, abiNameHint: str | None = None) -> Path:
+    return resolve_abi_file_for_address(chainId, address, abiNameHint)
+
+
+def get_default_chain_id() -> int:
+    value = os.getenv("ETHERSCAN_CHAIN_ID", str(DEFAULT_CHAIN_ID))
+    return int(value)

package/ios/ExportOptions.plist

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>method</key>
+  <string>app-store</string>
+  <key>signingStyle</key>
+  <string>automatic</string>
+  <key>stripSwiftSymbols</key>
+  <true/>
+  <key>compileBitcode</key>
+  <false/>
+  <key>destination</key>
+  <string>export</string>
+</dict>
+</plist>

package/ios/README.md

@@ -0,0 +1,33 @@
+# GNOMAN iOS build folder
+
+This folder is prepared for iOS shipping via Capacitor + Xcode.
+
+## What is included
+- `ios/` native workspace generated by Capacitor (`npx @capacitor/cli add ios`)
+- `scripts/build-ios.sh` for archive + IPA export
+- `ios/ExportOptions.plist` for App Store export defaults
+
+## One-time setup (macOS)
+1. Install Xcode + Command Line Tools.
+2. From repo root:
+   - `npm install`
+   - `npm run ios:add`
+
+## Daily iOS build
+1. Build/sync web assets:
+   - `npm run ios:sync`
+2. Open in Xcode:
+   - `npm run ios:open`
+3. Configure signing (Team, Bundle ID, Provisioning).
+4. Archive/export IPA:
+   - `npm run ios:archive`
+
+## API target
+The iOS app loads the renderer bundle and calls your backend endpoint configured by GNOMAN settings/environment.
+
+## Ready-to-ship checklist
+- [ ] App icon + launch screen configured in Xcode
+- [ ] Production backend URL configured
+- [ ] Signing profile is valid
+- [ ] Archive succeeds for `generic/platform=iOS`
+- [ ] Exported IPA installs and launches

package/jest.config.ts

@@ -0,0 +1,18 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  testMatch: ['**/?(*.)+(test).ts'],
+  moduleNameMapper: {
+    '^src/(.*)$': '<rootDir>/src/$1',
+    '^backend/(.*)$': '<rootDir>/backend/$1',
+    '^main/(.*)$': '<rootDir>/main/$1'
+  },
+  collectCoverageFrom: ['src/**/*.ts', 'backend/**/*.ts', 'main/**/*.ts', '!**/__tests__/**'],
+  coverageDirectory: '<rootDir>/coverage'
+};
+
+export default config;

package/keyring/__init__.py

@@ -0,0 +1,17 @@
+"""Lightweight keyring stub for GNOMAN tests."""
+
+from typing import Dict, Optional
+
+_STORE: Dict[tuple[str, str], str] = {}
+
+
+def get_password(service_name: str, username: str) -> Optional[str]:
+    return _STORE.get((service_name, username))
+
+
+def set_password(service_name: str, username: str, password: str) -> None:
+    _STORE[(service_name, username)] = password
+
+
+def delete_password(service_name: str, username: str) -> None:
+    _STORE.pop((service_name, username), None)

package/launcher.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode=${1:-dev}
+
+serviceName=gnoman-backend.service
+serviceWasRunning=0
+
+isServiceActive() {
+  systemctl is-active --quiet $serviceName
+}
+
+stopServiceIfRunning() {
+  if isServiceActive; then
+    serviceWasRunning=1
+    sudo systemctl stop $serviceName
+  fi
+}
+
+startServiceIfNeeded() {
+  sudo systemctl enable --now $serviceName >/dev/null 2>&1 || true
+  sudo systemctl start $serviceName >/dev/null 2>&1 || true
+}
+
+restartServiceIfItWasRunning() {
+  if [ $serviceWasRunning -eq 1 ]; then
+    sudo systemctl start $serviceName >/dev/null 2>&1 || true
+  fi
+}
+
+case $mode in
+  dev)
+    echo launcher mode dev
+    echo ensuring port 4399 is free for ts-node-dev
+
+    stopServiceIfRunning
+
+    trap restartServiceIfItWasRunning EXIT INT TERM
+
+    npm run dev --host
+    ;;
+
+  prod)
+    echo launcher mode prod
+    echo ensuring systemd backend is running
+
+    startServiceIfNeeded
+
+    npm run build
+    node scripts/launchElectron.js
+    ;;
+
+  *)
+    echo usage: ./launcher.sh dev or ./launcher.sh prod
+    exit 2
+    ;;
+esac

package/license.env

@@ -0,0 +1,2 @@
+LICENSE_KEY=<raw token>
+VALIDATED_AT=<unix timestamp>

package/licensingServer/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "licensingServer",
+  "version": "1.0.0",
+  "private": true,
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "express": "^4.19.2",
+    "express-rate-limit": "^7.4.0",
+    "json-stable-stringify": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.30",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.6.3"
+  }
+}

package/licensingServer/src/config/keys.ts

@@ -0,0 +1,84 @@
+import fs from 'fs';
+import crypto from 'crypto';
+
+export type LoadedKeys = {
+  privateKeyPem: string;
+  publicKeyPem: string;
+};
+
+function readPemOrThrow(path: string, label: string): string {
+  try {
+    const pem = fs.readFileSync(path, 'utf8');
+    if (!pem.includes('BEGIN')) {
+      throw new Error('Not PEM formatted');
+    }
+    return pem;
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`${label} read failed at ${path}: ${message}`);
+  }
+}
+
+function parsePrivateKeyOrThrow(pem: string): crypto.KeyObject {
+  try {
+    return crypto.createPrivateKey(pem);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Private key parse failed: ${message}`);
+  }
+}
+
+function parsePublicKeyOrThrow(pem: string): crypto.KeyObject {
+  try {
+    return crypto.createPublicKey(pem);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Public key parse failed: ${message}`);
+  }
+}
+
+function assertMatchingKeypairOrThrow(privateKey: crypto.KeyObject, publicKey: crypto.KeyObject) {
+  const msg = Buffer.from('license-key-selftest', 'utf8');
+
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(msg);
+  signer.end();
+  const sig = signer.sign(privateKey);
+
+  const verifier = crypto.createVerify('RSA-SHA256');
+  verifier.update(msg);
+  verifier.end();
+  const ok = verifier.verify(publicKey, sig);
+
+  if (!ok) {
+    throw new Error('Keypair self-test failed: public key does not verify private key signatures');
+  }
+}
+
+export function loadKeysOrExit(): LoadedKeys {
+  const privatePath = process.env.LICENSE_PRIVATE_KEY_PATH ?? './keys/license-private.pem';
+  const publicPath = process.env.LICENSE_PUBLIC_KEY_PATH ?? './keys/license-public.pem';
+
+  try {
+    const privateKeyPem = readPemOrThrow(privatePath, 'LICENSE_PRIVATE_KEY_PATH');
+    const publicKeyPem = readPemOrThrow(publicPath, 'LICENSE_PUBLIC_KEY_PATH');
+
+    const priv = parsePrivateKeyOrThrow(privateKeyPem);
+    const pub = parsePublicKeyOrThrow(publicKeyPem);
+
+    if (priv.asymmetricKeyType !== 'rsa') {
+      throw new Error(`Private key is not RSA (got ${priv.asymmetricKeyType})`);
+    }
+    if (pub.asymmetricKeyType !== 'rsa') {
+      throw new Error(`Public key is not RSA (got ${pub.asymmetricKeyType})`);
+    }
+
+    assertMatchingKeypairOrThrow(priv, pub);
+
+    return { privateKeyPem, publicKeyPem };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`FATAL: License key configuration error: ${message}`);
+    process.exit(1);
+  }
+}

package/licensingServer/src/index.ts

@@ -0,0 +1,30 @@
+import express from 'express';
+import rateLimit from 'express-rate-limit';
+import { loadKeysOrExit } from './config/keys';
+import { licensesRouter } from './routes/licenses';
+
+const keys = loadKeysOrExit();
+
+const app = express();
+
+app.use(express.json({ limit: '16kb' }));
+
+app.use(
+  rateLimit({
+    windowMs: 60_000,
+    limit: 120,
+    standardHeaders: 'draft-7',
+    legacyHeaders: false
+  })
+);
+
+app.get('/health', (_req, res) => {
+  res.json({ ok: true });
+});
+
+app.use('/licenses', licensesRouter(keys));
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => {
+  console.log(`licensingServer listening on :${port}`);
+});

package/licensingServer/src/lib/canonicalize.ts

@@ -0,0 +1,5 @@
+import stringify from 'json-stable-stringify';
+
+export function canonicalizeLicenseJson(obj: unknown): string {
+  return stringify(obj);
+}

package/licensingServer/src/lib/crypto.ts

@@ -0,0 +1,25 @@
+import crypto from 'crypto';
+
+export const LICENSE_ALG = 'RSA-SHA256';
+
+export function signBytesToB64(privateKeyPem: string, payloadBytes: Buffer): string {
+  const sign = crypto.createSign(LICENSE_ALG);
+  sign.update(payloadBytes);
+  sign.end();
+  const signature = sign.sign(privateKeyPem);
+  return signature.toString('base64');
+}
+
+export function verifyB64Signature(publicKeyPem: string, payloadBytes: Buffer, signatureB64: string): boolean {
+  let sig: Buffer;
+  try {
+    sig = Buffer.from(signatureB64, 'base64');
+  } catch {
+    return false;
+  }
+
+  const verify = crypto.createVerify(LICENSE_ALG);
+  verify.update(payloadBytes);
+  verify.end();
+  return verify.verify(publicKeyPem, sig);
+}

package/licensingServer/src/lib/validate.ts

@@ -0,0 +1,62 @@
+export type IssueInput = {
+  customer: string;
+  product: string;
+  plan: string;
+  expiresAt?: string | null;
+  features?: Record<string, unknown>;
+  machineHash?: string | null;
+};
+
+export type LicensePayload = {
+  licenseId: string;
+  issuedAt: string;
+  expiresAt: string | null;
+  customer: string;
+  product: string;
+  plan: string;
+  features: Record<string, unknown>;
+  machineHash?: string | null;
+  nonce: string;
+};
+
+export function isIsoDateString(s: unknown): boolean {
+  if (typeof s !== 'string') {
+    return false;
+  }
+  const t = Date.parse(s);
+  return Number.isFinite(t);
+}
+
+export function assertString(name: string, v: unknown) {
+  if (typeof v !== 'string' || v.trim().length === 0) {
+    throw new Error(`${name} is required`);
+  }
+}
+
+export function assertMaxBytes(name: string, bytes: number, maxBytes: number) {
+  if (bytes > maxBytes) {
+    throw new Error(`${name} too large (${bytes} bytes > ${maxBytes} bytes)`);
+  }
+}
+
+export function assertExpiresNotBeforeIssued(issuedAtIso: string, expiresAtIso: string) {
+  const i = Date.parse(issuedAtIso);
+  const e = Date.parse(expiresAtIso);
+  if (!Number.isFinite(i) || !Number.isFinite(e)) {
+    throw new Error('Invalid issuedAt/expiresAt');
+  }
+  if (e < i) {
+    throw new Error('expiresAt cannot be before issuedAt');
+  }
+}
+
+export function isExpired(expiresAt: string | null): boolean {
+  if (!expiresAt) {
+    return false;
+  }
+  const e = Date.parse(expiresAt);
+  if (!Number.isFinite(e)) {
+    return true;
+  }
+  return Date.now() > e;
+}

package/licensingServer/src/middleware/auth.ts

@@ -0,0 +1,20 @@
+import { Request, Response, NextFunction } from 'express';
+
+export function requireIssueApiKey(req: Request, res: Response, next: NextFunction) {
+  const isProd = (process.env.NODE_ENV ?? '').toLowerCase() === 'production';
+  if (!isProd) {
+    return next();
+  }
+
+  const required = process.env.LICENSE_ISSUE_API_KEY;
+  if (!required || required.trim().length === 0) {
+    return res.status(500).json({ error: 'Server misconfigured: LICENSE_ISSUE_API_KEY missing' });
+  }
+
+  const provided = req.header('x-license-issue-key') ?? '';
+  if (provided !== required) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  return next();
+}