auramaxx 1.0.0-alpha.4

package/skills/aurawallet-setup/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: aurawallet-setup
+description: |
+  Setup-only AuraWallet skill for MCP agents. Use this when the user needs onboarding,
+  vault initialization, unlock, and first scoped API key issuance.
+compatibility: Requires Node.js 18+ and local AuraWallet server/dashboard.
+allowed-tools: Bash(npx aurawallet *), Bash(curl *), MCP(create_vault,wallet_api,request_human_action)
+metadata:
+  author: auramaxx
+  version: "1.0"
+---
+
+# AuraWallet Setup Skill (MCP)
+
+Use this skill when the user asks to get started, onboard, initialize, unlock, or bootstrap agent access.
+
+## Install
+
+```bash
+TMP_SKILL_DIR="$(mktemp -d /tmp/aurawallet-setup-skill-XXXXXX)"
+cp -R ./skills/aurawallet-setup "$TMP_SKILL_DIR/"
+npx -y skills add "$TMP_SKILL_DIR/aurawallet-setup" --yes
+```
+
+If the skill is already pushed to GitHub, you can install by ref:
+
+```bash
+python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
+  --repo Aura-Industry/aurawallet \
+  --path skills/aurawallet-setup \
+  --ref <branch-or-commit>
+```
+
+## Agent Prompt
+
+Example user prompt:
+
+`Use the AuraWallet setup skill and onboard me via MCP.`
+
+## Setup Flow
+
+1. Check service health:
+
+```text
+wallet_api GET /health
+wallet_api GET /setup
+```
+
+2. If wallet is missing:
+- Human-assisted: `npx aurawallet init --dashboard`
+- Autonomous: `create_vault` with a generated password
+
+3. If wallet exists but locked:
+- Prefer dashboard unlock (`http://localhost:4747/app`)
+- Fallback: `npx aurawallet unlock`
+
+4. Bootstrap an agent token:
+- Request token with least privilege first:
+  - `secret:read`
+  - `secret:write`
+- Use `request_human_action` if approval is needed.
+
+5. Validate setup complete:
+
+```text
+wallet_api GET /setup
+```
+
+## Done Criteria
+
+- `hasWallet=true`
+- `unlocked=true`
+- agent has an active scoped token
+- user gets a short summary of what was configured and what remains optional

package/skills/security-review/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: security-review
+description: |
+  Security review checklist for AuraWallet Express server changes.
+  Use when: modifying server/routes/*.ts, adding new endpoints,
+  changing authentication logic, or updating permissions.
+  Also use after completing any task that touches the wallet server.
+---
+
+# Security Review Checklist
+
+Use this checklist when modifying the Express wallet server.
+
+## Before Completing Any Task
+
+1. **All tests pass** - Run `npm test` and ensure all tests pass
+2. **Documentation updated** - See checklist below
+
+## Documentation Checklist
+
+Update the relevant docs when making changes:
+
+| Change Type | Update |
+|-------------|--------|
+| New/modified endpoint | `docs/API.md` - add endpoint spec |
+| New/modified permission | `docs/AUTH.md` - update permission matrix |
+| New route with auth | `docs/AUTH.md` - add to route→permission table |
+| WebSocket event changes | `docs/WORKSPACE.md` - update event reference |
+| Security model changes | `docs/security.md` - update architecture |
+| New wallet tier/feature | `CLAUDE.md` - update overview |
+
+## Security Architecture Requirements
+
+- [ ] Auth decisions use memory only (not database)
+- [ ] Permissions are properly checked via `requirePermission` middleware
+- [ ] Wallet ownership is enforced (token can only access owned wallets)
+- [ ] Cold wallet operations require human approval (unlocked wallet)
+- [ ] No spending limit bypass (fund endpoint enforces limits)
+
+## Route Permission Checklist
+
+When adding a new endpoint:
+
+1. Add permission to `server/lib/permissions.ts` if needed
+2. Add `requirePermission('permission:name')` middleware
+3. Add endpoint spec to `docs/API.md`
+4. Add route to permission matrix in `docs/AUTH.md`
+5. If permission should be in `trade:all` or `wallet:write`, update compound expansion in `server/lib/permissions.ts`
+
+## Key Files to Review
+
+- `server/lib/auth.ts` - Token signing/validation (SIGNING_KEY)
+- `server/lib/sessions.ts` - Spending limit tracking (memory Map)
+- `server/lib/permissions.ts` - Permission definitions + compound expansion
+- `server/middleware/auth.ts` - Auth middleware (signature, expiry, revocation, permissions)
+
+## Common Security Mistakes
+
+- Using database for auth decisions (must use memory)
+- Forgetting wallet ownership check on wallet operations
+- Not updating AUTH.md permission matrix
+- Skipping tests for auth edge cases
+- Not checking if new permission belongs in `trade:all` compound
+
+## Security Model Summary
+
+```
+IN MEMORY (security-critical):          IN DATABASE (UI/logs only):
+├── SIGNING_KEY (random 32 bytes)       ├── AgentToken table
+├── sessions Map (spending tracking)     │   ├── tokenHash (for display)
+└── revokedTokens Set                    │   ├── agentId, limit, spent
+                                         │   └── isRevoked, expiresAt
+```
+
+**Key principle**: Auth decisions use ONLY memory. DB is just for display.
+
+## Token Validation Checklist
+
+When working with token validation:
+
+- [ ] Token signature verified with SIGNING_KEY
+- [ ] Token expiry checked
+- [ ] Token revocation checked against revokedTokens Set
+- [ ] Permissions expanded (compound → individual)
+- [ ] Required permission checked
+
+## Wallet Access Checklist
+
+When working with wallet operations:
+
+- [ ] Token ownership verified (tokenHash matches wallet.tokenHash)
+- [ ] OR wallet in token's walletAccess array
+- [ ] Ownership checked BEFORE executing the operation
+- [ ] Cold wallet requires unlocked state for operations
+- [ ] Hot wallet keys encrypted with mnemonic
+
+## Spending Limit Checklist
+
+When working with spending endpoints (`/fund`, `/send`, `/swap`):
+
+- [ ] Limit embedded in token (tamper-proof)
+- [ ] Spending tracked in memory sessions Map
+- [ ] Amount checked against remaining limit
+- [ ] Spent amount updated after successful transfer
+- [ ] Send/swap limits are optional (can be null/undefined)
+- [ ] Sends to cold wallet address bypass send limit (returning funds)
+- [ ] Admin tokens bypass all limits
+
+## What Restart Does
+
+1. New SIGNING_KEY generated → 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.**
+
+## Quick Reference: Route → Permission
+
+| Route | Permission |
+|-------|------------|
+| `GET /wallets` | `wallet:list` |
+| `POST /wallet/create` | `wallet:create:hot` or `wallet:create:temp` |
+| `POST /wallet/rename` | `wallet:rename` |
+| `POST /send` | `send:hot` or `send:temp` |
+| `POST /swap` | `swap` |
+| `POST /fund` | `fund` |
+| `POST /launch` | `launch` |
+| `POST /actions` | `action:create` |
+| `GET /apikeys` | `apikey:get` |
+| `POST /apikeys` | `apikey:set` |
+| `DELETE /apikeys/:id` | `apikey:set` |
+| `GET /strategies*` | `strategy:read` |
+| `POST /strategies/*` | `strategy:manage` |
+| App storage endpoints | `app:storage` |
+| `POST /apps/:id/message` | `app:accesskey` |
+| WebSocket mutations | `workspace:modify` |
+| `GET /adapters` | `adapter:manage` |
+| `POST /adapters` | `adapter:manage` |
+| `/actions/resolve`, `/lock`, `/nuke` | `admin:*` |
+
+## Compound Permissions
+
+| Compound | Expands To |
+|----------|-----------|
+| `trade:all` | `wallet:list`, `wallet:create:hot`, `wallet:create:temp`, `send:hot`, `send:temp`, `swap`, `fund`, `launch`, `apikey:get`, `strategy:read` |
+| `wallet:write` | `wallet:create:hot`, `wallet:create:temp`, `wallet:rename`, `wallet:tx:add`, `wallet:asset:add`, `wallet:asset:remove` |

package/src/app/api/agent-requests/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from 'next/server';
+
+const EXPRESS_URL = process.env.WALLET_SERVER_URL || 'http://localhost:4242';
+
+/**
+ * GET /api/agent-requests
+ * Proxy to Express /dashboard endpoint for agent actions and tokens
+ * No authentication required - returns pending actions and tokens
+ */
+export async function GET() {
+  try {
+    const response = await fetch(`${EXPRESS_URL}/dashboard`);
+    const data = await response.json();
+
+    if (!response.ok) {
+      return NextResponse.json(
+        { success: false, error: data.error || 'Failed to fetch agent requests' },
+        { status: response.status }
+      );
+    }
+
+    return NextResponse.json(data);
+  } catch (error) {
+    console.error('[AgentDashboard] Error fetching from Express:', error);
+    return NextResponse.json(
+      { success: false, error: 'Failed to fetch agent requests' },
+      { status: 500 }
+    );
+  }
+}

package/src/app/api/apps/install/route.ts

@@ -0,0 +1,126 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { installApp, removeApp } from '../../../../../server/lib/app-installer';
+
+const WALLET_API = process.env.WALLET_SERVER_URL || 'http://localhost:4242';
+
+/**
+ * Validate admin access by forwarding the Authorization header to Express.
+ * Returns true if the token is valid and has admin permissions.
+ */
+async function validateAdmin(authHeader: string | null): Promise<boolean> {
+  if (!authHeader) return false;
+
+  try {
+    // Use a lightweight endpoint to verify the token is valid + admin
+    const resp = await fetch(`${WALLET_API}/setup`, {
+      headers: { Authorization: authHeader },
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * POST /api/apps/install — Install a app from a source
+ * Body: { source: string, name?: string, force?: boolean }
+ */
+export async function POST(req: NextRequest) {
+  const authHeader = req.headers.get('authorization');
+  const isAdmin = await validateAdmin(authHeader);
+  if (!isAdmin) {
+    return NextResponse.json(
+      { success: false, error: 'Admin access required' },
+      { status: 403 },
+    );
+  }
+
+  try {
+    const body = await req.json();
+    const { source, name, force } = body;
+
+    if (!source || typeof source !== 'string') {
+      return NextResponse.json(
+        { success: false, error: 'source is required' },
+        { status: 400 },
+      );
+    }
+
+    const result = installApp(source, { name, force });
+
+    // Hot-reload: create token for the new app without restart
+    try {
+      await fetch(`${WALLET_API}/apps/${result.id}/reload`, {
+        method: 'POST',
+        headers: {
+          Authorization: authHeader!,
+          'Content-Type': 'application/json',
+        },
+      });
+    } catch {
+      // Non-critical — app will get a token on next server restart
+    }
+
+    return NextResponse.json({
+      success: true,
+      app: {
+        id: result.id,
+        name: result.name,
+        source: result.source,
+      },
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Install failed';
+    return NextResponse.json(
+      { success: false, error: message },
+      { status: 400 },
+    );
+  }
+}
+
+/**
+ * DELETE /api/apps/install — Remove an installed app
+ * Body: { appId: string }
+ */
+export async function DELETE(req: NextRequest) {
+  const authHeader = req.headers.get('authorization');
+  const isAdmin = await validateAdmin(authHeader);
+  if (!isAdmin) {
+    return NextResponse.json(
+      { success: false, error: 'Admin access required' },
+      { status: 403 },
+    );
+  }
+
+  try {
+    const body = await req.json();
+    const { appId } = body;
+
+    if (!appId || typeof appId !== 'string') {
+      return NextResponse.json(
+        { success: false, error: 'appId is required' },
+        { status: 400 },
+      );
+    }
+
+    // Revoke the app's token via Express (separate process, holds token in memory)
+    try {
+      await fetch(`${WALLET_API}/apps/${appId}/approve`, {
+        method: 'DELETE',
+        headers: { Authorization: authHeader! },
+      });
+    } catch {
+      // Non-critical if Express is down — token expires in 24h max
+    }
+
+    removeApp(appId);
+
+    return NextResponse.json({ success: true, appId, removed: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Remove failed';
+    return NextResponse.json(
+      { success: false, error: message },
+      { status: 400 },
+    );
+  }
+}

package/src/app/api/apps/manifests/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from 'next/server';
+import { loadAppManifests } from '@/lib/app-loader';
+
+// GET /api/apps/manifests - Return all loaded app manifests
+export async function GET() {
+  try {
+    const manifests = loadAppManifests();
+    return NextResponse.json({ success: true, manifests });
+  } catch (error) {
+    console.error('Failed to load app manifests:', error);
+    return NextResponse.json(
+      { success: false, error: 'Failed to load app manifests' },
+      { status: 500 }
+    );
+  }
+}

package/src/app/api/apps/static/[...path]/route.ts

@@ -0,0 +1,57 @@
+import { NextRequest, NextResponse } from 'next/server';
+import fs from 'fs';
+import path from 'path';
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.svg': 'image/svg+xml',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+};
+
+// GET /api/apps/static/[...path] - Serve static files from apps/ directory
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> }
+) {
+  try {
+    const { path: segments } = await params;
+    const relativePath = segments.join('/');
+
+    // Security: prevent path traversal
+    if (relativePath.includes('..') || relativePath.includes('\0')) {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+
+    const appsDir = path.join(process.cwd(), 'apps');
+    const filePath = path.join(appsDir, relativePath);
+
+    // Ensure resolved path is within apps/
+    const resolved = path.resolve(filePath);
+    if (!resolved.startsWith(path.resolve(appsDir))) {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+
+    if (!fs.existsSync(filePath) || fs.statSync(filePath).isDirectory()) {
+      return NextResponse.json({ error: 'Not found' }, { status: 404 });
+    }
+
+    const ext = path.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+    const content = fs.readFileSync(filePath);
+
+    return new NextResponse(content, {
+      headers: { 'Content-Type': contentType },
+    });
+  } catch (error) {
+    console.error('Failed to serve app static file:', error);
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+}

package/src/app/api/events/route.ts

@@ -0,0 +1,92 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { broadcast } from '@/lib/websocket-server';
+import { prisma } from '@/lib/db';
+import type { WalletEvent } from '@/lib/events';
+
+/**
+ * GET /api/events
+ * Query events from database with optional filtering
+ * No authentication required
+ */
+export async function GET(request: NextRequest) {
+  try {
+    const { searchParams } = new URL(request.url);
+    const type = searchParams.get('type');
+    const category = searchParams.get('category');
+    const limit = Math.min(parseInt(searchParams.get('limit') || '50'), 250);
+    const offset = parseInt(searchParams.get('offset') || '0');
+
+    // Build where clause
+    const where: Record<string, unknown> = {};
+    if (type) {
+      where.type = type;
+    } else if (category) {
+      where.type = { startsWith: `${category}:` };
+    }
+
+    // Query events
+    const [events, total] = await Promise.all([
+      prisma.event.findMany({
+        where,
+        orderBy: { timestamp: 'desc' },
+        take: limit,
+        skip: offset,
+      }),
+      prisma.event.count({ where }),
+    ]);
+
+    return NextResponse.json({
+      success: true,
+      events: events.map((e: any) => ({
+        ...e,
+        data: typeof e.data === 'string' ? JSON.parse(e.data) : e.data,
+      })),
+      pagination: {
+        total,
+        limit,
+        offset,
+        hasMore: offset + events.length < total,
+      },
+    });
+  } catch (error) {
+    console.error('[Events] Error fetching events:', error);
+    return NextResponse.json(
+      { success: false, error: 'Failed to fetch events' },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * POST /api/events
+ * Webhook endpoint to receive events from Express server
+ * and broadcast them to WebSocket clients
+ */
+export async function POST(request: NextRequest) {
+  try {
+    const event: WalletEvent = await request.json();
+
+    // Validate event structure
+    if (!event.type || !event.timestamp || !event.data) {
+      return NextResponse.json(
+        { error: 'Invalid event structure' },
+        { status: 400 }
+      );
+    }
+
+    // Broadcast to all connected WebSocket clients
+    broadcast(event);
+
+    return NextResponse.json({
+      success: true,
+      type: event.type,
+      clientsNotified: true,
+    });
+  } catch (error) {
+    console.error('[Events] Error processing webhook:', error);
+    return NextResponse.json(
+      { error: 'Failed to process event' },
+      { status: 500 }
+    );
+  }
+}