auramaxx 0.0.1

package/server/cli/lib/credential-create.ts

@@ -0,0 +1,74 @@
+/**
+ * CLI helper for creating credentials via the server API.
+ */
+
+import { serverUrl } from './http';
+
+interface CreateCredentialOpts {
+  token: string;
+  vaultId: string;
+  name: string;
+  type?: string;
+  fields: Array<{ key: string; value: string }>;
+}
+
+interface CreateResult {
+  success: boolean;
+  credential?: { id: string; name: string };
+  error?: string;
+}
+
+/**
+ * Create a credential via POST /credentials.
+ * Fields are sent as sensitiveFields (server encrypts them).
+ */
+export async function createCredentialViaApi(opts: CreateCredentialOpts): Promise<CreateResult> {
+  const base = serverUrl();
+  const body = {
+    vaultId: opts.vaultId,
+    type: opts.type || 'api',
+    name: opts.name,
+    sensitiveFields: opts.fields.map(f => ({
+      key: f.key,
+      value: f.value,
+      sensitive: true,
+    })),
+  };
+
+  const res = await fetch(`${base}/credentials`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${opts.token}`,
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(10000),
+  });
+
+  const data = await res.json() as CreateResult;
+  if (!res.ok) {
+    return { success: false, error: data.error || `HTTP ${res.status}` };
+  }
+  return data;
+}
+
+/**
+ * Get the primary vault ID.
+ */
+export async function getPrimaryVaultId(token: string): Promise<string> {
+  const base = serverUrl();
+  const res = await fetch(`${base}/vaults/credential`, {
+    headers: { 'Authorization': `Bearer ${token}` },
+    signal: AbortSignal.timeout(5000),
+  });
+
+  if (!res.ok) throw new Error(`Failed to list vaults: HTTP ${res.status}`);
+
+  const data = await res.json() as { vaults: Array<{ id: string; name: string; isPrimary: boolean }> };
+  const primary = data.vaults?.find(v => v.isPrimary);
+  if (!primary) {
+    if (data.vaults?.length > 0) return data.vaults[0].id;
+    throw new Error('No vaults found. Run `npx auramaxx` first.');
+  }
+  return primary.id;
+}

package/server/cli/lib/credential-resolve.ts

@@ -0,0 +1,280 @@
+/**
+ * Shared credential resolution logic for env.ts and shell-hook.ts
+ *
+ * Consolidates search → read → decrypt flow to prevent drift between
+ * the two consumers (audit finding #3).
+ */
+
+import { getErrorMessage } from '../../lib/error';
+import {
+  evaluateProjectScopeAccess,
+  emitProjectScopeEvent,
+  type ProjectScopeMode,
+} from '../../lib/project-scope';
+
+// ── Types ──
+
+export interface CredentialMeta {
+  id: string;
+  name: string;
+  type: string;
+  vaultId: string;
+}
+
+export interface DecryptedCredential {
+  id: string;
+  vaultId: string;
+  type: string;
+  fields: Array<{ key: string; value: string }>;
+}
+
+export interface AuraMapping {
+  envVar: string;
+  vault: string | null;
+  credentialName: string;
+  field: string;
+}
+
+export interface ResolveResult {
+  resolved: Map<string, string>;
+  errors: string[];
+  missing: AuraMapping[];
+}
+
+// ── Env var name validation (audit finding #6) ──
+
+const ENV_VAR_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export function isValidEnvVarName(name: string): boolean {
+  return ENV_VAR_NAME_RE.test(name);
+}
+
+export function validateEnvVarName(name: string): void {
+  if (!isValidEnvVarName(name)) {
+    throw new Error(
+      `Invalid env var name '${name}': must match [A-Za-z_][A-Za-z0-9_]*`
+    );
+  }
+}
+
+// ── Shell escaping (audit finding #1) ──
+
+/**
+ * Escape a value for safe use in shell export statements.
+ * Uses ANSI-C quoting ($'...') to safely handle newlines, tabs,
+ * single quotes, backslashes, and other control characters.
+ */
+export function escapeForShell(value: string): string {
+  // Use ANSI-C $'...' quoting which handles all special chars
+  const escaped = value
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t')
+    .replace(/\0/g, '\\0')
+    // Escape any other control characters
+    .replace(/[\x01-\x08\x0b\x0c\x0e-\x1f\x7f]/g, (ch) => {
+      return '\\x' + ch.charCodeAt(0).toString(16).padStart(2, '0');
+    });
+  return `$'${escaped}'`;
+}
+
+function normalizeProjectScopeMode(raw: unknown): ProjectScopeMode {
+  const value = String(raw || '').trim().toLowerCase();
+  if (value === 'strict') return 'strict';
+  if (value === 'off') return 'off';
+  return 'auto';
+}
+
+async function fetchProjectScopeMode(baseUrl: string): Promise<ProjectScopeMode> {
+  try {
+    const res = await fetch(`${baseUrl}/setup`, {
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) return 'auto';
+    const data = await res.json() as { projectScopeMode?: unknown };
+    return normalizeProjectScopeMode(data.projectScopeMode);
+  } catch {
+    return 'auto';
+  }
+}
+
+// ── Credential search with exact-match preference (audit finding #4) ──
+
+export async function searchCredential(
+  baseUrl: string,
+  token: string,
+  name: string,
+): Promise<CredentialMeta | null> {
+  for (const param of [
+    `q=${encodeURIComponent(name)}`,
+    `tag=${encodeURIComponent(name)}`,
+  ]) {
+    const res = await fetch(`${baseUrl}/credentials?${param}`, {
+      headers: { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) continue;
+
+    const data = (await res.json()) as { credentials: CredentialMeta[] };
+    const creds = data.credentials;
+    if (!creds || creds.length === 0) continue;
+
+    // Prefer exact name match (audit finding #4: ambiguous matching)
+    const exact = creds.find(
+      (c) => c.name.toLowerCase() === name.toLowerCase(),
+    );
+    if (exact) return exact;
+
+    // Warn if multiple non-exact matches
+    if (creds.length > 1) {
+      console.error(
+        `aura: warning: '${name}' matched ${creds.length} credentials, using first. ` +
+          `Matches: ${creds.map((c) => c.name).join(', ')}`,
+      );
+    }
+    return creds[0];
+  }
+  return null;
+}
+
+// ── Credential read + decrypt ──
+
+export async function readCredential(
+  baseUrl: string,
+  readToken: string,
+  credentialId: string,
+  decryptFn: (encrypted: string) => string,
+): Promise<DecryptedCredential> {
+  const res = await fetch(`${baseUrl}/credentials/${credentialId}/read`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${readToken}` },
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Read failed (${res.status}): ${text}`);
+  }
+  const data = (await res.json()) as { encrypted: string };
+  const plaintext = decryptFn(data.encrypted);
+  return JSON.parse(plaintext);
+}
+
+// ── Resolve mappings to env vars ──
+
+export async function resolveMappings(
+  mappings: AuraMapping[],
+  baseUrl: string,
+  token: string,
+  readToken: string,
+  decryptFn: (encrypted: string) => string,
+): Promise<ResolveResult> {
+  const resolved = new Map<string, string>();
+  const errors: string[] = [];
+  const missing: AuraMapping[] = [];
+
+  const credentialCache = new Map<string, DecryptedCredential | null>();
+  const CONCURRENCY = 5;
+
+  let vaultNameById = new Map<string, string>();
+  const projectScopeMode = await fetchProjectScopeMode(baseUrl);
+  try {
+    const vaultRes = await fetch(`${baseUrl}/setup/vaults`, { signal: AbortSignal.timeout(5000) });
+    if (vaultRes.ok) {
+      const vaultData = await vaultRes.json() as { vaults?: Array<{ id: string; name: string }> };
+      vaultNameById = new Map((vaultData.vaults || []).map((v) => [v.id, v.name]));
+    }
+  } catch {
+    // best effort only
+  }
+
+  const uniqueTargets = new Map<string, AuraMapping>();
+  for (const mapping of mappings) {
+    const key = `${(mapping.vault || '').toLowerCase()}::${mapping.credentialName.toLowerCase()}`;
+    if (!uniqueTargets.has(key)) uniqueTargets.set(key, mapping);
+  }
+
+  const targetList = [...uniqueTargets.values()];
+
+  for (let i = 0; i < targetList.length; i += CONCURRENCY) {
+    const batch = targetList.slice(i, i + CONCURRENCY);
+    await Promise.all(
+      batch.map(async (mapping) => {
+        const cacheKey = `${(mapping.vault || '').toLowerCase()}::${mapping.credentialName.toLowerCase()}`;
+        const meta = await searchCredential(baseUrl, token, mapping.credentialName);
+        if (!meta) {
+          credentialCache.set(cacheKey, null);
+          return;
+        }
+
+        const decision = evaluateProjectScopeAccess({
+          surface: 'cli_env',
+          requested: { vaultName: mapping.vault, credentialName: mapping.credentialName },
+          candidates: [{ id: meta.id, name: meta.name, vaultName: vaultNameById.get(meta.vaultId) || null }],
+          actor: 'cli-env',
+          projectScopeMode,
+        });
+        emitProjectScopeEvent({
+          actor: 'cli-env',
+          surface: 'cli_env',
+          requestedCredential: { vaultName: mapping.vault, credentialName: mapping.credentialName },
+          decision,
+        });
+        if (!decision.allowed) {
+          credentialCache.set(cacheKey, null);
+          errors.push(`credential '${mapping.credentialName}': ${decision.code}: ${decision.remediation}`);
+          return;
+        }
+
+        try {
+          const decrypted = await readCredential(
+            baseUrl,
+            readToken,
+            meta.id,
+            decryptFn,
+          );
+          credentialCache.set(cacheKey, decrypted);
+        } catch (err) {
+          credentialCache.set(cacheKey, null);
+          errors.push(`credential '${mapping.credentialName}': ${getErrorMessage(err)}`);
+        }
+      }),
+    );
+  }
+
+  for (const mapping of mappings) {
+    const cacheKey = `${(mapping.vault || '').toLowerCase()}::${mapping.credentialName.toLowerCase()}`;
+    const cred = credentialCache.get(cacheKey);
+    if (!cred) {
+      if (
+        !errors.some((e) =>
+          e.startsWith(`credential '${mapping.credentialName}'`),
+        )
+      ) {
+        errors.push(
+          `${mapping.envVar}: credential '${mapping.credentialName}' not found`,
+        );
+      } else {
+        errors.push(
+          `${mapping.envVar}: credential '${mapping.credentialName}' failed to resolve`,
+        );
+      }
+      missing.push(mapping);
+      continue;
+    }
+    const field = cred.fields.find(
+      (f) => f.key.toLowerCase() === mapping.field.toLowerCase(),
+    );
+    if (!field) {
+      const available = cred.fields.map((f) => f.key).join(', ');
+      errors.push(
+        `${mapping.envVar}: field '${mapping.field}' not found in '${mapping.credentialName}' (available: ${available})`,
+      );
+      continue;
+    }
+    resolved.set(mapping.envVar, field.value);
+  }
+
+  return { resolved, errors, missing };
+}

package/server/cli/lib/dotenv-migrate.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared dotenv → vault migration logic.
+ * Used by both `aura init --from-dotenv` and `aura env init`.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseDotenv, groupByPrefix, noGrouping, generateAuraFile, type CredentialGroup } from './dotenv-parser';
+import { createCredentialViaApi, getPrimaryVaultId } from './credential-create';
+
+export interface MigrateOptions {
+  token: string;
+  envPath: string;
+  noGroup?: boolean;
+  dryRun?: boolean;
+}
+
+export interface MigrateResult {
+  groups: CredentialGroup[];
+  created: number;
+  failed: number;
+  auraPath: string;
+}
+
+/**
+ * Migrate a .env file into the vault and generate a .aura file.
+ * Returns summary of what was done.
+ */
+export async function migrateDotenv(opts: MigrateOptions): Promise<MigrateResult> {
+  const { token, envPath, noGroup, dryRun } = opts;
+
+  if (!fs.existsSync(envPath)) {
+    throw new Error(`No .env file found at ${envPath}`);
+  }
+
+  const auraPath = path.join(path.dirname(envPath), '.aura');
+  const shouldWriteAura = !fs.existsSync(auraPath);
+
+  if (!shouldWriteAura && !dryRun) {
+    console.log(`\n  Note: existing .aura file found at ${auraPath} — skipping overwrite.`);
+  }
+
+  const envContent = fs.readFileSync(envPath, 'utf-8');
+  const vars = parseDotenv(envContent);
+
+  if (vars.size === 0) {
+    throw new Error('No variables found in .env file.');
+  }
+
+  const groups = noGroup ? noGrouping(vars) : groupByPrefix(vars);
+
+  if (dryRun) {
+    console.log(`\n  .env → .aura migration plan (${vars.size} variables → ${groups.length} credentials)\n`);
+    for (const group of groups) {
+      console.log(`  📦 ${group.name} (${group.fields.length} field${group.fields.length > 1 ? 's' : ''})`);
+      for (const field of group.fields) {
+        const preview = field.value.length > 20 ? field.value.substring(0, 20) + '...' : field.value;
+        console.log(`     ${field.envVar} → ${group.name}/${field.key}  (${preview})`);
+      }
+    }
+    console.log(`\n  Run without --dry-run to execute.\n`);
+    return { groups, created: 0, failed: 0, auraPath };
+  }
+
+  const vaultId = await getPrimaryVaultId(token);
+
+  console.log(`\n  Migrating ${vars.size} variables → ${groups.length} credentials\n`);
+
+  let created = 0;
+  let failed = 0;
+
+  for (const group of groups) {
+    const result = await createCredentialViaApi({
+      token,
+      vaultId,
+      name: group.name,
+      fields: group.fields.map(f => ({ key: f.key, value: f.value })),
+    });
+
+    if (result.success) {
+      console.log(`  ✓ Created credential: ${group.name} (${group.fields.length} field${group.fields.length > 1 ? 's' : ''})`);
+      created++;
+    } else if (result.error?.includes('already exists') || result.error?.includes('duplicate')) {
+      console.log(`  ⚠ Skipped credential: ${group.name} (already exists)`);
+    } else {
+      console.error(`  ✗ Failed to create ${group.name}: ${result.error}`);
+      failed++;
+    }
+  }
+
+  // Generate .aura file when needed
+  if (shouldWriteAura) {
+    const auraContent = generateAuraFile(groups);
+    fs.writeFileSync(auraPath, auraContent, 'utf-8');
+    console.log(`\n  ✓ Generated .aura file (${groups.length} credential${groups.length > 1 ? 's' : ''})`);
+  }
+
+  // Add .env to .gitignore
+  const gitignorePath = path.join(path.dirname(envPath), '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    const gitignore = fs.readFileSync(gitignorePath, 'utf-8');
+    if (!gitignore.includes('.env')) {
+      fs.appendFileSync(gitignorePath, '\n.env\n');
+      console.log('  ✓ Added .env to .gitignore');
+    }
+  }
+
+  console.log(`\n  Summary: ${created} created, ${failed} failed`);
+  if (created > 0) {
+    console.log('  Your .env variables are now in the vault.');
+    console.log('  Use `aura env -- <cmd>` to run commands with vault-injected env vars.');
+    console.log('  You can safely delete your .env file.\n');
+  }
+
+  return { groups, created, failed, auraPath };
+}

package/server/cli/lib/dotenv-parser.ts

@@ -0,0 +1,146 @@
+/**
+ * .env file parser and credential grouping for `aura env init`
+ */
+
+import { isValidEnvVarName } from './credential-resolve';
+
+export interface CredentialGroup {
+  name: string;
+  fields: Array<{ key: string; value: string; envVar: string }>;
+}
+
+/**
+ * Parse a .env file into key-value pairs.
+ * Handles: comments, blank lines, `export` prefix, single/double quotes, escaped chars.
+ * Does NOT handle: multiline values, variable expansion.
+ */
+export function parseDotenv(content: string): Map<string, string> {
+  const result = new Map<string, string>();
+
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+
+    // Skip empty lines and comments
+    if (!line || line.startsWith('#')) continue;
+
+    // Strip optional `export ` prefix
+    const stripped = line.startsWith('export ') ? line.slice(7).trim() : line;
+
+    const eqIdx = stripped.indexOf('=');
+    if (eqIdx === -1) continue;
+
+    const key = stripped.substring(0, eqIdx).trim();
+    if (!key) continue;
+
+    // Validate env var name (audit finding #6)
+    if (!isValidEnvVarName(key)) {
+      console.error(`warning: skipping invalid env var name '${key}'`);
+      continue;
+    }
+
+    let value = stripped.substring(eqIdx + 1).trim();
+
+    // Handle quoted values
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      const quote = value[0];
+      value = value.slice(1, -1);
+      if (quote === '"') {
+        // Unescape double-quoted values
+        value = value
+          .replace(/\\n/g, '\n')
+          .replace(/\\r/g, '\r')
+          .replace(/\\t/g, '\t')
+          .replace(/\\"/g, '"')
+          .replace(/\\\\/g, '\\');
+      }
+      // Single-quoted: literal, no escaping
+    } else {
+      // Unquoted: strip inline comment
+      const commentIdx = value.indexOf(' #');
+      if (commentIdx !== -1) {
+        value = value.substring(0, commentIdx).trim();
+      }
+    }
+
+    result.set(key, value);
+  }
+
+  return result;
+}
+
+/**
+ * Group env vars by common prefix for credential creation.
+ *
+ * Rules:
+ * - Split var name by `_`, use first segment as group prefix
+ * - Groups with 1 member: credential name = full lowercased var name, field = "value"
+ * - Groups with 2+ members: credential name = prefix, field = rest lowercased
+ */
+export function groupByPrefix(vars: Map<string, string>): CredentialGroup[] {
+  const prefixGroups = new Map<string, Array<{ key: string; value: string; envVar: string }>>();
+
+  for (const [envVar, value] of vars) {
+    const underscoreIdx = envVar.indexOf('_');
+    const prefix = underscoreIdx === -1
+      ? envVar.toLowerCase()
+      : envVar.substring(0, underscoreIdx).toLowerCase();
+
+    if (!prefixGroups.has(prefix)) {
+      prefixGroups.set(prefix, []);
+    }
+
+    const fieldName = underscoreIdx === -1
+      ? 'value'
+      : envVar.substring(underscoreIdx + 1).toLowerCase();
+
+    prefixGroups.get(prefix)!.push({ key: fieldName, value, envVar });
+  }
+
+  const groups: CredentialGroup[] = [];
+
+  for (const [prefix, fields] of prefixGroups) {
+    if (fields.length === 1 && fields[0].key !== 'value') {
+      groups.push({
+        name: fields[0].envVar.toLowerCase(),
+        fields: [{ key: 'value', value: fields[0].value, envVar: fields[0].envVar }],
+      });
+    } else {
+      groups.push({ name: prefix, fields });
+    }
+  }
+
+  return groups;
+}
+
+/**
+ * No grouping — one credential per env var, field always "value".
+ */
+export function noGrouping(vars: Map<string, string>): CredentialGroup[] {
+  const groups: CredentialGroup[] = [];
+  for (const [envVar, value] of vars) {
+    groups.push({
+      name: envVar.toLowerCase(),
+      fields: [{ key: 'value', value, envVar }],
+    });
+  }
+  return groups;
+}
+
+/**
+ * Generate .aura file content from credential groups.
+ */
+export function generateAuraFile(groups: CredentialGroup[]): string {
+  const lines = ['# Generated by aura env init'];
+
+  for (const group of groups) {
+    for (const field of group.fields) {
+      const ref = field.key === 'value'
+        ? `${group.name}/value`
+        : `${group.name}/${field.key}`;
+      lines.push(`${field.envVar}=${ref}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}

package/server/cli/lib/escalation.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared 403 escalation handler for CLI commands.
+ *
+ * Parses structured permission-denied responses (from server/lib/permissions.ts)
+ * and outputs structured JSON guidance to stderr so agents can self-escalate.
+ */
+
+interface EscalationInfo {
+  via?: string;
+  permissions?: string[];
+  dashboard?: string;
+  note?: string;
+}
+
+interface PermissionDeniedBody {
+  error?: string;
+  required?: string[];
+  have?: string[];
+  escalation?: EscalationInfo;
+}
+
+function isPermissionDeniedBody(body: unknown): body is PermissionDeniedBody {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) return false;
+  const obj = body as Record<string, unknown>;
+  return typeof obj.error === 'string' && obj.escalation !== undefined;
+}
+
+/**
+ * Detect a 403 permission-denied response and print structured JSON guidance.
+ *
+ * Returns `true` if the error was handled (caller should exit),
+ * `false` if this isn't a permission-denied response.
+ */
+export function handlePermissionDenied(status: number, body: unknown): boolean {
+  if (status !== 403) return false;
+  if (!isPermissionDeniedBody(body)) return false;
+
+  const esc = body.escalation;
+  if (!esc || esc.via !== 'auth') return false;
+
+  const perms = esc.permissions || body.required || [];
+  const needsAdmin = perms.includes('admin:*');
+  const suggestedProfile = needsAdmin ? 'admin' : 'strict';
+
+  const guidance = {
+    error: body.error,
+    status: 403,
+    requiresHumanApproval: true,
+    approveAt: esc.dashboard || 'http://localhost:4747',
+    nextStep: `npx auramaxx auth request --profile ${suggestedProfile}`,
+    required: perms,
+    ...(body.have ? { have: body.have } : {}),
+  };
+
+  console.error(JSON.stringify(guidance, null, 2));
+  return true;
+}