auramaxx 0.0.1

package/docs/AUTH.md

@@ -0,0 +1,318 @@
+# Authentication & Permissions
+
+This document is the practical entry point for onboarding and using AuraMaxx auth safely.
+
+## Quick Start (read this first)
+
+### Who is this for?
+
+- 🤖 **Agents/CI tooling**: prefer `POST /auth` and token polling flows.
+- 🧑 **Humans**: open the approval link (`/approve/<requestId>`) to review and approve/deny requests.
+- 🛠️ **Developers running local MCP/CLI**: use MCP/socket defaults only when local trust is intentionally configured.
+
+### Fastest path (recommended)
+
+#### 1) Agent onboarding (least privilege, human approval)
+
+```bash
+# Request an agent token under a named profile.
+auramaxx auth request --agent-id my-agent --profile strict
+
+# Wait for approval in dashboard, then poll locally (or use --no-wait and poll manually)
+auramaxx auth poll <requestId> --secret <secret> --private-key-file /tmp/aura-agent-private.pem
+```
+
+#### 2) Human unlock (admin session)
+
+```bash
+auramaxx unlock
+# (or: curl POST /unlock for script-driven unlock with encrypted password)
+```
+
+#### 3) Validate and troubleshoot
+
+```bash
+curl -sS http://localhost:4242/auth/validate \
+  -H "Authorization: Bearer <token>"
+```
+
+- `200` = token is currently valid for permission checks.
+- non-200 = expired/revoked/syntax mismatch, re-run onboarding.
+
+---
+
+## Decision Matrix (pick the right path)
+
+| Use case | Best flow | Why | Typical command/endpoint |
+|---|---|---|---|
+| Standard agent needs ongoing access | **Profile onboarding** | Bound by profile defaults + tighten-only overrides | `POST /auth` (via `auramaxx auth request`) |
+| One-off escalation for one action | **Auth + action** | Token + auto-execute in one approval | `POST /auth` with `action` field |
+| Trusted admin automation / headless tool | **Direct issue (admin only)** | Explicit admin-controlled issuance | `POST /actions/token` |
+| Local MCP/CLI bootstrap on same host | **Socket bootstrap** | Fast path for trusted local callers | Unix socket + trust defaults |
+| Validate active token before use | **Token check** | Detect expiration/revocation before a failing call | `POST /auth/validate` |
+| Revoke compromised token | **Revoke token** | Immediate disable for one token | `POST /actions/tokens/revoke` |
+
+If uncertain, default to **profile onboarding** and keep it strict.
+
+---
+
+## Auth Flow Summary
+
+- `POST /auth` is **profile-based** and requires human approval. Supports an optional `action` field for auto-execute on approval.
+- `POST /actions` is **internal** (used by the strategy engine). Agents should use `POST /auth` with `action` instead.
+- `POST /actions/token` is **admin-only** and supports profile-mode or permissions-mode (never both).
+- `POST /auth/validate` checks token validity at runtime.
+- `POST /actions/tokens/revoke` invalidates issued tokens.
+
+---
+
+## For Agents
+
+> **IMPORTANT**: Agents should request tokens via `POST /auth` and use the approval flow. Human approval is still the security boundary, even when local trust is enabled.
+
+## CLI (recommended)
+
+```bash
+# Create auth request (profile flow)
+auramaxx auth request --agent-id my-agent --profile strict
+
+# Poll with CLI helper (agent private key decrypts response)
+auramaxx auth poll <requestId> --secret <secret> --private-key-file /tmp/aura-agent-private.pem
+```
+
+Advanced option (no interactive poll):
+
+```bash
+auramaxx auth request --agent-id my-agent --profile strict --no-wait
+auramaxx auth poll <requestId> --secret <secret> --private-key-file /tmp/aura-agent-private.pem --once
+```
+
+## MCP / socket bootstrap
+
+```bash
+# Start runtime
+auramaxx
+
+# Optional one-time IDE setup
+auramaxx mcp --install
+```
+
+MCP bootstrap path:
+1. Unix socket auto-approve (if local trust permits)
+2. `AURA_TOKEN` env fallback
+
+If socket bootstrap is blocked, fall back to normal token flow:
+
+```bash
+AURA_TOKEN=<token> auramaxx mcp
+```
+
+## Raw HTTP / cURL examples
+
+### `POST /auth` (profile flow)
+
+`POST /auth` is profile-based. Raw permission payloads and raw TTL are rejected.
+
+```bash
+# 1) Generate ephemeral RSA keypair for token transport
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out /tmp/aura-agent-private.pem
+openssl rsa -in /tmp/aura-agent-private.pem -pubout -out /tmp/aura-agent-public.pem
+PUBKEY_B64="$(base64 < /tmp/aura-agent-public.pem | tr -d '\n')"
+
+# 2) Request token issuance
+curl -sS -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d "{\"agentId\":\"my-agent\",\"profile\":\"strict\",\"profileVersion\":\"v1\",\"pubkey\":\"$PUBKEY_B64\"}"
+
+# 3) Poll request status
+curl -sS "http://localhost:4242/auth/<requestId>?secret=<secret>"
+```
+
+### `POST /auth/validate`
+
+```bash
+curl -sS -X POST http://localhost:4242/auth/validate \
+  -H "Authorization: Bearer <token>"
+```
+
+### `POST /actions/token`
+
+`/actions/token` supports **exactly one** issue mode:
+
+- `profile` mode: `profile`, `profileVersion`, optional tighten-only overrides
+- `permissions` mode: explicit permission grant
+
+```bash
+curl -sS -X POST http://localhost:4242/actions/token \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"profile":"strict","profileVersion":"v1","pubkey":"'$PUBKEY_B64'"}'
+```
+
+### Revoke a token
+
+```bash
+curl -sS -X POST http://localhost:4242/actions/tokens/revoke \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jti":"<token_id>","reason":"Compromised agent key"}'
+```
+
+## Auth Flow Comparison
+
+| Flow | Endpoint | Human gate? | Intended for |
+|---|---|---|---|
+| Agent Request | `POST /auth` + claim | Yes | Standard agent onboarding |
+| Auth + Action | `POST /auth` with `action` field | Yes | One-off action-scoped escalation (auto-executes on approval) |
+| Direct Admin Issue | `POST /actions/token` | Yes (admin required) | Headless/admin orchestration |
+| Local Socket | Unix socket bootstrap | Trust-dependent | Fast local MCP bootstrap |
+| Unlock/session | `POST /unlock` | Yes | Local machine setup/bootstrap |
+
+## Profile-Based Issuance
+
+### `/auth` is profile-only
+
+`POST /auth` requires:
+- `agentId`
+- `profile`
+- `pubkey`
+
+Optional:
+- `profileVersion` (defaults to `v1`)
+- `profileOverrides` (tighten-only)
+- `limit` / `limits.fund`
+- `action` — pre-computed action to auto-execute on approval: `{ endpoint, method, body? }`
+
+Rejected:
+- raw `permissions`
+- raw `ttl`
+- raw `credentialAccess`
+
+### `/actions/token` strict mode
+
+`POST /actions/token` accepts **exactly one** issuance strategy:
+
+- profile mode (`profile`, `profileVersion`, `profileOverrides`)
+- permissions mode (`permissions`)
+
+### Built-in Profiles (v1)
+
+| Profile | Permissions | Read Scopes | Write Scopes | Excluded Fields | TTL | Max Reads |
+|---------|------------|-------------|-------------|-----------------|-----|-----------|
+| `strict` | `secret:read` | `vault:agent` | none | `password, cvv, privateKey, seedPhrase, refresh_token` | 15 min | 50 |
+| `dev` | `wallet:list, secret:read, secret:write, action:create, action:read, action:resolve` | `vault:*` | `vault:*` | `cvv, seedPhrase, privateKey, refresh_token` | 1 hour | 500 |
+| `admin` | `admin:*` | `*` | `*` | none | 1 hour | unlimited |
+
+### Credential Scope Selectors
+
+Use selectors to bound what an agent can see or edit:
+
+- `vault:agent` — agent vault only
+- `vault:primary` — primary vault only
+- `vault:*` — all vaults
+- `*` — all credentials
+- `tag:<label>` — credentials with a specific tag
+- `cred-xxxxx` — a specific credential by ID
+
+### Profile Overrides (`profileOverrides`)
+
+Overrides are **tighten-only** — they can only reduce privilege, never broaden it.
+
+| Override Key | Type | Tighten-only Rule |
+|---|---|---|
+| `ttlSeconds` | number | Must be shorter than profile default |
+| `maxReads` | number | Must be ≤ profile default |
+| `scope` | string[] | Must be subset of profile permissions |
+| `readScopes` | string[] | Must be subset of profile read scopes |
+| `writeScopes` | string[] | Must be subset of profile write scopes |
+| `excludeFields` | string[] | Can only add exclusions, never remove profile-required ones |
+
+Example — request a `dev` profile but restrict to agent vault and shorten TTL:
+
+```bash
+curl -sS -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "my-agent",
+    "profile": "dev",
+    "pubkey": "'$PUBKEY_B64'",
+    "profileOverrides": {
+      "ttlSeconds": 600,
+      "readScopes": ["vault:agent"],
+      "writeScopes": ["vault:agent"],
+      "excludeFields": ["cvv", "seedPhrase", "privateKey", "refresh_token", "password"]
+    }
+  }'
+```
+
+Use `POST /actions/token/preview` to inspect the effective policy before issuing:
+
+```bash
+curl -sS -X POST http://localhost:4242/actions/token/preview \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"profile": "dev", "profileOverrides": {"ttlSeconds": 600}}'
+```
+
+## Socket defaults and trust
+
+Defaults:
+
+- API server: `http://localhost:4242`
+- Socket path: `/tmp/aura-cli-<uid>.sock`
+- Local socket perms: `0600`
+- Default trust profile: `dev`
+- `trust.localAutoApprove = false`
+
+Use admin auth for trust tuning:
+
+```bash
+curl -sS -X PATCH http://localhost:4242/defaults/trust.localAutoApprove \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"value": true}'
+```
+
+## Approving Requests (for humans)
+
+When an agent requests access, a human must approve it. Every request gets a dedicated approval page:
+
+```
+http://localhost:4747/approve/<requestId>
+```
+
+The page shows the action summary, requested permissions, risk level, and spending limits. Review the details, then click **Approve** or **Deny**.
+
+**Where to find the link:**
+- The `POST /auth` response includes an `approveUrl` field — agents should surface this to the human
+- MCP `auth` tool returns `approveUrl` — give this link to the human
+- CLI `auramaxx auth request` prints the approval URL
+- The dashboard at `http://localhost:4747` also shows pending requests
+
+**For agents:** Always give the human the approval URL. Do not just say "approve in the dashboard" — provide the direct link so they can review and approve with one click.
+
+## Token lifecycle and claim behavior
+
+1) Agent requests token → returns `requestId` + `secret` + `approveUrl`.
+2) Human opens approval URL, reviews permissions, and approves.
+3) Agent polls `GET /auth/:requestId?secret=...` → one-time claim semantics.
+4) On approval returns `encryptedToken` + metadata.
+5) On restart: in-memory state rotates, tokens may be invalidated.
+6) On revoke: `POST /actions/tokens/revoke` removes active token from trust boundary immediately.
+
+## Encrypted password transport
+
+Passwords for `/unlock` and `/setup` are RSA-OAEP encrypted before transmission.
+
+- RSA keypair generated on server startup
+- Frontend fetches `/auth/connect` pubkey and encrypts password
+- Password decrypts server-side; token returns only to validated clients
+- Private key stays in process memory
+
+## Related references
+
+- [MCP](./MCP.md)
+- [CLI](./CLI.md)
+- [Security](./security.md)
+- [Authentication API](./api/authentication.md)
+- [Troubleshooting](./TROUBLESHOOTING.md)

package/docs/BEST-PRACTICES.md

@@ -0,0 +1,82 @@
+# Best Practices
+
+Guidance for humans, agents, and developers working with AuraMaxx.
+
+---
+
+## For Humans
+
+### Password Management
+
+- Use a strong, unique password for each vault (min 8 characters, passphrase recommended)
+- Never share your vault password - it unlocks all child vaults
+- Never store your vault password digitally — treat it like a seed phrase
+- If you forget your password, the seed phrase is your only recovery path
+
+### Multi-Vault Usage
+
+- Use separate vaults for separate purposes (e.g., trading vault, savings vault)
+- Child vaults can auto-unlock when the parent vault is unlocked; independent vaults stay separate
+- Hot wallets are bound to their vault and cannot be moved between vaults
+
+### Backup Schedule
+
+- Back up your seed phrase on paper immediately after vault creation
+- Store it offline in a secure location (safe, safety deposit box)
+- Never photograph, screenshot, or digitally copy your seed phrase
+- Test your backup by verifying the cold wallet address matches
+
+### Token Hygiene
+
+- Revoke tokens you're no longer using — don't leave stale tokens active
+- Each agent should have its own token with its own limits
+- Review active tokens periodically in the dashboard
+- Server restart invalidates all tokens — this is intentional security, not a bug
+
+### Secret Input Safety
+
+- Never give your agent a plaintext secret directly in chat/prompt text — model providers may see prompt content.
+- Only set secrets manually via AuraMaxx CLI or UI.
+
+---
+
+## For Agents
+
+### Permission Scoping
+
+- Request the minimum permissions needed for your task
+- Use `trade:all` for trading operations instead of listing individual permissions
+- `trade:all` does NOT include `apikey:set` or `adapter:manage` — request those explicitly if needed for onboarding
+- Never request `admin:*` unless you genuinely need full access
+
+### Token Lifecycle
+
+- Tokens live only in server memory — expect them to vanish on restart
+- Always implement re-authentication logic: catch 401 → re-request via `POST /auth`
+- Don't persist tokens to disk — request fresh ones each session
+- The token from `GET /auth/:id?secret=...` can only be read once — save it immediately
+
+### Error Handling Patterns
+
+| Error | Pattern |
+|-------|---------|
+| 401 `Invalid or expired token` | Re-request token via `POST /auth`, wait for human approval |
+| 401 `Cold wallet must be unlocked` | Tell human to unlock at dashboard or `http://localhost:4242/unlock` |
+| 403 `Insufficient permissions` | Use `request_human_action` for one-time approval, or request a new token via `POST /auth` with the needed profile/scope |
+| 403 `Amount exceeds spending limit` | Use `request_human_action` with the specific amount needed |
+| Connection refused | Server not running — tell human to run `auramaxx` |
+
+### Credential Access
+
+- Use `secret:read` with narrow `credentialAccess.read` scopes — don't request wildcard access unless needed
+- Use `excludeFields` to strip fields you don't need (e.g., exclude `refresh_token` if you only need `access_token`)
+- For OAuth2 credentials, just read the credential — auto-refresh handles expired tokens transparently
+- For TOTP, use `POST /credentials/:id/totp` to get the current code rather than reading the raw secret
+- Check credential health badges — flag compromised credentials to the user proactively
+
+### Multi-Step Operations
+
+- Check `GET /setup` before starting any workflow — know what's configured
+- For operations that require multiple endpoints (e.g., create wallet → fund → swap), verify each step succeeded before proceeding
+- If a multi-step operation fails partway through, report what completed and what didn't — don't silently retry
+

package/docs/CLI.md

@@ -0,0 +1,141 @@
+# CLI
+
+## Commands
+
+The most common commands. All use the `aura` alias (or `npx auramaxx`).
+
+| Command | Description |
+|---------|-------------|
+| `aura get <name>` | Read a credential (`--json` for full payload) |
+| `aura set <name> <value>` | Create or update a secret |
+| `aura list` | List credential names |
+| `aura diary write --entry "<text>"` | Append an authenticated daily diary entry |
+| `aura share <name>` | Create a shareable secret gist link |
+| `aura inject <name> [-- <cmd>]` | Save to env var and optionally run command |
+| `aura del <name>` | Delete a credential |
+
+> **Note:** `aura get` returns encrypted ciphertext by default — this is a protected route.
+> To decrypt and print a value, use `aura inject <name> -- printenv AURA_SECRET`.
+> To pass a secret to a command under a custom env var: `aura inject <name> --env MY_VAR -- <your-command>`.
+
+## Fast Path
+
+If your vault is unlocked, secret reads work immediately via CLI or MCP:
+
+```bash
+aura get OURSECRET
+# or
+npx auramaxx get OURSECRET
+```
+
+## First Success (Run In Order)
+
+```bash
+aura status
+aura list
+aura set OURSECRET 123
+aura get OURSECRET
+aura share OURSECRET --expires-after 24h
+```
+
+If `status` fails, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
+`status` checks both services: API server (`http://localhost:4242`) and dashboard UI (`http://localhost:4747`).
+
+## Admin Commands
+
+Essential admin commands for setup and maintenance.
+
+| Command | Description |
+|---------|-------------|
+| `aura start` | Start Aura services (includes first-run bootstrap) |
+| `aura status` | Check runtime health |
+| `aura init` | Advanced/recovery setup flow (most users should run `start`) |
+| `aura mcp` | Start MCP server for Claude Code, Cursor, etc. |
+| `aura skill` | Install AuraMaxx skills for Claude/Codex/OpenClaw |
+| `aura auth` | Request/poll agent auth approvals |
+
+Run `aura --help --all` to see all commands including advanced admin (stop, lock, unlock, doctor, restore, etc.).
+
+## Stopping Servers
+
+```bash
+aura stop
+```
+
+Stops all running AuraMaxx processes:
+
+- **Wallet server** (`server/index.ts` on port 4242)
+- **Cron server** (`server/cron/index.ts` — balance sync, price sync)
+- **Dashboard** (`next dev` on port 4747)
+
+Also cleans up temp files (CLI lock file, Unix socket).
+
+This does **not** affect the MCP server — that runs in its own stdio process managed by the client (Claude Code, Cursor, etc.) that started it.
+
+## Examples
+
+```bash
+# Check services
+aura status
+
+# Credentials
+aura list                                                 # List credential names
+aura get OURSECRET                                        # Read a credential
+aura set OURSECRET 123                                    # Create or update a credential value
+aura set GITHUB_LOGIN hunter2 --type login                # Store as login credential (password field)
+aura share OURSECRET --expires-after 24h                  # Create a shareable secret gist link
+aura del OURSECRET                                        # Delete a credential
+
+# Inject secret into a command
+aura inject DONTLOOK --env HIDETHIS -- printenv HIDETHIS  # Execute command with injected secret env var
+
+# Auth and approvals
+aura auth request --agent-id codex --profile strict
+aura auth request --profile strict --action '{"endpoint":"/send","method":"POST","body":{"to":"0x...","amount":"0.01"}}'
+aura auth poll <requestId> --secret <secret>
+aura diary write --entry "Heartbeat: no pending requests, sync ok"
+
+# Advanced
+aura api GET /health --no-auth                            # Call any API endpoint
+aura doctor                                               # Run diagnostics
+```
+
+Sensitive output defaults:
+
+- Sensitive fields return encrypted output by default.
+- To auto-decrypt sensitive output, set `AUTO_DECRYPT=true` and `AURA_VAULT_PASSWORD=<password>`.
+
+## All Commands
+
+Full list visible via `aura --help --all`. Summary:
+
+| Command | Description |
+|---------|-------------|
+| `start` | Start Aura services (includes bootstrap/setup) |
+| `stop` | Stop running servers |
+| `status` | Check runtime health |
+| `init` | Advanced/recovery setup flow |
+| `unlock` / `lock` | Unlock or lock vaults |
+| `mcp` | Start MCP server for Claude Code, Cursor, etc. |
+| `skill` | Install AuraMaxx skills for agents |
+| `auth` | Request/poll agent auth approvals |
+| `diary` | Append daily diary entries (auth-aware) |
+| `actions` | Internal: human actions and token management (use `auth` instead) |
+| `api` | Call any wallet API endpoint from CLI |
+| `doctor` | Run diagnostics |
+| `restore` | Restore backup + run migrations |
+| `app` | Manage installed apps |
+| `apikey` | List/validate/set/delete API keys |
+| `env` | Load env vars from vault via .aura file |
+| `shell-hook` | Auto-load .aura env vars on cd (like direnv) |
+| `experimental` | Toggle dev feature flags |
+| `cron` | Run cron server standalone |
+| `secret` | Run commands with injected secret env vars |
+| `release-check` | Run pre-release checklist (diff audit, sanity, privacy scan, security routes) |
+| `token` | Preview profile-based token policy |
+| `wallet` | Wallet API wrappers (status, assets, swap, send, fund) |
+
+## Next Steps
+
+- Builder / AI integration -> [MCP.md](./MCP.md)
+- Operator / Security -> [security.md](./security.md)

package/docs/DESKTOP_ELECTRON.md

@@ -0,0 +1,26 @@
+# Aura Desktop (Electron)
+
+## Overview
+Aura Desktop wraps the existing Aura web app in an Electron shell (no duplicate UI fork).
+
+## Security defaults
+- `contextIsolation: true`
+- `nodeIntegration: false`
+- `sandbox: true`
+- preload-only API bridge (`window.auraDesktop`)
+
+## Run (dev)
+1. Install deps: `npm install`
+2. Start desktop shell: `AURA_ELECTRON_DEV=1 electron apps/desktop-electron/main.js`
+
+This launches the web runtime and opens Electron against `http://localhost:4747`.
+
+## Build + package (local artifact)
+1. Build web app: `npx prisma generate && npx next build`
+2. Package desktop app: `npx electron-builder --config apps/desktop-electron/electron-builder.yml`
+
+Artifacts are generated under `dist/electron/`.
+
+## Signing notes
+- macOS notarization / Windows code signing are environment-specific and not enabled by default in this baseline.
+- Configure signing credentials in CI/local env before publishing distributables.