auramaxx 1.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2025 Aura Industry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The name "AuraWallet" and the AuraWallet logo are trademarks of Aura Industry
+and may not be used in derivative works without prior written permission.

package/README.md

@@ -0,0 +1,112 @@
+# AuraWallet
+
+AuraWallet is a local password manager and credential vault for humans and AI agents.
+
+It lets you store API keys, passwords, TOTP secrets, passkeys, and OAuth2 credentials in one place, then give agents scoped access without exposing long-lived plaintext secrets.
+
+## Why this matters
+
+- **Agent-safe secret access:** agents read encrypted payloads tied to their `pubkey`
+- **Scoped permissions:** tokens can be limited by capability and credential scope
+- **Local-first:** server runs on your machine (`localhost`), no hosted vault required
+- **Works in real workflows:** CLI, MCP, `.aura` project mapping, shell hooks, and browser extension
+
+## 10-minute quickstart
+
+```bash
+# 1) Install + initialize
+npx aurawallet init
+
+# 2) Start later sessions
+npx aurawallet start
+
+# 3) Check status
+npx aurawallet status
+```
+
+Then open the dashboard at `http://localhost:4747/app` and create your vault.
+
+### Add your first credential
+
+Use the dashboard, or call the API directly once you have a token:
+
+```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}
+    ],
+    "meta": {"tags":["prod","openai"]}
+  }'
+```
+
+### Read with CLI
+
+```bash
+# list
+npx aurawallet vault list
+
+# read one field (raw stdout)
+npx aurawallet vault get openai-prod --field api_key
+```
+
+### Load project env from vault (`.aura`)
+
+```bash
+# create mapping from existing .env
+npx aurawallet env init --from .env
+
+# run with vault-injected env vars
+npx aurawallet env -- npm run dev
+```
+
+### Connect an MCP client
+
+```bash
+# start MCP server over stdio
+npx aurawallet mcp
+
+# or auto-install configs for supported IDEs
+npx aurawallet mcp --install
+```
+
+## Practical examples
+
+- “Get `DATABASE_URL` from vault and run migrations.”
+- “Return only the current TOTP code for `github-admin`.”
+- “Use OAuth2 credential `google-workspace`; refresh access token if expired.”
+- “Load all secrets for this repo from `.aura`, not `.env`.”
+- “Request temporary permission upgrade instead of using broad token scope.”
+
+## Docs by job
+
+- [Start here: job-based runbooks](./docs/JOBS.md)
+
+## Core docs
+
+- [Credentials model](./docs/credentials.md)
+- [CLI guide](./docs/CLI.md)
+- [MCP guide](./docs/MCP.md)
+- [Agent auth model](./docs/agent-auth.md)
+- [Passkeys](./docs/passkeys.md)
+- [TOTP](./docs/totp.md)
+- [OAuth2 credential refresh](./docs/oauth2.md)
+- [`.aura` file format](./docs/aura-file.md)
+- [Wallet and trading docs](./docs/wallet/README.md)
+
+## Limits / current behavior
+
+- OAuth2 re-auth endpoint exists but full redirect-based re-auth flow is still TODO.
+- Passkey unlock still depends on server unlock state after restart (`vault_locked` until unlocked).
+- Credential files are local JSON under Aura data directory; secure your machine and backups.
+
+---
+
+Wallet server: `http://localhost:4242`  
+Dashboard: `http://localhost:4747/app`  
+WebSocket: `ws://localhost:4748`

package/bin/aurawallet.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/**
+ * AuraWallet CLI entry point
+ *
+ * Routes subcommands to server/cli/commands/<cmd>.ts via tsx.
+ * Works with: npx auramaxx <command> [args]
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const cmd = process.argv[2];
+const args = process.argv.slice(3);
+
+const COMMANDS = {
+  init: 'Full interactive first-time setup',
+  start: 'Start wallet servers (--headless for no dashboard)',
+  stop: 'Stop running servers',
+  status: 'Show server and wallet status',
+  doctor: 'Run deterministic onboarding/runtime diagnostics',
+  unlock: 'Unlock the vault interactively',
+  restore: 'Restore from a backup (--list, --latest, --dry-run)',
+  app: 'Manage installed apps (install, remove, list, update)',
+  mcp: 'Start MCP server (stdio) for Claude Code, Cursor, etc.',
+  cron: 'Run the cron server standalone (balance sync, price sync)',
+  vault: 'Retrieve credentials from the vault (get, list)',
+  token: 'Preview profile-based token policy before issuance',
+  env: 'Load env vars from vault via .aura file (run, inject, check, list, init)',
+  'shell-hook': 'Auto-load .aura env vars on cd (like direnv)',
+};
+
+function showHelp() {
+  // Inline Tyvek theme (bin/ is plain CJS — cannot import TS theme module)
+  const isTTY = process.stdout.isTTY && !process.env.NO_COLOR && process.env.CI !== 'true' && process.env.TERM !== 'dumb';
+  const RST = isTTY ? '\x1b[0m' : '';
+  const BOLD = isTTY ? '\x1b[1m' : '';
+  const DIM = isTTY ? '\x1b[2m' : '';
+  const CYAN = isTTY ? '\x1b[36m' : '';
+  const GRAY = isTTY ? '\x1b[90m' : '';
+
+  const W = 62;
+  const TL = `${GRAY}.-${RST}`;
+  const TR = `${GRAY}-.${RST}`;
+  const BL = `${GRAY}'-${RST}`;
+  const BR = `${GRAY}-'${RST}`;
+  const PIPE = `${GRAY}|${RST}`;
+  const SEP = '  ' + '- '.repeat(Math.floor(W / 2));
+
+  // Banner — three diagonal stripes in a square (aura_logo.svg)
+  const LP = `${GRAY}|${RST}`;
+  const LT = `${GRAY}.${RST}${DIM}----------${RST}${GRAY}.${RST}`;
+  const LB = `${GRAY}'${RST}${DIM}----------${RST}${GRAY}'${RST}`;
+
+  console.log('');
+  console.log(`  ${TL}${DIM}${' '.repeat(W - 4)}${RST}${TR}`);
+  console.log(`  ${PIPE}   ${LT}${' '.repeat(W - 19)}${PIPE}`);
+  console.log(`  ${PIPE}   ${LP}${BOLD}//${RST}  ${BOLD}//${RST}  ${BOLD}//${RST}${LP}    ${BOLD}A U R A${RST}${' '.repeat(W - 30)}${PIPE}`);
+  console.log(`  ${PIPE}   ${LP} ${BOLD}//${RST}  ${BOLD}//${RST}  ${BOLD}/${RST}${LP}    ${DIM}W A L L E T${RST}${' '.repeat(W - 34)}${PIPE}`);
+  console.log(`  ${PIPE}   ${LP}  ${BOLD}//${RST}  ${BOLD}//${RST}  ${LP}    ${CYAN}COMMAND REFERENCE${RST}${' '.repeat(W - 40)}${PIPE}`);
+  console.log(`  ${PIPE}   ${LB}${' '.repeat(W - 19)}${PIPE}`);
+  console.log(`  ${BL}${DIM}${' '.repeat(W - 4)}${RST}${BR}`);
+  console.log('');
+
+  console.log(`  ${BOLD}Usage:${RST} npx auramaxx <command> [options]`);
+  console.log(`  ${DIM}Alias:${RST} npx aurawallet <command>`);
+  console.log('');
+  console.log(SEP);
+  console.log(`  ${BOLD}[ COMMANDS ]${RST}`);
+  console.log('');
+
+  for (const [name, desc] of Object.entries(COMMANDS)) {
+    console.log(`    ${CYAN}${name.padEnd(14)}${RST}${desc}`);
+  }
+
+  console.log('');
+  console.log(SEP);
+  console.log(`  ${BOLD}[ OPTIONS ]${RST}`);
+  console.log('');
+  console.log(`    ${CYAN}${'--help'.padEnd(14)}${RST}Show this help message`);
+  console.log('');
+  console.log(SEP);
+  console.log(`  ${BOLD}[ EXAMPLES ]${RST}`);
+  console.log('');
+  console.log(`    npx auramaxx init                ${DIM}# Set up wallet for the first time${RST}`);
+  console.log(`    npx auramaxx start               ${DIM}# Start all services${RST}`);
+  console.log(`    npx auramaxx start --headless    ${DIM}# Start server only (no dashboard)${RST}`);
+  console.log(`    npx auramaxx status              ${DIM}# Check if wallet is running${RST}`);
+  console.log(`    npx auramaxx unlock              ${DIM}# Unlock the vault${RST}`);
+  console.log(`    npx auramaxx token preview       ${DIM}# Preview token policy${RST}`);
+  console.log(`    npx auramaxx stop                ${DIM}# Stop all services${RST}`);
+  console.log('');
+}
+
+if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  showHelp();
+  process.exit(0);
+}
+
+if (!COMMANDS[cmd]) {
+  console.error(`Unknown command: ${cmd}\n`);
+  console.error(`Run 'npx auramaxx --help' to see available commands.`);
+  process.exit(1);
+}
+
+const commandFile = path.join(root, 'server', 'cli', 'commands', `${cmd}.ts`);
+const useNodeTsxLoader = process.env.SANDBOX_MODE === 'true' || process.env.AURA_FORCE_NODE_TSX === '1';
+const runner = useNodeTsxLoader
+  ? { command: process.execPath, args: ['--import', 'tsx', commandFile, ...args] }
+  : { command: 'npx', args: ['tsx', commandFile, ...args] };
+
+try {
+  execFileSync(runner.command, runner.args, {
+    cwd: root,
+    stdio: 'inherit',
+    env: process.env,
+  });
+} catch (error) {
+  // tsx already printed the error, just exit with its code
+  process.exit(error.status || 1);
+}