auramaxx 1.0.0-alpha.4

package/docs/passkeys.md

@@ -0,0 +1,60 @@
+# Passkeys
+
+Aura supports **two separate passkey systems**:
+
+1. **Vault-unlock passkeys** (`/auth/passkey/*`) for session token issuance (Face ID / Touch ID / platform authenticator).
+2. **Credential passkeys** (`/credentials/passkey/*`) for website WebAuthn registration/authentication stored in Aura credentials.
+
+Do not treat these as the same trust boundary.
+
+## 1) Vault-unlock passkeys (session auth)
+
+### Endpoints
+
+- `GET /auth/passkey/status`
+- `POST /auth/passkey/register/options` (admin required)
+- `POST /auth/passkey/register/verify` (admin required)
+- `POST /auth/passkey/authenticate/options`
+- `POST /auth/passkey/authenticate/verify`
+- `DELETE /auth/passkey/:credentialId` (admin required)
+
+### Behavior
+
+- Registration requires unlocked vault + admin token.
+- Authentication verify requires caller `pubkey`; successful auth issues an admin token.
+- If vault is locked after restart, passkey auth endpoints return `vault_locked` until server unlock state is restored.
+
+### Storage
+
+Vault-unlock passkey records use Prisma `Passkey` model:
+
+- `credentialId`
+- `publicKey`
+- `counter`
+- `transports`
+- `rpId`
+- `aaguid`
+
+No private key material is stored by Aura for vault-unlock authenticators.
+
+## 2) Credential passkeys (site passkeys)
+
+### Endpoints
+
+- `GET /credentials/passkey/match?rpId=<rpId>`
+- `POST /credentials/passkey/register`
+- `POST /credentials/passkey/authenticate`
+
+### Behavior
+
+- Extension intercepts `navigator.credentials.create()` / `get()` and routes through Aura.
+- Registration requires explicit user confirmation in extension UI.
+- Authentication:
+  - Honors RP `allowCredentials` ordering when provided.
+  - Shows picker UI when multiple Aura passkeys match.
+  - Requires explicit confirmation for single-match authentication.
+- If Aura has no match, user denies, server is unavailable, or the request times out, flow declines so browser can fall back to native WebAuthn handling.
+
+### Storage
+
+Credential passkeys are stored as first-class `passkey` credentials in Aura credential storage with encrypted private key material and metadata (e.g. `rpId`, `credentialId`, `publicKey`, `userHandle`, `signCount`, transports/discoverable flags).

package/docs/security.md

@@ -0,0 +1,540 @@
+# Security Architecture
+
+This document describes the security model and architecture for AuraWallet.
+
+## Core Principles
+
+1. **Memory-only authentication** - All auth decisions use in-memory state only
+2. **Restart invalidates all tokens** - New SIGNING_KEY on restart = forced re-approval
+3. **Minimal permissions** - Agents request only what they need
+4. **Human controls cold wallet** - All cold wallet operations require human approval
+5. **Wallet ownership** - Agents can only access wallets they created
+
+---
+
+## Threat Model
+
+### Adversary Personas
+
+| Persona | Description | Access Level |
+|---------|-------------|--------------|
+| **Rogue Agent** | Compromised or malicious AI agent with a valid token | Network access to localhost:4242, limited permissions |
+| **Local Malware** | Malware running on the same machine as the server | File system access, process inspection, network sniffing |
+| **Database Attacker** | Attacker who obtains a copy of the SQLite database | Read access to `~/.aurawallet/aurawallet.db` |
+| **Network Observer** | Process or tool intercepting localhost HTTP traffic | Can read/modify HTTP requests between agent and server |
+
+### Asset Values
+
+| Asset | Storage | Compromise Impact |
+|-------|---------|-------------------|
+| **Cold mnemonic** | Encrypted file (AES-256-GCM, password-derived key) → decrypted in memory only when unlocked | Total fund loss — full control of cold wallet and all derived addresses |
+| **Hot wallet private keys** | DB (AES-256-GCM, encrypted with cold mnemonic) | Loss of individual hot wallet funds |
+| **SIGNING_KEY** | Memory only (random 32 bytes) | Token forgery — can create tokens with any permissions |
+| **Agent tokens** | Memory only (HMAC-signed payloads) | Impersonation — spend within token's limits/permissions |
+| **Vault password** | Never stored (used to decrypt vault file) | Can unlock vault → access cold mnemonic |
+
+### Risk Matrix
+
+| Attack | Likelihood | Impact | Mitigation |
+|--------|-----------|--------|------------|
+| Agent exceeds intended scope | Medium | Medium | Permission system, spending limits, wallet ownership |
+| Localhost traffic interception | Low | High | RSA-OAEP password encryption, tokens are bearer-only |
+| Database file exfiltration | Low | Low | DB alone cannot forge auth or decrypt cold wallet |
+| Memory dump of server process | Very Low | Critical | OS-level protection; restart invalidates all state |
+| Brute-force vault password | Low | Critical | Rate limit: 5 attempts / 15 min on unlock endpoints |
+
+---
+
+## Architecture Overview
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    MEMORY (Security-Critical)                     │
+├──────────────────────────────────────────────────────────────────┤
+│  SIGNING_KEY        - Random 32 bytes, regenerates on restart    │
+│  sessions Map       - tokenHash → { token, spentByType }         │
+│  revokedTokens Set  - Revoked token hashes                       │
+│  vaultSessions Map  - vaultId → { mnemonic, address, ... }       │
+│                       (per-vault unlock state, replaces           │
+│                        singleton unlockedMnemonic)                │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    DATABASE (Display Only)                        │
+├──────────────────────────────────────────────────────────────────┤
+│  AgentToken         - For UI display, NOT for auth decisions     │
+│  HotWallet          - Encrypted private keys + ownership         │
+│  HumanAction        - Pending actions awaiting human approval     │
+│  ApiKey             - Stored API keys                            │
+│  Log                - Audit trail                                │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+**Key insight**: A stolen database is useless without the in-memory SIGNING_KEY.
+
+---
+
+## Token Signing Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                       TOKEN CREATION                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  1. Build payload:                                                  │
+│     payload = {                                                     │
+│       agentId: "my-agent",                                          │
+│       permissions: ["wallet:create:hot", "send:hot", "fund"],       │
+│       exp: 1738600000000,                                           │
+│       limits: { fund: 1.0 }                                         │
+│     }                                                               │
+│                                                                     │
+│  2. Encode payload:                                                 │
+│     payloadStr = base64url(JSON.stringify(payload))                 │
+│                                                                     │
+│  3. Sign with SIGNING_KEY:                                          │
+│     signature = HMAC-SHA256(SIGNING_KEY, payloadStr)                │
+│     signatureStr = base64url(signature)                             │
+│                                                                     │
+│  4. Create token:                                                   │
+│     token = payloadStr + "." + signatureStr                         │
+│                                                                     │
+│  5. Register in memory:                                             │
+│     tokenHash = HMAC-SHA256(SIGNING_KEY, token).slice(0,16)         │
+│     sessions.set(tokenHash, { token: payload, spentByType: {} })    │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Token Validation
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                       TOKEN VALIDATION                              │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Input: "eyJhZ2VudElkIjo...".signature                              │
+│                                                                     │
+│  1. Split token:                                                    │
+│     [payloadStr, providedSig] = token.split(".")                    │
+│                                                                     │
+│  2. Verify signature:                                               │
+│     expectedSig = HMAC-SHA256(SIGNING_KEY, payloadStr)              │
+│     if (providedSig !== expectedSig) → REJECT (invalid signature)   │
+│                                                                     │
+│  3. Parse payload:                                                  │
+│     payload = JSON.parse(base64url.decode(payloadStr))              │
+│                                                                     │
+│  4. Check expiry:                                                   │
+│     if (payload.exp < Date.now()) → REJECT (expired)                │
+│                                                                     │
+│  5. Check revocation:                                               │
+│     tokenHash = HMAC-SHA256(SIGNING_KEY, token).slice(0,16)         │
+│     if (revokedTokens.has(tokenHash)) → REJECT (revoked)            │
+│                                                                     │
+│  6. Return payload with permissions                                 │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Permission Checking Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                     PERMISSION CHECK                                │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  Route: POST /fund                                                  │
+│  Required: "fund" permission                                        │
+│                                                                     │
+│  1. Token permissions: ["trade:all"]                                │
+│                                                                     │
+│  2. Check admin bypass:                                             │
+│     if (permissions.includes("admin:*")) → ALLOW                    │
+│                                                                     │
+│  3. Expand compound permissions:                                    │
+│     "trade:all" expands to:                                         │
+│       ["wallet:list", "wallet:create:hot", "wallet:create:temp",    │
+│        "send:hot", "send:temp", "swap", "fund", "apikey:get"]       │
+│                                                                     │
+│  4. Check if required permission in expanded list:                  │
+│     "fund" in expanded? → YES → ALLOW                               │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Compound Permissions
+
+| Permission | Expands To |
+|------------|------------|
+| `trade:all` | `wallet:list`, `wallet:create:hot`, `wallet:create:temp`, `send:hot`, `send:temp`, `swap`, `fund`, `launch`, `apikey:get`, `strategy:read` |
+| `admin:*` | Bypasses ALL permission checks |
+
+---
+
+## Multi-Vault Security Model
+
+AuraWallet supports multiple vaults, each with its own encrypted seed phrase, password, and derived wallets.
+
+### Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    MEMORY (Per-Vault Sessions)                     │
+├──────────────────────────────────────────────────────────────────┤
+│  vaultSessions: Map<string, VaultSession>                         │
+│    ├── "vault-primary" → { mnemonic, address, solanaAddress }     │
+│    ├── "vault-abc123"  → { mnemonic, address, solanaAddress }     │
+│    └── "vault-def456"  → (locked - not in map)                    │
+│                                                                    │
+│  Replaces singleton unlockedMnemonic with per-vault Map            │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    FILESYSTEM (Per-Vault Encrypted Seeds)          │
+├──────────────────────────────────────────────────────────────────┤
+│  ~/.aurawallet/vault-primary.json  ← Primary vault (migrated      │
+│                                      from cold.json)              │
+│  ~/.aurawallet/vault-abc123.json  ← Additional vault              │
+│  ~/.aurawallet/vault-def456.json  ← Additional vault              │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Key Properties
+
+| Property | Behavior |
+|----------|----------|
+| **Independent passwords** | Each vault has its own password; unlocking one does not unlock others |
+| **Per-vault locking** | Vaults can be locked/unlocked individually via `/lock/:vaultId` and `/unlock/:vaultId` |
+| **Lock all** | `POST /lock` (no vaultId) locks ALL vaults at once |
+| **Hot wallet scoping** | Hot wallets are scoped to their vault; private keys are encrypted with that vault's mnemonic |
+| **Primary vault compat** | The primary vault remains backward-compatible with existing `/unlock` and `/setup` endpoints |
+| **Auto-migration** | On first startup, `cold.json` is automatically migrated to `vault-primary.json` |
+| **Restart behavior** | Server restart clears all vault sessions (all vaults lock), consistent with existing security model |
+
+### Hot Wallet Encryption Scoping
+
+When a hot wallet is created under a specific vault, its private key is encrypted using that vault's mnemonic (AES-256-GCM). This means:
+
+- The vault must be unlocked to decrypt and use its hot wallets
+- Moving a hot wallet between vaults is not supported (it is bound to its vault's seed)
+- If a vault is locked, its hot wallets cannot sign transactions
+
+### Migration from Single Vault
+
+Existing deployments using a single `cold.json` file are automatically migrated:
+
+1. On startup, if `cold.json` exists but `vault-primary.json` does not, the file is copied to `vault-primary.json`
+2. The original `cold.json` is preserved as a backup
+3. All existing hot wallets continue to work under the primary vault
+4. No user action is required
+
+---
+
+## Credential Vault Security
+
+Credential reads follow a separate, encrypted flow:
+
+- At rest: credential files are encrypted with a vault-derived subkey (`credential-v1:<vaultId>:<mnemonic>` hash context).
+- Authorization: list/read/write are scoped with `credentialAccess.read` / `credentialAccess.write` (`*`, `vault:`, `tag:`, or credential ID).
+- Field minimization: sensitive fields can be stripped by token `excludeFields` (or type defaults like `password`/`cvv`) before response encryption.
+- Transport security: `/credentials/:id/read` returns ciphertext encrypted to token `agentPubkey` (RSA-OAEP; hybrid RSA+AES-GCM for larger payloads).
+- Read governance: `credentialAccess.ttl` and `credentialAccess.maxReads` are enforced from memory-only session state.
+- Token mint contract: every token mint path requires caller `pubkey` (`/setup`, `/unlock`, `/unlock/:vaultId`, `/auth`, `/actions/token`, approval-issued replacements).
+
+**Audit logging:** successful credential reads are logged with credential ID, agent ID, vault ID, and returned field names only (never field values).
+
+---
+
+## Spending Limit Enforcement
+
+```
+Human                      Server Memory                    Agent
+  │                             │                            │
+  │ Approve: fund limit 1 ETH   │                            │
+  ├────────────────────────────>│                            │
+  │                             │                            │
+  │                      sessions.set(tokenHash, {           │
+  │                        token: { limits: { fund: 1.0 } }, │
+  │                        spentByType: { fund: 0 }          │
+  │                      })                                  │
+  │                             │                            │
+  │                             │    POST /fund              │
+  │                             │    amount: 0.3 ETH         │
+  │                             │<───────────────────────────┤
+  │                             │                            │
+  │                      Check permission: "fund" ✓          │
+  │                      Get limit: 1.0 ETH                  │
+  │                      Get spent: 0 ETH                    │
+  │                      0 + 0.3 <= 1.0 ✓                    │
+  │                             │                            │
+  │                      Execute transfer                    │
+  │                      spentByType.fund = 0.3              │
+  │                             ├───────────────────────────>│
+  │                             │                            │
+  │                             │    POST /fund              │
+  │                             │    amount: 0.5 ETH         │
+  │                             │<───────────────────────────┤
+  │                             │                            │
+  │                      0.3 + 0.5 <= 1.0 ✓                  │
+  │                      Execute, spent = 0.8                │
+  │                             ├───────────────────────────>│
+  │                             │                            │
+  │                             │    POST /fund              │
+  │                             │    amount: 0.5 ETH         │
+  │                             │<───────────────────────────┤
+  │                             │                            │
+  │                      0.8 + 0.5 > 1.0 ✗                   │
+  │                      REJECT: exceeds limit               │
+  │                             ├───────────────────────────>│
+```
+
+### Limit Types
+
+| Type | Enforced On | Description |
+|------|-------------|-------------|
+| `fund` | `/fund` endpoint | Cold→hot transfers |
+| `send` | `/send` endpoint | Hot wallet sends (optional). Sends to cold wallet address bypass (vault return) |
+| `swap` | `/swap` endpoint | Swap volume (optional) |
+
+---
+
+## Wallet Tiers
+
+| Tier | Access | Key Storage | Use Case |
+|------|--------|-------------|----------|
+| **Cold** | Human only | Encrypted file (password) | Treasury, source of funds |
+| **Hot** | Agent with token | DB (encrypted with seed) | Agent operations |
+| **Temp** | Agent with token | DB (encrypted with seed) | Ephemeral, auto-sweep |
+
+### Hot Wallet Creation
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    HOT WALLET CREATION                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  Agent (with token) → POST /wallet/create { tier: "hot" }       │
+│       │                                                         │
+│       ▼                                                         │
+│  Check permission: "wallet:create:hot" ✓                        │
+│       │                                                         │
+│       ▼                                                         │
+│  ethers.Wallet.createRandom() → Random keypair (NOT HD)         │
+│       │                                                         │
+│       ▼                                                         │
+│  Encrypt privateKey with cold wallet mnemonic (AES-256-GCM)     │
+│       │                                                         │
+│       ▼                                                         │
+│  Store in DB: {                                                 │
+│    address,                                                     │
+│    encryptedPrivateKey,                                         │
+│    tokenHash,  ← Ownership: which token created this wallet     │
+│    tier: "hot"                                                  │
+│  }                                                              │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Wallet Ownership
+
+Agents can only access wallets they own:
+
+```typescript
+function tokenCanAccessWallet(tokenHash, walletAccess, address): boolean {
+  // 1. Token created the wallet (tokenHash matches)
+  if (wallet.tokenHash === tokenHash) return true;
+
+  // 2. Wallet is in token's walletAccess array
+  if (walletAccess?.includes(address)) return true;
+
+  return false;
+}
+```
+
+---
+
+## Full Request Flow
+
+```
+Human                      Server Memory                    Agent
+  │                             │                            │
+  │ POST /unlock                │                            │
+  │ { encrypted, pubkey }       │                            │
+  ├────────────────────────────>│                            │
+  │                             │ Decrypt cold wallet        │
+  │                             │ mnemonic → memory          │
+  │<────────────────────────────┤                            │
+  │                             │                            │
+  │                             │     POST /auth             │
+  │                             │     { agentId, perms,      │
+  │                             │       pubkey }             │
+  │                             │<───────────────────────────┤
+  │                             │ Create PendingAction       │
+  │                             │ Return requestId + secret  │
+  │                             ├───────────────────────────>│
+  │                             │                            │
+  │ POST /actions/:id/resolve   │                            │
+  ├────────────────────────────>│                            │
+  │                             │ payload = { agentId,       │
+  │                             │   permissions, limits }    │
+  │                             │                            │
+  │                             │ sig = HMAC(KEY, payload)   │
+  │                             │ token = payload.sig        │
+  │                             │                            │
+  │                             │ sessions.set(hash, {       │
+  │                             │   token, spentByType: {}   │
+  │                             │ })                         │
+  │                             │                            │
+  │                             │     GET /auth/:id          │
+  │                             │<───────────────────────────┤
+  │                             │ Return signed token        │
+  │                             ├───────────────────────────>│
+  │                             │                            │
+  │                             │     POST /wallet/create    │
+  │                             │     Authorization: Bearer  │
+  │                             │<───────────────────────────┤
+  │                             │                            │
+  │                             │ Verify HMAC signature ✓    │
+  │                             │ Check: wallet:create:hot ✓ │
+  │                             │ Create wallet, set owner   │
+  │                             ├───────────────────────────>│
+  │                             │                            │
+  │                             │     POST /fund             │
+  │                             │     { to: wallet, amt }    │
+  │                             │<───────────────────────────┤
+  │                             │                            │
+  │                             │ Verify signature ✓         │
+  │                             │ Check: fund permission ✓   │
+  │                             │ Check: owns wallet ✓       │
+  │                             │ Check: amt <= remaining ✓  │
+  │                             │                            │
+  │                             │ Sign tx with mnemonic      │
+  │                             │ Broadcast to chain         │
+  │                             │ Track: spentByType.fund    │
+  │                             ├───────────────────────────>│
+```
+
+---
+
+## Security Properties
+
+### What's Protected
+
+| Attack Vector | Mitigation | Mechanism |
+|---------------|------------|-----------|
+| Database theft | SIGNING_KEY in memory only — tokens can't be forged | HMAC-SHA256 requires the key to produce valid signatures; DB stores only tokenHash (truncated HMAC), not the key or raw tokens |
+| Token theft | Tokens expire, can be revoked, restart invalidates all | Raw token held in memory escrow only — never stored in DB. First poll claims it (second returns 410). Revocation checked in-memory Set |
+| Token replay | Spending tracked per-token in memory | Each operation increments `spentByType` in the sessions Map; cumulative spend checked before execution. Tokens are static (same signature), but spending tracking prevents reuse beyond limits |
+| Privilege escalation | Permissions signed in token, can't be modified | Payload is base64url-encoded and HMAC-signed; modifying any field invalidates the signature |
+| Cold wallet theft | Password-encrypted, requires human unlock | Vault file encrypted with AES-256-GCM using password-derived key (scrypt). Mnemonic only enters memory after correct password |
+| Hot wallet theft | Encrypted with mnemonic, ownership enforced | Private keys encrypted with AES-256-GCM using the cold wallet mnemonic; decryption requires unlocked vault. Ownership checked via tokenHash match or walletAccess array |
+| Password brute force | Rate limited: 5 attempts per 15 min | Applied to `/unlock`, `/setup`, `/actions`, `/nuke`, `/backup`. Keyed by IP. Resets after window expires |
+| Request spam / DoS | Tiered rate limiting | 100 req/min general, 30 req/min transactions (keyed by hashed token), 10 req/min auth. See Rate Limit Design below |
+| MEV sandwich attacks | Slippage floor enforced | 0.5% minimum for admin, 1% for agents. Explicit `minOut` validated against floor. Zero slippage rejected at input validation |
+| XSS via installed apps | Sandboxed iframe execution | `sandbox="allow-scripts"` (no `allow-same-origin`). App cannot access parent DOM, cookies, or localStorage. See [APPS.md](./APPS.md) |
+| XSS via iframe apps | URL scheme restriction + sandbox | Hardcoded `sandbox="allow-scripts allow-forms"` (no `allow-same-origin`), only `http:`/`https:` URLs allowed |
+| Adapter token exposure | Internal admin token scoped to adapter router | Signed with in-memory SIGNING_KEY, invalidated on restart. Same lifecycle as all other tokens. See [ADAPTERS.md](./ADAPTERS.md) |
+
+### What Restart Does
+
+1. New SIGNING_KEY generated (random 32 bytes) → all old tokens invalid
+2. Memory sessions cleared → spending tracking reset
+3. Revocation list cleared → (tokens invalid anyway)
+4. Cold wallet locks → requires password to unlock
+5. Agents must request new approval
+
+**This is intentional security, not a bug.**
+
+---
+
+## Design Rationale
+
+### Why memory-only auth?
+
+The hard boundary between database and runtime is the foundation of the security model. The database stores display data (UI, logs, audit trail), while all auth decisions happen against in-memory state. This means a stolen database — the most common attack surface — yields nothing actionable. An attacker cannot forge tokens, cannot reconstruct the SIGNING_KEY, and cannot access encrypted hot wallet keys (which require the cold mnemonic, also in memory only when unlocked).
+
+### Why 32 bytes for SIGNING_KEY?
+
+RFC 2104 recommends HMAC keys be at least as long as the hash output. HMAC-SHA256 produces 32 bytes, so the SIGNING_KEY is 32 bytes of `crypto.randomBytes()`. This provides 256 bits of entropy — computationally infeasible to brute-force.
+
+### Why restart invalidation is a feature
+
+Restart invalidation implements the fail-closed principle. If the server process is compromised, killed, or crashes, all auth state is wiped. There is no way for stale tokens to persist across process boundaries. This eliminates an entire class of token persistence attacks and ensures every session begins with a clean, human-approved auth state.
+
+### Why RSA-OAEP for password transport
+
+Even on localhost, HTTP traffic is observable by other processes (proxy tools, malware, debugging middleware). RSA-OAEP encrypts the vault password before it leaves the browser, so a network observer sees only ciphertext. The RSA keypair is ephemeral (regenerated on restart), and RSA-OAEP provides semantic security — encrypting the same password twice produces different ciphertext.
+
+---
+
+## Rate Limit Design
+
+| Tier | Limit | Endpoints | Key | Rationale |
+|------|-------|-----------|-----|-----------|
+| **Brute-force** | 5 / 15 min | `/unlock`, `/setup`, `/actions`, `/nuke`, `/backup` | IP | Protects password-based operations from automated guessing |
+| **Auth** | 10 / min | `/auth` | IP | Prevents token request flooding while allowing legitimate multi-agent setups |
+| **Transaction** | 30 / min | `/send`, `/swap`, `/fund`, `/launch` | Hashed token | Per-agent throttle; prevents a single agent from monopolizing chain operations |
+| **General** | 100 / min | All other endpoints | IP | Baseline DoS protection for informational endpoints |
+
+Rate limits are configurable via the defaults API (`PATCH /defaults`) and take effect immediately without restart (hot-reloadable).
+
+---
+
+## Database Security Model
+
+| Table | Encrypted? | What attacker gains from stolen DB |
+|-------|------------|-----------------------------------|
+| `AgentToken` | No | Token metadata (agentId, permissions, expiry) — but NOT the raw token or SIGNING_KEY. Cannot forge or replay tokens |
+| `HotWallet` | Yes (AES-256-GCM with cold mnemonic) | Ciphertext of private keys — cannot decrypt without the cold mnemonic (which is only in memory when unlocked) |
+| `HumanAction` | No | Pending/resolved action history — no secrets, no tokens |
+| `ApiKey` | No | Third-party API keys (Alchemy, Anthropic) — exposure risk, but cannot access wallet funds |
+| `Log` | No | Audit trail — addresses, amounts, timestamps. No private keys or tokens |
+| `Vault files` | Yes (AES-256-GCM with password-derived key) | Encrypted seed phrase — cannot decrypt without the vault password |
+
+**Key takeaway:** The database alone cannot forge auth tokens, decrypt hot wallet keys, or steal funds. The SIGNING_KEY (token forgery) and cold mnemonic (key decryption) exist only in server memory.
+
+---
+
+## Permission & Error Reference
+
+For the full permissions table, compound permission expansions, route→permission mapping, and error responses, see [AUTH.md](./AUTH.md).
+
+---
+
+## Temporary Action Tokens
+
+Apps can request per-operation human approval via `POST /actions`. On approval, a temporary scoped token is created with short TTL (default 60s).
+
+```
+App calls AuraApp.action({...})
+  → POST /actions (requires action:create permission)
+  → HumanAction created (type: 'action')
+  → Human approves via dashboard / Telegram / webhook
+  → Temp token created (short TTL, scoped permissions/limits)
+  → App polls GET /auth/:requestId?secret=... → receives temp token
+  → App uses temp token to call endpoint directly
+  → Token expires after TTL
+```
+
+### Security Properties
+
+| Property | Guarantee |
+|----------|-----------|
+| No privilege escalation | `admin:*` and `action:create` blocked in requested permissions |
+| Short TTL | Default 60 seconds — app must use token quickly |
+| Scoped permissions | Temp token only has the specific permissions requested |
+| Scoped limits | Spending limits enforced on the temp token |
+| Memory-only auth | Same SIGNING_KEY model — restart invalidates everything |
+| Human override | Approver can tighten limits/walletAccess before approval |
+| Single retrieval | Raw token held in memory escrow, claimed once on first poll (second poll returns 410). DB only stores tokenHash |
+
+---
+
+## Best Practices
+
+See [BEST-PRACTICES.md](./BEST-PRACTICES.md) for guidance on password management, spending limits, token hygiene (humans), permission scoping, error handling patterns (agents), and route auth patterns, security checklists (developers).

package/docs/specs/aura-open-protocol.md

@@ -0,0 +1,61 @@
+# Aura Open Protocol (.aura) v1
+
+## Scope
+Vendor-neutral `.aura` parsing + resolution contract.
+
+## Grammar (v1)
+- UTF-8, optional BOM ignored, CRLF normalized to LF.
+- Statements: blank, full-line comment (`#`), assignment (`KEY = VALUE`).
+- Key regex: `^[A-Z][A-Z0-9_]{0,127}$`.
+- Duplicate keys: `E_PARSE_DUPLICATE_KEY`.
+- Value forms:
+  - bare string
+  - quoted string (`\"`, `\\`, `\n`, `\r`, `\t`, `\uXXXX`)
+  - provider ref `${provider://resource?query}`
+  - var ref `${KEY}`
+- Inline trailing comments are not supported in v1.
+
+## Parse output contract
+`parse(text)` returns:
+- `version: "aura.v1"`
+- `nodes[]` with required `type` and `loc`
+- assignment nodes also include `keyRaw`, `keyNorm`, `valueType`, `valueRaw`, `valueNorm`
+
+## Validation + normalization contract
+`validate(doc)` returns deterministic lexical ordering by key:
+- `normalized.entries[]`
+- entry fields: `key`, `value`, `origin`, `dependencies`, optional `providerRef`
+
+## Resolver determinism
+- Fixed error precedence:
+  1) parse
+  2) validate
+  3) reference graph
+  4) provider resolution
+  5) merge/output policy
+- Bounded limits:
+  - max depth: 32 (`E_RESOLVE_DEPTH_EXCEEDED`)
+  - provider budget: 256 (`E_RESOLVE_PROVIDER_BUDGET`)
+  - default provider timeout: 5000ms
+
+## Compatibility matrix
+- Supported baseline: spec 1.x + parser 1.x + provider API 1.x
+- Unknown major spec: `E_COMPAT_SPEC_UNSUPPORTED`
+- Provider API major mismatch: `E_COMPAT_PROVIDER_API`
+
+## Trust/signature model (v1)
+- JCS canonicalization for signed payload.
+- Signature algorithm: `ed25519` only.
+- Required envelope fields:
+  - `algorithm`, `keyId`, `sig`, `createdAt`, `payloadSha256`
+
+## Error envelope
+All failures should expose:
+- `code`, `category`, `severity`, `message`, `retryable`
+- optional `details`, `loc`
+
+Code families:
+- `E_PARSE_*`, `E_VALIDATE_*`, `E_RESOLVE_*`, `E_POLICY_*`, `E_TRUST_*`, `E_COMPAT_*`
+
+## Canonical fixtures
+See `docs/specs/fixtures/` for v1 parse fixtures.