auramaxx 0.0.1

package/docs/credentials.md

@@ -0,0 +1,120 @@
+# Credentials
+
+AuraMaxx stores credentials as locally encrypted files, scoped by vault. This is the core of AuraMaxx — a credential vault and password manager with support for logins, TOTP/2FA, passkeys, SSH/GPG keys, OAuth2 tokens, and more.
+
+## Credential Types
+
+| Type | Description | Key Fields |
+|------|-------------|------------|
+| `login` | Website logins | username, password, URL, TOTP |
+| `note` | Secure notes | freeform text |
+| `card` | Payment cards | card number, expiry, CVV |
+| `api` | API credentials | API key, secret, endpoint |
+| `apikey` | Service API keys (internal) | service, name, key |
+| `ssh` | SSH keys | private key (PEM), public key, key type, passphrase, fingerprint, hosts |
+| `gpg` | GPG keys | private key (armored), public key, key ID, fingerprint, email/UID, expiration |
+| `passkey` | WebAuthn/FIDO2 passkeys | credential ID, public key, private key (ECDSA P-256), RP ID, user handle |
+| `oauth2` | OAuth2 refresh tokens | access_token, refresh_token, token_endpoint, client_id, client_secret, expires_at, scopes |
+| `custom` | Freeform key-value | user-defined fields |
+
+## Data Model
+
+Each credential has:
+
+- `id` — unique identifier
+- `vaultId` — which vault owns this credential
+- `type` — one of the types above
+- `name` — human-readable label
+- `meta` — search/filter fields, tags, type-specific metadata (plaintext for listing)
+- Encrypted sensitive fields (encrypted with vault credential key)
+
+## 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.
+
+### Canonical Built-In Field Keys
+
+AuraMaxx uses canonical field keys for built-in credential types. Current baseline:
+
+| Type | Canonical Field Keys | Notes |
+|------|----------------------|-------|
+| `login` | `url`, `username`, `password`, `notes`, `totp` | `otp` is accepted as legacy alias for `totp` |
+| `card` | `cardholder`, `brand`, `billing_zip`, `last4`, `number`, `cvv`, `expiry`, `notes` | `last4` is derived metadata; `number`/`cvv`/`expiry` are sensitive |
+| `note` | `content` | `value` is accepted as legacy alias and normalized to `content` on read/write paths |
+| `apikey` | `key`, `value` | `key` is metadata/display, `value` is secret |
+| `oauth2` | `token_endpoint`, `scopes`, `auth_method`, `expires_at`, `access_token`, `refresh_token`, `client_id`, `client_secret` | `access_token`/`refresh_token`/`client_id`/`client_secret` are sensitive |
+| `ssh` | `fingerprint`, `key_type`, `hosts`, `public_key`, `private_key`, `passphrase` | `private_key`/`passphrase` are sensitive |
+| `gpg` | `fingerprint`, `key_id`, `uid_email`, `expires_at`, `public_key`, `private_key` | `private_key` is sensitive |
+
+## Access Model
+
+- `secret:read` — list metadata and read encrypted fields
+- `secret:write` — create, update, and delete credentials
+- Optional credential scopes (`credentialAccess.read` / `.write`) — restrict to specific vaults, tags, or credential IDs
+- Optional `excludeFields` — strip sensitive fields before response encryption
+- Optional `ttl` and `maxReads` — governance limits on credential reads
+
+Credential read endpoint returns data encrypted to the caller's `agentPubkey` (RSA-OAEP or hybrid RSA+AES-GCM for larger payloads).
+
+## Credential Health
+
+Credentials are scanned for security issues:
+
+- **Weak passwords** — entropy/length heuristics
+- **Reused passwords** — duplicate detection across credentials
+- **Breached passwords** — HIBP k-anonymity API (only 5-char SHA-1 prefix sent, never the full hash)
+
+Health badges appear per-credential in the vault UI. MCP `get_secret` includes a `health` field so agents can flag compromised credentials.
+
+CLI: `aura doctor` includes health summary, `aura vault health` for standalone check.
+
+## Credential Lifecycle
+
+Credentials support soft-delete:
+
+1. First delete → archived
+2. Second delete → recently deleted
+3. After 30 days → permanently purged
+
+## TOTP Support
+
+Any credential with a `totp` or `otp` field automatically gains TOTP code generation:
+
+- `POST /credentials/:id/totp` — returns current 6-digit code + time remaining
+- MCP `get_secret` returns current TOTP code when present
+- Extension autofills 2FA fields automatically
+
+## OAuth2 Auto-Refresh
+
+`oauth2` credentials auto-refresh expired access tokens:
+
+- On `get_secret` or credential read, if `access_token` is expired, transparently refreshes via `token_endpoint`
+- Updated tokens are saved back to the credential
+- Agents receive fresh `access_token` without seeing `refresh_token`
+
+## Endpoints
+
+- `POST /credentials` — create credential
+- `GET /credentials` — list credentials (metadata, scope-filtered)
+- `GET /credentials/:id` — get credential metadata
+- `PUT /credentials/:id` — update credential
+- `DELETE /credentials/:id` — soft-delete (archive → recently deleted → purge)
+- `POST /credentials/:id/read` — read credential (encrypted to `agentPubkey`)
+- `POST /credentials/:id/totp` — generate current TOTP code
+- `GET /credentials/:id/secrets` — admin-only plaintext read
+- `POST /credentials/import` — bulk import (1Password CSV, Bitwarden, Chrome, etc.)
+
+## Notes
+
+- `oauth2` credentials are restricted to the primary vault.
+- TOTP capability is auto-detected when `totp`/`otp` field exists.
+- Credential files are stored under AuraMaxx data directory (`~/.auramaxx/credentials/`).
+- SSH/GPG credentials store keys in PEM/armored format with auto-computed fingerprints.
+- `aura ssh-agent` can act as an SSH agent (SSH_AUTH_SOCK) backed by vault keys.

package/docs/external/HOW_TO_AURAMAXX/GETTING_SECRETS.md

@@ -0,0 +1,33 @@
+# Getting Secrets
+
+## Fast Path
+
+If your vault is unlocked, secret reads should work immediately via CLI or MCP.
+
+```bash
+auramaxx get OURSECRET
+# or
+auramaxx get OURSECRET
+```
+
+MCP path:
+
+- call `get_secret` with `name: "OURSECRET"`
+
+## If It Fails
+
+1. Check runtime health:
+   - `auramaxx status`
+2. If vault is locked:
+   - unlock in dashboard (`http://localhost:4747`) or run `auramaxx unlock`
+3. If MCP/agent call gets permission denied:
+   - follow [AGENT_SETUP.md](../../AGENT_SETUP.md) for MCP setup
+   - then use [AUTH.md](../../AUTH.md) for token/approval flow details
+
+## Optional: Seed Test Secret
+
+If `OURSECRET` does not exist yet:
+
+```bash
+auramaxx set OURSECRET 123
+```

package/docs/external/HOW_TO_AURAMAXX/README.md

@@ -0,0 +1,45 @@
+# HOW TO AURAMAXX
+
+This is the single external entrypoint for understanding and using AuraMaxx.
+
+## Fast start
+
+### First run
+
+```bash
+npx auramaxx
+npx auramaxx status
+```
+
+Open `http://localhost:4747/`, create/unlock your vault, and add one credential.
+
+### Returning run
+
+- Service already running: `npx auramaxx status`
+- Service not running: `npx auramaxx && npx auramaxx status`
+
+If using global install and prompted to update:
+
+```bash
+npm i -g auramaxx
+```
+
+## Core concepts (condensed)
+
+- **Auth:** access is explicit and scoped (not just process identity).
+- **Safety:** least-privilege defaults + approval flows.
+- **Understanding Aura:** local-first credential runtime for humans + agents.
+- **Security transparency:** source is auditable on GitHub: <https://github.com/Aura-Industry/auramaxx>
+
+## Main usage path
+
+- **Start here:** [GETTING_SECRETS.md](./GETTING_SECRETS.md)
+- Then configure MCP clients: [AGENT_SETUP.md](../../AGENT_SETUP.md)
+
+## Next references
+
+- [CLI](../../CLI.md)
+- [MCP](../../MCP.md)
+- [Auth + permissions](../../AUTH.md)
+- [Security model](../../security.md)
+- [Share secret guide](../share-secret.md)

package/docs/external/getting-started.md

@@ -0,0 +1,10 @@
+# Getting Started
+
+External getting-started now routes through **HOW TO AURAMAXX**.
+
+## Start here
+
+- [HOW TO AURAMAXX](./HOW_TO_AURAMAXX/README.md)
+- [SETUP](../AGENT_SETUP.md)
+
+For core bootstrap commands, use the root [README](../../README.md).

package/docs/external/overview.md

@@ -0,0 +1,19 @@
+# Aura Overview
+
+AuraMaxx is a local credential vault and agent-safe secret runtime.
+
+It helps you store secrets once, use them across CLI/UI/agents, and enforce least-privilege access by default.
+
+## External docs entrypoint
+
+- Start here: [HOW TO AURAMAXX](./HOW_TO_AURAMAXX/README.md)
+- Main usage path: [SETUP](../AGENT_SETUP.md)
+
+## 2-minute proof
+
+```bash
+npx auramaxx
+npx auramaxx status
+```
+
+Then open `http://localhost:4747/`, create your vault, and add one credential.

package/docs/external/persona-paths.md

@@ -0,0 +1,7 @@
+# Deprecated: Persona Paths
+
+Persona-based external navigation has been replaced by tool-first usage paths.
+
+Use:
+- [HOW TO AURAMAXX](./HOW_TO_AURAMAXX/README.md)
+- [SETUP](../AGENT_SETUP.md)

package/docs/external/share-secret.md

@@ -0,0 +1,76 @@
+# Share a Secret (CLI + UI)
+
+This guide covers the current AuraMaxx sharing flow:
+
+1. **Preferred:** create a GitHub Gist share link.
+2. **Fallback:** use a local link (only works if recipient can reach your machine).
+
+---
+
+## Prerequisite: GitHub CLI auth (for Gist sharing)
+
+Check auth:
+
+```bash
+gh auth status
+```
+
+If not authenticated:
+
+```bash
+gh auth login
+```
+
+If `gh` is missing, install GitHub CLI first, then authenticate.
+
+---
+
+## CLI sharing
+
+### Recommended command
+
+```bash
+auramaxx vault share OPENAI_KEY --expires-after 24h
+```
+
+### Alias path (same behavior)
+
+```bash
+auramaxx share OPENAI_KEY --expires-after 24h
+```
+
+### What to expect
+
+- If GitHub auth is available, CLI generates a share via Gist and returns a shareable link.
+- If GitHub/Gist path is unavailable, use local-link fallback (see below).
+
+---
+
+## UI sharing
+
+1. Open Vault and select a credential.
+2. Click **SHARE** in credential detail.
+3. In the share modal:
+   - Prefer **SHARE GIST** (recommended for remote recipients).
+   - Use local link only when recipient can reach your host/network.
+
+---
+
+## Local-link limitation (important)
+
+A local link is often **not reachable** by remote recipients.
+
+Use local links only when:
+- recipient is on the same network, or
+- you provide a secure tunnel/network path.
+
+---
+
+## Tunnel/network fallback options
+
+If Gist sharing is unavailable and recipient is remote, use one of these:
+
+- Cloudflare Tunnel: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/
+- Tailscale: https://tailscale.com/kb
+
+These options can make local-hosted share endpoints reachable in a controlled way.

package/docs/external/why-aura.md

@@ -0,0 +1,7 @@
+# Deprecated: Why Aura
+
+This page has been consolidated into **HOW TO AURAMAXX**.
+
+Use:
+- [HOW TO AURAMAXX](./HOW_TO_AURAMAXX/README.md)
+- [SETUP](../AGENT_SETUP.md)

package/docs/security.md

@@ -0,0 +1,227 @@
+# Security
+
+This document reflects the current security model implemented in the codebase.
+
+## Security Overview (why the model is safe)
+
+AuraMaxx uses a **three-layer model**:
+
+1. **Profile-based issuance** (how a token is created)
+2. **Permission-based runtime enforcement** (what a token can do)
+3. **Granular credential access policy** (which secrets and fields can be touched)
+
+The result: tokens are easy to issue, strict to scope, and hard to overscope.
+
+### The model in one pass
+
+- Agents usually start with an **agent profile** (`POST /auth`) that defines:
+  - base permissions
+  - credential read/write scopes (vaults/tags/ids)
+  - TTL and read limits
+  - field redaction policies
+- Issuance is intentionally **human-approved** and not self-service by default.
+- Every API request is still validated again using runtime permission checks.
+- Secret access is additionally constrained by selector checks and read budgets.
+- Tokens are short-lived and can be revoked proactively.
+
+### What “least privilege” means here
+
+- Profiles give sensible defaults, but they are not blanket trust.
+- Every request is still gated by permissions + scope.
+- Agent callers can only operate on explicitly authorized vaults and fields.
+- If a profile must be tighter, overrides must be **tighten-only**.
+
+---
+
+## Core Principles
+
+1. **Memory-rooted auth/session state** — in-memory SIGNING_KEY, sessions, and revocation state drive runtime trust boundaries.
+2. **Restart invalidates all tokens** — new SIGNING_KEY is generated each restart.
+3. **Minimal permissions** — tokens carry exactly the permissions needed.
+4. **Encrypted secrets at rest** — credential fields are encrypted in local DB with vault-derived keys.
+5. **Encrypted credential transport** — secret reads are encrypted to the caller's RSA pubkey.
+6. **Human-controlled unlocks** — privileged operations require explicit human action.
+7. **Scoped ownership** — credential access requires explicit credential selectors + permission checks.
+
+## Current Security Model
+
+AuraMaxx is **profile-first** for issuance, but **permission- and scope-enforced at runtime**.
+
+- Issuance determines token payload (permissions, TTL, credential selectors, exclusions).
+- Middleware enforces per-route permissions on every call.
+- Credential read/write governance adds extra controls:
+  - selector checks
+  - per-token read budgets
+  - max read/window throttles
+  - excluded field minimization
+
+Auth/session truth source is still memory-first:
+
+- Tokens are signed in memory (`SIGNING_KEY`).
+- Session counters/tracking are memory-backed.
+- Revocations are memory-backed (`revokedTokens`).
+- DB is authoritative for UI/audit views, not for runtime auth decisions.
+
+## Agent Token Paths
+
+> For quickstart usage and CLI examples, see [AUTH.md](./AUTH.md). This section describes the security enforcement model for each path.
+
+### 1) `POST /auth` (profile-only request + human approval)
+
+Standard agent onboarding path.
+
+- Required: `agentId`, `profile`, `pubkey`.
+- Rejects raw issuance (`permissions`, `ttl`, `credentialAccess`) on `/auth`.
+- Resolves profile policy and stores approval request in memory.
+- After approval, claim via `GET /auth/:requestId?secret=...`.
+
+### 2) `POST /actions` + `/actions/:id/resolve` (internal — strategy engine only)
+
+> **Note**: `/actions` routes are internal. Agents should use `POST /auth` with an optional `action` field for one-off escalation with auto-execute.
+
+- Used internally by the strategy engine's `request_human_action` tool.
+- Caller needs `action:create` to submit.
+- Payload is permission-based.
+- Self-escalation is blocked for `admin:*` and `action:create`.
+- Approved request gets a scoped token and escrowed claim path.
+
+### 3) `POST /actions/token` (admin direct issuance)
+
+Admin-only endpoint with XOR mode:
+
+- `profile` mode: profile + optional tighten-only overrides
+- `permissions` mode: explicit permissions
+
+Exactly one mode must be supplied.
+
+### 4) Validation and revocation
+
+- `POST /auth/validate` validates token status, expiry, and revocation.
+- `POST /actions/tokens/revoke` forcibly removes active token trust.
+
+## Profile-Based Security (Current)
+
+Built-in profile IDs (`v1`): `strict`, `dev`, `admin`.
+
+See [AUTH.md — Built-in Profiles](./AUTH.md#built-in-profiles-v1) for the full breakdown of permissions, scopes, excluded fields, TTL, and max reads per profile.
+
+Profile resolution (`resolveProfileToEffectivePolicy`) produces:
+
+- expanded permissions
+- `credentialAccess.read` / `credentialAccess.write`
+- `excludeFields`
+- `ttlSeconds`
+- `maxReads`
+- `effectivePolicyHash`
+
+### Tighten-only overrides
+
+Overrides are only allowed to reduce privilege:
+
+- shorter TTL / fewer reads
+- narrower permission scope
+- narrower credential selectors
+- stronger field exclusions
+
+## Permission Enforcement (Runtime)
+
+Runtime enforcement always applies:
+
+- route middleware validates signature, expiry, revocation
+- permission checks (`requirePermission`, `hasAnyPermission`) gate capabilities
+- `admin:*` remains privileged bypass flag where explicitly required
+
+Profile is issuance; permission enforcement is the live guardrail.
+
+## Granular credential access controls
+
+AuraMaxx supports fine-grained secret governance:
+
+- `secret:read` and `secret:write` route gating
+- credential selectors:
+  - `vault:agent`, `vault:primary`, `vault:*`, `*`
+  - `tag:<label>`
+  - `cred-xxxxx`
+- policy TTL and `maxReads`
+- per-credential/minute rate limits
+- field minimization via `excludeFields`
+
+This means permissions can say “can read secrets,” and selectors define **where** and **what field-level data** is reachable.
+
+### Recommended mental model
+
+- Permissions say **action** (`read`/`write`/`totp`),
+- selectors say **scope** (vault/field scope),
+- TTL/limits say **time/volume**.
+
+## Encrypted transport boundaries
+
+- `GET /auth/connect` returns a short-lived server public key.
+- `/setup` and `/unlock` accept encrypted payloads.
+- Agent token claim endpoints return `encryptedToken`.
+- Secret reads return ciphertext suitable to caller key material.
+
+This prevents plaintext secrets in transit for normal operations.
+
+## Strict mode and local auto-approve
+
+Strict posture is preferred for high-trust environments.
+
+Set strict local defaults:
+
+- `trust.localProfile = strict`
+- `trust.localAutoApprove = false`
+
+Quick commands:
+
+```bash
+curl -sS -X PATCH http://localhost:4242/defaults/trust.localProfile \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"value":"strict"}'
+
+curl -sS -X PATCH http://localhost:4242/defaults/trust.localAutoApprove \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"value":false}'
+```
+
+## Profile creation and validation
+
+Profiles are derived from built-ins + tighten-only overrides.
+
+Supported override keys:
+
+- `ttlSeconds`
+- `maxReads`
+- `scope`
+- `readScopes`
+- `writeScopes`
+- `excludeFields`
+
+Prefer preview before issuing:
+
+- `POST /actions/token/preview`
+- `auramaxx token preview --profile <id> [--profile-version v1] [--overrides '{...}']`
+
+## Endpoint Cheat Sheet
+
+| Endpoint | Style | Typical use |
+|---|---|---|
+| `POST /auth` | Profile onboarding | Standard agent setup (human approval) |
+| `GET /auth/:requestId?secret=...` | Profile claim | Agent retrieves encrypted token |
+| `POST /auth/validate` | Validation | Verify token validity before use |
+| `POST /actions` | Internal (strategy engine) | Temporary action request |
+| `POST /actions/:id/resolve` | Internal (approval) | Human approves action request |
+| `POST /actions/token` | Admin direct issue | Admin direct token issuance |
+| `POST /actions/tokens/revoke` | Revocation | Immediate invalidate token |
+| `POST /actions/token/preview` | Preview | Validate effective policy before issue |
+| `POST /unlock` / `POST /setup` | Session bootstrap | Human local admin access |
+
+## Related Docs
+
+- [Auth](./AUTH.md)
+- [API Authentication](./api/authentication.md)
+- [API System](./api/system.md)
+- [CLI](./CLI.md)
+- [Best Practices](./BEST-PRACTICES.md)

package/docs/templates/RELEASE_NOTES_TEMPLATE.md

@@ -0,0 +1,22 @@
+# Release Notes Template
+
+## Operator changes
+
+- What changed for humans running Aura locally?
+- What setup/upgrade action is required?
+- How to verify success (`npx auramaxx doctor` output expectation)?
+
+## Agent changes
+
+- What changed for agent auth/token behavior?
+- Any profile/scope defaults changed?
+- Any remediation for existing automations?
+
+## Verification checklist
+
+```bash
+node scripts/validate-job-docs.mjs
+npx auramaxx doctor
+```
+
+Mark release notes complete only after both checks pass.