auramaxx 0.0.20 → 0.1.1

package/skills/auramaxx/docs/AUTH.md

@@ -1,318 +0,0 @@
-# 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` | `agent:agent` | none | `password, cvv, privateKey, seedPhrase, refresh_token` | 15 min | 50 |
-| `dev` | `wallet:list, secret:read, secret:write, action:create, action:read, action:resolve` | `agent:*` | `agent:*` | `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:
-
-- `agent:agent` — agent agent only
-- `agent:primary` — primary agent only
-- `agent:*` — all agents
-- `*` — 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 agent 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": ["agent:agent"],
-      "writeScopes": ["agent: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/skills/auramaxx/docs/CLI.md

@@ -1,130 +0,0 @@
-# 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>`.
-
-## 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_AGENT_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 agents |
-| `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 agent 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 |
-| `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/skills/auramaxx/docs/MCP.md

@@ -1,192 +0,0 @@
-# MCP
-
-AuraMaxx MCP server exposes credential agent and wallet APIs to MCP clients over stdio.
-
-## Start
-
-```bash
-auramaxx
-auramaxx mcp
-```
-
-`auramaxx` starts the API server on `http://localhost:4242` and dashboard UI on `http://localhost:4747`.
-
-Auto-configure local IDE MCP files:
-
-```bash
-auramaxx mcp --install
-```
-
-## Per-client setup (exact locations + JSON)
-
-Use the client-specific setup guide:
-
-- `docs/AGENT_SETUP.md`
-
-It includes exact config locations, copy-paste JSON, restart steps, and quick verification for Cursor, Codex, Claude Desktop, OpenClaw, and generic MCP clients.
-
-## Quickstart (TL;DR: get / set / list)
-
-Use this flow first. It mirrors the `WORKING_WITH_SECRETS.md` command patterns.
-
-### Set a secret (`put_secret`)
-
-```json
-{
-  "name": "OURSECRET",
-  "value": "123"
-}
-```
-
-### Get a secret (`get_secret`)
-
-```json
-{
-  "name": "DONTLOOK"
-}
-```
-
-- This returns redacted output (`"secret": "*******"`) and sets `AURA_DONTLOOK` in MCP server process scope.
-
-Command-scoped injection (recommended):
-
-```json
-{
-  "name": "DONTLOOK",
-  "command": ["/bin/zsh", "-lc", "printenv AURA_DONTLOOK"]
-}
-```
-
-Unsafe plaintext debug output:
-
-```json
-{
-  "name": "DONTLOOK",
-  "dangerPlaintext": true
-}
-```
-
-### List secrets (`list_secrets`)
-
-```json
-{}
-```
-
-Filter by name/tag/agent:
-
-```json
-{
-  "q": "github",
-  "tag": "prod",
-  "agent": "primary"
-}
-```
-
-### Custom env var name (`inject_secret`)
-
-```json
-{
-  "name": "DONTLOOK",
-  "envVar": "AURA_DONTNOTE",
-  "command": ["/bin/zsh", "-lc", "printenv AURA_DONTNOTE"]
-}
-```
-
-## MCP Resources
-
-- `docs://api`
-- `docs://auth`
-- `docs://guide`
-
-## Tools (12)
-
-| # | Tool | Description |
-|---|------|-------------|
-| 1 | `get_secret` | Look up a credential, inject default env var (`AURA_{SECRETNAME}`), return redacted metadata by default |
-| 2 | `put_secret` | Store a new credential (note type) in the default agent |
-| 3 | `list_secrets` | List credentials with optional query/tag/agent/lifecycle filters |
-| 4 | `del_secret` | Delete a credential by name |
-| 5 | `inject_secret` | Read a credential and inject into env var (custom name optional), redacted output by default |
-| 6 | `share_secret` | Create a time-limited shareable link for a credential |
-| 7 | `api` | Generic AuraMaxx API caller (any endpoint, any method) |
-| 8 | `auth` | Request an authenticated session token (ephemeral RSA + human approval polling) |
-| 9 | `get_token` | Check if session has an active token (poll after `auth` for approval status) |
-| 10 | `status` | Get server setup/unlock health state |
-| 11 | `start` | Start the AuraMaxx server in headless mode if not already running |
-| 12 | `write_diary` | Append an entry to a daily diary note |
-
-`api` is the generic fallback for any endpoint; the other tools provide typed, higher-level operations.
-
-## Skill Install
-
-Install AuraMaxx skills for your AI agents:
-
-```bash
-npx auramaxx skill
-```
-
-This auto-installs skills for Claude, Codex, and OpenClaw. Verify with:
-
-```bash
-npx auramaxx skill --doctor
-```
-
-If auto-install fails, use the fallback:
-
-```bash
-cd <your-codebase> && npx -y skills add Aura-Industry/auramaxx
-```
-
-For a pushed GitHub ref (branch or commit):
-
-```bash
-python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
-  --repo Aura-Industry/auramaxx \
-  --path skills/auramaxx \
-  --ref <branch-or-commit>
-```
-
-`write_diary` appends to `{YYYY-MM-DD}_LOGS` notes using agent agent by default, with fallback to primary agent.
-Diary notes use canonical note field key `content` (`value` is accepted as a legacy alias and normalized).
-
-## Credential read flow via MCP
-
-1. Obtain token (`auth` tool, or socket bootstrap, or `AURA_TOKEN` env var)
-2. If using `auth`, poll with `get_token` until `hasToken: true` (approval is async)
-3. Call `get_secret` (high-level) or `api` POST `/credentials/:id/read` (low-level)
-4. Use `command` when you need command-scoped injection; omit `command` to set env var in MCP process and receive WHATDO guidance
-
-Note:
-- Typed tools (`get_secret`, `put_secret`, `del_secret`, `share_secret`, `inject_secret`, `write_diary`) use the active MCP token directly.
-- `get_secret` and `inject_secret` are redacted by default (`secret: "*******"`). Set `dangerPlaintext: true` only for break-glass local debugging.
-- `get_secret` uses the default env var name `AURA_{SECRETNAME}`.
-- Both tools accept optional `command` (array of executable + args). When omitted, they return a `whatDo` guidance block and keep scope in MCP server process.
-- Typed helpers have **built-in 403 escalation** — on permission denied they automatically return a structured `requiresHumanApproval` response. You do not need to detect 403s yourself for typed tools.
-- The generic `api` tool does **not** auto-escalate — on 403, check the error response and request appropriate permissions via `auth`.
-
-## 403 escalation ladder
-
-1. Call the typed tool or `api`.
-2. If 403, typed tools auto-return a `nextStep` with the `api` call params — follow it.
-   For `api`, request a new token via `auth` with the required profile/permissions.
-3. Tell the human to approve in the dashboard at `http://localhost:4747` (or via Telegram/CLI adapter).
-4. **Never** retry the same blocked call without escalating first.
-
-## Safety pattern
-
-- Start with least privilege (`secret:read`, narrow `credentialAccess.read` scopes)
-- Typed tools auto-escalate on 403; for `api`, use `auth` to request a new token
-- Tell the human to approve at `http://localhost:4747`
-- Avoid broad long-lived tokens
-
-## Example call
-
-```json
-{
-  "method": "POST",
-  "endpoint": "/credentials/cred-123/read",
-  "body": {}
-}
-```
-
-See also: [GETTING_SECRETS](./external/HOW_TO_AURAMAXX/GETTING_SECRETS.md), [AUTH](AUTH.md), and [Troubleshooting](TROUBLESHOOTING.md).