auramaxx 0.0.1

package/docs/API.md

@@ -0,0 +1,127 @@
+# AuraMaxx API
+
+This file is the **API entrypoint** for agents.
+
+Use this page for the common path, then jump to the deep reference docs listed below.
+
+Server base URL:
+
+```text
+http://localhost:4242
+```
+
+## Common Path (Agent First)
+
+### 1) Request an agent token
+
+```http
+POST /auth
+Content-Type: application/json
+
+{
+  "agentId": "my-agent",
+  "profile": "strict",
+  "profileVersion": "v1",
+  "pubkey": "<RSA public key PEM or base64>",
+  "action": {                          // optional: auto-execute on approval
+    "endpoint": "/send",
+    "method": "POST",
+    "body": { "to": "0x...", "amount": "0.01" }
+  }
+}
+```
+
+When `action` is provided, the pre-computed action auto-executes with the newly-minted token after human approval.
+
+Human approves in dashboard, then poll:
+
+```http
+GET /auth/:requestId?secret=:secret
+```
+
+### 2) Read a secret (`get_secret`)
+
+`get_secret` maps to credential APIs under the hood:
+
+- find credential metadata: `GET /credentials`
+- read encrypted fields: `POST /credentials/:id/read`
+
+### 3) Set/update a secret (`put_secret`)
+
+Most common write path:
+
+```http
+POST /credentials
+```
+
+Update existing credential:
+
+```http
+PUT /credentials/:id
+```
+
+### 4) Write diary (`write_diary`)
+
+```http
+POST /what_is_happening/diary
+```
+
+### 5) Call broader APIs (`wallet_api`)
+
+Common starts:
+
+```http
+GET /wallets
+GET /token/search?q=PEPE&chain=base
+POST /wallet/create
+POST /send
+POST /swap
+POST /fund
+```
+
+If you get `403`, request human approval via `POST /auth` (include an `action` field for auto-execute on approval).
+
+## Quick Common Endpoints
+
+| Endpoint | Method | Typical Use |
+|---|---|---|
+| `/auth` | POST | Request token (approval flow) |
+| `/auth/:requestId?secret=...` | GET | Poll token request status |
+| `/credentials` | GET | List credential metadata |
+| `/credentials` | POST | Create credential |
+| `/credentials/:id/read` | POST | Read credential (encrypted response) |
+| `/credentials/:id` | PUT | Update credential |
+| `/credential-shares` | POST | Create share link |
+| `/credential-shares/gist` | POST | Create GitHub secret gist share |
+| `/what_is_happening/diary` | POST | Append diary note |
+| `/wallets` | GET | List wallets |
+
+## Read More In Depth (Complete API Docs Map)
+
+All API docs files are listed here. Keep this section updated when adding/moving API docs.
+
+### Getting Started
+
+- `docs/API.md` (this file)
+- [`docs/api/authentication.md`](/api?doc=api/authentication.md)
+
+### Secrets
+
+- [`docs/api/secrets/credentials.md`](/api?doc=api/secrets/credentials.md)
+- [`docs/api/secrets/sharing.md`](/api?doc=api/secrets/sharing.md)
+- [`docs/api/secrets/api-keys.md`](/api?doc=api/secrets/api-keys.md)
+
+### Wallets
+
+- [`docs/api/wallets/core.md`](/api?doc=api/wallets/core.md)
+- [`docs/api/wallets/data-portfolio.md`](/api?doc=api/wallets/data-portfolio.md)
+- [`docs/api/wallets/apps-strategies.md`](/api?doc=api/wallets/apps-strategies.md)
+
+### System
+
+- [`docs/api/system.md`](/api?doc=api/system.md)
+
+## Related Docs
+
+- [AUTH.md](/docs/AUTH.md) — full auth/permission model
+- [MCP.md](/docs/MCP.md) — MCP tools and usage

package/docs/APPS.md

@@ -0,0 +1,199 @@
+# Apps
+
+Overview of the AuraMaxx 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 AuraMaxx 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
+auramaxx app install github.com/user/my-app
+
+# Install from a git repo subdirectory
+auramaxx app install github.com/user/repo#path=apps/my-app
+
+# Install from a local path
+auramaxx app install ./path/to/app
+
+# Install from a tarball or zip
+auramaxx app install https://example.com/app.tar.gz
+
+# Override the app folder name
+auramaxx app install github.com/user/app --name custom-id
+
+# Overwrite an existing app
+auramaxx app install github.com/user/app --force
+
+# List all installed apps
+auramaxx app list
+
+# Update an app from its original source
+auramaxx app update my-app
+
+# Remove an app
+auramaxx app remove my-app
+
+# Remove without confirmation prompt
+auramaxx 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 `auramaxx 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 an 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 AuraMaxx and appear in the App Store under "BUILT-IN":
+
+| Type | Title | Singleton | Description |
+|------|-------|:---------:|-------------|
+| `logs` | EVENT LOGS | Yes | Real-time event log viewer |
+| `send` | SEND | Yes | Send transactions from hot wallets |
+| `agentKeys` | AGENT KEYS | Yes | View and manage agent tokens |
+| `token` | TOKEN | No | Market data for a token |
+| `setup` | GETTING STARTED | Yes | First-time setup wizard |
+| `transactions` | TRANSACTIONS | Yes | Transaction history log |
+| `walletDetail` | WALLET | No | Detailed view of a single wallet |
+| `iframe` | IFRAME | No | Embed any URL in an iframe |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,235 @@
+# Architecture
+
+How AuraMaxx works, from the simple version to the full security model.
+
+---
+
+## What AuraMaxx Is
+
+AuraMaxx is a local-first credential and wallet manager designed for AI agents. It runs on your machine, stores secrets encrypted on disk, and gives agents scoped access through short-lived tokens that a human must approve.
+
+```
+Human unlocks vault → Agent requests access → Human approves → Agent gets scoped token
+```
+
+That's it. Everything else is enforcement.
+
+---
+
+## The Simple Version
+
+**Three things run locally:**
+
+1. **Wallet server** (`:4242`) — the API. Handles auth, wallets, credentials, transactions.
+2. **Dashboard** (`:4747`) — web UI for approvals, wallet management, monitoring.
+3. **Cron** — background jobs (balance sync, price updates). No HTTP port.
+
+**Data lives in `~/.auramaxx/`** — SQLite database, encrypted vault files, config. All local, outside the repo.
+
+**Agents talk to the wallet server** with a Bearer token. Humans interact through the dashboard or CLI.
+
+---
+
+## How Agents Get Access
+
+Agents cannot self-issue tokens. Every token starts with a human decision.
+
+### The standard flow
+
+```
+1. Agent sends POST /auth with { agentId, profile, pubkey }
+2. Server creates a pending request, returns requestId + secret + approveUrl
+3. Human opens approval URL, reviews permissions, approves or denies
+4. Agent polls GET /auth/:requestId?secret=... and claims the encrypted token
+5. Agent uses token as Bearer header on all subsequent API calls
+```
+
+The token is encrypted to the agent's RSA public key during transport — the server never sends a plaintext token over the wire.
+
+### Why profiles instead of raw permissions
+
+Agents request access by **profile name** (`strict`, `dev`, `admin`), not by listing individual permissions. This is intentional:
+
+- Profiles bundle sensible defaults — permissions, vault scopes, field redactions, TTL, read limits
+- Agents cannot request arbitrary permission sets on the standard path (`POST /auth` rejects raw `permissions`, `ttl`, and `credentialAccess`)
+- Humans review a known profile with predictable behavior, not an ad-hoc permission list
+- Overrides are **tighten-only** — an agent can ask for less access than a profile grants, never more
+
+See [AUTH.md — Built-in Profiles](./AUTH.md#built-in-profiles-v1) for the full profile breakdown.
+
+---
+
+## Why It's Secure
+
+### 1. Memory-only auth state
+
+The core security property: **auth decisions never touch the database**.
+
+```
+IN MEMORY (drives all auth):           IN DATABASE (display only):
+├── SIGNING_KEY (random 32 bytes)      ├── AgentToken table
+├── sessions Map (spending tracking)    │   ├── tokenHash
+├── revokedTokens Set                   │   ├── agentId, limit, spent
+└── pendingRequests Map                 │   └── isRevoked, expiresAt
+```
+
+- `SIGNING_KEY` is generated fresh on every server start — all old tokens are instantly invalid
+- A stolen database is useless without the in-memory key
+- Token validation checks memory signature + expiry + revocation status, never the DB
+- Restart = forced re-approval = security feature, not a bug
+
+### 2. Three-layer enforcement
+
+Every API call passes through three independent checks:
+
+**Layer 1 — Profile issuance** (what the token was created with):
+- Permissions, vault scopes, field exclusions, TTL, read budget
+- Set at creation time, cannot be modified after
+
+**Layer 2 — Route middleware** (checked on every request):
+- Signature validation against in-memory `SIGNING_KEY`
+- Expiry check
+- Revocation check
+- Permission check (`requirePermission` / `hasAnyPermission`)
+
+**Layer 3 — Credential access policy** (for secret operations):
+- Vault/tag/ID selector matching
+- Per-token read budget tracking
+- Field minimization (`excludeFields` strips sensitive data before encryption)
+- Rate limiting per credential per minute
+
+A request must pass all three layers. Issuance defines the ceiling; runtime enforcement is the live guardrail.
+
+### 3. Encrypted transport everywhere
+
+- **Vault unlock**: password is RSA-OAEP encrypted before transmission (server pubkey from `GET /auth/connect`)
+- **Token claim**: token is encrypted to the agent's RSA public key
+- **Secret reads**: credential fields are encrypted to the caller's key material
+- No plaintext secrets cross the wire in normal operation
+
+### 4. Human approval gate
+
+Every token issuance path requires human involvement:
+
+| Path | Human gate |
+|------|-----------|
+| `POST /auth` | Human must approve the pending request |
+| `POST /actions` | Human must resolve the action (`/actions/:id/resolve`) |
+| `POST /actions/token` | Caller must already have admin token |
+| Socket bootstrap | Trust-dependent (configurable, default: `localAutoApprove = false`) |
+
+Agents cannot escalate their own permissions — `admin:*` and `action:create` are blocked from self-escalation via `POST /actions`.
+
+---
+
+## Credential Vault
+
+Credentials are the core data type. The vault provides encrypted storage with scoped access.
+
+### Encryption
+
+```
+Vault Mnemonic → HKDF("credential-v1:<vaultId>") → Per-Vault Key → AES-256-GCM per credential
+```
+
+- Each vault derives its own encryption key from its mnemonic
+- Credentials are individual encrypted files under `~/.auramaxx/credentials/`
+- Metadata (name, type, tags) stays plaintext for listing/search
+- Sensitive fields are encrypted at rest and in transport
+
+### Access control
+
+Token-level scoping via `credentialAccess`:
+
+- **Selectors** define where: `vault:agent`, `vault:*`, `tag:<label>`, `cred-xxxxx`, `*`
+- **Permissions** define what: `secret:read`, `secret:write`, `totp:read`
+- **Limits** define how much: `maxReads`, `ttl`, per-credential rate limits
+- **Field minimization** defines visibility: `excludeFields` strips fields before they're encrypted to the caller
+
+Mental model: permissions say **action**, selectors say **scope**, limits say **budget**.
+
+---
+
+## Process Model
+
+```
+┌────────────────────┐     ┌────────────────────┐
+│   Express :4242    │     │   Dashboard :4747   │
+│   Wallet API       │◄────│   Next.js UI        │
+└────────┬───────────┘     └────────┬────────────┘
+         │                          │
+         ▼                          ▼
+┌────────────────────┐     ┌────────────────────┐
+│  WebSocket :4748   │◄────│   Cron (background) │
+│  Event broadcast   │     │   Balance sync      │
+└────────────────────┘     │   Price updates     │
+                           └────────────────────┘
+┌────────────────────┐
+│  MCP Server        │
+│  stdio transport   │──── HTTP ───► Express :4242
+│  Claude/Cursor/etc │
+└────────────────────┘
+```
+
+| Process | Port | Purpose |
+|---------|------|---------|
+| **Express** | 4242 | Wallet API — auth, wallets, credentials, transactions |
+| **Dashboard** | 4747 / 4748 (WS) | Web UI + real-time event broadcast |
+| **Cron** | None | Background jobs — balance sync, price updates |
+| **MCP** | None (stdio) | Tool interface for AI agents (Claude, Cursor, etc.) |
+
+All processes communicate through WebSocket broadcasts and HTTP calls to Express.
+
+### Data directory (`~/.auramaxx/`)
+
+| Path | Purpose |
+|------|---------|
+| `auramaxx.db` | SQLite database |
+| `vault-primary.json` | Primary vault (encrypted seed phrase) |
+| `vault-*.json` | Additional vaults |
+| `config.json` | Chain configs, server port |
+
+---
+
+## Middleware Stack
+
+```
+Request
+  │
+  ├─ CORS
+  ├─ JSON body parser
+  ├─ Rate limiters (hot-reloadable)
+  │   ├─ Brute-force: 5/15min  → /unlock, /setup, /actions, /nuke
+  │   ├─ Auth:        10/min   → /auth
+  │   ├─ Transaction:  30/min  → /send, /swap, /fund, /launch
+  │   └─ General:     100/min  → everything else
+  ├─ Request logging
+  └─ Error handler
+```
+
+Rate limits are configurable via SystemDefaults (hot-reloadable without restart).
+
+---
+
+## Token Lifecycle
+
+```
+Agent requests token  →  Pending (in memory, waiting for human)
+Human approves        →  Token signed with SIGNING_KEY, encrypted to agent pubkey
+Agent claims token    →  One-time claim, token cleared from escrow
+Agent uses token      →  Every call: signature + expiry + revocation + permission check
+                         Spending tracked in memory, synced to DB for display
+Server restarts       →  Memory wiped, new SIGNING_KEY, all tokens invalid
+                         Agent must re-request, human must re-approve
+Token revoked         →  Added to revokedTokens set, immediately rejected
+```
+
+---
+
+## Related Docs
+
+- [Auth](./AUTH.md) — practical auth guide, profile builder, CLI examples
+- [Security](./security.md) — security model deep dive, enforcement details
+- [MCP](./MCP.md) — MCP server configuration and tool reference
+- [CLI](./CLI.md) — headless CLI mode
+- [Credentials](./credentials.md) — credential types and vault reference