auramaxx 0.0.1

package/server/cli/commands/vault.ts

@@ -0,0 +1,1323 @@
+/**
+ * auramaxx vault — Retrieve and manage credentials from the vault
+ */
+
+import {
+  generateEphemeralKeypair,
+  bootstrapViaSocket,
+  bootstrapViaAuthRequest,
+  decryptWithPrivateKey,
+  createReadToken,
+  encryptToAgentPubkey,
+  type EphemeralKeypair,
+  type ProfileIssuanceSelection,
+} from '../../lib/credential-transport';
+import { spawn } from 'child_process';
+import { serverUrl } from '../lib/http';
+import { getErrorMessage } from '../../lib/error';
+import {
+  evaluateProjectScopeAccess,
+  emitProjectScopeEvent,
+  type ProjectScopeMode,
+} from '../../lib/project-scope';
+import { printHelp } from '../lib/theme';
+import { handlePermissionDenied } from '../lib/escalation';
+import { maybeHandleLockError } from '../lib/lock-unlock-helper';
+import {
+  canonicalizeCredentialFieldKey,
+  getCredentialPrimaryFieldKey,
+  normalizeCredentialFieldsForType,
+} from '../../../shared/credential-field-schema';
+import {
+  createSecretGist,
+  SecretGistError,
+} from '../../lib/secret-gist-share';
+
+// ── Auth ──────────────────────────────────────────────────────────────
+
+async function getAuthToken(
+  keypair: EphemeralKeypair,
+  authSelection?: ProfileIssuanceSelection,
+): Promise<string> {
+  const envToken = process.env.AURA_TOKEN;
+  if (envToken) return envToken;
+
+  try {
+    return await bootstrapViaSocket('cli-vault', keypair);
+  } catch (socketErr) {
+    const socketMessage = getErrorMessage(socketErr).toLowerCase();
+    const indicatesLockedVault =
+      socketMessage.includes('wallet is locked') ||
+      socketMessage.includes('vault is locked') ||
+      socketMessage.includes('daemon is locked') ||
+      socketMessage.includes('unlock before socket auto-approve');
+    if (indicatesLockedVault) {
+      throw new Error('Vault is locked. Run `auramaxx unlock` and retry.');
+    }
+
+    if (authSelection?.profile) {
+      const result = await bootstrapViaAuthRequest(serverUrl(), 'cli-vault', keypair, {
+        ...authSelection,
+        noWait: true,
+        onStatus: (message) => console.error(message),
+      });
+      if (result.approveUrl) {
+        console.error(`Approve at: ${result.approveUrl}`);
+      }
+      console.error(`After approval, re-run with: AURA_TOKEN=<token> npx auramaxx vault ...`);
+      console.error(`Or use: npx auramaxx auth request --profile ${authSelection.profile} --raw-token`);
+      process.exit(1);
+    }
+
+    return bootstrapViaAuthRequest(serverUrl(), 'cli-vault', keypair, {
+      ...authSelection,
+      onStatus: (message) => console.error(message),
+    }).catch((authErr) => {
+      throw new Error(`${getErrorMessage(socketErr)}\n${getErrorMessage(authErr)}`);
+    });
+  }
+}
+
+async function getReadToken(
+  authToken: string,
+  keypair: EphemeralKeypair,
+  authSelection?: ProfileIssuanceSelection,
+): Promise<string> {
+  try {
+    return await createReadToken(serverUrl(), authToken, keypair, 'cli-vault-reader', authSelection);
+  } catch (error) {
+    const message = getErrorMessage(error);
+    if (message.includes('(401)') || message.includes('(403)')) {
+      // Profile-issued tokens may not have action:create; direct read can still succeed when secret:read exists.
+      return authToken;
+    }
+    throw error;
+  }
+}
+
+function decryptCredentialPayload(encrypted: string, keypair: EphemeralKeypair): DecryptedCredential {
+  const plaintext = decryptWithPrivateKey(encrypted, keypair.privateKeyPem);
+  return JSON.parse(plaintext) as DecryptedCredential;
+}
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+interface CredentialMeta {
+  id: string;
+  name: string;
+  type: string;
+  vaultId: string;
+  meta: Record<string, unknown>;
+}
+
+interface DecryptedCredential {
+  id: string;
+  vaultId: string;
+  type: string;
+  fields: Array<{ key: string; value: string; type?: string; sensitive?: boolean }>;
+  health?: {
+    status: string;
+    flags: { weak: boolean; reused: boolean; breached: boolean; unknown: boolean };
+    lastScannedAt: string | null;
+  };
+}
+
+interface CredentialHealthSummaryResponse {
+  summary: {
+    totalAnalyzed: number;
+    safe: number;
+    weak: number;
+    reused: number;
+    breached: number;
+    unknown: number;
+    lastScanAt: string | null;
+  };
+}
+
+interface VaultSummary {
+  id: string;
+  name?: string;
+  isPrimary?: boolean;
+}
+
+interface ShareCreateResponse {
+  success?: boolean;
+  share?: {
+    token: string;
+    credentialId: string;
+    expiresAt: number;
+    accessMode: 'anyone' | 'password';
+    oneTimeOnly: boolean;
+  };
+  error?: string;
+}
+
+// ── API helpers ───────────────────────────────────────────────────────
+
+async function listCredentials(token: string, query?: string): Promise<CredentialMeta[]> {
+  const qs = query ? `?q=${encodeURIComponent(query)}` : '';
+  const res = await fetch(`${serverUrl()}/credentials${qs}`, {
+    headers: { 'Authorization': `Bearer ${token}` },
+    signal: AbortSignal.timeout(8_000),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as unknown;
+    if (handlePermissionDenied(res.status, body)) process.exit(1);
+    throw new Error(`List failed (${res.status})`);
+  }
+  const data = await res.json() as { credentials?: CredentialMeta[] };
+  return data.credentials || [];
+}
+
+async function readCredential(
+  credentialId: string,
+  readToken: string,
+  keypair: EphemeralKeypair,
+): Promise<DecryptedCredential> {
+  const res = await fetch(`${serverUrl()}/credentials/${credentialId}/read`, {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${readToken}` },
+    signal: AbortSignal.timeout(8_000),
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    let body: unknown;
+    try { body = JSON.parse(text) as unknown; } catch { body = text; }
+    if (handlePermissionDenied(res.status, body)) process.exit(1);
+    throw new Error(`Read failed (${res.status}): ${text}`);
+  }
+
+  const data = await res.json() as { encrypted: string };
+  return decryptCredentialPayload(data.encrypted, keypair);
+}
+
+async function searchCredentials(token: string, name: string): Promise<CredentialMeta[]> {
+  for (const param of [`q=${encodeURIComponent(name)}`, `tag=${encodeURIComponent(name)}`]) {
+    const res = await fetch(`${serverUrl()}/credentials?${param}`, {
+      headers: { 'Authorization': `Bearer ${token}` },
+      signal: AbortSignal.timeout(8_000),
+    });
+    if (!res.ok) {
+      if (res.status === 403) {
+        const body = await res.json().catch(() => ({})) as unknown;
+        if (handlePermissionDenied(res.status, body)) process.exit(1);
+      }
+      continue;
+    }
+
+    const data = await res.json() as { credentials?: CredentialMeta[] };
+    if (data.credentials && data.credentials.length > 0) {
+      return data.credentials;
+    }
+  }
+  return [];
+}
+
+async function fetchTotpCode(credentialId: string, token: string): Promise<{ code: string; remaining: number }> {
+  const res = await fetch(`${serverUrl()}/credentials/${credentialId}/totp`, {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${token}` },
+    signal: AbortSignal.timeout(8_000),
+  });
+  if (!res.ok) {
+    const data = await res.json().catch(() => ({ error: `HTTP ${res.status}` })) as { error?: string };
+    throw new Error(data.error || `TOTP request failed (${res.status})`);
+  }
+  return await res.json() as { code: string; remaining: number };
+}
+
+async function fetchVaults(): Promise<VaultSummary[]> {
+  const res = await fetch(`${serverUrl()}/setup/vaults`, {
+    signal: AbortSignal.timeout(8_000),
+  });
+  if (!res.ok) return [];
+  const data = await res.json() as { vaults?: VaultSummary[] };
+  return data.vaults || [];
+}
+
+async function fetchVaultNameMap(): Promise<Map<string, string>> {
+  const vaults = await fetchVaults();
+  return new Map(vaults.map((v) => [v.id, v.name || v.id]));
+}
+
+async function fetchHealthSummary(token: string): Promise<CredentialHealthSummaryResponse['summary']> {
+  const res = await fetch(`${serverUrl()}/credentials/health/summary`, {
+    headers: { 'Authorization': `Bearer ${token}` },
+    signal: AbortSignal.timeout(8_000),
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({})) as unknown;
+    if (handlePermissionDenied(res.status, body)) process.exit(1);
+    throw new Error(`Health summary failed (${res.status})`);
+  }
+  const data = await res.json() as CredentialHealthSummaryResponse;
+  return data.summary;
+}
+
+async function createCredential(
+  token: string,
+  body: {
+    vaultId: string;
+    name: string;
+    type: string;
+    sensitiveFields: Array<{ key: string; value: string; sensitive?: boolean }>;
+    meta?: Record<string, unknown>;
+  },
+): Promise<CredentialMeta> {
+  const res = await fetch(`${serverUrl()}/credentials`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(8_000),
+  });
+
+  const data = await res.json().catch(() => ({})) as {
+    success?: boolean;
+    error?: string;
+    credential?: CredentialMeta;
+  };
+
+  if (!res.ok || !data.success || !data.credential) {
+    if (handlePermissionDenied(res.status, data)) process.exit(1);
+    throw new Error(data.error || `Create failed (${res.status})`);
+  }
+
+  return data.credential;
+}
+
+async function updateCredential(
+  token: string,
+  credentialId: string,
+  body: {
+    sensitiveFields?: Array<{ key: string; value: string; sensitive?: boolean }>;
+    name?: string;
+    meta?: Record<string, unknown>;
+  },
+): Promise<CredentialMeta> {
+  const res = await fetch(`${serverUrl()}/credentials/${encodeURIComponent(credentialId)}`, {
+    method: 'PUT',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(8_000),
+  });
+
+  const data = await res.json().catch(() => ({})) as {
+    success?: boolean;
+    error?: string;
+    credential?: CredentialMeta;
+  };
+
+  if (!res.ok || !data.success || !data.credential) {
+    if (handlePermissionDenied(res.status, data)) process.exit(1);
+    throw new Error(data.error || `Update failed (${res.status})`);
+  }
+
+  return data.credential;
+}
+
+async function deleteCredential(
+  token: string,
+  credentialId: string,
+  location: 'active' | 'archive' | 'recently_deleted' = 'active',
+): Promise<{ success: boolean; action?: string; deleted?: boolean; error?: string }> {
+  const qs = new URLSearchParams({ location }).toString();
+  const res = await fetch(`${serverUrl()}/credentials/${encodeURIComponent(credentialId)}?${qs}`, {
+    method: 'DELETE',
+    headers: { 'Authorization': `Bearer ${token}` },
+    signal: AbortSignal.timeout(8_000),
+  });
+  const data = await res.json().catch(() => ({})) as {
+    success?: boolean;
+    action?: string;
+    deleted?: boolean;
+    error?: string;
+  };
+  if (!res.ok) {
+    if (handlePermissionDenied(res.status, data)) process.exit(1);
+    throw new Error(data.error || `Delete failed (${res.status})`);
+  }
+  return { success: data.success === true, action: data.action, deleted: data.deleted };
+}
+
+async function createShare(
+  token: string,
+  body: {
+    credentialId: string;
+    expiresAfter?: string;
+    accessMode?: 'anyone' | 'password';
+    password?: string;
+    oneTimeOnly?: boolean;
+  },
+): Promise<ShareCreateResponse['share']> {
+  const res = await fetch(`${serverUrl()}/credential-shares`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(8_000),
+  });
+
+  const data = await res.json().catch(() => ({})) as ShareCreateResponse;
+  if (!res.ok || !data.success || !data.share) {
+    if (handlePermissionDenied(res.status, data)) process.exit(1);
+    throw new Error(data.error || `Share create failed (${res.status})`);
+  }
+  return data.share;
+}
+
+function resolveShareUrlForGist(shareToken: string): string {
+  const configuredBase = String(process.env.AURA_SHARE_BASE_URL || '').trim();
+  if (configuredBase) {
+    try {
+      const parsed = new URL(configuredBase);
+      if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+        const normalizedBase = configuredBase.replace(/\/+$/, '');
+        return `${normalizedBase}/share/${shareToken}`;
+      }
+    } catch {
+      // fall back to API share URL below when base URL is invalid
+    }
+  }
+  return `${serverUrl()}/credential-shares/${shareToken}`;
+}
+
+// ── Scope + target resolution ─────────────────────────────────────────
+
+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(): Promise<ProjectScopeMode> {
+  try {
+    const res = await fetch(`${serverUrl()}/setup`, { signal: AbortSignal.timeout(5_000) });
+    if (!res.ok) return 'auto';
+    const data = await res.json() as { projectScopeMode?: unknown };
+    return normalizeProjectScopeMode(data.projectScopeMode);
+  } catch {
+    return 'auto';
+  }
+}
+
+async function resolveCredentialTarget(
+  token: string,
+  name: string,
+  options: {
+    vaultName?: string;
+    first?: boolean;
+    surface: string;
+    actor: string;
+  },
+): Promise<{ target: CredentialMeta; vaultNames: Map<string, string> }> {
+  const matches = await searchCredentials(token, name);
+  if (matches.length === 0) {
+    throw new Error(`No credential found matching "${name}"`);
+  }
+
+  const exactMatches = matches.filter((m) => m.name.toLowerCase() === name.toLowerCase());
+  const candidateMatches = exactMatches.length > 0 ? exactMatches : matches;
+
+  const vaultNames = await fetchVaultNameMap();
+  const projectScopeMode = await fetchProjectScopeMode();
+
+  const scopedDecision = evaluateProjectScopeAccess({
+    surface: options.surface,
+    requested: { vaultName: options.vaultName || null, credentialName: name },
+    candidates: candidateMatches.map((m) => ({
+      id: m.id,
+      name: m.name,
+      vaultName: vaultNames.get(m.vaultId) || null,
+    })),
+    actor: options.actor,
+    projectScopeMode,
+  });
+
+  emitProjectScopeEvent({
+    actor: options.actor,
+    surface: options.surface,
+    requestedCredential: { vaultName: options.vaultName || null, credentialName: name },
+    decision: scopedDecision,
+  });
+
+  if (!scopedDecision.allowed) {
+    throw new Error(`${scopedDecision.code}: ${scopedDecision.remediation}`);
+  }
+
+  const allowedIds = new Set(scopedDecision.allowedCandidates.map((c) => c.id).filter(Boolean));
+  const scopedMatches = candidateMatches.filter((m) => allowedIds.has(m.id));
+  const vaultFiltered = options.vaultName
+    ? scopedMatches.filter((m) => (vaultNames.get(m.vaultId) || '').toLowerCase() === options.vaultName!.toLowerCase())
+    : scopedMatches;
+
+  if (vaultFiltered.length === 0) {
+    throw new Error(`PROJECT_SCOPE_DENIED: No allowed credential found for "${name}" in vault "${options.vaultName}".`);
+  }
+
+  if (vaultFiltered.length > 1 && !options.first) {
+    const lines = [`Multiple credentials match "${name}":`];
+    for (const m of vaultFiltered) {
+      const resolvedVault = vaultNames.get(m.vaultId) || m.vaultId;
+      lines.push(`  - ${m.name}  (${m.type}, vault: ${resolvedVault}, id: ${m.id})`);
+    }
+    lines.push('Use --first to select the first match, or specify --vault.');
+    throw new Error(lines.join('\n'));
+  }
+
+  return { target: vaultFiltered[0], vaultNames };
+}
+
+function resolveVaultId(vaults: VaultSummary[], vaultName?: string): string {
+  if (vaults.length === 0) {
+    throw new Error('No vaults found. Initialize setup first.');
+  }
+
+  if (vaultName) {
+    const found = vaults.find((v) => (v.name || '').toLowerCase() === vaultName.toLowerCase());
+    if (!found) {
+      throw new Error(`Vault not found: ${vaultName}`);
+    }
+    return found.id;
+  }
+
+  const primary = vaults.find((v) => v.isPrimary);
+  if (primary) return primary.id;
+  return vaults[0].id;
+}
+
+// ── CLI parsing ────────────────────────────────────────────────────────
+
+function showHelp(): void {
+  printHelp('VAULT', 'npx auramaxx vault <subcommand> [options]', [
+    { name: 'list', desc: 'List credential names (supports --name/--field filters)' },
+    { name: 'get <name>', desc: 'Print primary value only (use --json for full payload)' },
+    { name: 'inject <name> [-- <cmd>]', desc: 'Save primary secret to env var and optionally run command' },
+    { name: 'set <name> <value>', desc: 'Upsert secret (default type: api key, default field: value)' },
+    { name: 'share <name>', desc: 'Create GitHub secret gist share for credential by name' },
+    { name: 'delete <name>', desc: 'Delete credential by name (lifecycle delete)' },
+    { name: 'health', desc: 'Print credential health summary' },
+  ], [
+    'Options:',
+    '  --field <f>              get/set: field key override; list: field key/value contains query',
+    '  --name <v>               list: credential name/title contains query',
+    '  --env <v>                inject: env var override',
+    '  --type <t>               Set type (set only; default: api key)',
+    '  --tags <a,b,c>            Comma-separated tags (set only)',
+    '  --vault <v>              Restrict to vault name',
+    '  --json                   JSON output',
+    '  --first                  Use first match if ambiguous',
+    '  --totp                   Print current TOTP code only (get)',
+    '  --expires-after <v>      Share expiry: 15m|1h|24h|7d|30d (default: 24h)',
+    '  --password <pwd>         Share password (implies accessMode=password)',
+    '  --one-time               Share one-time-only access',
+    '  --location <v>           Delete location: active|archive|recently_deleted',
+    '  --profile <p>            /auth fallback profile when socket is blocked',
+    '  --profile-version <v>    /auth fallback profile version',
+    '  --profile-overrides <j>  Tighten-only profile override JSON',
+    '',
+    'Examples:',
+    '  npx auramaxx vault list --name prod',
+    '  npx auramaxx vault list --name prod --field token',
+    '',
+    'Auth: Uses Unix socket by default. Falls back to /auth polling when strict local mode blocks auto-approve.',
+    '      Set AURA_TOKEN for headless/CI.',
+  ]);
+}
+
+export function parseArgs(args: string[]): {
+  subcommand: string | undefined;
+  flagJson: boolean;
+  flagFirst: boolean;
+  flagTotp: boolean;
+  flagOneTime: boolean;
+  fieldName: string | undefined;
+  secretEnvName: string | undefined;
+  vaultName: string | undefined;
+  expiresAfter: string | undefined;
+  sharePassword: string | undefined;
+  deleteLocation: string | undefined;
+  authProfile: string | undefined;
+  authProfileVersion: string | undefined;
+  authProfileOverrides: string | undefined;
+  typeName: string | undefined;
+  tags: string[] | undefined;
+  extraFields: Array<{ key: string; value: string }>;
+  positional: string[];
+  execCommand: string[];
+} {
+  const separatorIdx = args.indexOf('--');
+  const parseableArgs = separatorIdx === -1 ? args : args.slice(0, separatorIdx);
+  const execCommand = separatorIdx === -1 ? [] : args.slice(separatorIdx + 1);
+
+  const subcommand = parseableArgs[0];
+  const flagJson = parseableArgs.includes('--json');
+  const flagFirst = parseableArgs.includes('--first');
+  const flagTotp = parseableArgs.includes('--totp');
+  const flagOneTime = parseableArgs.includes('--one-time');
+  const fieldIdx = parseableArgs.indexOf('--field');
+  const fieldName = fieldIdx !== -1 ? parseableArgs[fieldIdx + 1] : undefined;
+  const secretEnvIdx = parseableArgs.indexOf('--env');
+  const legacySecretEnvIdx = parseableArgs.indexOf('--name');
+  const secretEnvName = secretEnvIdx !== -1
+    ? parseableArgs[secretEnvIdx + 1]
+    : (legacySecretEnvIdx !== -1 ? parseableArgs[legacySecretEnvIdx + 1] : undefined);
+  const vaultIdx = parseableArgs.indexOf('--vault');
+  const vaultName = vaultIdx !== -1 ? parseableArgs[vaultIdx + 1] : undefined;
+  const expiresAfterIdx = parseableArgs.indexOf('--expires-after');
+  const expiresAfter = expiresAfterIdx !== -1 ? parseableArgs[expiresAfterIdx + 1] : undefined;
+  const passwordIdx = parseableArgs.indexOf('--password');
+  const sharePassword = passwordIdx !== -1 ? parseableArgs[passwordIdx + 1] : undefined;
+  const locationIdx = parseableArgs.indexOf('--location');
+  const deleteLocation = locationIdx !== -1 ? parseableArgs[locationIdx + 1] : undefined;
+  const profileIdx = parseableArgs.indexOf('--profile');
+  const authProfile = profileIdx !== -1 ? parseableArgs[profileIdx + 1] : undefined;
+  const profileVersionIdx = parseableArgs.indexOf('--profile-version');
+  const authProfileVersion = profileVersionIdx !== -1 ? parseableArgs[profileVersionIdx + 1] : undefined;
+  const profileOverridesIdx = parseableArgs.indexOf('--profile-overrides');
+  const authProfileOverrides = profileOverridesIdx !== -1 ? parseableArgs[profileOverridesIdx + 1] : undefined;
+  const typeIdx = parseableArgs.indexOf('--type');
+  const typeName = typeIdx !== -1 ? parseableArgs[typeIdx + 1] : undefined;
+  const tagsIdx = parseableArgs.indexOf('--tags');
+  const tagsRaw = tagsIdx !== -1 ? parseableArgs[tagsIdx + 1] : undefined;
+  const tags = tagsRaw
+    ? Array.from(new Set(tagsRaw.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)))
+    : undefined;
+
+  const knownValueFlags = new Set([
+    '--field', '--name', '--env', '--vault', '--expires-after', '--password', '--location', '--profile', '--profile-version', '--profile-overrides', '--type', '--tags',
+  ]);
+  const knownBooleanFlags = new Set(['--json', '--first', '--totp', '--one-time']);
+
+  const positional: string[] = [];
+  const extraFields: Array<{ key: string; value: string }> = [];
+  for (let i = 1; i < parseableArgs.length; i++) {
+    const arg = parseableArgs[i];
+    if (!arg) continue;
+    if (!arg.startsWith('--')) {
+      positional.push(arg);
+      continue;
+    }
+
+    if (knownValueFlags.has(arg)) {
+      i++;
+      continue;
+    }
+
+    if (knownBooleanFlags.has(arg)) {
+      continue;
+    }
+
+    const key = arg.slice(2).trim();
+    if (!key) continue;
+
+    const value = parseableArgs[i + 1];
+    if (!value || value.startsWith('--')) {
+      continue;
+    }
+
+    extraFields.push({ key, value });
+    i++;
+  }
+
+  return {
+    subcommand,
+    flagJson,
+    flagFirst,
+    flagTotp,
+    flagOneTime,
+    fieldName,
+    secretEnvName,
+    vaultName,
+    expiresAfter,
+    sharePassword,
+    deleteLocation,
+    authProfile,
+    authProfileVersion,
+    authProfileOverrides,
+    typeName,
+    tags,
+    extraFields,
+    positional,
+    execCommand,
+  };
+}
+
+type CredentialField = { key: string; value: string; type?: string; sensitive?: boolean };
+
+const TYPE_ALIASES: Record<string, string> = {
+  'api key': 'apikey',
+  'api-key': 'apikey',
+  api_key: 'apikey',
+};
+
+function normalizeCredentialType(type: string | undefined): string {
+  const normalized = String(type || '').trim().toLowerCase();
+  if (!normalized) return 'apikey';
+  return TYPE_ALIASES[normalized] || normalized;
+}
+
+function resolvePrimaryField(type: string, fields: CredentialField[]): CredentialField | undefined {
+  const defaultFieldKey = getCredentialPrimaryFieldKey(type);
+  return fields.find((f) => f.key.toLowerCase() === defaultFieldKey.toLowerCase())
+    || fields.find((f) => f.key.toLowerCase() === 'value')
+    || fields[0];
+}
+
+function resolvePrimarySecretField(type: string, fields: CredentialField[]): CredentialField | undefined {
+  const defaultFieldKey = getCredentialPrimaryFieldKey(type).toLowerCase();
+  return fields.find((f) => f.key.toLowerCase() === defaultFieldKey && f.sensitive !== false)
+    || fields.find((f) => f.sensitive !== false);
+}
+
+function shouldAutoDecryptSensitiveValues(): boolean {
+  return String(process.env.AUTO_DECRYPT || '').trim().toLowerCase() === 'true'
+    && String(process.env.AURA_VAULT_PASSWORD || '').trim().length > 0;
+}
+
+function isSensitiveField(field: CredentialField): boolean {
+  return field.sensitive !== false;
+}
+
+function toMetaBackedFields(meta: Record<string, unknown> | undefined): CredentialField[] {
+  if (!meta || typeof meta !== 'object') return [];
+  const out: CredentialField[] = [];
+  for (const [key, rawValue] of Object.entries(meta)) {
+    if (rawValue === undefined || rawValue === null) continue;
+
+    if (typeof rawValue === 'string' || typeof rawValue === 'number' || typeof rawValue === 'boolean') {
+      out.push({ key, value: String(rawValue), type: 'text', sensitive: false });
+      continue;
+    }
+
+    if (Array.isArray(rawValue) && rawValue.every((v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')) {
+      out.push({ key, value: rawValue.map((v) => String(v)).join(','), type: 'text', sensitive: false });
+    }
+  }
+  return out;
+}
+
+function mergeCredentialFields(
+  type: string,
+  decryptedFields: CredentialField[],
+  meta: Record<string, unknown> | undefined,
+): CredentialField[] {
+  const out = [...decryptedFields];
+  const known = new Set(out.map((field) => field.key.toLowerCase()));
+  for (const metaField of normalizeCredentialFieldsForType(type, toMetaBackedFields(meta))) {
+    const key = metaField.key.toLowerCase();
+    if (known.has(key)) continue;
+    known.add(key);
+    out.push(metaField);
+  }
+  return out;
+}
+
+function findField(type: string, fields: CredentialField[], key: string): CredentialField | undefined {
+  const normalizedKey = key.trim().toLowerCase();
+  if (!normalizedKey) return undefined;
+  const direct = fields.find((field) => field.key.toLowerCase() === normalizedKey);
+  if (direct) return direct;
+  const canonicalKey = canonicalizeCredentialFieldKey(type, key);
+  return fields.find((field) => field.key.toLowerCase() === canonicalKey.toLowerCase());
+}
+
+function normalizeSecretExecEnvName(input: string | undefined): string | null {
+  const candidate = String(input || '').trim();
+  if (!candidate) return null;
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(candidate)) return null;
+  return candidate;
+}
+
+function normalizeListFilterQuery(input: string | undefined): string | null {
+  const candidate = String(input || '').trim().toLowerCase();
+  return candidate.length > 0 ? candidate : null;
+}
+
+function matchesListNameFilter(credential: CredentialMeta, query: string): boolean {
+  if (credential.name.toLowerCase().includes(query)) return true;
+  const title = typeof credential.meta?.title === 'string' ? credential.meta.title.toLowerCase() : '';
+  return title.includes(query);
+}
+
+function matchesListFieldFilter(
+  credential: CredentialMeta,
+  decrypted: DecryptedCredential,
+  query: string,
+): boolean {
+  const normalizedType = normalizeCredentialType(decrypted.type || credential.type);
+  const mergedFields = mergeCredentialFields(normalizedType, decrypted.fields, credential.meta);
+  return mergedFields.some((field) => {
+    const keyMatch = field.key.toLowerCase().includes(query);
+    const valueMatch = field.value.toLowerCase().includes(query);
+    return keyMatch || valueMatch;
+  });
+}
+
+const SECRET_EXEC_USAGE = 'Usage: npx auramaxx secret exec <name> [--env ENV_VAR] [-- <command>]';
+const SECRET_INJECT_USAGE = 'Usage: npx auramaxx inject <name> [--env ENV_VAR] [-- <command>]';
+
+async function runSecretExec(command: string[], envVarName: string, secretValue: string): Promise<number> {
+  if (command.length === 0) {
+    process.env[envVarName] = secretValue;
+    console.log(`Saved to env variable ${envVarName}.`);
+    console.log("Scope: current CLI process only. Use '-- <command>' to inject into a child command.");
+    return 0;
+  }
+
+  return await new Promise<number>((resolve) => {
+    const child = spawn(command[0], command.slice(1), {
+      stdio: 'inherit',
+      env: {
+        ...process.env,
+        [envVarName]: secretValue,
+      },
+    });
+
+    child.on('error', (error) => {
+      console.error(`Failed to execute command: ${getErrorMessage(error)}`);
+      resolve(1);
+    });
+
+    child.on('exit', (code, signal) => {
+      if (signal) {
+        resolve(1);
+        return;
+      }
+      resolve(typeof code === 'number' ? code : 1);
+    });
+  });
+}
+
+function resolveSetType(typeName: string | undefined): { requestType: string; normalizedType: string; defaultFieldKey: string } {
+  const normalizedType = normalizeCredentialType(typeName);
+  const requestType = ['login', 'card', 'note', 'plain_note', 'hot_wallet', 'api', 'apikey', 'custom', 'passkey', 'oauth2', 'ssh', 'gpg'].includes(normalizedType)
+    ? normalizedType
+    : 'custom';
+  const defaultFieldKey = getCredentialPrimaryFieldKey(normalizedType);
+  return { requestType, normalizedType, defaultFieldKey };
+}
+
+// ── Output formatting ──────────────────────────────────────────────────
+
+export function formatCredential(
+  target: { name: string; type: string; id: string; vaultId?: string; meta?: Record<string, unknown> },
+  decrypted: DecryptedCredential,
+  opts: {
+    json: boolean;
+    fieldName?: string;
+    autoDecryptSensitive?: boolean;
+    encryptSensitiveValue?: (value: string) => string;
+  },
+): { output: string; exitCode: number } {
+  if (opts.json) {
+    return {
+      output: JSON.stringify({
+        name: target.name,
+        type: target.type,
+        id: target.id,
+        vaultId: decrypted.vaultId || target.vaultId,
+        meta: target.meta || {},
+        health: decrypted.health,
+        fields: decrypted.fields,
+      }, null, 2),
+      exitCode: 0,
+    };
+  }
+
+  const resolvedType = normalizeCredentialType(decrypted.type || target.type);
+  const allFields = mergeCredentialFields(resolvedType, decrypted.fields, target.meta);
+  const autoDecryptSensitive = opts.autoDecryptSensitive ?? true;
+  const serializeFieldValue = (field: CredentialField): string => {
+    if (!isSensitiveField(field) || autoDecryptSensitive) {
+      return field.value;
+    }
+    if (!opts.encryptSensitiveValue) {
+      return field.value;
+    }
+    return opts.encryptSensitiveValue(field.value);
+  };
+
+  if (opts.fieldName) {
+    const field = findField(resolvedType, allFields, opts.fieldName);
+    if (!field) {
+      return {
+        output: `Field "${opts.fieldName}" not found. Available: ${allFields.map((f) => f.key).join(', ')}`,
+        exitCode: 1,
+      };
+    }
+    return { output: serializeFieldValue(field), exitCode: 0 };
+  }
+
+  const primary = resolvePrimaryField(resolvedType, allFields);
+  if (!primary) {
+    return {
+      output: 'No fields found on credential.',
+      exitCode: 1,
+    };
+  }
+
+  return {
+    output: serializeFieldValue(primary),
+    exitCode: 0,
+  };
+}
+
+// ── Main command ───────────────────────────────────────────────────────
+
+export async function runVaultCli(args: string[]): Promise<number> {
+  const {
+    subcommand,
+    flagJson,
+    flagFirst,
+    flagTotp,
+    flagOneTime,
+    fieldName,
+    secretEnvName,
+    vaultName,
+    expiresAfter,
+    sharePassword,
+    deleteLocation,
+    authProfile,
+    authProfileVersion,
+    authProfileOverrides,
+    typeName,
+    tags,
+    extraFields,
+    positional,
+    execCommand,
+  } = parseArgs(args);
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    showHelp();
+    return 0;
+  }
+
+  const keypair = generateEphemeralKeypair();
+  let profileOverrides: ProfileIssuanceSelection['profileOverrides'] | undefined;
+  if (authProfileOverrides) {
+    try {
+      const parsed = JSON.parse(authProfileOverrides) as unknown;
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('must be a JSON object');
+      }
+      profileOverrides = parsed as ProfileIssuanceSelection['profileOverrides'];
+    } catch (error) {
+      console.error(`Invalid --profile-overrides: ${getErrorMessage(error)}`);
+      return 1;
+    }
+  }
+
+  const authSelection: ProfileIssuanceSelection = {
+    ...(authProfile ? { profile: authProfile } : {}),
+    ...(authProfileVersion ? { profileVersion: authProfileVersion } : {}),
+    ...(profileOverrides ? { profileOverrides } : {}),
+  };
+
+  try {
+    const token = await getAuthToken(keypair, authSelection);
+
+    if (subcommand === 'list') {
+      const listNameQuery = normalizeListFilterQuery(secretEnvName);
+      const listFieldQuery = normalizeListFilterQuery(fieldName);
+
+      let credentials = await listCredentials(token);
+      if (listNameQuery) {
+        credentials = credentials.filter((credential) => matchesListNameFilter(credential, listNameQuery));
+      }
+
+      if (listFieldQuery) {
+        const readToken = await getReadToken(token, keypair, authSelection);
+        const fieldMatches = await Promise.all(credentials.map(async (credential) => {
+          try {
+            const decrypted = await readCredential(credential.id, readToken, keypair);
+            return matchesListFieldFilter(credential, decrypted, listFieldQuery);
+          } catch {
+            // Best effort: unreadable credentials are excluded from field-filtered results.
+            return false;
+          }
+        }));
+        credentials = credentials.filter((_credential, idx) => fieldMatches[idx]);
+      }
+
+      if (flagJson) {
+        console.log(JSON.stringify(credentials.map((c) => ({ name: c.name, type: c.type, id: c.id })), null, 2));
+      } else if (credentials.length === 0) {
+        console.log('No credentials found.');
+      } else {
+        for (const c of credentials) {
+          console.log(`${c.name}  (${c.type})`);
+        }
+      }
+      return 0;
+    }
+
+    if (subcommand === 'health') {
+      const summary = await fetchHealthSummary(token);
+      if (flagJson) {
+        console.log(JSON.stringify(summary, null, 2));
+      } else {
+        console.log(`Analyzed: ${summary.totalAnalyzed}`);
+        console.log(`Safe: ${summary.safe}`);
+        console.log(`Weak: ${summary.weak}`);
+        console.log(`Reused: ${summary.reused}`);
+        console.log(`Breached: ${summary.breached}`);
+        console.log(`Unknown: ${summary.unknown}`);
+      }
+      return 0;
+    }
+
+    if (subcommand === 'secret' || subcommand === 'inject' || subcommand === 'use') {
+      const isInjectShortcut = subcommand === 'inject' || subcommand === 'use';
+      const action = isInjectShortcut ? 'exec' : positional[0];
+      const name = isInjectShortcut ? positional[0] : positional[1];
+      if (action !== 'exec' || !name) {
+        console.error(isInjectShortcut ? SECRET_INJECT_USAGE : SECRET_EXEC_USAGE);
+        return 1;
+      }
+
+      const envVarName = normalizeSecretExecEnvName(secretEnvName || 'AURA_SECRET');
+      if (!envVarName) {
+        console.error('Invalid --env. Expected shell env var format like AURA_SECRET or GITHUB_PAT.');
+        return 1;
+      }
+
+      const { target } = await resolveCredentialTarget(token, name, {
+        vaultName,
+        first: flagFirst,
+        surface: 'cli_secret_exec',
+        actor: 'cli-vault',
+      });
+
+      const readToken = await getReadToken(token, keypair, authSelection);
+      const decrypted = await readCredential(target.id, readToken, keypair);
+      const primarySecret = resolvePrimarySecretField(
+        normalizeCredentialType(decrypted.type || target.type),
+        decrypted.fields,
+      );
+      if (!primarySecret) {
+        console.error('No sensitive field found on credential.');
+        return 1;
+      }
+
+      return await runSecretExec(execCommand, envVarName, primarySecret.value);
+    }
+
+    if (subcommand === 'get') {
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: npx auramaxx vault get <name>');
+        return 1;
+      }
+
+      const { target } = await resolveCredentialTarget(token, name, {
+        vaultName,
+        first: flagFirst,
+        surface: 'cli_vault_get',
+        actor: 'cli-vault',
+      });
+
+      if (flagTotp) {
+        const totp = await fetchTotpCode(target.id, token);
+        process.stdout.write(totp.code);
+        return 0;
+      }
+
+      const readToken = await getReadToken(token, keypair, authSelection);
+      const decrypted = await readCredential(target.id, readToken, keypair);
+
+      const hasTotpField = decrypted.fields.some((f) => f.key === 'totp' || f.key === 'otp');
+      if (hasTotpField) {
+        try {
+          const totp = await fetchTotpCode(target.id, token);
+          decrypted.fields.push({ key: 'totp_code', value: totp.code, type: 'text', sensitive: false });
+        } catch {
+          // ignore TOTP enrichment failure
+        }
+      }
+
+      const autoDecryptSensitive = shouldAutoDecryptSensitiveValues();
+      const result = formatCredential(target, decrypted, {
+        json: flagJson,
+        fieldName,
+        autoDecryptSensitive,
+        encryptSensitiveValue: (value: string) => encryptToAgentPubkey(value, keypair.publicKeyPem),
+      });
+      if (result.exitCode !== 0) {
+        console.error(result.output);
+        return result.exitCode;
+      }
+
+      if (fieldName) {
+        process.stdout.write(result.output);
+      } else {
+        console.log(result.output);
+      }
+      return 0;
+    }
+
+    if (subcommand === 'set') {
+      const name = positional[0];
+      const value = positional[1];
+      const resolvedType = resolveSetType(typeName);
+      const fieldKey = fieldName || resolvedType.defaultFieldKey;
+
+      if (!name || value === undefined) {
+        console.error('Usage: npx auramaxx vault set <name> <value> [--type <type>] [--field <key>] [--tags a,b,c] [--vault <name>] [--another-field <value>]');
+        return 1;
+      }
+
+      const setFields: Array<{ key: string; value: string; sensitive?: boolean }> = [
+        { key: fieldKey, value, sensitive: true },
+        ...extraFields.map((f) => ({ key: f.key, value: f.value, sensitive: true })),
+      ];
+      const nextMeta = tags ? { tags } : undefined;
+
+      const matches = await searchCredentials(token, name);
+      if (matches.length > 0) {
+        const { target } = await resolveCredentialTarget(token, name, {
+          vaultName,
+          first: flagFirst,
+          surface: 'cli_vault_set',
+          actor: 'cli-vault',
+        });
+
+        let nextFields: Array<{ key: string; value: string; type?: string; sensitive?: boolean }> = [...setFields];
+
+        // Preserve existing fields when read scope is available.
+        try {
+          const readToken = await getReadToken(token, keypair, authSelection);
+          const decrypted = await readCredential(target.id, readToken, keypair);
+          const existing = [...decrypted.fields];
+          for (const next of setFields) {
+            const index = existing.findIndex((f) => f.key.toLowerCase() === next.key.toLowerCase());
+            if (index >= 0) {
+              existing[index] = { ...existing[index], key: next.key, value: next.value, sensitive: true };
+            } else {
+              existing.push({ key: next.key, value: next.value, sensitive: true });
+            }
+          }
+          nextFields = existing;
+        } catch {
+          // write-only tokens may not be allowed to read; replace with single field in that case.
+        }
+
+        const updated = await updateCredential(token, target.id, {
+          sensitiveFields: nextFields.map((f) => ({ key: f.key, value: f.value, sensitive: true })),
+          ...(nextMeta ? { meta: nextMeta } : {}),
+        });
+
+        if (flagJson) {
+          console.log(JSON.stringify({ success: true, action: 'updated', credential: updated }, null, 2));
+        } else {
+          console.log(`Updated ${updated.name} (${updated.id})`);
+        }
+        return 0;
+      }
+
+      const vaults = await fetchVaults();
+      const vaultId = resolveVaultId(vaults, vaultName);
+      const created = await createCredential(token, {
+        vaultId,
+        type: resolvedType.requestType,
+        name,
+        sensitiveFields: setFields,
+        ...(nextMeta ? { meta: nextMeta } : {}),
+      });
+
+      if (flagJson) {
+        console.log(JSON.stringify({ success: true, action: 'created', credential: created }, null, 2));
+      } else {
+        console.log(`Created ${created.name} (${created.id})`);
+      }
+      return 0;
+    }
+
+    if (subcommand === 'share') {
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: npx auramaxx vault share <name> [--expires-after 24h] [--password xxx] [--one-time]');
+        return 1;
+      }
+
+      const { target } = await resolveCredentialTarget(token, name, {
+        vaultName,
+        first: flagFirst,
+        surface: 'cli_vault_share',
+        actor: 'cli-vault',
+      });
+
+      const accessMode: 'anyone' | 'password' = sharePassword ? 'password' : 'anyone';
+      const share = await createShare(token, {
+        credentialId: target.id,
+        expiresAfter: expiresAfter || '24h',
+        accessMode,
+        ...(sharePassword ? { password: sharePassword } : {}),
+        oneTimeOnly: flagOneTime,
+      });
+
+      const link = resolveShareUrlForGist(share.token);
+      const fallbackLink = `${serverUrl()}/credential-shares/${share.token}`;
+      const normalizedType = normalizeCredentialType(target.type);
+      let gistFields = normalizeCredentialFieldsForType(
+        normalizedType,
+        toMetaBackedFields(target.meta),
+      )
+        .map((field) => ({
+          key: String(field.key || '').trim(),
+          value: String(field.value || '').trim(),
+          sensitive: field.sensitive !== false,
+        }))
+        .filter((field) => field.key.length > 0 && field.value.length > 0);
+      try {
+        const readToken = await getReadToken(token, keypair, authSelection);
+        const decrypted = await readCredential(target.id, readToken, keypair);
+        gistFields = mergeCredentialFields(
+          normalizedType,
+          decrypted.fields,
+          target.meta,
+        )
+          .map((field) => ({
+            key: String(field.key || '').trim(),
+            value: String(field.value || '').trim(),
+            sensitive: field.sensitive !== false,
+          }))
+          .filter((field) => field.key.length > 0 && field.value.length > 0);
+      } catch {
+        // Preserve share behavior for write-only tokens; gist may still include non-secret metadata.
+      }
+      let gist: Awaited<ReturnType<typeof createSecretGist>> | null = null;
+      let gistError: SecretGistError | null = null;
+      try {
+        gist = await createSecretGist({
+          credentialId: target.id,
+          credentialName: target.name,
+          credentialType: target.type,
+          shareUrl: link,
+          accessMode: share.accessMode,
+          oneTimeOnly: share.oneTimeOnly,
+          expiresAfter: expiresAfter || '24h',
+          fields: gistFields,
+        });
+      } catch (error) {
+        if (error instanceof SecretGistError) {
+          gistError = error;
+        } else {
+          throw error;
+        }
+      }
+
+      if (flagJson) {
+        console.log(JSON.stringify({
+          success: true,
+          share,
+          link: gist ? link : fallbackLink,
+          gist,
+          fallback: gist ? null : 'local_link',
+          gistError: gistError
+            ? {
+                code: gistError.code,
+                message: gistError.message,
+                remediation: gistError.remediation,
+                detail: gistError.detail,
+              }
+            : null,
+        }, null, 2));
+      } else {
+        if (gist) {
+          console.log(`Secret gist created for ${target.name}`);
+          console.log(`  gist: ${gist.url}`);
+          console.log(`  marker: ${gist.marker}`);
+          console.log(`  title: ${gist.title}`);
+        } else {
+          console.log(`GitHub gist unavailable for ${target.name}; using local share link fallback.`);
+          if (gistError) {
+            console.log(`  gistError: ${gistError.message}`);
+            console.log(`  remediation: ${gistError.remediation}`);
+            if (gistError.detail) {
+              console.log(`  detail: ${gistError.detail}`);
+            }
+          }
+          console.log(`  shareLink: ${fallbackLink}`);
+        }
+        console.log(`  token: ${share.token}`);
+        console.log(`  shareLink: ${gist ? link : fallbackLink}`);
+        console.log(`  accessMode: ${share.accessMode}`);
+        console.log(`  oneTimeOnly: ${share.oneTimeOnly}`);
+      }
+      return 0;
+    }
+
+    if (subcommand === 'delete' || subcommand === 'del') {
+      const name = positional[0];
+      if (!name) {
+        console.error('Usage: npx auramaxx vault delete <name> [--location active|archive|recently_deleted]');
+        return 1;
+      }
+
+      const location = (deleteLocation || 'active').toLowerCase();
+      if (!['active', 'archive', 'recently_deleted'].includes(location)) {
+        console.error('Invalid --location. Expected active, archive, or recently_deleted.');
+        return 1;
+      }
+
+      const { target } = await resolveCredentialTarget(token, name, {
+        vaultName,
+        first: flagFirst,
+        surface: 'cli_vault_delete',
+        actor: 'cli-vault',
+      });
+
+      const result = await deleteCredential(
+        token,
+        target.id,
+        location as 'active' | 'archive' | 'recently_deleted',
+      );
+
+      if (flagJson) {
+        console.log(JSON.stringify({ success: true, credentialId: target.id, result }, null, 2));
+      } else {
+        console.log(`Deleted ${target.name} (${target.id}) -> ${result.action || 'ok'}`);
+      }
+      return 0;
+    }
+
+    console.error(`Unknown vault subcommand: ${subcommand}`);
+    showHelp();
+    return 1;
+  } catch (error) {
+    if (error instanceof SecretGistError) {
+      console.error(`Error: ${error.message}`);
+      console.error(`Remediation: ${error.remediation}`);
+      if (error.detail) {
+        console.error(`Detail: ${error.detail}`);
+      }
+      return 1;
+    }
+    const handledLock = await maybeHandleLockError({ context: 'vault command', error });
+    if (!handledLock) {
+      console.error(`Error: ${getErrorMessage(error)}`);
+    }
+    return 1;
+  }
+}
+
+async function main(): Promise<void> {
+  const exitCode = await runVaultCli(process.argv.slice(2));
+  process.exit(exitCode);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`Error: ${getErrorMessage(error)}`);
+    process.exit(1);
+  });
+}