auramaxx 0.0.1

package/skills/auramaxx/docs/AGENT_SETUP.md

@@ -0,0 +1,155 @@
+# Agent Setup
+
+Make sure AuraMaxx is running first:
+
+```bash
+auramaxx
+auramaxx status
+```
+
+---
+
+## What are you using?
+
+| Client | Setup |
+|--------|-------|
+| 🦞 OpenClaw | [Skills](#skills) |
+| 🤖 Claude Code | [Skills](#skills) |
+| 📟 Codex CLI | [Skills](#skills) |
+| 🖥️ Claude Desktop | [MCP](#mcp) |
+| 🖱️ Cursor IDE | [MCP](#mcp) |
+| 🏄 Windsurf | [MCP](#mcp) |
+| 🚀 Antigravity | [MCP](#mcp) |
+| 🔌 VS Code + Continue | [MCP](#mcp) |
+| 🧩 Any MCP client | [MCP](#mcp) |
+
+---
+
+## Skills
+
+Skills give your agent built-in knowledge of AuraMaxx commands and workflows.
+
+Install all at once:
+
+```bash
+auramaxx skill
+```
+
+Or install per client:
+
+### 🤖 Claude Code
+
+```bash
+auramaxx skill --claude
+
+# Or manually, from your project:
+mkdir -p .claude/skills
+cd .claude/skills
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Installs to `~/.claude/skills/auramaxx`.
+
+### 📟 Codex CLI
+
+```bash
+auramaxx skill --codex
+
+# Or manually, from anywhere:
+mkdir -p ~/.codex/skills
+cd ~/.codex/skills
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Installs to `~/.codex/skills/auramaxx`.
+
+### 🦞 OpenClaw
+
+```bash
+auramaxx skill --openclaw
+
+# Or manually, from your workspace:
+mkdir -p skills
+cd skills
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Installs to `~/.openclaw/skills/auramaxx`.
+
+### Other clients
+
+```bash
+cd <your-codebase>
+npx -y skills add Aura-Industry/auramaxx
+```
+
+### Verify
+
+```bash
+auramaxx skill --doctor
+```
+
+---
+
+## MCP
+
+MCP gives your agent direct tool access to the vault (read secrets, write secrets, manage wallets). If your client supports [Skills](#skills), use those instead — they're simpler and don't require a running server connection.
+
+Auto-configure all detected clients at once:
+
+```bash
+auramaxx mcp --install
+```
+
+Or paste this config block into your client's MCP config:
+
+```json
+{
+  "mcpServers": {
+    "auramaxx": {
+      "command": "npx",
+      "args": ["auramaxx", "mcp"]
+    }
+  }
+}
+```
+
+### 🤖 Claude Code
+
+```bash
+claude mcp add auramaxx -- npx auramaxx mcp
+```
+
+### 📟 Codex CLI
+
+```bash
+codex mcp add auramaxx -- npx auramaxx mcp
+```
+
+### Where to paste the config block
+
+- 🖥️ **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+- 🖱️ **Cursor IDE** — MCP settings JSON editor
+- 🏄 **Windsurf** — `~/.windsurf/mcp.json`
+- 🔌 **VS Code + Continue** — `.vscode/mcp.json` in your project
+- 🦞 **OpenClaw** — add stdio server `npx auramaxx mcp` in MCP settings
+
+Restart your client after saving.
+
+---
+
+## Verify
+
+```bash
+auramaxx get OURSECRET
+```
+
+Then ask your agent:
+
+`Use auramaxx to get the secret OURSECRET.`
+
+---
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

package/skills/auramaxx/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](AUTH.md) — full auth/permission model
+- [MCP.md](MCP.md) — MCP tools and usage

package/skills/auramaxx/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)