auramaxx 1.0.0-alpha.4

package/docs/EXTENSION.md

@@ -0,0 +1,97 @@
+# AuraWallet Browser Extension
+
+A 1Password-style browser extension for AuraWallet. Autofill credentials, browse wallets, and approve agent actions — all from your browser toolbar.
+
+## Features
+
+- **🔑 Credential Autofill** — Fill usernames & passwords on any site with Cmd+Shift+L or one click
+- **🌐 Domain Matching** — Automatically surfaces credentials matching the current site (subdomain-aware)
+- **💰 Wallet Browser** — View wallet addresses and copy to clipboard
+- **✅ Action Approval** — Approve or reject pending agent actions with badge count
+- **🔒 Auto-Lock** — Configurable idle timer (default 15 min)
+- **🔐 Scoped Token** — Extension gets a limited `extension:*` token, not full admin access
+
+## Setup
+
+### Prerequisites
+
+- AuraWallet server running locally (`npx aurawallet`)
+- Chrome or Chromium-based browser
+
+### Install (Development)
+
+```bash
+cd extension
+npm install
+npm run build
+```
+
+1. Open `chrome://extensions`
+2. Enable "Developer mode" (top right)
+3. Click "Load unpacked"
+4. Select the `extension/dist` directory
+
+### Usage
+
+1. Click the AuraWallet icon in your toolbar (or press **Cmd+Shift+L**)
+2. Enter your vault password to unlock
+3. Browse credentials — domain-matched items appear first
+4. Click a login credential to autofill, or click non-login items to view details
+5. Switch tabs to view wallets or pending actions
+
+## Architecture
+
+```
+extension/
+├── manifest.json              # MV3 manifest
+├── src/
+│   ├── background/
+│   │   └── service-worker.ts  # Alarms, health checks, auto-lock
+│   ├── components/
+│   │   ├── App.tsx            # Root: offline/locked/unlocked routing
+│   │   ├── UnlockForm.tsx     # Password → RSA-encrypted unlock
+│   │   ├── Dashboard.tsx      # Tabs: credentials/wallets/actions
+│   │   ├── CredentialDetail.tsx  # Field-level view with reveal/copy
+│   │   └── Settings.tsx       # Server URL, auto-lock timer
+│   ├── lib/
+│   │   ├── api.ts             # Fetch wrapper + token management
+│   │   ├── crypto.ts          # RSA-OAEP keypair + encrypt/decrypt
+│   │   └── state.ts           # chrome.storage.session state
+│   └── popup/
+│       ├── index.html         # Popup entry
+│       ├── main.tsx           # Preact render
+│       └── styles.ts          # Shared inline styles
+├── public/icons/              # Extension icons (16/48/128)
+├── vite.config.ts             # Vite + @crxjs/vite-plugin + Preact
+└── package.json
+```
+
+## Security Model
+
+- Password is **RSA-OAEP encrypted** before sending to server (same as web UI)
+- Extension receives a **scoped token** with `extension:*` permissions:
+  - `wallet:list` — Read-only wallet access
+  - `secret:read` — Read credentials (encrypted to extension's RSA pubkey)
+  - `action:read` — List pending actions
+  - `action:resolve` — Approve/reject actions
+- Token stored in `chrome.storage.session` (cleared on browser close)
+- RSA keypair stored in `chrome.storage.session` (regenerated each session)
+- Auto-lock clears all session data after configurable idle period
+
+## Server Changes
+
+The extension required minimal server changes:
+
+1. **`server/lib/permissions.ts`** — Added `action:read`, `action:resolve` permissions and `extension:*` compound permission
+2. **`server/routes/actions.ts`** — Changed `requireAdmin` → `requirePermission('action:read'/'action:resolve')` on pending/resolve routes
+3. **`server/routes/unlock.ts`** — Added `scope: "extension"` parameter to issue scoped tokens with `credentialAccess: { read: ['*'] }`
+
+## Configuration
+
+Settings accessible via the ⚙ gear icon:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Server URL | `http://localhost:4242` | AuraWallet server address |
+| Auto-lock | 15 minutes | Idle time before auto-locking |
+| Shortcut | Cmd+Shift+L | Open popup (configurable in chrome://extensions/shortcuts) |

package/docs/JOBS.md

@@ -0,0 +1,33 @@
+# Aura Docs by Job (Start Here)
+
+Use this page when you need to get a real job done fast.
+
+## Pick your goal
+
+- **I am a developer**
+  - [Migrate from `.env` to vault-backed `.aura`](./jobs/migrate-from-dotenv.md)
+- **I run agents locally**
+  - [Connect an agent with least privilege](./jobs/connect-agent.md)
+- **I own CI/security**
+  - [Secure CI with scoped Aura access](./jobs/secure-ci.md)
+- **I am locked out / recovery mode**
+  - [Recover from lockout safely](./jobs/recover-from-lockout.md)
+
+## Contract for every runbook
+
+Each guide includes:
+- preflight checks
+- copy/paste commands
+- deterministic success checks
+- known failure signatures + fixes
+- a final `aura doctor` verification step
+
+## Keep these docs trustworthy
+
+Run the docs validator before release:
+
+```bash
+npm run docs:validate
+```
+
+This checks job-guide structure and command snippets used in these runbooks.

package/docs/MCP.md

@@ -0,0 +1,76 @@
+# MCP
+
+Aura MCP server exposes wallet + credential APIs to MCP clients over stdio.
+
+## Start
+
+```bash
+npx aurawallet mcp
+```
+
+Auto-configure local IDE MCP files:
+
+```bash
+npx aurawallet mcp --install
+```
+
+## MCP Resources
+
+- `docs://api`
+- `docs://auth`
+- `docs://guide`
+- `docs://setup-guide` (setup-only skill guide)
+
+## Tools currently exposed
+
+- `create_vault`
+- `wallet_api`
+- `request_human_action`
+
+## Setup Skill
+
+Install the setup-focused skill and ask your agent to onboard via MCP.
+
+For local testing before a commit is pushed:
+
+```bash
+TMP_SKILL_DIR="$(mktemp -d /tmp/aurawallet-setup-skill-XXXXXX)"
+cp -R ./skills/aurawallet-setup "$TMP_SKILL_DIR/"
+npx -y skills add "$TMP_SKILL_DIR/aurawallet-setup" --yes
+```
+
+For a pushed GitHub ref (branch or commit):
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo Aura-Industry/aurawallet \
+  --path skills/aurawallet-setup \
+  --ref <branch-or-commit>
+```
+
+Note: dedicated `get_secret` / `put_secret` wrappers are not currently in `server/mcp/tools.ts`; use `wallet_api` against credential endpoints.
+
+## Credential read flow via MCP
+
+1. Obtain token (`POST /auth` + approval + `GET /auth/:id?secret=...`)
+2. Create scoped token if needed (`POST /actions/token`)
+3. Call `POST /credentials/:id/read`
+4. Decrypt returned `encrypted` payload in your MCP host
+
+## Safety pattern
+
+- Start with least privilege (`secret:read`, narrow `credentialAccess.read` scopes)
+- Use `request_human_action` when you hit 403
+- Avoid broad long-lived tokens
+
+## Example call
+
+```json
+{
+  "method": "POST",
+  "endpoint": "/credentials/cred-123/read",
+  "body": {}
+}
+```
+
+See also: [agent auth model](./agent-auth.md).

package/docs/PROTOCOL.md

@@ -0,0 +1,142 @@
+# The `.aura` File Format
+
+**Version:** 0.1.0 (Draft)
+**Status:** Draft
+**Date:** 2026-02-16
+
+## 1. Introduction
+
+### 1.1 Why
+
+Applications need secrets. Developers pass them via environment variables, typically stored in `.env` files. This creates a problem: `.env` files contain plaintext secrets and must never be committed to version control. Teams share them over Slack, email, or sticky notes. They drift. They leak.
+
+The `.aura` format solves this by separating **what a project needs** from **the secrets themselves**. A `.aura` file maps environment variables to credential references in a vault. It contains no secrets — only pointers. It is safe to commit, review, and share.
+
+### 1.2 Design Goals
+
+- **Commit-safe.** No secrets, ever.
+- **Simple.** One mapping per line. No templating, no interpolation, no nesting.
+- **Vault-agnostic.** Any secret store can implement resolution.
+- **Familiar.** If you've used `.env`, you already know 90% of `.aura`.
+
+## 2. File Format
+
+### 2.1 General
+
+- **Filename:** `.aura` (lowercase, leading dot)
+- **Encoding:** UTF-8
+- **Line endings:** LF or CRLF (implementations MUST accept both)
+
+### 2.2 Grammar
+
+```
+file        = *line
+line        = blank / comment / mapping
+blank       = *WSP NEWLINE
+comment     = "#" *CHAR NEWLINE
+mapping     = key "=" reference NEWLINE
+key         = 1*( ALPHA / DIGIT / "_" )
+reference   = [ "@" vault-name "/" ] credential-name "/" field
+vault-name  = 1*( ALPHA / DIGIT / "-" / "_" )
+credential-name = 1*( ALPHA / DIGIT / "-" / "_" / "." )
+field       = 1*( ALPHA / DIGIT / "-" / "_" / "." )
+```
+
+### 2.3 Mappings
+
+Each mapping is a single line of the form:
+
+```
+ENV_VAR=reference
+```
+
+- **No whitespace** around `=`. `KEY = ref` is invalid.
+- **No quoting.** Values are never quoted.
+- **No multiline values.**
+- **No duplicate keys.** If a key appears more than once, implementations MUST reject the file.
+
+### 2.4 References
+
+A reference points to a field within a credential in a vault:
+
+| Form | Meaning |
+|------|---------|
+| `credential/field` | Field `field` of credential `credential` in the primary vault |
+| `@vault/credential/field` | Field `field` of credential `credential` in vault `vault` |
+
+The **primary vault** is determined by the resolution environment (e.g., a CLI config or SDK default). The `.aura` file itself does not define which vault is primary.
+
+### 2.5 Comments and Blank Lines
+
+Lines beginning with `#` (optionally preceded by whitespace) are comments. Blank lines are ignored. Both are preserved for human readability.
+
+## 3. Resolution Algorithm
+
+Given a `.aura` file, a resolver MUST:
+
+1. **Parse** the file into an ordered list of `(key, reference)` mappings.
+2. **For each mapping**, decompose the reference into `(vault, credential, field)`. If no `@vault` prefix, use the primary vault.
+3. **Resolve** each `(vault, credential, field)` tuple against the vault provider. Obtain the plaintext secret value.
+4. **Fail loudly** if any credential or field does not exist. Implementations MUST NOT substitute defaults, empty strings, or fallback values. A missing secret is a fatal error.
+5. **Inject** each `key=resolved_value` pair into the target environment.
+
+### 3.1 Error Handling
+
+| Condition | Behavior |
+|-----------|----------|
+| Credential not found | MUST fail with error identifying the missing credential |
+| Field not found | MUST fail with error identifying the credential and missing field |
+| Vault not reachable | MUST fail with connection error |
+| Duplicate key | MUST fail at parse time |
+| Malformed line | MUST fail at parse time with line number |
+
+Implementations MUST NOT partially inject. Either all mappings resolve or none do.
+
+## 4. Example
+
+```aura
+# Database
+DATABASE_URL=database-prod/url
+DATABASE_POOL_SIZE=database-prod/pool_size
+
+# Payments
+STRIPE_SECRET_KEY=stripe/secret_key
+STRIPE_WEBHOOK_SECRET=stripe/webhook_secret
+
+# AWS (staging vault)
+AWS_ACCESS_KEY_ID=@staging/aws/access_key
+AWS_SECRET_ACCESS_KEY=@staging/aws/secret_key
+```
+
+## 5. Implementing a Resolver
+
+Any tool can resolve `.aura` files. A resolver needs:
+
+1. **A parser** — split lines, ignore comments/blanks, extract `(key, reference)` pairs.
+2. **A vault backend** — given `(vault, credential, field)`, return the secret value. This could be AuraWallet, 1Password, HashiCorp Vault, AWS Secrets Manager, a YAML file — anything.
+3. **An injector** — set environment variables or write a `.env` file.
+
+That's it. The format is intentionally trivial to parse. A working parser is ~30 lines in any language.
+
+### 5.1 Reference CLI
+
+The `aura` CLI provides a reference implementation:
+
+| Command | Description |
+|---------|-------------|
+| `aura env -- <cmd>` | Resolve `.aura`, inject env vars, run `<cmd>` |
+| `aura env inject` | Resolve `.aura`, write `.env` file |
+| `aura env check` | Verify all referenced credentials exist (no values printed) |
+| `aura env list` | Print mappings without resolving values |
+| `aura init --from-dotenv` | Generate `.aura` from an existing `.env` file |
+
+## 6. Security Considerations
+
+- `.aura` files contain **no secrets** and are safe to commit to version control.
+- Resolved `.env` files (output of `aura env inject`) MUST be gitignored.
+- Implementations SHOULD NOT log resolved secret values.
+- Implementations SHOULD clear resolved values from memory after injection when possible.
+
+## 7. MIME Type
+
+`text/x-aura` (informational, not registered).

package/docs/SETUP.md

@@ -0,0 +1,219 @@
+# Setup & First-Time Guide
+
+End-to-end walkthrough from zero to an agent with a token executing operations.
+
+**Prerequisites:** Node.js 18+
+
+---
+
+## 1. Install & Initialize
+
+```bash
+npx aurawallet init
+```
+
+> **Agents:** The base `init` command is interactive. For agent-driven setup, use `npx aurawallet init --dashboard` — this skips prompts, starts the dashboard, and waits for the human to create the vault in the browser.
+
+This will:
+- Create the data directory (`~/.aurawallet/`)
+- Run database migrations
+- Start the wallet server
+- Ask: **Dashboard** or **Terminal** setup?
+- Walk you through vault creation
+- Print your cold wallet address + funding guidance
+- Keep the servers running
+
+After init completes, the servers stay running. Press `Ctrl+C` to stop them. To start again later:
+
+```bash
+npx aurawallet start
+```
+
+### Dashboard Mode (default)
+
+Press Enter (or type `1`) at the mode prompt. This opens the dashboard in your browser at `http://localhost:4747/app` where you create your vault with a password. One browser action and you're done.
+
+### Autonomous Mode (agents / CI)
+
+For fully non-interactive vault creation — no browser, no prompts:
+
+```bash
+npx aurawallet init --password "your-secure-password"
+```
+
+This creates the vault, prints the seed phrase and admin token to stdout, and keeps the servers running. Store the password securely (e.g. as `AURA_VAULT_PASSWORD`) for future unlocks.
+
+Agents using MCP can also call `create_vault` directly — see [MCP.md](./MCP.md).
+
+### Terminal Mode
+
+Type `2` at the mode prompt. This walks you through setup entirely in the terminal:
+
+1. **Password** — enter and confirm (min 8 characters, hidden input)
+2. **Seed phrase** — displayed in a numbered box; confirm you've saved it
+3. **Anthropic API key** — optional, validates before saving (Enter to skip)
+4. **Alchemy API key** — optional, same validate-and-save flow (Enter to skip)
+5. **Telegram** — optional bot token + chat ID, tests the connection (Enter to skip)
+6. **Summary** — shows what's configured vs skipped
+
+Terminal mode is ideal for headless servers, SSH sessions, and power users who prefer not to leave the terminal.
+
+### Verify it's running
+
+```bash
+npx aurawallet status
+# or
+curl -s http://localhost:4242/health
+```
+
+---
+
+## 3. Unlock the Vault
+
+After starting (or after a server restart), the vault is locked. Three ways to unlock:
+
+### Option A: Dashboard (recommended for agent + human collaboration)
+
+Open `http://localhost:4747/app` — the dashboard auto-prompts for your password on first load.
+
+An agent can tell the human: *"Open http://localhost:4747/app to unlock your vault."*
+
+### Option B: ENV auto-unlock (headless / autonomous agents)
+
+```bash
+VAULT_PASSWORD=yourpassword npx aurawallet start
+```
+
+The vault auto-unlocks on server startup. The password is scrubbed from the process environment after use. The agent then calls `POST /unlock` with the same password **and a caller RSA pubkey** to get its admin token (same flow as the dashboard). Wrong password causes the server to exit with an error.
+
+### Option C: CLI
+
+```bash
+npx aurawallet unlock
+```
+
+Prompts for password in the terminal. Works over SSH.
+
+### Option D: Standalone unlock page (fallback)
+
+If the dashboard isn't running (headless mode), the Express server serves a
+self-contained unlock page at `http://localhost:4242/unlock`.
+
+---
+
+## 4. Agent Gets a Token
+
+Once the vault is unlocked, an agent requests a token:
+
+Generate an RSA keypair in the caller runtime and send the public key on token mint requests.
+
+```bash
+# One-time example (store private key locally in your runtime)
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out agent-private.pem
+openssl rsa -pubout -in agent-private.pem -out agent-public.pem
+
+# 1. Request access (no auth required)
+curl -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "my-agent",
+    "limit": 0.5,
+    "permissions": ["trade:all"],
+    "ttl": 3600,
+    "pubkey": "<contents of agent-public.pem>"
+  }'
+# Returns: { "requestId": "...", "secret": "..." }
+```
+
+A human approves the request via:
+- Dashboard UI (`http://localhost:4747/app`)
+- CLI mode (`npm run cli`)
+- Telegram / webhook adapter (if configured)
+
+Then the agent polls for its token:
+
+```bash
+# 2. Poll until approved
+curl "http://localhost:4242/auth/<requestId>?secret=<secret>"
+# When approved: { "status": "approved", "token": "eyJ..." }
+```
+
+The agent uses the token for all subsequent requests:
+
+```bash
+curl http://localhost:4242/wallets -H "Authorization: Bearer <token>"
+```
+
+---
+
+## 5. Agent Starts Working
+
+```bash
+# Create a hot wallet
+curl -X POST http://localhost:4242/wallet/create \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"tier": "hot", "name": "trading"}'
+
+# Fund it from the cold wallet
+curl -X POST http://localhost:4242/fund \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"to": "0xHOT_ADDRESS", "amount": "0.1"}'
+
+# Execute a swap
+curl -X POST http://localhost:4242/swap \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"from": "0xHOT_ADDRESS", "token": "0xTOKEN", "direction": "buy", "amount": "0.05", "slippage": 1}'
+```
+
+---
+
+## 6. After Server Restart
+
+Server restart is a security feature — all tokens are invalidated (new signing key generated).
+
+The recovery flow:
+1. **Start the server** — `npx aurawallet start` or `npx aurawallet start --headless`
+2. **Unlock the vault** — Option A, B, or C from step 3
+3. **Agent re-requests a token** — same flow as step 4
+4. **Hot wallets and data persist** — only tokens are reset, not wallets or transaction history
+
+---
+
+## 7. Optional Configuration
+
+Configure these after init, via the dashboard or API:
+
+| Feature | How to Configure |
+|---------|-----------------|
+| Alchemy RPC | `POST /apikeys` or dashboard Settings |
+| Telegram approvals | `POST /adapters` or dashboard Settings — see [ADAPTERS.md](./ADAPTERS.md) |
+| Custom RPC endpoints | Dashboard Settings or `POST /api/workspace/config` with `chainOverrides` |
+| Strategies | Place YAML manifests in `~/.aurawallet/strategies/` — see strategy docs |
+
+Agents can check `GET /setup` to see which optional features are configured:
+
+```json
+{
+  "hasWallet": true,
+  "unlocked": true,
+  "address": "0x...",
+  "adapters": { "telegram": false, "webhook": false },
+  "apiKeys": { "alchemy": true, "anthropic": false },
+  "defaultChain": "base"
+}
+```
+
+---
+
+## 8. MCP Server (Optional)
+
+Connect AI agents (Claude Code, Claude Desktop, Cursor, etc.) via MCP:
+
+```bash
+npx aurawallet mcp    # starts stdio MCP server
+```
+
+Or configure your IDE to spawn it automatically. See [MCP.md](./MCP.md) for config examples.