auramaxx 1.0.0-alpha.4

package/src/lib/crypto.ts

@@ -0,0 +1,112 @@
+/**
+ * Frontend Crypto Utilities
+ *
+ * RSA-OAEP encryption for secure password transport.
+ * Uses Web Crypto API for encryption with server's public key.
+ */
+
+import { getVaultPublicKeyBase64 } from './vault-crypto';
+
+/**
+ * Convert PEM-encoded public key to ArrayBuffer for Web Crypto API
+ */
+function pemToArrayBuffer(pem: string): ArrayBuffer {
+  // Remove PEM headers and newlines
+  const b64 = pem
+    .replace(/-----BEGIN PUBLIC KEY-----/, '')
+    .replace(/-----END PUBLIC KEY-----/, '')
+    .replace(/\s/g, '');
+
+  // Decode base64 to binary
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Encrypt a password using RSA-OAEP with the server's public key
+ *
+ * @param password - The plaintext password to encrypt
+ * @param pemPublicKey - PEM-encoded RSA public key from /auth/connect
+ * @returns Base64-encoded encrypted password
+ */
+export async function encryptPassword(
+  password: string,
+  pemPublicKey: string
+): Promise<string> {
+  // Import the PEM public key
+  const keyData = pemToArrayBuffer(pemPublicKey);
+  const publicKey = await crypto.subtle.importKey(
+    'spki',
+    keyData,
+    { name: 'RSA-OAEP', hash: 'SHA-256' },
+    false,
+    ['encrypt']
+  );
+
+  // Encrypt the password
+  const encoded = new TextEncoder().encode(password);
+  const encrypted = await crypto.subtle.encrypt(
+    { name: 'RSA-OAEP' },
+    publicKey,
+    encoded
+  );
+
+  // Convert to base64 for transport
+  const bytes = new Uint8Array(encrypted);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+let tokenMintPubkeyPromise: Promise<string> | null = null;
+
+/**
+ * Generate (or reuse) an in-memory RSA-OAEP public key for token mint requests.
+ *
+ * Private key persistence/decryption lifecycle is handled separately by vault UI
+ * code (TODO-029). This helper only provides the required pubkey.
+ */
+export async function getTokenMintPubkey(): Promise<string> {
+  // Prefer the vault keypair when available (UI unlock flow)
+  const vaultPubkey = getVaultPublicKeyBase64();
+  if (vaultPubkey) return vaultPubkey;
+
+  if (!tokenMintPubkeyPromise) {
+    tokenMintPubkeyPromise = (async () => {
+      const pair = await crypto.subtle.generateKey(
+        {
+          name: 'RSA-OAEP',
+          modulusLength: 2048,
+          publicExponent: new Uint8Array([1, 0, 1]),
+          hash: 'SHA-256',
+        },
+        true,
+        ['encrypt', 'decrypt'],
+      );
+      const spki = await crypto.subtle.exportKey('spki', pair.publicKey);
+      return arrayBufferToBase64(spki);
+    })();
+  }
+
+  try {
+    return await tokenMintPubkeyPromise;
+  } catch (error) {
+    tokenMintPubkeyPromise = null;
+    throw error;
+  }
+}

package/src/lib/db.ts

@@ -0,0 +1,21 @@
+import { PrismaClient } from '@prisma/client';
+import path from 'path';
+import os from 'os';
+
+// Resolve DATABASE_URL to ~/.aurawallet/aurawallet.db
+// Tests and explicit overrides are preserved
+const envUrl = process.env.DATABASE_URL;
+if (!envUrl || envUrl === 'file:./dev.db') {
+  const dbPath = path.join(os.homedir(), '.aurawallet', 'aurawallet.db');
+  process.env.DATABASE_URL = `file:${dbPath}`;
+}
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined;
+};
+
+export const prisma = globalForPrisma.prisma ?? new PrismaClient();
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma;
+}

package/src/lib/docs.ts

@@ -0,0 +1,390 @@
+import 'server-only';
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { marked } from 'marked';
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+
+const HTTP_METHODS = new Set<HttpMethod>(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD']);
+const DOCS_DIR = path.join(process.cwd(), 'docs');
+const ROOT_README = path.join(process.cwd(), 'README.md');
+const EXCLUDED_DOC_FILES = new Set(['API.md']);
+const ALWAYS_EXCLUDED_TOP_LEVEL_DIRS = new Set(['specs']);
+const TRUTHY_ENV = new Set(['1', 'true', 'yes', 'on']);
+const FALSY_ENV = new Set(['0', 'false', 'no', 'off']);
+
+const parseBooleanEnv = (value: string | undefined): boolean | null => {
+  if (!value) return null;
+  const normalized = value.trim().toLowerCase();
+  if (TRUTHY_ENV.has(normalized)) return true;
+  if (FALSY_ENV.has(normalized)) return false;
+  return null;
+};
+
+const shouldShowInternalDocs = (): boolean => {
+  const explicit = parseBooleanEnv(process.env.NEXT_PUBLIC_SHOW_INTERNAL_DOCS);
+  if (explicit !== null) return explicit;
+
+  // In hosted environments, NODE_ENV is "production" for preview/staging too.
+  // Prefer VERCEL_ENV when present so preview/dev deploys can still see internal docs.
+  const vercelEnv = process.env.VERCEL_ENV?.trim().toLowerCase();
+  if (vercelEnv) return vercelEnv !== 'production';
+
+  return process.env.NODE_ENV !== 'production';
+};
+
+const SHOW_INTERNAL_DOCS = shouldShowInternalDocs();
+
+/** README.md lives at repo root, not in docs/. Map it to a virtual entry. */
+const README_ENTRY = 'README.md';
+const README_SIDEBAR_TITLE = 'Getting Started';
+
+export interface DocFile {
+  filename: string;
+  title: string;
+  summary: string;
+}
+
+export interface DocGroup {
+  label: string;
+  docs: DocFile[];
+}
+
+/**
+ * Sidebar groupings for public docs. Internal docs are appended in dev only.
+ * Public docs not listed here are intentionally hidden until explicitly categorized.
+ */
+const DOC_CATEGORIES: { label: string; filenames: string[] }[] = [
+  { label: 'START HERE', filenames: ['README.md', 'JOBS.md', 'SETUP.md'] },
+  { label: 'CREDENTIAL VAULT', filenames: ['credentials.md', 'passkeys.md', 'totp.md', 'oauth2.md', 'aura-file.md'] },
+  { label: 'PLATFORM & SECURITY', filenames: ['ARCHITECTURE.md', 'security.md', 'AUTH.md', 'BEST-PRACTICES.md', 'WORKSPACE.md'] },
+  { label: 'APPS & TOOLS', filenames: ['APPS.md', 'DEVELOPING-APPS.md', 'EXTENSION.md', 'MCP.md', 'CLI.md', 'ADAPTERS.md', 'agent-auth.md', 'PROTOCOL.md'] },
+  { label: 'WALLET (LEGACY)', filenames: ['wallet/README.md', 'wallet/STRATEGY.md', 'wallet/DEVELOPING-STRATEGIES.md', 'wallet/AI.md'] },
+];
+
+export interface ApiEndpoint {
+  method: HttpMethod;
+  path: string;
+  section: string;
+  source: 'http-fence' | 'table' | 'inline';
+  permission?: string;
+  authentication?: string;
+}
+
+interface EndpointCandidate extends ApiEndpoint {
+  lineIndex: number;
+}
+
+const stripMarkdown = (value: string) => value.replace(/[`*_]/g, '').trim();
+
+const cleanPath = (value: string): string | null => {
+  const normalized = value.trim().replace(/^`|`$/g, '').replace(/[),.;]+$/, '');
+  if (!normalized.startsWith('/')) return null;
+  return normalized;
+};
+
+const parseSummary = (content: string): string => {
+  const lines = content.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) continue;
+    if (line.startsWith('```')) continue;
+    if (line.startsWith('|')) continue;
+    if (line === '---') continue;
+    return stripMarkdown(line);
+  }
+  return 'No summary available.';
+};
+
+const parseTitle = (filename: string, content: string): string => {
+  const headingMatch = content.match(/^#\s+(.+)$/m);
+  if (headingMatch) return stripMarkdown(headingMatch[1]);
+  return path.basename(filename).replace(/\.md$/i, '').toUpperCase();
+};
+
+const normalizeDocPath = (value: string): string =>
+  path.posix.normalize(value.replace(/\\/g, '/').replace(/^\/+/, ''));
+
+const isTopLevelDirExcluded = (topLevelDir?: string): boolean => {
+  if (!topLevelDir) return false;
+  if (ALWAYS_EXCLUDED_TOP_LEVEL_DIRS.has(topLevelDir)) return true;
+  if (!SHOW_INTERNAL_DOCS && topLevelDir === 'internal') return true;
+  return false;
+};
+
+const isExcludedDocPath = (docPath: string): boolean => {
+  const normalized = normalizeDocPath(docPath);
+  if (normalized === 'API.md') return true;
+  const [topLevel] = normalized.split('/');
+  if (isTopLevelDirExcluded(topLevel)) return true;
+  return false;
+};
+
+const collectPublicDocFiles = async (dirPath: string, prefix = ''): Promise<string[]> => {
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  const sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+  const collected: string[] = [];
+
+  for (const entry of sorted) {
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (!prefix && isTopLevelDirExcluded(entry.name)) continue;
+      collected.push(...await collectPublicDocFiles(path.join(dirPath, entry.name), relativePath));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (!entry.name.toLowerCase().endsWith('.md')) continue;
+    if (isExcludedDocPath(relativePath)) continue;
+    if (EXCLUDED_DOC_FILES.has(path.basename(relativePath))) continue;
+    collected.push(relativePath);
+  }
+
+  return collected;
+};
+
+const parseEndpointMeta = (lines: string[], lineIndex: number): Pick<ApiEndpoint, 'permission' | 'authentication'> => {
+  const lookahead = lines.slice(lineIndex + 1, lineIndex + 10).join('\n');
+  const permissionMatch = lookahead.match(/Permission:\s*`([^`]+)`/i);
+  const authenticationMatch = lookahead.match(/Authentication:\s*([^\n]+)/i);
+  const publicMatch = lookahead.match(/no authentication required/i);
+
+  return {
+    permission: permissionMatch ? stripMarkdown(permissionMatch[1]) : undefined,
+    authentication: publicMatch
+      ? 'Public (no auth)'
+      : authenticationMatch
+        ? stripMarkdown(authenticationMatch[1])
+        : undefined,
+  };
+};
+
+const maybePushCandidate = (
+  candidates: EndpointCandidate[],
+  params: Omit<EndpointCandidate, 'permission' | 'authentication'>,
+  lines: string[],
+) => {
+  const pathValue = cleanPath(params.path);
+  if (!pathValue) return;
+  if (!HTTP_METHODS.has(params.method)) return;
+  const meta = parseEndpointMeta(lines, params.lineIndex);
+  candidates.push({ ...params, path: pathValue, ...meta });
+};
+
+export const listDocFiles = async (): Promise<DocFile[]> => {
+  const markdownFiles = (await collectPublicDocFiles(DOCS_DIR))
+    .sort((a, b) => {
+      const order: Record<string, number> = { 'SETUP.md': 0, 'wallet/README.md': 1 };
+      const aPriority = order[a] ?? 999;
+      const bPriority = order[b] ?? 999;
+      if (aPriority !== bPriority) return aPriority - bPriority;
+      return a.localeCompare(b);
+    });
+
+  // Root README.md goes first as "Getting Started"
+  const readmeContent = await fs.readFile(ROOT_README, 'utf8').catch(() => '');
+  const readmeEntry: DocFile = {
+    filename: README_ENTRY,
+    title: README_SIDEBAR_TITLE,
+    summary: readmeContent ? parseSummary(readmeContent) : 'Getting started with AuraWallet.',
+  };
+
+  const docs = await Promise.all(
+    markdownFiles.map(async (filename) => {
+      const fullPath = path.join(DOCS_DIR, filename);
+      const content = await fs.readFile(fullPath, 'utf8');
+      return {
+        filename,
+        title: parseTitle(filename, content),
+        summary: parseSummary(content),
+      };
+    }),
+  );
+
+  return [readmeEntry, ...docs];
+};
+
+export const listDocGroups = async (): Promise<DocGroup[]> => {
+  const allDocs = await listDocFiles();
+  const docMap = new Map(allDocs.map((doc) => [doc.filename, doc]));
+
+  const groups: DocGroup[] = DOC_CATEGORIES.map(({ label, filenames }) => ({
+    label,
+    docs: filenames
+      .filter((f) => docMap.has(f))
+      .map((f) => docMap.get(f)!),
+  })).filter((g) => g.docs.length > 0);
+
+  if (SHOW_INTERNAL_DOCS) {
+    const internalDocs = allDocs
+      .filter((doc) => doc.filename.startsWith('internal/'))
+      .sort((a, b) => a.filename.localeCompare(b.filename));
+    if (internalDocs.length > 0) {
+      groups.push({ label: 'INTERNAL (DEV ONLY)', docs: internalDocs });
+    }
+  }
+
+  return groups;
+};
+
+export const readDocFile = async (filename: string): Promise<string> => {
+  const normalized = normalizeDocPath(filename);
+  if (!normalized.toLowerCase().endsWith('.md')) {
+    throw new Error(`Invalid doc file: ${filename}`);
+  }
+  // Root README.md is served from repo root, not docs/
+  if (normalized === README_ENTRY) {
+    return fs.readFile(ROOT_README, 'utf8');
+  }
+  if (normalized === 'API.md') {
+    return fs.readFile(path.join(DOCS_DIR, 'API.md'), 'utf8');
+  }
+  if (normalized.startsWith('../') || normalized === '..') {
+    throw new Error('Path traversal attempt blocked');
+  }
+  if (isExcludedDocPath(normalized)) {
+    throw new Error(`Doc is excluded from /docs: ${filename}`);
+  }
+  const fullPath = path.join(DOCS_DIR, normalized);
+  if (!fullPath.startsWith(DOCS_DIR)) {
+    throw new Error('Path traversal attempt blocked');
+  }
+  return fs.readFile(fullPath, 'utf8');
+};
+
+export const parseApiEndpoints = (content: string): ApiEndpoint[] => {
+  const lines = content.split(/\r?\n/);
+  let currentH2 = 'General';
+  let currentH3 = '';
+  let inCodeBlock = false;
+  let codeFenceLang = '';
+  const candidates: EndpointCandidate[] = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trim = line.trim();
+
+    if (trim.startsWith('```')) {
+      if (!inCodeBlock) {
+        inCodeBlock = true;
+        codeFenceLang = trim.slice(3).trim().toLowerCase();
+      } else {
+        inCodeBlock = false;
+        codeFenceLang = '';
+      }
+      continue;
+    }
+
+    if (!inCodeBlock) {
+      const h2Match = trim.match(/^##\s+(.+)$/);
+      if (h2Match) {
+        currentH2 = stripMarkdown(h2Match[1]);
+        currentH3 = '';
+        continue;
+      }
+      const h3Match = trim.match(/^###\s+(.+)$/);
+      if (h3Match) {
+        currentH3 = stripMarkdown(h3Match[1]);
+        continue;
+      }
+    }
+
+    const section = currentH3 ? `${currentH2} / ${currentH3}` : currentH2;
+
+    if (inCodeBlock && ['', 'http', 'bash', 'sh', 'shell', 'text'].includes(codeFenceLang)) {
+      const methodPath = trim.match(/^(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+(`?)(\/[^\s`]+)\2$/i);
+      if (methodPath) {
+        maybePushCandidate(
+          candidates,
+          {
+            method: methodPath[1].toUpperCase() as HttpMethod,
+            path: methodPath[3],
+            section,
+            source: 'http-fence',
+            lineIndex: index,
+          },
+          lines,
+        );
+      }
+    }
+
+    if (!inCodeBlock && trim.startsWith('|')) {
+      const columns = trim.split('|').map((value) => value.trim());
+      if (columns.length >= 4) {
+        const methodCell = columns[1].toUpperCase();
+        const pathCell = columns[2];
+        if (HTTP_METHODS.has(methodCell as HttpMethod)) {
+          maybePushCandidate(
+            candidates,
+            {
+              method: methodCell as HttpMethod,
+              path: pathCell,
+              section,
+              source: 'table',
+              lineIndex: index,
+            },
+            lines,
+          );
+        }
+      }
+    }
+
+    if (!inCodeBlock) {
+      for (const match of trim.matchAll(/\b(GET|POST|PUT|PATCH|DELETE|OPTIONS|HEAD)\s+`?(\/[A-Za-z0-9:._?=&/%\-]+)`?/gi)) {
+        maybePushCandidate(
+          candidates,
+          {
+            method: match[1].toUpperCase() as HttpMethod,
+            path: match[2],
+            section,
+            source: 'inline',
+            lineIndex: index,
+          },
+          lines,
+        );
+      }
+    }
+  }
+
+  const deduped = new Map<string, ApiEndpoint>();
+  for (const candidate of candidates) {
+    const key = `${candidate.method} ${candidate.path}`;
+    const existing = deduped.get(key);
+    if (!existing) {
+      const endpoint: ApiEndpoint = {
+        method: candidate.method,
+        path: candidate.path,
+        section: candidate.section,
+        source: candidate.source,
+        permission: candidate.permission,
+        authentication: candidate.authentication,
+      };
+      deduped.set(key, endpoint);
+      continue;
+    }
+    if (!existing.permission && candidate.permission) existing.permission = candidate.permission;
+    if (!existing.authentication && candidate.authentication) existing.authentication = candidate.authentication;
+    if (existing.section === 'General' && candidate.section !== 'General') existing.section = candidate.section;
+  }
+
+  return [...deduped.values()].sort((a, b) => {
+    const sectionCompare = a.section.localeCompare(b.section);
+    if (sectionCompare !== 0) return sectionCompare;
+    const pathCompare = a.path.localeCompare(b.path);
+    if (pathCompare !== 0) return pathCompare;
+    return a.method.localeCompare(b.method);
+  });
+};
+
+export const slugify = (text: string): string =>
+  text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+
+export const renderMarkdown = (content: string): string => {
+  const renderer = new marked.Renderer();
+  renderer.heading = ({ text, depth }) => {
+    const id = slugify(text.replace(/<[^>]*>/g, ''));
+    return `<h${depth} id="${id}">${text}</h${depth}>`;
+  };
+  return marked.parse(content, { async: false, renderer }) as string;
+};