auramaxx 1.0.0-alpha.4

package/docs/agent-auth.md

@@ -0,0 +1,63 @@
+# Agent Auth Model
+
+Aura auth is approval-based and pubkey-bound.
+
+## Token bootstrap
+
+1. Agent calls `POST /auth` with `agentId`, permissions, limits, and `pubkey`
+2. Human approves request
+3. Agent polls `GET /auth/:requestId?secret=...`
+4. Server returns `encryptedToken` (read-once)
+
+All token mint flows require a valid RSA `pubkey`.
+
+## Why pubkey-bound
+
+- Token transport is encrypted to caller public key
+- Credential reads (`/credentials/:id/read`) require `agentPubkey` on token
+- Plaintext credential payloads are not returned to non-admin agents
+
+## Local IPC path
+
+CLI helpers can bootstrap via Unix socket:
+
+- socket: `/tmp/aura-cli-{uid}.sock`
+- owner-only permissions (0600)
+- useful for local subagents without storing raw token in env
+
+## Least-privilege templates
+
+Read-only credentials for one vault:
+
+```json
+{
+  "permissions": ["secret:read", "totp:read"],
+  "credentialAccess": {
+    "read": ["vault:primary/*"],
+    "excludeFields": ["refresh_token", "client_secret"]
+  }
+}
+```
+
+Write-only credential automation:
+
+```json
+{
+  "permissions": ["secret:write"],
+  "credentialAccess": { "write": ["tag:generated/*"] }
+}
+```
+
+## Do / Don't
+
+Do:
+
+- request the narrowest scope you can
+- rotate/re-approve when task changes
+- use temporary tokens for elevated actions
+
+Don't:
+
+- store long-lived admin tokens in plaintext files
+- request `admin:*` for routine secret reads
+- grant wildcard scopes to untrusted subagents

package/docs/aura-file.md

@@ -0,0 +1,48 @@
+# `.aura` File Format
+
+`.aura` maps environment variable names to vault credential fields.
+
+## Syntax
+
+```ini
+# comment
+ENV_NAME=credentialName/field
+OTHER_ENV=@vaultName/credentialName/field
+```
+
+Rules:
+
+- one mapping per line
+- comments start with `#`
+- env var names are validated (must be shell-safe)
+- `@vault/...` form selects a specific vault mapping
+
+## Examples
+
+```ini
+DATABASE_URL=postgres-prod/url
+OPENAI_API_KEY=openai-prod/api_key
+GITHUB_TOKEN=@agent/github/token
+```
+
+## Usage
+
+```bash
+npx aurawallet env check
+npx aurawallet env -- npm run dev
+npx aurawallet env inject
+```
+
+Migration helper:
+
+```bash
+npx aurawallet env init --from .env
+# or during setup
+npx aurawallet init --from-dotenv
+```
+
+## Security notes
+
+- `env inject` writes `.env` with mode `0600`
+- `shell-hook` requires explicit allowlist per project
+- avoid committing generated `.env`

package/docs/credentials.md

@@ -0,0 +1,53 @@
+# Credentials
+
+Aura stores credentials as local encrypted files, scoped by vault.
+
+## Data model
+
+Each credential has:
+
+- `id`
+- `vaultId`
+- `type` (`login`, `card`, `note`, `api`, `apikey`, `custom`, `passkey`, `oauth2`)
+- `name`
+- `meta` (search/filter fields, tags, type-specific metadata)
+- encrypted sensitive fields
+
+Sensitive fields are encrypted with the vault credential key. Metadata stays plaintext for listing and search.
+
+## Field model
+
+Field shape:
+
+- `key` (string)
+- `value` (string)
+- `type` (`text`, `secret`, `url`, `email`, `number`)
+- `sensitive` (boolean)
+
+Non-sensitive fields can be mirrored into `meta` for searchability.
+
+## Access model
+
+- `secret:read` to list/read
+- `secret:write` to create/update/delete
+- optional credential scopes (`credentialAccess.read` / `.write`)
+- optional excluded fields (`excludeFields`)
+
+Credential read endpoint returns data encrypted to the caller's `agentPubkey`.
+
+## Endpoints
+
+- `POST /credentials`
+- `GET /credentials`
+- `GET /credentials/:id`
+- `PUT /credentials/:id`
+- `DELETE /credentials/:id`
+- `POST /credentials/:id/read` (encrypted response)
+- `POST /credentials/:id/totp`
+- `GET /credentials/:id/secrets` (admin-only plaintext)
+
+## Notes
+
+- `oauth2` credentials are restricted to the primary vault.
+- TOTP capability is auto-detected when `totp`/`otp` field exists.
+- Credential files are stored under Aura data directory `credentials/`.

package/docs/external/getting-started.md

@@ -0,0 +1,65 @@
+# Getting Started (First Value Fast)
+
+This guide is optimized for first success in under 10 minutes.
+
+## 1) Install + initialize
+
+```bash
+npx aurawallet init
+```
+
+## 2) Start Aura
+
+```bash
+npx aurawallet start
+```
+
+Open the dashboard at `http://localhost:4747/app` and create/unlock your vault.
+
+## 3) Add one credential
+
+In UI: add an API key credential (example: `openai-prod`).
+
+Or via API:
+
+```bash
+curl -X POST http://localhost:4242/credentials \
+  -H "Authorization: Bearer $AURA_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "vaultId": "primary",
+    "type": "apikey",
+    "name": "openai-prod",
+    "fields": [{"key":"api_key","value":"sk-...","type":"secret","sensitive":true}]
+  }'
+```
+
+## 4) Read it back from CLI
+
+```bash
+npx aurawallet vault get openai-prod --field api_key
+```
+
+If this returns your value, Aura is working end-to-end.
+
+## 5) Replace one `.env` workflow
+
+```bash
+npx aurawallet env init --from .env
+npx aurawallet env -- npm run dev
+```
+
+Now your app can load secrets from vault mappings instead of raw `.env` files.
+
+## Troubleshooting quick checks
+
+```bash
+npx aurawallet status
+npx aurawallet doctor
+```
+
+## Next steps
+
+- [Use cases](./use-cases.md)
+- [Why Aura](./why-aura.md)
+- Operational runbooks: [Docs by job](../JOBS.md)

package/docs/external/overview.md

@@ -0,0 +1,45 @@
+# Aura Overview
+
+Aura is a local-first password manager and credential vault designed for both humans and AI agents.
+
+## Who Aura is for
+
+- Developers managing API keys, passwords, OAuth2 tokens, and TOTP in one place
+- Agent operators who need **scoped, auditable** secret access
+- Teams moving away from `.env` sprawl and ad-hoc token sharing
+
+## What you get
+
+- **One credential system** for CLI + app + agents
+- **Scoped access controls** so agents can read only what they should
+- **Project boundaries via `.aura`** to prevent cross-project secret bleed
+- **Local-first runtime** (run on your own machine/infrastructure)
+
+## Why users switch
+
+Without Aura:
+- Secrets spread across `.env` files, notes, and CI variables
+- Hard to rotate safely
+- Hard to prove who accessed what
+
+With Aura:
+- Secrets are centralized and typed
+- Agent access is explicit and bounded
+- Access can be traced and reviewed
+
+## Fast proof (2 minutes)
+
+```bash
+npx aurawallet init
+npx aurawallet start
+npx aurawallet status
+```
+
+Then open `http://localhost:4747/app` and create your vault.
+
+## Where to go next
+
+- [Getting started](./getting-started.md)
+- [Use cases](./use-cases.md)
+- [Why Aura (trust model)](./why-aura.md)
+- Deep technical docs: [Docs by job](../JOBS.md)

package/docs/external/use-cases.md

@@ -0,0 +1,48 @@
+# Aura Use Cases
+
+## 1) Developer workflow (replace scattered `.env` files)
+
+Outcome: run projects with vault-backed secrets instead of manually copying credentials.
+
+```bash
+npx aurawallet env init --from .env
+npx aurawallet env -- npm run dev
+```
+
+Best when you want local speed with less secret sprawl.
+
+## 2) Agent operator workflow (scoped access)
+
+Outcome: let agents read only approved secrets, not your entire vault.
+
+```bash
+npx aurawallet mcp
+```
+
+Use profile/scoped token issuance so agent permissions match task risk.
+
+More: [Agent auth model](../agent-auth.md), [MCP guide](../MCP.md)
+
+## 3) CI/security workflow (controlled non-human access)
+
+Outcome: deterministic runtime checks and remediation before deploy.
+
+```bash
+npx aurawallet doctor
+```
+
+Use doctor output in CI to fail early when Aura runtime/auth assumptions are broken.
+
+More: [Secure CI runbook](../jobs/secure-ci.md)
+
+## 4) Incident recovery workflow
+
+Outcome: recover safely from lockout/misconfiguration.
+
+Start with: [Recover from lockout](../jobs/recover-from-lockout.md)
+
+## Picking your first path
+
+- Solo developer: start with `.env` migration
+- Agent-heavy workflow: start with MCP + scoped issuance
+- Team/ops context: start with CI checks + recovery runbook

package/docs/external/why-aura.md

@@ -0,0 +1,35 @@
+# Why Aura
+
+Aura is built around one idea: **process identity is not enough; secret access must be explicitly authorized and scoped.**
+
+## Trust model in plain language
+
+- Local auth bootstrap proves a process can talk to Aura
+- Authorization policy decides what that process can read/write
+- `.aura` mappings enforce project-level boundaries
+- Token/profile policy enforces least privilege
+- Audit trails explain who accessed what and when
+
+## How Aura differs
+
+- Not just a password vault UI: it is also an agent-safe credential runtime
+- Not just static secret storage: supports typed credentials (TOTP, OAuth2 refresh, passkeys, SSH/GPG)
+- Not just convenience: designed for deny-by-default and forensic traceability
+
+## Security posture highlights
+
+- Local-first deployment (you control host/runtime)
+- Scoped token profiles and permission boundaries
+- Explicit project scoping and policy contracts
+- Deterministic diagnostics via `aura doctor`
+
+## Reality check
+
+Aura does **not** replace host security hygiene. Protect the machine, backups, and operator tokens.
+
+## Read deeper
+
+- [Agent auth model](../agent-auth.md)
+- [`.aura` format](../aura-file.md)
+- [CLI guide](../CLI.md)
+- [Job-based runbooks](../JOBS.md)

package/docs/jobs/connect-agent.md

@@ -0,0 +1,77 @@
+# Job: Connect an Agent (Least Privilege)
+
+Connect an agent to Aura using local bootstrap and scoped secret access.
+
+## Preflight
+
+```bash
+npx aurawallet status
+```
+
+Expected: Aura server is healthy.
+
+## Runbook
+
+1) Verify local socket/bootstrap path is available.
+
+```bash
+npx aurawallet vault list
+```
+
+Expected: credentials can be listed without manually exporting long-lived admin tokens.
+
+2) Validate project-scoped mapping if this is a repo flow.
+
+```bash
+npx aurawallet env check
+```
+
+3) Start MCP server for agent tooling.
+
+```bash
+npx aurawallet mcp
+```
+
+Optional helper install for supported clients:
+
+```bash
+npx aurawallet mcp --install
+```
+
+## Success check
+
+```bash
+npx aurawallet vault get openai-prod --field api_key
+```
+
+Expected:
+- command returns the requested field value (or structured denial for insufficient scope)
+- no plaintext long-lived admin token committed to files
+
+## Failure signatures + fixes
+
+- **"Access denied" / insufficient credential scope**
+  - Fix: request/approve a profile with required scope, then retry command.
+
+- **"Socket unavailable" / local auth bootstrap failed**
+  - Fix: ensure Aura runtime is running and retry.
+  - Command:
+    ```bash
+    npx aurawallet start
+    ```
+
+- **MCP tool not connecting**
+  - Fix: restart MCP process and verify client config install.
+  - Commands:
+    ```bash
+    npx aurawallet mcp --install
+    npx aurawallet mcp
+    ```
+
+## Final verification (`aura doctor`)
+
+```bash
+npx aurawallet doctor
+```
+
+Doctor should report auth/bootstrap checks as pass or actionable warnings.

package/docs/jobs/migrate-from-dotenv.md

@@ -0,0 +1,79 @@
+# Job: Migrate from `.env` to Aura
+
+Move existing `.env` secrets into Aura and run your app without plaintext env files.
+
+## Preflight
+
+```bash
+npx aurawallet status
+```
+
+Expected: server and dashboard are reachable (or actionable status output).
+
+If Aura is not initialized yet:
+
+```bash
+npx aurawallet init
+```
+
+## Runbook
+
+1) Generate `.aura` mapping from your existing `.env` file.
+
+```bash
+npx aurawallet env init --from .env
+```
+
+2) Validate mapping + server/vault readiness.
+
+```bash
+npx aurawallet env check
+```
+
+3) Run app with vault-injected env.
+
+```bash
+npx aurawallet env -- npm run dev
+```
+
+## Success check
+
+```bash
+npx aurawallet env list
+```
+
+Expected:
+- command returns mapped variables from `.aura`
+- app starts using injected values
+- no need to source `.env` manually
+
+## Failure signatures + fixes
+
+- **"No active vault" / unlock-related errors**
+  - Fix: unlock vault, then rerun checks.
+  - Command:
+    ```bash
+    npx aurawallet unlock
+    ```
+
+- **"No .aura mapping" / parse errors**
+  - Fix: regenerate from `.env`, then rerun `env check`.
+  - Command:
+    ```bash
+    npx aurawallet env init --from .env
+    ```
+
+- **Server unreachable**
+  - Fix: start Aura runtime.
+  - Command:
+    ```bash
+    npx aurawallet start
+    ```
+
+## Final verification (`aura doctor`)
+
+```bash
+npx aurawallet doctor
+```
+
+If doctor reports warnings/failures, follow remediation output and rerun doctor until stable.

package/docs/jobs/recover-from-lockout.md

@@ -0,0 +1,72 @@
+# Job: Recover from Lockout
+
+Safely recover access when vault unlock/auth paths are broken.
+
+## Preflight
+
+1) Check runtime health.
+
+```bash
+npx aurawallet status
+```
+
+2) If server is down, start it.
+
+```bash
+npx aurawallet start
+```
+
+## Runbook
+
+1) Attempt normal unlock path.
+
+```bash
+npx aurawallet unlock
+```
+
+2) If unlock fails and backups exist, inspect restore options.
+
+```bash
+npx aurawallet restore --list
+```
+
+3) Dry-run latest restore to validate migration compatibility.
+
+```bash
+npx aurawallet restore --dry-run --latest
+```
+
+4) If dry-run is clean, execute restore.
+
+```bash
+npx aurawallet restore --latest
+```
+
+## Success check
+
+```bash
+npx aurawallet vault list
+```
+
+Expected:
+- vault/credentials are readable after unlock or restore
+- no schema mismatch errors after restore
+
+## Failure signatures + fixes
+
+- **"vault_locked" persists after unlock**
+  - Fix: re-run unlock, verify password, then confirm server state with `status`.
+
+- **Restore migration errors**
+  - Fix: keep backup untouched, upgrade Aura version, retry `--dry-run` first.
+
+- **No backups listed**
+  - Fix: recover from external/system backups and re-run restore flow.
+
+## Final verification (`aura doctor`)
+
+```bash
+npx aurawallet doctor --strict
+```
+
+Only close incident after doctor returns pass (or explicitly accepted warnings).

package/docs/jobs/secure-ci.md

@@ -0,0 +1,63 @@
+# Job: Secure CI with Scoped Aura Access
+
+Run CI jobs with minimal Aura permissions and deterministic health checks.
+
+## Preflight
+
+- Ensure CI has a scoped Aura token in secret storage (for example `AURA_TOKEN`).
+- Never commit tokens to repo files.
+
+Quick connectivity check in CI shell:
+
+```bash
+npx aurawallet status
+```
+
+## Runbook
+
+1) Validate env mapping and readiness in CI workspace.
+
+```bash
+npx aurawallet env check
+```
+
+2) Fetch only required secret fields (example).
+
+```bash
+npx aurawallet vault get ci-npm-token --field token
+```
+
+3) Run build/test command with vault-injected env.
+
+```bash
+npx aurawallet env -- npm run build
+```
+
+## Success check
+
+```bash
+npx aurawallet vault list
+```
+
+Expected:
+- only scoped credentials are accessible
+- CI job completes without raw `.env` files in repository
+
+## Failure signatures + fixes
+
+- **HTTP 401 / unauthorized**
+  - Fix: rotate or reissue CI token with required scopes and TTL.
+
+- **Credential not found in scope**
+  - Fix: update CI token/profile scope or `.aura` mapping to include required key.
+
+- **Rate-limit / policy deny**
+  - Fix: inspect token policy and adjust per-credential budget for CI workload.
+
+## Final verification (`aura doctor`)
+
+```bash
+npx aurawallet doctor --json
+```
+
+Store doctor JSON artifact in CI for auditability; remediate any fail state before release.

package/docs/oauth2.md

@@ -0,0 +1,42 @@
+# OAuth2 Credential Type
+
+Aura supports `oauth2` credentials with transparent access-token refresh.
+
+## Required metadata
+
+- `meta.token_endpoint` (string)
+- `meta.expires_at` (unix seconds)
+
+`oauth2` credentials must be in the primary vault.
+
+## Expected sensitive fields
+
+- `access_token`
+- `refresh_token`
+- `client_id`
+- `client_secret`
+
+Optional meta:
+
+- `auth_method` (`client_secret_post` default, or `client_secret_basic`)
+
+## Refresh behavior
+
+On `POST /credentials/:id/read`:
+
+1. if access token expired/near expiry, Aura calls token endpoint
+2. updates stored access token (and refresh token if returned)
+3. updates `expires_at` + `last_refreshed`
+4. returns filtered fields encrypted to `agentPubkey`
+
+Default excluded fields for oauth2 agent reads:
+
+- `refresh_token`
+- `client_secret`
+- `client_id`
+- `token_endpoint`
+
+## Re-auth status
+
+`POST /credentials/:id/reauth` exists but full authorization-code redirect flow is not implemented yet.
+Aura marks credentials `needs_reauth` on revoked refresh token detection.