auramaxx 1.0.0-alpha.4

package/docs/APPS.md

@@ -0,0 +1,198 @@
+# Apps
+
+Overview of the AuraWallet app system — what apps are, how to install them, and how to create a minimal one.
+
+For the full developer reference (manifest format, SDK API, theming, security model, strategy hooks, examples), see [DEVELOPING-APPS.md](./DEVELOPING-APPS.md).
+
+---
+
+## Overview
+
+Apps are self-contained HTML applications that run inside sandboxed iframes on the AuraWallet dashboard. There are two kinds:
+
+- **Built-in apps** -- React components registered in `src/lib/app-registry.ts` (wallets, logs, send, etc.)
+- **Installed apps** -- standalone HTML+JS bundles installed as folders under `apps/`
+
+Apps can also be extended with AI capabilities by adding strategy fields (`ticker`, `hooks`, `sources`, etc.) to the manifest. This activates the AI engine, turning the app into a strategy that runs on a schedule or responds to messages. See [STRATEGY.md](./wallet/STRATEGY.md) for an overview and [DEVELOPING-STRATEGIES.md](./wallet/DEVELOPING-STRATEGIES.md) for the full reference.
+
+Installed apps consist of two files in a folder inside `apps/`:
+
+```
+apps/
+  my-app/
+    app.md      <-- manifest (YAML frontmatter + description)
+    index.html     <-- app entry point (HTML + inline JS/CSS)
+```
+
+The system discovers apps at runtime by scanning `apps/*/app.md`. Each app's `index.html` is served via `/api/apps/static/<folder>/index.html`, then loaded into a sandboxed iframe as a blob URL with the SDK and theme CSS injected.
+
+### How It Works (Lifecycle)
+
+```
+1. Server starts: scans apps/ → creates scoped Bearer tokens for each app
+2. GET /api/apps/manifests returns parsed manifest data to the App Store UI
+3. User clicks "ADD" in App Store
+4. ThirdPartyApp component fetches /api/apps/static/<id>/index.html
+5. ThirdPartyApp fetches GET /apps/<id>/token to get the app's Bearer token
+6. Host injects: theme CSS + token globals + App SDK script + app HTML
+7. Combined HTML is turned into a blob URL and loaded in a sandboxed iframe
+8. SDK makes direct fetch() calls to Express :4242/apps/<id>/storage/* with Bearer token
+9. SDK makes direct fetch() calls to Express :4242/apps/<id>/message for send()
+10. SDK proxies external API requests through Express :4242/apps/<id>/fetch
+11. postMessage used only for on() subscriptions (host-bridged)
+```
+
+---
+
+## Installing Apps
+
+Apps can be installed from git repos, tarballs, zips, or local paths using the CLI or the dashboard UI.
+
+### CLI
+
+```bash
+# Install from a git repo
+npx aurawallet app install github.com/user/my-app
+
+# Install from a git repo subdirectory
+npx aurawallet app install github.com/user/repo#path=apps/my-app
+
+# Install from a local path
+npx aurawallet app install ./path/to/app
+
+# Install from a tarball or zip
+npx aurawallet app install https://example.com/app.tar.gz
+
+# Override the app folder name
+npx aurawallet app install github.com/user/app --name custom-id
+
+# Overwrite an existing app
+npx aurawallet app install github.com/user/app --force
+
+# List all installed apps
+npx aurawallet app list
+
+# Update a app from its original source
+npx aurawallet app update my-app
+
+# Remove a app
+npx aurawallet app remove my-app
+
+# Remove without confirmation prompt
+npx aurawallet app remove my-app --yes
+```
+
+### Dashboard UI
+
+1. Open the App Store drawer (click the "+" button on the dashboard)
+2. Select the **ALL** or **INSTALLED** tab
+3. Paste a source URL into the "Install from URL" input at the top
+4. Click **INSTALL** (or press Enter)
+5. The app appears in the installed list immediately
+
+### Supported Sources
+
+| Pattern | Type | Example |
+|---------|------|---------|
+| Starts with `.` or `/` | Local copy | `./apps/my-app` |
+| Ends with `.tar.gz` / `.tgz` | Tarball download | `https://example.com/app.tar.gz` |
+| Ends with `.zip` | Zip download | `https://example.com/app.zip` |
+| Everything else | Git clone | `github.com/user/repo` |
+| `#path=subdir` fragment | Subdirectory | `github.com/user/repo#path=apps/foo` |
+
+### Validation
+
+The installer validates each app before copying it to `apps/`:
+
+- `app.md` must exist with valid YAML frontmatter
+- `index.html` is loaded if present (optional — headless apps use a default UI)
+- No symlinks escaping the app directory
+- No file larger than 5MB
+- Total size under 20MB
+- No ID conflict with existing apps (unless `--force`)
+
+### Provenance
+
+Each installed app gets a `.source.json` file recording where it was installed from:
+
+```json
+{
+  "type": "git",
+  "url": "https://github.com/user/my-app.git",
+  "ref": null,
+  "subdir": null,
+  "installedAt": "2026-02-10T12:00:00.000Z"
+}
+```
+
+This file is used by `npx aurawallet app update <id>` to re-install from the original source.
+
+---
+
+## Quick Start
+
+Create a minimal app in 3 steps:
+
+### 1. Create the folder
+
+```bash
+mkdir apps/hello-world
+```
+
+### 2. Create the manifest (`apps/hello-world/app.md`)
+
+```markdown
+---
+name: Hello World
+icon: Smile
+category: general
+size: 1x1
+permissions:
+data:
+---
+
+A minimal example app that displays a greeting.
+```
+
+### 3. Create the entry point (`apps/hello-world/index.html`)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+  body {
+    font-family: ui-monospace, monospace;
+    background: var(--color-surface, #fff);
+    color: var(--color-text, #0a0a0a);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 100vh;
+    font-size: 12px;
+  }
+</style>
+</head>
+<body>
+  <div>Hello from a app!</div>
+</body>
+</html>
+```
+
+The app will appear in the App Store under the "INSTALLED" tab. Click "ADD" to place it on your workspace.
+
+---
+
+## Built-in Apps
+
+These apps ship with AuraWallet and appear in the App Store under "BUILT-IN":
+
+| Type | Title | Description |
+|------|-------|-------------|
+| `wallets` | WALLETS | View and manage all wallet tiers |
+| `logs` | EVENT LOGS | Real-time event log viewer |
+| `send` | SEND | Send transactions from hot wallets |
+| `agentKeys` | AGENT KEYS | View and manage agent tokens |
+| `status` | STATUS | Server and connection status |
+| `walletDetail` | WALLET | Detailed view of a single wallet |
+| `iframe` | IFRAME | Embed any URL in an iframe |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,350 @@
+# System Architecture
+
+Technical overview of AuraWallet's processes, subsystems, and data flow.
+
+---
+
+## Process Model
+
+AuraWallet runs as four cooperating processes on a single machine:
+
+```
+┌────────────────────┐     ┌────────────────────┐
+│   Express :4242    │     │   Dashboard :4747   │
+│   Wallet API       │◄────│   Next.js UI        │
+│   25 route modules │     │   API routes        │
+└────────┬───────────┘     └────────┬────────────┘
+         │                          │
+         │        ┌─────────────────┘
+         │        │
+         ▼        ▼
+┌────────────────────┐     ┌────────────────────┐
+│  WebSocket :4748   │◄────│   Cron (background) │
+│  Event broadcast   │     │   4 scheduled jobs  │
+│  Client fan-out    │     │   No HTTP port      │
+└────────────────────┘     └────────────────────┘
+```
+
+| Process | Port | Technology | Entry Point |
+|---------|------|------------|-------------|
+| **Express** | 4242 | Express.js | `server/index.ts` |
+| **Cron** | None | Node.js (setTimeout scheduler) | `server/cron/index.ts` |
+| **MCP** | None (stdio) | `@modelcontextprotocol/sdk` | `server/mcp/server.ts` |
+| **Dashboard** | 4747 (HTTP) / 4748 (WS) | Next.js 14 | `src/` |
+
+All processes communicate through WebSocket broadcasts and HTTP calls to the Express server. Data directory: `~/.aurawallet/` (SQLite DB, vault files, config — outside repo).
+
+---
+
+## Express Server
+
+### Startup Sequence
+
+1. Run `prisma migrate deploy` (apply pending DB migrations)
+2. Preload SystemDefaults cache from DB (hot-reloadable config)
+3. Recover crashed strategy sessions + cleanup old logs
+4. Auto-unlock vault if `VAULT_PASSWORD` env var set
+5. Start Express on `127.0.0.1:4242`
+6. Load approval adapters from DB (Telegram, webhooks)
+7. Start ApprovalRouter (connects to WebSocket for events)
+8. Schedule daily strategy summaries
+
+### Middleware Stack
+
+```
+Request
+  │
+  ├─ CORS (allow all origins — blob:// iframes use opaque origin)
+  ├─ JSON body parser
+  ├─ Rate limiters (hot-reloadable via SystemDefaults)
+  │   ├─ Brute-force: 5/15min  → /unlock, /setup, /actions, /nuke, /backup
+  │   ├─ Auth:        10/min   → /auth
+  │   ├─ Transaction:  30/min  → /send, /swap, /fund, /launch (keyed by hashed token)
+  │   └─ General:     100/min  → everything else
+  ├─ Request/response logging (structured JSON + event storage)
+  └─ Error handler (500 + pino logger)
+```
+
+### Graceful Shutdown
+
+SIGTERM/SIGINT → stop approval router → close HTTP server → end active strategy sessions. Force exit after 35s if shutdown hangs.
+
+---
+
+## Route Categories
+
+25 route modules grouped by function:
+
+### Auth & Setup
+
+| Route File | Key Endpoints | Auth |
+|------------|---------------|------|
+| `setup.ts` | `POST /setup` | Public (creates vault) |
+| `unlock.ts` | `GET /unlock`, `POST /unlock`, `POST /unlock/:vaultId` | Public (password required) |
+| `lock.ts` | `POST /lock`, `POST /lock/:vaultId` | Admin |
+| `auth.ts` | `POST /auth`, `GET /auth/:id`, `POST /auth/validate`, `GET /auth/connect` | Public / Any token |
+| `actions.ts` | `POST /actions`, `POST /actions/token`, `POST /actions/:id/resolve`, `GET /actions/tokens` | Admin / action:create |
+
+### Wallet Operations
+
+| Route File | Key Endpoints | Auth |
+|------------|---------------|------|
+| `wallet.ts` | `GET /wallets`, `POST /wallet/create`, `POST /wallet/rename`, `POST /wallet/:addr/export` | wallet:list / wallet:create:* / wallet:rename / wallet:export |
+| `send.ts` | `POST /send`, `POST /send/estimate` | send:hot / send:temp |
+| `fund.ts` | `POST /fund` | fund (limit enforced) |
+| `swap.ts` | `POST /swap` | swap |
+| `launch.ts` | `POST /launch`, `POST /launch/collect-fees` | launch |
+| `batch.ts` | `POST /batch` | Public (auth per sub-request) |
+
+### Data & Queries
+
+| Route File | Key Endpoints | Auth |
+|------------|---------------|------|
+| `price.ts` | `GET /price/:address` | Public |
+| `token.ts` | `GET /token/search`, `GET /token/safety/:addr`, `GET /token/holders/:addr` | Public |
+| `portfolio.ts` | `GET /wallet/:addr/assets`, `GET /wallet/:addr/transactions` | wallet:list |
+| `resolve.ts` | ENS/address resolution | Public |
+| `defaults.ts` | `GET /defaults`, `PATCH /defaults/:key` | Admin |
+
+### Admin & Extensions
+
+| Route File | Key Endpoints | Auth |
+|------------|---------------|------|
+| `strategy.ts` | `GET /strategies`, `POST /strategies/:id/toggle`, `PUT /strategies/:id/config` | strategy:read / strategy:manage |
+| `apps.ts` | `GET/PUT/DELETE /apps/:id/storage/:key`, `POST /apps/:id/message` | app:storage |
+| `adapters.ts` | `GET/POST /adapters`, `POST /adapters/test`, `POST /adapters/restart` | adapter:manage |
+| `apikeys.ts` | `GET /apikeys`, `POST /apikeys`, `POST /apikeys/validate` | apikey:get / apikey:set |
+| `backup.ts` | Backup/export endpoints | Admin |
+| `bookmarks.ts` | `GET/POST/DELETE /bookmarks` | bookmark:write |
+| `addressbook.ts` | `GET/POST/DELETE /address-labels` | addressbook:write |
+| `ai.ts` | `GET /ai/status` | Admin |
+| `nuke.ts` | `POST /nuke` | Admin |
+
+---
+
+## Cron Server
+
+Runs as a separate Node process with no HTTP port. Uses setTimeout-based scheduler (not system cron). Jobs skip if already running (no concurrent ticks).
+
+### Jobs
+
+| Job | ID | Default Interval | Purpose |
+|-----|----|-----------------|---------|
+| **Balance Sync** | `balance-sync` | 30s | Fetches native balances (ETH/SOL) and tracked asset balances per wallet/chain via RPC |
+| **Incoming Scan** | `incoming-scan` | 10s | Scans blockchain for incoming transactions; emits `transaction:detected` events |
+| **Native Price** | `native-price` | 5min | Updates native currency prices (ETH, SOL → USD) from CoinGecko |
+| **Strategy Runner** | `strategy-runner` | 1s | Orchestrates tick cycles for all active strategies |
+
+### Communication
+
+Events emitted via HTTP POST to `http://localhost:4748/broadcast`, which the WebSocket server fans out to all connected clients (dashboards, apps, adapters).
+
+All intervals are configurable via SystemDefaults keys (hot-reloadable without restart).
+
+---
+
+## MCP Server
+
+Stdio transport — no HTTP port. Used by Claude Code (auto-discovered via `.mcp.json`), Claude Desktop, Cursor, VS Code, Windsurf.
+
+| Component | Purpose |
+|-----------|---------|
+| **Tools** | `wallet_api` (HTTP proxy), `request_human_action` (escalation) — socket/bootstrap auth handles session token activation |
+| **Resources** | `docs://api`, `docs://auth`, `docs://guide`, `docs://setup-guide` — on-demand doc access |
+| **Shared definitions** | `server/mcp/tools.ts` powers MCP, Anthropic SDK, and CLI paths |
+
+See [MCP.md](./MCP.md) for configuration and tool reference.
+
+---
+
+## Dashboard
+
+Next.js 14 application serving the UI and API routes.
+
+| Port | Protocol | Purpose |
+|------|----------|---------|
+| 4747 | HTTP | Dashboard UI (`/app`), Next.js API routes (`/api/*`) |
+| 4748 | WebSocket | Real-time event broadcast to all clients |
+
+### Key Components
+
+- **WorkspaceContext** — Manages app grid state (drag-and-drop layout)
+- **WebSocketContext** — Connects to WS, receives and distributes events
+- **AppGrid** — Renders workspace apps in a grid layout
+- **IFrameApp** — Renders third-party apps with `sandbox="allow-scripts allow-forms"` (no `allow-same-origin`)
+- **HumanActionBar** — Shows pending approvals with approve/reject UI
+
+### WebSocket Protocol
+
+Events flow: Cron/Express → `POST http://localhost:4748/broadcast` → WS server fans out to all connected clients. Event types include `balance:updated`, `action:created`, `strategy:result`, `transaction:detected`, etc.
+
+---
+
+## Subsystem: Strategy Engine
+
+16+ files in `server/lib/strategy/`. Strategies extend apps by adding scheduling and hook fields to the `app.md` manifest placed in `apps/`.
+
+### State Machine (Single Tick)
+
+```
+FETCH SOURCES
+  └─ Load external data (HTTP, API keys)
+      │
+CALL TICK HOOK (AI)
+  ├─ System prompt + hook instructions
+  ├─ Context: sources, state, config, permissions
+  └─ Output: intents[] + state updates
+      │
+APPROVAL PHASE (if config.approve=true)
+  ├─ Create HumanAction → emit via WebSocket
+  └─ Wait for human approval (2min timeout)
+      │
+EXECUTE EACH INTENT
+  ├─ Call execute hook (AI validates + transforms)
+  └─ Execute action (on-chain tx, API call)
+      │
+CALL RESULT HOOK
+  ├─ Process outcomes + state updates
+  └─ Queue follow-up intents (max depth: 3)
+```
+
+### Tick Tiers
+
+| Tier | Interval | Use Case |
+|------|----------|----------|
+| `sniper` | 10s | High-frequency trading |
+| `active` | 30s | Active management, rebalancing |
+| `standard` | 60s | Normal strategies |
+| `slow` | 5min | Periodic checks |
+| `maintenance` | 1hr | Cleanup, logging, admin tasks |
+
+### Hook Dispatch
+
+| Hook | When | Purpose |
+|------|------|---------|
+| `init` | Strategy enabled | One-time setup, initialize state |
+| `tick` | Each tick cycle | Main decision loop, output intents |
+| `execute` | Per intent | Validate and transform before action |
+| `result` | After execution | Process outcomes, queue follow-ups |
+| `message` | Human message received | Handle queued chat replies |
+
+### Context Deduplication
+
+Source data + state are hashed each tick. If the hash matches `lastContextHash`, the LLM call is skipped (reduces cost, prevents duplicate actions).
+
+---
+
+## Subsystem: App System
+
+Apps are HTML files + `app.md` manifests placed in `apps/`. They run in sandboxed iframes with scoped tokens.
+
+### Iframe Sandbox
+
+```html
+<iframe src={url} sandbox="allow-scripts allow-forms" />
+```
+
+No `allow-same-origin` — apps cannot access parent DOM, cookies, or localStorage. Communication via `postMessage` only.
+
+### App Token Registry
+
+- One token per app, created at server startup from `app.md` manifests
+- Token has app's declared permissions + `app:storage`
+- Token injected into iframe as `window.__AURA_TOKEN__`
+- Revoked on uninstall, invalidated on restart
+
+### Storage API
+
+Apps get persistent key-value storage scoped to their app ID via REST endpoints:
+
+- `GET /apps/:id/storage/:key` — Read
+- `PUT /apps/:id/storage/:key` — Write
+- `DELETE /apps/:id/storage/:key` — Delete
+
+---
+
+## Subsystem: Approval Adapters
+
+All approval channels converge on `POST /actions/:id/resolve`.
+
+```
+                    ┌── Dashboard UI
+                    │
+Agent → POST /auth ─┼── CLI terminal
+                    │
+                    ├── Telegram bot
+                    │
+                    └── Webhook → target POSTs back to /actions/:id/resolve
+```
+
+| Adapter | Bidirectional | Description |
+|---------|:---:|-------------|
+| **Telegram** | Yes | Bot with inline keyboard buttons (Approve/Reject). Long-polling via raw fetch. Supports chat mode |
+| **Webhook** | No | POSTs action events to configured URL. Optional HMAC-SHA256 signature. Notification-only |
+| **Internal Router** | Yes | CLI approval listener (`npx aurawallet cli`) for headless environments |
+
+The **ApprovalRouter** connects to WebSocket, subscribes to `action:created` events, and fans out notifications to all configured adapters.
+
+---
+
+## Data Model
+
+### Filesystem (`~/.aurawallet/`)
+
+| Path | Purpose |
+|------|---------|
+| `aurawallet.db` | SQLite database (all tables below) |
+| `vault-primary.json` | Primary vault (encrypted seed phrase) |
+| `vault-*.json` | Additional vaults |
+| `config.json` | Chain configs, server port |
+| `logs/` | Hook audit logs, strategy session logs |
+
+### Key Database Tables
+
+| Table | Purpose |
+|-------|---------|
+| `HotWallet` | Hot/temp wallets — address, encryptedPrivateKey, tokenHash (owner), chain |
+| `HumanAction` | Pending/resolved approvals — type, amount, status, metadata |
+| `AgentToken` | Token registry (display only) — tokenHash, agentId, permissions, spent |
+| `Event` | Audit trail — type, source, data (JSON), timestamp |
+| `Strategy` | Strategy records — manifest, config, state, enabled, lastTickAt |
+| `ApiKey` | External API keys — service, name, key |
+| `Transaction` | Transaction history — walletAddress, txHash, type, amount, chain |
+| `TrackedAsset` | Watched tokens — walletAddress, tokenAddress, symbol, balance |
+| `NativeBalance` | Native coin balances per wallet/chain |
+| `NativePrice` | Exchange rates (ETH, SOL → USD) |
+| `Workspace` | Dashboard tabs — name, slug, order |
+| `WorkspaceApp` | App instances — workspaceId, appType, position, config |
+
+---
+
+## Dependency Flow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        HUMAN                                     │
+│  Browser (Dashboard :4747)  /  Telegram  /  CLI terminal         │
+└──────────┬──────────────────────────────────┬────────────────────┘
+           │ HTTP                              │ WebSocket
+           ▼                                   ▼
+┌─────────────────────┐              ┌──────────────────────┐
+│   Express :4242     │──── HTTP ───►│   WebSocket :4748    │
+│   Wallet API        │              │   Event broadcast    │
+│   Strategy Engine   │              └──────────┬───────────┘
+│   Approval Router   │                         │
+└─────────┬───────────┘                         │
+          │                                     │
+          │ Prisma                              │ Events
+          ▼                                     ▼
+┌─────────────────────┐              ┌──────────────────────┐
+│   SQLite DB         │              │   Cron Server        │
+│   ~/.aurawallet/    │◄─── Prisma ──│   balance-sync       │
+│   aurawallet.db     │              │   incoming-scan      │
+└─────────────────────┘              │   native-price       │
+                                     │   strategy-runner    │
+┌─────────────────────┐              └──────────────────────┘
+│   MCP Server        │
+│   stdio transport   │──── HTTP ───► Express :4242
+│   Claude/Cursor/etc │
+└─────────────────────┘
+```