auramaxx 0.0.1

package/docs/PERMISSION.md

@@ -0,0 +1,137 @@
+# PERMISSION
+
+Canonical reference for AuraMaxx permission surfaces, request flows, and policy controls.
+
+## 1) Permission map (runtime vocabulary)
+
+High-impact permissions observed in code/docs surfaces:
+
+- `admin:*` — full administrative bypass for guarded routes.
+- `action:create` — create human-approval requests (internal `POST /actions`, or `POST /auth` with `action` field).
+- `action:read` — list/view pending action requests.
+- `action:resolve` — approve/reject pending actions.
+- `secret:read` — list/read credential material (subject to token policy + field controls).
+- `secret:write` — create/update/delete credential data.
+- `trade:all` — broad trade operation scope (high risk).
+- `workspace:modify` — workspace mutation capabilities.
+- `extension:*` — extension-related broad scope.
+
+Risk guidance:
+- **Blocker/High:** `admin:*`, broad write/trade scopes.
+- **Medium:** `action:resolve`, `secret:write` (without narrow selectors).
+- **Lower (still sensitive):** narrow `secret:read` with strict selector + redaction policy.
+
+## 2) Issuance paths and where permissions come from
+
+### A) `POST /auth` (profile-first, human approval)
+- Inputs: `agentId`, `profile`, `pubkey` (+ optional tighten-only overrides).
+- Returns request + secret; after approval, agent claims encrypted token.
+- Raw permission arrays are not the primary `/auth` contract.
+
+### B) `POST /actions` (internal — strategy engine only)
+- Internal route used by the strategy engine's `request_human_action` tool.
+- Agents should use `POST /auth` with an optional `action` field instead.
+- Requires caller permission: `action:create`.
+- Payload includes requested permissions for temporary escalation.
+- Human resolves via approve/reject; approved action mints scoped token.
+
+### C) `POST /actions/token` (direct issuance)
+- Admin-gated path.
+- XOR mode: exactly one of `profile` or `permissions`.
+- Supports preview via `POST /actions/token/preview`.
+
+## 3) Runtime enforcement model
+
+- Bearer token validated at route middleware.
+- Route guards apply permission checks (`requirePermission`, compound expansion helpers).
+- Additional secret-access governance is layered on top of route perms:
+  - selector scope checks
+  - TTL limits
+  - read-count limits
+  - field exclusion/redaction
+
+## 4) Config-passable policy controls (code-scan aligned)
+
+Common controls seen in policy/profile surfaces:
+
+- `ttlSeconds` — token lifetime window.
+- `maxReads` — cap on successful secret reads.
+- `scope` — permission scope list.
+- `readScopes` / `writeScopes` — selector constraints.
+- `excludeFields` — redact sensitive fields from readable payloads.
+- `profileOverrides` — tighten-only adjustments (cannot broaden base profile).
+
+Practical examples:
+
+```json
+{
+  "profile": "strict",
+  "profileVersion": "v1",
+  "profileOverrides": {
+    "ttlSeconds": 900,
+    "maxReads": 25,
+    "excludeFields": ["refresh_token", "seedPhrase"]
+  }
+}
+```
+
+```json
+{
+  "permissions": ["secret:read"],
+  "credentialAccess": {
+    "read": ["vault:prod/*"],
+    "excludeFields": ["password", "privateKey"],
+    "maxReads": 10
+  }
+}
+```
+
+## 5) Request flows (quick examples)
+
+### Agent escalation flow (recommended)
+1. Agent calls `POST /auth` with `action` field containing the operation to execute.
+2. Human approves in dashboard.
+3. Token is created and the pre-computed action auto-executes on approval.
+
+### `/actions` API flow (internal — strategy engine)
+1. Strategy engine creates action request with needed permissions.
+2. Human approves/rejects (`/actions/:id/resolve`).
+3. Approved action auto-executes with scoped token.
+
+### CLI flow
+```bash
+# Recommended (agents):
+npx auramaxx auth request --profile strict --action '{"endpoint":"/send","method":"POST","body":{...}}'
+
+# Internal (strategy engine / admin):
+npx auramaxx actions create --summary "Read prod creds" --permissions secret:read
+npx auramaxx actions pending
+npx auramaxx actions resolve <actionId> --approve
+```
+
+### MCP flow
+- Start with least-privilege token.
+- On 403, the MCP `auth` tool handles escalation via `POST /auth`.
+- Retry only after approved token/policy is active.
+
+## 6) Deny, revoke, and escalation implications
+
+- **Deny:** operation remains blocked; caller must request different scope or abort.
+- **Revoke:** use token revoke surfaces (`/actions/tokens/revoke` / console) to invalidate issued tokens.
+- **Escalation limits:** privileged self-escalation patterns should be blocked; use human-reviewed action/token flows.
+
+## 7) Operator defaults checklist
+
+- Prefer profile-based issuance for normal onboarding.
+- Keep TTL short and selectors narrow.
+- Always set `excludeFields` when full fields are unnecessary.
+- Use approve links/actions for one-time elevated tasks.
+- Revoke stale/high-risk tokens after task completion.
+
+## Related docs
+
+- `docs/AUTH.md`
+- `docs/security.md`
+- `docs/api/authentication.md`
+- `docs/CLI.md`
+- `docs/MCP.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 AuraMaxx, 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/README.md

@@ -0,0 +1,50 @@
+# Docs — What are you trying to do?
+
+Use this file like the `/docs` homepage: pick your goal, then open the linked doc.
+
+## CORE CONCEPTS
+- [Features](./core-concepts/FEATURES.md)
+
+## START HERE
+- [Getting Started](../README.md)
+- [Setup](./AGENT_SETUP.md)
+- [CLI](./CLI.md)
+- [Troubleshooting](./TROUBLESHOOTING.md)
+- [Agent setup entrypoint](../agents/README.md)
+
+## UNDERSTAND AURA
+- [Overview](./external/overview.md)
+- [Getting Started (external)](./external/getting-started.md)
+- [HOW TO AURAMAXX](./external/HOW_TO_AURAMAXX/README.md)
+- [GETTING_SECRETS](./external/HOW_TO_AURAMAXX/GETTING_SECRETS.md)
+## CREDENTIAL WORKFLOWS
+- [Credentials](./credentials.md)
+- [Share Secret](./external/share-secret.md)
+<!-- - [.aura File](./aura-file.md) -->
+
+## AUTH & SAFETY
+- [Auth](./AUTH.md)
+- [Security](./security.md)
+- [Best Practices](./BEST-PRACTICES.md)
+
+## INTEGRATIONS & AUTOMATION
+- [MCP](./MCP.md)
+<!-- - [Desktop / Electron](./DESKTOP_ELECTRON.md) -->
+<!-- - [Apps](./APPS.md) -->
+<!-- - [Developing Apps](./DEVELOPING-APPS.md) -->
+<!-- - [Adapters](./ADAPTERS.md) -->
+<!-- - [Workspace](./WORKSPACE.md) -->
+
+## ARCHITECTURE
+- [Architecture](./ARCHITECTURE.md)
+<!-- - [Protocol](./PROTOCOL.md) -->
+
+<!-- ## WALLET (LATER)
+- [Wallet Overview](./wallet/README.md)
+- [Wallet Strategy](./wallet/STRATEGY.md)
+- [Developing Strategies](./wallet/DEVELOPING-STRATEGIES.md)
+- [Wallet + AI](./wallet/AI.md) -->
+
+---
+
+If you’re unsure, start at **START HERE → Getting Started**.

package/docs/SKILLS.md

@@ -0,0 +1,132 @@
+# Skills
+
+Skills give your agent built-in knowledge of AuraMaxx commands and workflows — no MCP server or running connection required.
+
+Quickest path: install the skill in your workspace.
+
+```bash
+cd <your-codebase>
+npx -y skills add Aura-Industry/auramaxx
+```
+
+---
+
+## Install
+
+Install all supported clients 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, install globally for all OpenClaw agents:
+mkdir -p ~/.openclaw/skills
+cd ~/.openclaw/skills
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Installs to `~/.openclaw/skills/auramaxx`.
+OpenClaw resolves workspace-local `skills/` first; for shared skills across agents, keep this in `~/.openclaw/skills` and avoid same-name workspace copies.
+
+### Other clients
+
+```bash
+cd <your-codebase>
+npx -y skills add Aura-Industry/auramaxx
+```
+
+---
+
+## Manual Install (download from GitHub)
+
+If you don't want to use the CLI or `npx`, you can grab the skill folder directly from GitHub:
+
+1. Go to [github.com/Aura-Industry/auramaxx](https://github.com/Aura-Industry/auramaxx)
+2. Download or clone the repo
+3. Copy the `skills/auramaxx` folder into your client's skill directory:
+
+```bash
+# Claude Code
+cp -r skills/auramaxx ~/.claude/skills/auramaxx
+
+# Codex CLI
+cp -r skills/auramaxx ~/.codex/skills/auramaxx
+
+# OpenClaw
+cp -r skills/auramaxx ~/.openclaw/skills/auramaxx
+
+# Any other client — drop it wherever your agent reads skills from
+cp -r skills/auramaxx /path/to/your/skills/auramaxx
+```
+
+The folder contains:
+- `SKILL.md` — main skill file (commands, workflows, error recovery)
+- `HEARTBEAT.md` — periodic check-in routine (vault status, secret access, human updates)
+- `docs/` — bundled reference docs (API, auth, MCP, security, etc.)
+
+---
+
+## Verify
+
+```bash
+auramaxx skill --doctor
+```
+
+Then test with your agent:
+
+```bash
+auramaxx set OURSECRET "hello from the vault"
+```
+
+Ask your agent:
+
+`Use auramaxx to get the secret OURSECRET.`
+
+---
+
+## What's in the skill
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Setup flow, wallet operations, permissions, error recovery, tool-call and intent modes |
+| `HEARTBEAT.md` | Periodic heartbeat routine — checks vault status, reports secret access, updates human |
+| `docs/` | Flattened copies of API.md, AUTH.md, MCP.md, security.md, and other reference docs |
+
+---
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).